owenloop 0.5.8 → 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 (131) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.md +81 -39
  3. package/bin/owenloop.mjs +16 -1
  4. package/dist/packages/work/src/agent/loop.d.ts +23 -8
  5. package/dist/packages/work/src/agent/loop.js +55 -6
  6. package/dist/packages/work/src/bundle/pull.d.ts +21 -0
  7. package/dist/packages/work/src/bundle/pull.js +118 -0
  8. package/dist/packages/work/src/consumed-verifier.js +6 -17
  9. package/dist/packages/work/src/exec/instructions.d.ts +4 -1
  10. package/dist/packages/work/src/exec/instructions.js +3 -0
  11. package/dist/packages/work/src/exec/loop.d.ts +2 -2
  12. package/dist/packages/work/src/exec/loop.js +273 -46
  13. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  14. package/dist/packages/work/src/exec/receipt.js +6 -6
  15. package/dist/packages/work/src/harness/claude.js +116 -0
  16. package/dist/packages/work/src/harness/codex.d.ts +8 -0
  17. package/dist/packages/work/src/harness/codex.js +27 -1
  18. package/dist/packages/work/src/harness/contract.d.ts +9 -0
  19. package/dist/packages/work/src/hub/client.d.ts +19 -4
  20. package/dist/packages/work/src/hub/client.js +7 -3
  21. package/dist/packages/work/src/hub/types.d.ts +84 -0
  22. package/dist/packages/work/src/main.js +1 -0
  23. package/dist/packages/work/src/roles/agent-run.js +57 -32
  24. package/dist/packages/work/src/roles/exec.js +27 -8
  25. package/dist/packages/work/src/roles/settings.js +2 -0
  26. package/dist/packages/work/src/roles/shift.js +14 -2
  27. package/dist/packages/work/src/roles/util.d.ts +1 -0
  28. package/dist/packages/work/src/roles/util.js +10 -0
  29. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  30. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  31. package/dist/packages/work/src/settings/roster.d.ts +84 -0
  32. package/dist/packages/work/src/settings/roster.js +364 -5
  33. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  34. package/dist/packages/work/src/settings/serving.js +79 -0
  35. package/dist/packages/work/src/settings/settings.d.ts +14 -1
  36. package/dist/packages/work/src/settings/settings.js +14 -0
  37. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  38. package/dist/packages/work/src/shift/loop.js +416 -54
  39. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  40. package/dist/packages/work/src/shift/runtime.d.ts +18 -0
  41. package/dist/packages/work/src/shift/runtime.js +104 -5
  42. package/dist/packages/work/src/shift/server.js +2 -0
  43. package/dist/packages/work/src/shift/spawn.d.ts +17 -2
  44. package/dist/packages/work/src/shift/spawn.js +16 -13
  45. package/dist/packages/work/src/shift/state.d.ts +29 -2
  46. package/dist/packages/work/src/shift/state.js +45 -15
  47. package/dist/packages/work/src/submit-proof.d.ts +11 -8
  48. package/dist/packages/work/src/submit-proof.js +11 -8
  49. package/dist/packages/work/src/usage.d.ts +1 -1
  50. package/dist/packages/work/src/usage.js +7 -1
  51. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  52. package/dist/packages/work/src/util/modifier-init.js +73 -0
  53. package/dist/src/bundle/tar.d.ts +9 -4
  54. package/dist/src/bundle/tar.js +9 -4
  55. package/dist/src/capabilities.d.ts +76 -6
  56. package/dist/src/capabilities.js +49 -6
  57. package/dist/src/capability-mapping-client.d.ts +29 -0
  58. package/dist/src/capability-mapping-client.js +160 -0
  59. package/dist/src/cli.d.ts +16 -3
  60. package/dist/src/cli.js +1925 -281
  61. package/dist/src/config-dir.d.ts +1 -1
  62. package/dist/src/config-dir.js +1 -1
  63. package/dist/src/crypto/index.d.ts +1 -1
  64. package/dist/src/crypto/index.js +1 -1
  65. package/dist/src/crypto/org-root.d.ts +30 -12
  66. package/dist/src/crypto/org-root.js +162 -14
  67. package/dist/src/crypto/records.d.ts +2 -0
  68. package/dist/src/crypto/records.js +2 -0
  69. package/dist/src/defs.d.ts +38 -2
  70. package/dist/src/defs.js +593 -86
  71. package/dist/src/engine.d.ts +103 -25
  72. package/dist/src/engine.js +331 -79
  73. package/dist/src/hub.d.ts +77 -0
  74. package/dist/src/hub.js +162 -0
  75. package/dist/src/implements.d.ts +56 -0
  76. package/dist/src/implements.js +790 -0
  77. package/dist/src/index.d.ts +11 -9
  78. package/dist/src/index.js +6 -5
  79. package/dist/src/mcp/serve.d.ts +22 -0
  80. package/dist/src/mcp/serve.js +330 -41
  81. package/dist/src/mcp/server.d.ts +10 -7
  82. package/dist/src/mcp/server.js +53 -8
  83. package/dist/src/model.d.ts +48 -10
  84. package/dist/src/model.js +252 -99
  85. package/dist/src/order-resolver.d.ts +1 -0
  86. package/dist/src/order-resolver.js +8 -1
  87. package/dist/src/schemas/index.d.ts +11 -0
  88. package/dist/src/schemas/order.v1.schema.json +7 -1
  89. package/dist/src/store/def-source.d.ts +19 -0
  90. package/dist/src/store/def-source.js +87 -17
  91. package/dist/src/store/gc-recovery.d.ts +46 -0
  92. package/dist/src/store/gc-recovery.js +258 -0
  93. package/dist/src/store/gc.d.ts +94 -0
  94. package/dist/src/store/gc.js +562 -0
  95. package/dist/src/store/index.d.ts +3 -1
  96. package/dist/src/store/index.js +2 -0
  97. package/dist/src/store/install.d.ts +34 -5
  98. package/dist/src/store/install.js +73 -11
  99. package/dist/src/store/pre-commit-verifier.js +42 -2
  100. package/dist/src/store/snapshot-guard.d.ts +18 -0
  101. package/dist/src/store/snapshot-guard.js +94 -0
  102. package/dist/src/store.d.ts +69 -4
  103. package/dist/src/store.js +254 -16
  104. package/dist/src/types.d.ts +101 -20
  105. package/dist/src/util.js +4 -1
  106. package/docs/authoring.md +235 -10
  107. package/docs/bundles.md +45 -2
  108. package/docs/cli.md +437 -55
  109. package/docs/crypto.md +32 -10
  110. package/docs/design.md +177 -47
  111. package/docs/evals/mcp-charter-baseline.json +428 -0
  112. package/docs/mcp-charter-eval.md +124 -0
  113. package/docs/routing.md +189 -34
  114. package/docs/shift-logs.md +38 -9
  115. package/docs/wire-contracts.md +78 -14
  116. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  117. package/examples/workflows/delivery.yaml +31 -14
  118. package/examples/workflows/ship.yaml +38 -4
  119. package/package.json +2 -1
  120. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  121. package/plugins/claude-code/plugin/.mcp.json +1 -1
  122. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  123. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  124. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  125. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  126. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  127. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  128. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  129. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  130. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  131. 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) |
56
- | `start <defName> [--provide name=json …] [--crew <name>] [--title <text>] [--hub <url>]` | start a published workflow on the bound hub with the human credential |
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 |
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) |
@@ -73,13 +94,20 @@ for the full breakdown.
73
94
  | `setup [--hub <url>] [--new-agent <name> \| --replace-agent <name>] [--crews <a,b>] [--scopes <a,b>] [--reuse-ssh-key <path>]` | onboard this machine: may store human and Scoped Identity credentials, ensure the three principal signing keys, relay the machine enrollment grant, write only execution-settings `hubOrigin`, and converge the bundled plugins for Claude Code and Codex — see [`setup`](#setup--onboard-a-machine) |
74
95
  | `enrollments [--hub <url>]` | read and locally classify the hub's relayed machine enrollment grants; never creates keys or writes the roster — see [`enrollments`](#enrollments--inspect-machine-enrollment) |
75
96
  | `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
76
- | `roster show [crew]` | print the merged **crew roster** and the provenance of every selected candidate layer |
97
+ | `roster show [crew]` | print the offline merged **crew roster**, all inspected machine and cached-hub layers, winner provenance, cache age, and shadowed rows |
98
+ | `roster org [--hub <url>]` | read the live hub org-global and per-crew rosters (human credential) |
99
+ | `roster org put <capability> --candidate <harness>:<model>:<effort>… [--crew <name>] [--hub <url>]` | replace one org-global or named crew roster row (human admin credential) |
100
+ | `roster org rm <capability> [--crew <name>] [--hub <url>]` | remove one org-global or named crew roster row (human admin credential) |
101
+ | `roster registry [--hub <url>]` | read the hub's known harnesses, models, and efforts (human credential) |
102
+ | `roster registry put <harness> [--model <model>:<effort,effort…>]… [--display-name <text>] [--hub <url>]` | replace one harness's full hub model snapshot (human admin credential); omit every `--model` to clear it |
103
+ | `roster sync [--hub <url>] [--as agent\|agent:<account>]` | refresh the local hub-roster cache explicitly with the same agent credential a shift uses |
77
104
  | `mcp [--hub <url>]` | serve the hub control plane to a local MCP host over stdio — spawned by MCP hosts, not run by humans — see [`mcp`](#mcp--stdio-control-plane-server-for-mcp-hosts) |
78
105
  | `shift start <crew...>`, `shift next`, `shift status`, `shift end` | run the foreground shift daemon and its local clients — see [`shift`](#shift--foreground-daemon-and-client) |
79
106
  | `work <subcommand> [options]` | run the execution-side CLI companion — see [`work`](#work--execution-side-cli-companion) |
107
+ | `util modifier-init --default <value>` | choose a modifier from rejection feedback, the order hint, or a default; intended for command steps |
80
108
  | `trust init\|grant\|revoke` | create and sign local enrollment trust records offline — see [`trust`](#trust--local-enrollment-trust) |
81
109
  | `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
82
- | `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 |
83
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 |
84
112
  | `reap <wf> [--now]` | run the reaper; `--now` forces every claim stale (TTL 0) — see below |
85
113
  | `runs <wf> [--open]` | list this instance's runs, joining claim state for open ones |
@@ -90,18 +118,35 @@ for the full breakdown.
90
118
  | `green <wf> <run> <path> [--value json] [--terminal]` | accept an owed output |
91
119
  | `emit <wf> <run> --items '[{…},{…}]'` | add collection elements |
92
120
  | `seal <wf> <run> [--value json]` | mark a collection complete |
93
- | `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 |
94
122
  | `retract <wf> <path> --by <author> --text <msg>` | drop a collection member |
95
123
  | `skip <wf> <path> --by <author> --text <msg>` | a step declines its own output |
96
- | `retry <wf> <path> [--by a] [--text guidance]` | clear a stall, reset the counter |
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 |
97
125
  | `close <wf> <run> [--outcome ok\|no_work\|failed\|skipped] [--summary s]` | release a claimed job |
98
126
  | `delete <wf>` | delete an instance and all its rows |
99
127
  | `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
100
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
+
101
146
  ## Bundles
102
147
 
103
- Bundle commands are deliberately dispatched before the CLI opens the engine
104
- 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`
105
150
  read or write only the paths named by the command; they do not create
106
151
  `.owenloop/state.db`, contact a remote coordinator, or use workflow definitions
107
152
  from `--defs`. Successful commands print one JSON object on stdout. Failures
@@ -112,8 +157,60 @@ owenloop bundle pack <source-dir> [--output <bundle.wnlp>]
112
157
  owenloop bundle unpack <bundle.wnlp> <destination-dir>
113
158
  owenloop bundle inspect <bundle.wnlp>
114
159
  owenloop bundle digest <bundle.wnlp>
160
+ owenloop bundle gc [--keep <n>] [--global] [--yes]
115
161
  ```
116
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
+
117
214
  `pack` requires a source directory containing root `bundle.yaml` and every
118
215
  workflow path listed by the manifest's `workflows` map. The source manifest is
119
216
  not modified. If `--output` is omitted,
@@ -181,14 +278,14 @@ By default, the execution settings file is `$HOME/.owenloop/settings.json`.
181
278
  For test or throwaway isolation, `OWENLOOP_CONFIG_DIR` may name an absolute
182
279
  directory used verbatim; `XDG_CONFIG_HOME` is not consulted. In the paths below,
183
280
  `<config>` means the resolved owenloop config directory. The same directory
184
- holds `credentials.json`, `allowed_signers`, `org-root.pub`, `roster/`, and
281
+ holds `credentials.json`, `allowed_signers`, `org-root.pub`, `grants/`, and
185
282
  `revocations/`.
186
283
 
187
284
  ### `shift start <crew...>`
188
285
 
189
286
  ```text
190
287
  owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
191
- [--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]
288
+ [--cap <n>] [--max-agents <n>] [--exec-reserve <n>] [--local-queue-hold <ms>] [--poll-interval <ms>] [--once]
192
289
  [--cache-dir <p>] [--state-dir <p>] [--log-dir <p>] [--log-max-age <ms>]
193
290
  [--work-root <dir>]...
194
291
  ```
@@ -206,6 +303,8 @@ one loop sweep and exits instead of keeping the foreground daemon running.
206
303
  | `--name <n>` | use this shift name; otherwise generate one from the host and current directory with a process/shift suffix |
207
304
  | `--cap <n>` | dispatch capacity; precedence is flag, then `settings.dispatchCap`, then `3` |
208
305
  | `--max-agents <n>` | concurrent agent limit; precedence is flag, then `settings.maxConcurrentAgents`, then `4` |
306
+ | `--exec-reserve <n>` | slots inside `--cap` that `agent-run` children may never occupy, so an exec/command order always has room; precedence is flag, then `settings.execReserve`, then `1`. Clamped to `cap - 1`, so a `--cap 1` shift gets no reserve. `0` disables the reserve and lets agents fill the whole cap. This does not raise the total child ceiling — `--cap` still bounds every child. |
307
+ | `--local-queue-hold <ms>` | how long to retain a claim this shift cannot dispatch before returning it to the hub; precedence is flag, then `settings.localQueueHoldMs`, then `0`. The value is clamped to 90 seconds. `0` means the shift never holds an undispatchable claim locally, so another daemon can be offered it immediately. |
209
308
  | `--poll-interval <ms>` | loop polling interval; defaults to `5000` milliseconds |
210
309
  | `--once` | run one loop sweep and exit; without it, keep the daemon in the foreground |
211
310
  | `--cache-dir <p>` | cache root; precedence is flag, then `OWENLOOP_CACHE_DIR`, then `settings.cacheDir`, then `$XDG_CACHE_HOME/owenloop`, then `$HOME/.cache/owenloop` |
@@ -214,6 +313,16 @@ one loop sweep and exits instead of keeping the foreground daemon running.
214
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 |
215
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 |
216
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
+
217
326
  **On-disk logs.** A running shift appends its dispatch record to
218
327
  `<log-dir>/shift.log` as JSON Lines, and gives each dispatched worker's stdout
219
328
  and stderr their own `<log-dir>/<run>.log`. Both files outlive the shift
@@ -254,25 +363,44 @@ directories an order is **allowed to name**. Neither derives from the other.
254
363
  owenloop shift start build --work-root ~/code --work-root /srv/work
255
364
  ```
256
365
 
257
- **Crew roster selection.** “Roster” in this section means the **crew
258
- roster** for capability routing, not the unrelated trust roster of signed
259
- enrollment grants in `~/.owenloop/roster/`. A selected roster candidate decides
366
+ **Crew roster selection.** A selected roster candidate decides
260
367
  the harness, model, and effort for an agent order. Its precedence is:
261
368
 
262
- 1. the first available candidate in the first matching crew roster;
369
+ 1. the first available candidate in the first matching crew roster named in
370
+ the hub-stamped `order.crews` sequence;
263
371
  2. `owenloop work agent-run --harness` (a local debug override);
264
372
  3. the verified step's `x.harness.id`;
265
373
  4. the first registered adapter.
266
374
 
267
- The shift passes its start crews to each agent worker internally. A named crew
268
- uses `~/.owenloop/crews/<crew>.json` above the machine-global
269
- `~/.owenloop/settings.json` `roster` key. Each capability row is atomic:
375
+ The shift advertises its start crews through worker → hub `serve_crews` and
376
+ its derived serving set through `serve_capabilities`. The latter is the raw
377
+ key union from the roster cascade (bare names and exact compounds are both
378
+ preserved), recomputed at startup and on the roughly 15-minute roster refresh;
379
+ it is not operator-set. **Today's hub ignores `serve_capabilities`; the
380
+ hub-side intersect ships separately.** The shift passes no crews to agent
381
+ workers. For a capability-bearing order, the worker resolves rosters only from
382
+ the hub-stamped `order.crews` list, in that stamped order. If the stamp is
383
+ missing, empty, malformed, or cannot be resolved locally, the worker refuses
384
+ and releases the order rather than falling back to the shift's start crews. The
385
+ complete strongest-first cascade for each stamped crew is: machine
386
+ `~/.owenloop/crews/<crew>.json`, machine
387
+ `~/.owenloop/settings.json` `roster`, the cached hub row for that crew, then
388
+ the cached hub org-global row. Hub rows live in a separate
389
+ `~/.owenloop/hub-rosters/` cache directory — never in the D5 trust
390
+ `~/.owenloop/grants/` directory. Each capability row is atomic:
270
391
  the stronger layer replaces the weaker candidate array, and candidates are
271
392
  tried in listed order. A step's `x.harness.id` is a policy constraint: a row
272
393
  whose candidates do not include it is released as
273
394
  `incompatible-harness-policy`; no available candidate is
274
395
  `unresolvable-capability`.
275
396
 
397
+ The shift refreshes that hub cache at startup and periodically while parked;
398
+ `owenloop roster sync` is the manual repair path. Failed refreshes never stop a
399
+ shift or refuse an order: a missing or corrupt cache becomes an explicitly
400
+ reported absent layer and the machine rows keep routing. `owenloop roster show`
401
+ is offline by design, so it prints exactly the layers an `agent-run` child can
402
+ see, including fetch age and any lower-priority rows shadowed by a winner.
403
+
276
404
  ```json
277
405
  {
278
406
  "roster": {
@@ -305,6 +433,40 @@ file). `owenloop doctor` adds one line for each present crew roster file,
305
433
  showing its found/absent layers and registered versus missing candidate
306
434
  harnesses.
307
435
 
436
+ Crew names are data, not filesystem paths. A fresh safe crew keeps the literal
437
+ `~/.owenloop/crews/<crew>.json` filename for rollback compatibility. Unsafe or
438
+ too-wide names use the dedicated codec-only
439
+ `~/.owenloop/crews/.owenloop-machine-roster-codec-namespace-reserved-v1-ownership/`
440
+ directory: short names use a reversible `crew-hex--<lowercase-hex>.json` basename,
441
+ while names too wide for one filesystem component use a bounded
442
+ `crew-hex-hash--…` basename. The current codec's distinct `crew-hex--` prefix
443
+ and lowercase hexadecimal payload keep it disjoint from older base64url files
444
+ and stable on case-insensitive filesystems; explicitly owned older
445
+ `crew--<base64url>.json` files remain readable during migration. Every codec
446
+ file records its exact `crew` identity in
447
+ the JSON document, so a reversible basename alone can never claim an old
448
+ legacy file. Do not derive either filename by hand. The reserved directory
449
+ itself can be the prefix of a valid 64-character nested legacy crew name, so a
450
+ file inside it is codec storage only when its JSON `crew` identity reproduces
451
+ its codec basename; a shorter unowned child remains a legacy path. A complete
452
+ codec path is nevertheless too long to be a hub-valid legacy crew name.
453
+ Existing safe legacy
454
+ `<crew>.json` files — including names containing spaces, colons, percent
455
+ signs, Unicode, and (on POSIX) backslashes — plus any lexically contained
456
+ legacy tree such as `crews/foo/bar.json` for crew `foo/bar` — remain readable
457
+ and take precedence only when their on-disk spelling exactly matches the crew,
458
+ so `Delivery` and `delivery` cannot silently share one strongest layer on a
459
+ case-insensitive filesystem. The short-lived feature-branch directory
460
+ `.owenloop-encoded-rosters/` is treated as codec storage only when a file
461
+ declares the codec basename's exact `crew`; otherwise it remains a legacy
462
+ nested path. A literal crew name that spells an owned historical codec file is
463
+ distinct from that file's declared owner and receives its own current codec
464
+ path, never an alias of the historical strongest layer.
465
+ Routing probes only its requested crew paths. Doctor combines global file
466
+ diagnostics with the verified agent's crew list, so a malformed bounded hash
467
+ file is reported rather than silently disappearing. Traversal-shaped hub crew
468
+ names stay confined to the `crews/` directory.
469
+
308
470
  A clean start or `--once` completion exits `0`. `owenloop shift --help` also
309
471
  exits `0`. Runtime failures such as credential reads or socket/runtime setup
310
472
  exit `1`. Usage and
@@ -326,6 +488,17 @@ version loops sharing the directory are configured with different total or
326
488
  agent caps, each loop enforces its own configured limits under the shared lock.
327
489
  Use identical cap settings for every loop sharing a state directory.
328
490
 
491
+ Reconciliation uses that same lock and re-checks record identity before it
492
+ changes anything: an abandoned reservation must still match the observed
493
+ reservation token, a dead child must still have the observed PID, and a
494
+ persisted start gate must still match both the observed PID and gate token. If
495
+ another loop re-dispatches the same run while a stale scan is waiting for the
496
+ lock, the replacement record and gate are preserved and no `abandoned` or
497
+ `reaped` event is reported. Startup reconciliation defers briefly when the
498
+ lock is busy and the poll loop retries it. A worker exit notification releases
499
+ its PID record on every terminal outcome, including a clean exit with status
500
+ `0`; reconciliation remains the crash/restart backstop.
501
+
329
502
  Canonical `*.json` child and reservation records are capacity-bearing state.
330
503
  Missing records are benign, including a record that disappears between listing
331
504
  and read. A truncated, malformed, or unreadable canonical record is not benign:
@@ -384,7 +557,7 @@ either `exec` or `agent-run`:
384
557
  - `reaped`: `{ "type": "reaped", "workflow": "...", "run": "...", "kind": "exec", "pid": 123 }`
385
558
  - `failed`: `{ "type": "failed", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "message": "..." }`
386
559
  - `bundle-miss`: `{ "type": "bundle-miss", "workflow": "...", "def": "..." }` — a legacy order named a def with no cached bundle, so it was left for hub pickup
387
- - `order-dropped`: `{ "type": "order-dropped", "workflow": "...", "run": "...", "step": "...", "reason": "unsupported-worker", "message": "..." }` — the shift refused one order. Match on `reason` (`malformed-digest`, `malformed-worker`, `unsupported-worker`, `verification-failed`, `metadata-unavailable`); display `message`
560
+ - `order-dropped`: `{ "type": "order-dropped", "workflow": "...", "run": "...", "step": "...", "reason": "unsupported-worker", "message": "..." }` — the shift refused one order. Match on `reason` (`malformed-digest`, `malformed-worker`, `unsupported-worker`, `verification-failed`, `metadata-unavailable`, `agent-lane-closed`, `dispatch-cap-full`, `agent-cap-full`, `claim-expired`); display `message`. The capacity, expiry, and `agent-lane-closed` reasons return the claim to the hub; malformed and unsupported reasons leave it for the pickup window.
388
561
  - `ended`: `{ "type": "ended" }`, delivered to a parked `next` when `shift end` explicitly shuts down the daemon
389
562
 
390
563
  Every event above is also appended to `<log-dir>/shift.log` as JSON Lines, which
@@ -429,11 +602,13 @@ owenloop shift status [--state-dir <p>]
429
602
  With a daemon, status exits `0` and prints:
430
603
 
431
604
  ```json
432
- { "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "attended_at": null, "started_at": 1738000000000 }
605
+ { "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "agent_ceiling": 2, "attended_at": null, "started_at": 1738000000000 }
433
606
  ```
434
607
 
435
- `attended_at` remains `null` until the first accepted `next` request. Without a
436
- daemon, status is still a successful question: it exits `0` and prints
608
+ `agent_ceiling` is the effective maximum number of `agent-run` children after
609
+ applying `--max-agents`, `--cap`, and `--exec-reserve`; command and exec work
610
+ may still use any free slot inside `cap`. `attended_at` remains `null` until the
611
+ first accepted `next` request. Without a daemon, status is still a successful question: it exits `0` and prints
437
612
  `{ "status": "no daemon", "socket": "<path>" }`. Invalid arguments exit `2`;
438
613
  other client/runtime errors exit `1`.
439
614
 
@@ -482,6 +657,28 @@ The execution settings file is `<config>/settings.json` (see
482
657
  | `release --session <id> [options]` | drain a session's held claims |
483
658
  | `settings` | print the resolved execution settings file |
484
659
  | `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
660
+ | `util modifier-init --default <value>` | print the requested modifier from `OWENLOOP_FEEDBACK`, else `OWENLOOP_MODIFIER`, else the required default |
661
+
662
+ ### `util modifier-init`
663
+
664
+ `owenloop util modifier-init --default <value>` is a deterministic helper for
665
+ a command step that produces a bound modifier artifact. It prints one value and
666
+ does no model or harness work. Its precedence is:
667
+
668
+ 1. the newest `reject` reason carrying `requested` in `OWENLOOP_FEEDBACK`;
669
+ 2. the current order modifier in `OWENLOOP_MODIFIER`;
670
+ 3. the required `--default` value.
671
+
672
+ The helper accepts a single-word result only. It reads feedback inline from
673
+ `OWENLOOP_FEEDBACK` or from the temporary path in `OWENLOOP_FEEDBACK_FILE`,
674
+ using the same 64 KiB threshold and collision rule as consumed inputs. Exit 0
675
+ prints the value; exit 2 is a usage error; exit 3 means the feedback could not
676
+ be parsed or the resolved value was invalid.
677
+
678
+ The helper prints the selected word as ordinary stdout. A command artifact is
679
+ submitted as the full `CommandReceipt`; if a workflow binds a field inside a
680
+ command payload, the command must emit the `##owenloop:payload##` JSON marker and
681
+ the bind must name that field (for example, `from: payload.value`).
485
682
 
486
683
  ### `work agent-run` — the only Step Agent dispatcher
487
684
 
@@ -568,11 +765,11 @@ separate concern.
568
765
  `owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
569
766
  `workflows/**` folder (via GitHub's REST API and Node's built-in `fetch` — no
570
767
  new dependency), validates every def with the same lint/validate/`check`
571
- machinery `owenloop lint`/`owenloop check` use — plus a strict cross-def
572
- backstop (include expansion, `calls:` target/inputs/output-count checks,
573
- cycle detection) on the staged tree, so an error `loadDefsRaw` would
574
- otherwise swallow still refuses the install — and only then installs them
575
- 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
576
773
  characters of `sha256(owner/repo)`. The hash keeps distinct sources that used
577
774
  to collide on the same `<owner>-<repo>` folder (e.g. `a-b/c` and `a/b-c`)
578
775
  from clobbering each other. `owner` and `repo` are restricted to the
@@ -716,16 +913,25 @@ defs dir is guarded only on the default `cwd/workflows` fallback — an explicit
716
913
  matching the `--db`/`OWENLOOP_DB` rule above.
717
914
 
718
915
  **Installed-def discovery.** Defs installed by `add` are discovered by default:
719
- 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
720
917
  (`cwd/workflows`) sees them by name, no `--defs` flag needed. `loadDefs` itself
721
918
  stays a pure dir-scanner (top-level `*.yaml` plus immediate-subdir
722
919
  `workflow.yaml`); the CLI folds installed subfolders in on top, ledger-driven and
723
920
  bounded — it only loads folders named by the fail-closed-validated
724
921
  `.owenloop/installed.json` entries, never a raw recurse of the tree.
725
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
+
726
931
  - **Only under the default defs dir.** An explicit `--defs`/`OWENLOOP_DEFS` is
727
932
  operator intent to target a literal dir and keeps the pure-scan behavior with
728
- 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",
729
935
  so even `OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
730
936
  Pointing `--defs` straight at an install folder
731
937
  (`--defs workflows/<owner>-<repo>-<hash>`) still works exactly as before.
@@ -736,9 +942,12 @@ bounded — it only loads folders named by the fail-closed-validated
736
942
  - **Fail-open.** The fold-in never breaks base loading. A corrupt or
737
943
  structurally-invalid `installed.json`, a missing install folder, or an install
738
944
  folder that fails to load each emits a `warning:` on stderr and is skipped;
739
- your project defs still load and the command still exits 0. The add-time
740
- fail-closed lockfile validation is unchanged — discovery consumes it and simply
741
- 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.
742
951
 
743
952
  Public repos only — no auth/token support yet; a private repo (or a bad
744
953
  ref) surfaces as a 404 from the sha-resolve step.
@@ -1340,6 +1549,17 @@ usage errors before credential or network access. The command does not claim,
1340
1549
  dispatch, close, or otherwise drive work—the standing Shift discovers the run
1341
1550
  through its normal crew inbox.
1342
1551
 
1552
+ `--scope <label>` is forwarded as the run's `scope`: a free routing label
1553
+ recorded on the instance, with no registry and no fixed set of values. Omit it
1554
+ and the run carries no scope. `--priority <low|normal|high>` is forwarded as the
1555
+ run's `priority`; omit it and the hub applies `normal`. A value outside
1556
+ `low|normal|high` is a local usage error before any credential or network
1557
+ access, not a forwarded request. Like `--crew`/`--title`, a bare
1558
+ `--scope`/`--priority` or a `--scope=`/`--priority=` is a local usage error.
1559
+ Both are recorded at start only and are never writable afterwards. Do not
1560
+ confuse `--scope` (this routing label) with `--scopes` on `agent new`/`setup`,
1561
+ which lists an agent token's authorization scopes.
1562
+
1343
1563
  ### `cancel` — stop a running instance
1344
1564
 
1345
1565
  `owenloop cancel <workflow>` sends `POST /api/cancel_run` and prints whether the
@@ -1457,6 +1677,14 @@ stream cancelled) rather than buffered, closing the same memory-exhaustion gap
1457
1677
  on the hub path that the `add` download cap closes on the archive path.
1458
1678
  `OWENLOOP_HUB_MAX_RESPONSE_BYTES` overrides the cap (a test knob).
1459
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
+
1460
1688
  ### `login` — authenticate the CLI against a hub
1461
1689
 
1462
1690
  Two ways to get a credential, both of which **verify before storing** (a token
@@ -1734,6 +1962,18 @@ On a `401`, an OAuth credential is refreshed once and the request retried; an
1734
1962
  agent (`olp_`) token has no refresh path, so a `401` is a hard "re-mint it"
1735
1963
  error.
1736
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
+
1737
1977
  **Include and bodyFile limitations.** A def whose file uses `include:` is
1738
1978
  refused (`uses include:, not hub-pushable`): the hub's `create_workflow`
1739
1979
  parses the raw YAML without include expansion, and a re-serialized expanded
@@ -1742,6 +1982,73 @@ def isn't round-trippable. A def using `bodyFile:` is refused the same way
1742
1982
  resolve the external file against once the YAML leaves this machine. Inline
1743
1983
  both before pushing.
1744
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
+
1745
2052
  ### `publish` — pack and publish a workflow bundle
1746
2053
 
1747
2054
  ```text
@@ -2402,7 +2709,7 @@ lines (the tolerant-false notices, the transfer summary) go to stderr only.
2402
2709
 
2403
2710
  ## `setup` — onboard a machine
2404
2711
 
2405
- `owenloop setup` is the one-shot onboarding command. It runs seven ordered steps.
2712
+ `owenloop setup` is the one-shot onboarding command. It runs eight ordered steps.
2406
2713
  Depending on the machine state, setup may store the human credential, mint or
2407
2714
  rekey and store a Scoped Identity credential, ensure the three principal
2408
2715
  signing keys, relay a signed machine enrollment grant, and write only
@@ -2429,7 +2736,15 @@ plugin version already installed performs no plugin writes. The steps:
2429
2736
  5. **execution settings** — write only `hubOrigin` into the execution settings
2430
2737
  file so the local Step Agent talks to this hub, preserving every other key
2431
2738
  (skipped when `hubOrigin` already matches).
2432
- 6. **plugin** — probe and converge the bundled `owenloop` plugin separately
2739
+ 6. **crew rosters** — for every crew known to the verified or newly minted
2740
+ Scoped Identity, materialize a local strongest-layer skeleton at its resolved
2741
+ `crews/<crew>.json` path. Each new file contains a descriptive `note`, its
2742
+ exact `crew` identity when needed by the bounded filename codec, and
2743
+ `"roster": {}`, so the machine initially inherits the weaker settings and
2744
+ hub layers. Setup never overwrites an existing acceptable crew-roster file:
2745
+ it reports that file as skipped and leaves its bytes untouched. If setup does
2746
+ not know any crews for the identity, it records a non-fatal noted result.
2747
+ 7. **plugin** — probe and converge the bundled `owenloop` plugin separately
2433
2748
  for Claude Code and Codex. When the installed plugin is missing or its
2434
2749
  version differs from the CLI package, setup adds the bundled marketplace
2435
2750
  when needed and installs or updates the plugin. Claude Code uses
@@ -2440,10 +2755,10 @@ plugin version already installed performs no plugin writes. The steps:
2440
2755
  **Non-fatal:** a missing harness or failed convergence is reported as
2441
2756
  `noted` and never fails setup. If the bundled marketplace root is
2442
2757
  unavailable, setup prints manual commands instead.
2443
- 7. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
2758
+ 8. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
2444
2759
  the same surfaces, whose result becomes setup's exit code.
2445
2760
 
2446
- Progress lines (the `[n/7]` headers and `✓`/`✗` marks) go to **stderr**; the
2761
+ Progress lines (the `[n/8]` headers and `✓`/`✗` marks) go to **stderr**; the
2447
2762
  final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
2448
2763
  **stdout**.
2449
2764
 
@@ -2719,6 +3034,14 @@ inference. Contrast this with [`agent new`](#agent-new--mint-an-agent-token-into
2719
3034
  which **mints** a new credential directly and therefore stops rather than
2720
3035
  ever guessing — a wrong guess there is a side effect a retry cannot undo.
2721
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
+
2722
3045
  **`~/.owenloop/config.json`** is written by
2723
3046
  [`login`](#login--authenticate-the-cli-against-a-hub): a small, non-secret
2724
3047
  JSON file (`{"version": 1, "hub": "<origin>"}`) recording the hub `login` most
@@ -2731,32 +3054,68 @@ like every other command — an explicit bad value is reported, never silently
2731
3054
  skipped, precisely because rungs 1–2 come from something the operator typed
2732
3055
  or set, not from inference.
2733
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
+
2734
3080
  ### Tools
2735
3081
 
2736
- The server exposes 17 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
2737
3083
  `create_agent`, plus four [crew](#crews) tools (`list_crews`, `create_crew`,
2738
3084
  `add_crew_member`, `remove_crew_member`) that do not mirror the hub's own MCP
2739
- toolset. Each baseline tool's result is the hub REST response as one text
2740
- 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.
2741
3094
 
2742
3095
  | tool | what it does |
2743
3096
  |---|---|
2744
- | `whats_next` | tick a workflow and get the next work order(s), or the inbox of started instances |
2745
- | `submit` | submit a work order output |
2746
- | `reject_artifact` | send an upstream artifact back to its producer with a reason |
2747
- | `provide_input` | answer a human gate — provide a value for a seeded/owed input |
2748
- | `start_run` | create a new instance from a definition name |
2749
- | `create_workflow` | parse + load a workflow def YAML (the authoring hard gate) |
2750
- | `get_workflow` | fetch one loaded definition |
2751
- | `list_workflows` | names, titles, step counts, and def hash/version of every loaded def |
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 |
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 |
2752
3109
  | `get_status` | `engine.status` verbatim plus a plain-English rendering |
2753
3110
  | `heartbeat` | touch the liveness timestamp on an open run so it is not reaped mid-step |
2754
3111
  | `get_order` | re-fetch the persisted order packet and lease state for a run you hold |
2755
3112
  | `release` | give back a claim so its order is re-offered without waiting out the reap TTL |
2756
3113
  | `publish_event` | publish an event against a contract, starting one run per matched subscription |
2757
3114
  | `list_subscriptions` | the org's contract subscriptions |
2758
- | `presence_ping` | register/refresh this Shift's presence — name, crews served (empty/omitted `serve_crews` means every crew this principal belongs to), and optionally which process incarnation is reporting (`shift_id`/`started_at`); observability only, a separate mechanism from the `heartbeat` lease tool above |
3115
+ | `presence_ping` | register/refresh this Shift's presence — name, crews served (empty/omitted `serve_crews` means every crew this principal belongs to), optional raw `serve_capabilities`, and optionally which process incarnation is reporting (`shift_id`/`started_at`); observability only, a separate mechanism from the `heartbeat` lease tool above |
2759
3116
  | `list_shifts` | your principal's registered Shifts — online/offline derived at read time from last ping, crews served (returned as `crews`; empty means every crew this principal belongs to), and each one's reporting incarnation (`shiftId`/`startedAt`) when the hub recorded one |
3117
+ | `get_rosters` | read the org-global and per-crew capability rosters available to this principal |
3118
+ | `list_harness_models` | read the org's registered harnesses, models, and supported efforts |
2760
3119
  | `wake` | cheap "has anything changed since cursor X" pre-check for a polling loop |
2761
3120
  | `create_agent` | create a NEW Scoped Identity and store its credential locally — **never returns the token** |
2762
3121
  | `list_crews` | list the org's crews, each with its member rows inline — a plain passthrough, no filtering |
@@ -2774,6 +3133,19 @@ message is surfaced verbatim; error bodies never carry tokens). If the store
2774
3133
  write fails, the result says so and tells you to revoke/re-key the agent from
2775
3134
  the console.
2776
3135
 
3136
+ `start_run`'s `scope` has one default the CLI does not have: when the caller
3137
+ supplies no `scope`, the server fills in the session's repository name, taken
3138
+ from the `origin` remote's URL (its last path segment, trailing `.git`
3139
+ removed) — `owenloop` for
3140
+ `https://github.com/typicalday/owenloop.git`. It is read from the remote rather
3141
+ than the directory name so that every worktree of one repo reports the same
3142
+ scope. It is a default, never an override: an explicitly supplied `scope` is
3143
+ always forwarded unchanged. When no repository name can be determined — not a
3144
+ git checkout, no `origin` remote, an unparseable URL — the server sends no
3145
+ `scope` at all rather than guessing a label. Two repositories with the same
3146
+ name under different owners therefore share a scope; pass an explicit `scope`
3147
+ to tell them apart.
3148
+
2777
3149
  **The four crew tools** (`list_crews`, `create_crew`, `add_crew_member`,
2778
3150
  `remove_crew_member`) cover the same four operations as the [`crew` CLI
2779
3151
  family](#crews) — `crew list`, `crew new`, `crew member add`, `crew member
@@ -2843,7 +3215,8 @@ interactively.
2843
3215
 
2844
3216
  The [`examples/workflows`](../examples/workflows) folder has a workflow per
2845
3217
  idea: [`delivery`](../examples/workflows/delivery.yaml) (a review knock-back
2846
- loop), [`ship`](../examples/workflows/ship.yaml) (delivery grown up: the full
3218
+ loop — a teaching example, not the production line),
3219
+ [`ship`](../examples/workflows/ship.yaml) (delivery grown up: the full
2847
3220
  production line with provisioned workspaces, an adversarial reviewer, a doc
2848
3221
  pass, and teardown owned as a step),
2849
3222
  [`research`](../examples/workflows/research.yaml) (collections),
@@ -2877,7 +3250,7 @@ wf=$(owenloop create delivery \
2877
3250
  run=$(owenloop tick $wf | jq -r '.orders[0].run') # claim the planner job
2878
3251
  owenloop green $wf $run plan --value '{"plan":"…"}' # report its output
2879
3252
 
2880
- owenloop status $wf # owed / eligible / blocked / done
3253
+ owenloop status $wf # done / debts / eligible / blocked / pending / inFlight
2881
3254
  ```
2882
3255
 
2883
3256
  **A knock-back.** When the reviewer's job comes up, instead of greening its
@@ -2890,7 +3263,9 @@ owenloop reject $wf pr --by reviewer --text "tests are missing"
2890
3263
  That re-arms `builder` with the reason attached to its next job. Do it past
2891
3264
  `builder`'s `maxAttempts` and `pr` **stalls** — owenloop stops re-arming it
2892
3265
  and waits for a human. `owenloop retry $wf pr --text "use the new fixture"`
2893
- clears the stall and resets the counter.
3266
+ clears the stall and resets the counter. `retry --text` is also the answer
3267
+ path for a step that escalated with `ask`; pass `--hub <url>` to answer an
3268
+ ask on a hub-hosted run.
2894
3269
 
2895
3270
  ## `reap`, `runs`, and `status.inFlight` — observing and clearing in-flight work
2896
3271
 
@@ -2943,6 +3318,12 @@ refuses it. The result JSON is always written to stdout; the human-readable
2943
3318
  reason goes to stderr. A successful call exits 0 — a Step Agent should treat a
2944
3319
  non-zero exit as a failure, not a success.
2945
3320
 
3321
+ For a bound modifier artifact, local `reject` also accepts
3322
+ `--requested <modifier>`. The engine checks that the requested value is one of
3323
+ the workflow's declared modifiers and carries it in the artifact's next reason
3324
+ thread, where a deterministic producer such as `util modifier-init` can read it.
3325
+ The flag is only valid for an artifact bound to `modifier`.
3326
+
2946
3327
  ## What a job looks like
2947
3328
 
2948
3329
  `tick` returns `{ workflow, orders, reaped }`. Each order is a **reference
@@ -2963,6 +3344,7 @@ them.
2963
3344
  "inputs": ["plan"],
2964
3345
  "outputs": ["pr"],
2965
3346
  "worker": "command", // the authored step's executor:, mapped verbatim (absent = 'agent')
3347
+ "modifier": "standard", // modifier used for this offer; absent when unmodified
2966
3348
  "consumes": { "plan": { /* the accepted input value */ } },
2967
3349
  "owes": [ // the feedback channel
2968
3350
  { "path": "pr", "judgmentRejects": 2, "schemaRejects": 0,
@@ -2976,7 +3358,7 @@ A worker first **resolves the reference**: the `(defDigest, step, key)`
2976
3358
  boundary maps the order to the exact authored instructions from the worker's
2977
3359
  trusted local definition source — the same resolver the embedded engine and
2978
3360
  the CLI use. Resolution returns the authored `prompt` (with
2979
- `${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}`
3361
+ `${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MODIFIER}`/`${MAX_ATTEMPTS}`
2980
3362
  materialized), the authored `command` if the step has one, and nothing
2981
3363
  fabricated. If the worker's source does not know the digest — the definition
2982
3364
  was never delivered, or the current on-disk definition no longer matches the