owenloop 0.5.7 → 0.5.9

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 (111) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/README.md +7 -8
  3. package/dist/packages/work/src/agent/capability-model.d.ts +64 -82
  4. package/dist/packages/work/src/agent/capability-model.js +94 -91
  5. package/dist/packages/work/src/agent/loop.d.ts +55 -26
  6. package/dist/packages/work/src/agent/loop.js +144 -50
  7. package/dist/packages/work/src/bundle/types.d.ts +3 -3
  8. package/dist/packages/work/src/consumed-verifier.js +6 -17
  9. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  10. package/dist/packages/work/src/exec/loop.js +206 -35
  11. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  12. package/dist/packages/work/src/exec/receipt.js +6 -6
  13. package/dist/packages/work/src/harness/child-env.js +4 -5
  14. package/dist/packages/work/src/harness/claude.js +100 -0
  15. package/dist/packages/work/src/harness/codex.js +3 -4
  16. package/dist/packages/work/src/harness/session-store.d.ts +63 -3
  17. package/dist/packages/work/src/harness/session-store.js +104 -9
  18. package/dist/packages/work/src/hub/client.d.ts +19 -4
  19. package/dist/packages/work/src/hub/client.js +7 -3
  20. package/dist/packages/work/src/hub/types.d.ts +87 -3
  21. package/dist/packages/work/src/main.js +1 -0
  22. package/dist/packages/work/src/roles/agent-run.js +46 -43
  23. package/dist/packages/work/src/roles/exec.js +2 -0
  24. package/dist/packages/work/src/roles/sessions.d.ts +3 -2
  25. package/dist/packages/work/src/roles/sessions.js +9 -2
  26. package/dist/packages/work/src/roles/settings.js +3 -1
  27. package/dist/packages/work/src/roles/shift.js +14 -2
  28. package/dist/packages/work/src/roles/util.d.ts +1 -0
  29. package/dist/packages/work/src/roles/util.js +10 -0
  30. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  31. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  32. package/dist/packages/work/src/settings/roster.d.ts +105 -0
  33. package/dist/packages/work/src/settings/roster.js +439 -0
  34. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  35. package/dist/packages/work/src/settings/serving.js +79 -0
  36. package/dist/packages/work/src/settings/settings.d.ts +25 -24
  37. package/dist/packages/work/src/settings/settings.js +29 -33
  38. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  39. package/dist/packages/work/src/shift/loop.js +299 -51
  40. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  41. package/dist/packages/work/src/shift/runtime.d.ts +15 -0
  42. package/dist/packages/work/src/shift/runtime.js +95 -13
  43. package/dist/packages/work/src/shift/server.js +2 -0
  44. package/dist/packages/work/src/shift/spawn.d.ts +18 -50
  45. package/dist/packages/work/src/shift/spawn.js +30 -65
  46. package/dist/packages/work/src/shift/state.d.ts +29 -2
  47. package/dist/packages/work/src/shift/state.js +45 -15
  48. package/dist/packages/work/src/usage.d.ts +1 -1
  49. package/dist/packages/work/src/usage.js +10 -5
  50. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  51. package/dist/packages/work/src/util/modifier-init.js +73 -0
  52. package/dist/src/bundle/tar.d.ts +9 -4
  53. package/dist/src/bundle/tar.js +9 -4
  54. package/dist/src/capabilities.d.ts +50 -0
  55. package/dist/src/capabilities.js +38 -0
  56. package/dist/src/cli.d.ts +15 -1
  57. package/dist/src/cli.js +1099 -32
  58. package/dist/src/config-dir.d.ts +14 -19
  59. package/dist/src/config-dir.js +16 -24
  60. package/dist/src/credentials.d.ts +1 -1
  61. package/dist/src/credentials.js +1 -1
  62. package/dist/src/crypto/index.d.ts +1 -1
  63. package/dist/src/crypto/index.js +1 -1
  64. package/dist/src/crypto/org-root.d.ts +30 -12
  65. package/dist/src/crypto/org-root.js +162 -14
  66. package/dist/src/crypto/records.d.ts +3 -0
  67. package/dist/src/crypto/records.js +8 -0
  68. package/dist/src/crypto/trust-roots.d.ts +2 -2
  69. package/dist/src/crypto/trust-roots.js +2 -2
  70. package/dist/src/defs.d.ts +6 -1
  71. package/dist/src/defs.js +203 -8
  72. package/dist/src/engine.d.ts +55 -6
  73. package/dist/src/engine.js +172 -22
  74. package/dist/src/global-config.d.ts +4 -7
  75. package/dist/src/global-config.js +4 -7
  76. package/dist/src/hub.d.ts +207 -5
  77. package/dist/src/hub.js +263 -3
  78. package/dist/src/index.d.ts +5 -5
  79. package/dist/src/index.js +3 -3
  80. package/dist/src/mcp/serve.d.ts +22 -0
  81. package/dist/src/mcp/serve.js +88 -8
  82. package/dist/src/model.d.ts +2 -0
  83. package/dist/src/model.js +32 -25
  84. package/dist/src/order-resolver.d.ts +1 -0
  85. package/dist/src/order-resolver.js +8 -1
  86. package/dist/src/schemas/index.d.ts +19 -0
  87. package/dist/src/schemas/order.v1.schema.json +13 -2
  88. package/dist/src/store/pre-commit-verifier.js +1 -1
  89. package/dist/src/store.d.ts +5 -0
  90. package/dist/src/store.js +43 -8
  91. package/dist/src/types.d.ts +64 -7
  92. package/dist/src/work-settings.d.ts +2 -4
  93. package/dist/src/work-settings.js +2 -4
  94. package/docs/agent-runner.md +2 -2
  95. package/docs/authoring.md +90 -2
  96. package/docs/bundles.md +29 -3
  97. package/docs/cli.md +456 -120
  98. package/docs/crypto.md +32 -16
  99. package/docs/design.md +70 -1
  100. package/docs/routing.md +762 -0
  101. package/docs/shift-logs.md +37 -10
  102. package/docs/wire-contracts.md +50 -7
  103. package/examples/workflows/delivery.yaml +31 -14
  104. package/examples/workflows/ship.yaml +10 -2
  105. package/package.json +1 -1
  106. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  107. package/plugins/claude-code/plugin/.mcp.json +1 -1
  108. package/plugins/claude-code/plugin/skills/author/SKILL.md +1 -2
  109. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  110. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  111. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +1 -2
package/docs/cli.md CHANGED
@@ -53,13 +53,18 @@ for the full breakdown.
53
53
  | `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
54
  | `connect [--hub <url>] [--as <slot>]` | verify a resolved hub credential and record an optional per-project override in `.owenloop/hub.json` |
55
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 |
56
+ | `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 |
57
57
  | `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
58
  | `logout [--hub <url>] [--as <slot>]` | delete the stored credential for a hub |
59
59
  | `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) |
60
60
  | `capability bind <capability> <crew> [--hub <url>]` | add a crew to a workflow capability on the hub org — a capability may route to many crews (admin; human credential) — see [Capability routes](#capability-routes) |
61
61
  | `capability unbind <capability> <crew> [--hub <url>]` | remove one `(capability, crew)` route — see [Capability routes](#capability-routes) |
62
62
  | `capability list [--hub <url>]` | list the hub org's capability routes — see [Capability routes](#capability-routes) |
63
+ | `routing alerts [--workflow <wf>] [--limit <n>] [--hub <url>]` | list the hub org's routing alerts — every hold, reroute, wait and fallback the hub recorded — see [Routing](#routing) |
64
+ | `routing show <workflow> [--hub <url>]` | print one **hub run's** routing: modifier, wait policy, alerts, resolution reports and escalations — see [Routing](#routing) |
65
+ | `routing rule list [--hub <url>]` | list the org's capability **reroute rules**, in the order the hub tries them — see [Routing](#routing) |
66
+ | `routing rule add <capability> <target> [--position <n>] [--hub <url>]` | add one reroute rule — offer `<capability>` as `<target>` when it has no live crew binding (admin; human credential) — see [Routing](#routing) |
67
+ | `routing rule rm <capability> <target> [--hub <url>]` | remove one reroute rule — see [Routing](#routing) |
63
68
  | `crew list [--hub <url>]` | list the hub org's crews with their members (includes the orphan crew once one exists) — see [Crews](#crews) |
64
69
  | `crew new <name> --kind personal\|shared [--owner <memberId>] [--hub <url>]` | create a crew on the hub org (admin, or own personal crew; human credential) — see [Crews](#crews) |
65
70
  | `crew rm <crewId> [--hub <url>]` | delete a crew; work stamped to it moves to the org's orphan crew — see [Crews](#crews) |
@@ -68,9 +73,17 @@ for the full breakdown.
68
73
  | `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) |
69
74
  | `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) |
70
75
  | `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 offline merged **crew roster**, all inspected machine and cached-hub layers, winner provenance, cache age, and shadowed rows |
77
+ | `roster org [--hub <url>]` | read the live hub org-global and per-crew rosters (human credential) |
78
+ | `roster org put <capability> --candidate <harness>:<model>:<effort>… [--crew <name>] [--hub <url>]` | replace one org-global or named crew roster row (human admin credential) |
79
+ | `roster org rm <capability> [--crew <name>] [--hub <url>]` | remove one org-global or named crew roster row (human admin credential) |
80
+ | `roster registry [--hub <url>]` | read the hub's known harnesses, models, and efforts (human credential) |
81
+ | `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 |
82
+ | `roster sync [--hub <url>] [--as agent\|agent:<account>]` | refresh the local hub-roster cache explicitly with the same agent credential a shift uses |
71
83
  | `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) |
72
84
  | `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) |
73
85
  | `work <subcommand> [options]` | run the execution-side CLI companion — see [`work`](#work--execution-side-cli-companion) |
86
+ | `util modifier-init --default <value>` | choose a modifier from rejection feedback, the order hint, or a default; intended for command steps |
74
87
  | `trust init\|grant\|revoke` | create and sign local enrollment trust records offline — see [`trust`](#trust--local-enrollment-trust) |
75
88
  | `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
76
89
  | `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
@@ -87,7 +100,7 @@ for the full breakdown.
87
100
  | `reject <wf> <path> --by <author> --text <msg>` | reject an output (re-arms its producer) |
88
101
  | `retract <wf> <path> --by <author> --text <msg>` | drop a collection member |
89
102
  | `skip <wf> <path> --by <author> --text <msg>` | a step declines its own output |
90
- | `retry <wf> <path> [--by a] [--text guidance]` | clear a stall, reset the counter |
103
+ | `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 |
91
104
  | `close <wf> <run> [--outcome ok\|no_work\|failed\|skipped] [--summary s]` | release a claimed job |
92
105
  | `delete <wf>` | delete an instance and all its rows |
93
106
  | `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
@@ -171,23 +184,18 @@ but attendance is advisory and observability-only. Attendance never changes
171
184
  routing, dispatch, or lease behavior.
172
185
 
173
186
  <a id="config-dir"></a>
174
- The execution settings file is `<config>/settings.json`. Throughout this
175
- document `<config>` is owenloop's own config directory, resolved from the
176
- environment by this ladder, highest first:
177
-
178
- 1. `$OWENLOOP_CONFIG_DIR` when set to a non-blank ABSOLUTE path — used verbatim,
179
- with no `owenloop` segment appended;
180
- 2. `$XDG_CONFIG_HOME/owenloop` when `XDG_CONFIG_HOME` is non-blank;
181
- 3. `$HOME/.config/owenloop`.
182
-
183
- The same directory holds `credentials.json`, `allowed_signers`, `org-root.pub`,
184
- `roster/`, and `revocations/`.
187
+ By default, the execution settings file is `$HOME/.owenloop/settings.json`.
188
+ For test or throwaway isolation, `OWENLOOP_CONFIG_DIR` may name an absolute
189
+ directory used verbatim; `XDG_CONFIG_HOME` is not consulted. In the paths below,
190
+ `<config>` means the resolved owenloop config directory. The same directory
191
+ holds `credentials.json`, `allowed_signers`, `org-root.pub`, `grants/`, and
192
+ `revocations/`.
185
193
 
186
194
  ### `shift start <crew...>`
187
195
 
188
196
  ```text
189
197
  owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
190
- [--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]
198
+ [--cap <n>] [--max-agents <n>] [--exec-reserve <n>] [--local-queue-hold <ms>] [--poll-interval <ms>] [--once]
191
199
  [--cache-dir <p>] [--state-dir <p>] [--log-dir <p>] [--log-max-age <ms>]
192
200
  [--work-root <dir>]...
193
201
  ```
@@ -205,6 +213,8 @@ one loop sweep and exits instead of keeping the foreground daemon running.
205
213
  | `--name <n>` | use this shift name; otherwise generate one from the host and current directory with a process/shift suffix |
206
214
  | `--cap <n>` | dispatch capacity; precedence is flag, then `settings.dispatchCap`, then `3` |
207
215
  | `--max-agents <n>` | concurrent agent limit; precedence is flag, then `settings.maxConcurrentAgents`, then `4` |
216
+ | `--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. |
217
+ | `--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. |
208
218
  | `--poll-interval <ms>` | loop polling interval; defaults to `5000` milliseconds |
209
219
  | `--once` | run one loop sweep and exit; without it, keep the daemon in the foreground |
210
220
  | `--cache-dir <p>` | cache root; precedence is flag, then `OWENLOOP_CACHE_DIR`, then `settings.cacheDir`, then `$XDG_CACHE_HOME/owenloop`, then `$HOME/.cache/owenloop` |
@@ -253,102 +263,109 @@ directories an order is **allowed to name**. Neither derives from the other.
253
263
  owenloop shift start build --work-root ~/code --work-root /srv/work
254
264
  ```
255
265
 
256
- **One harness per shift.** A shift has no per-order harness switch and no
257
- `--harness` flag. It never puts `--harness` on a worker's command line; each
258
- `agent-run` child resolves its own adapter, in this order:
266
+ **Crew roster selection.** A selected roster candidate decides
267
+ the harness, model, and effort for an agent order. Its precedence is:
259
268
 
260
- 1. its own `--harness` flag — which a shift never supplies;
261
- 2. `OWENLOOP_HARNESS` in the environment the child inherits, which is the
262
- shift's environment;
263
- 3. the `harness:` field on the verified step definition;
269
+ 1. the first available candidate in the first matching crew roster named in
270
+ the hub-stamped `order.crews` sequence;
271
+ 2. `owenloop work agent-run --harness` (a local debug override);
272
+ 3. the verified step's `x.harness.id`;
264
273
  4. the first registered adapter.
265
274
 
266
- Rank 2 is the operator's control. Export `OWENLOOP_HARNESS` in the shell that
267
- starts the shift and every agent order that shift dispatches runs on that
268
- adapter. To run two adapters at once, start two shifts:
269
-
270
- ```bash
271
- OWENLOOP_HARNESS=claude-code OWENLOOP_CONFIG_DIR=~/.config/owenloop-shifts/claude/owenloop owenloop shift start build --state-dir ~/.local/state/owenloop/claude
272
- ```
273
-
274
- ```bash
275
- OWENLOOP_HARNESS=codex OWENLOOP_CONFIG_DIR=~/.config/owenloop-shifts/codex/owenloop owenloop shift start build --state-dir ~/.local/state/owenloop/codex
276
- ```
277
-
278
- Both shifts may serve the SAME crew. The hub does not route by harness — it
279
- offers an order to any shift whose crew is bound to the order's capability, and
280
- whichever shift claims it first runs it on its own adapter.
281
-
282
- **A per-shift config directory is not optional when the adapters differ.** The
283
- settings file resolves from the config directory (see above), and it carries
284
- `capabilityModels` — a map of composed capability to `{model, effort}` whose
285
- model ids are strings the SHIFT'S OWN adapter accepts. Two shifts on different
286
- adapters need different model ids for the same capability, so they need
287
- different settings files, so they need different config directories. A shared
288
- config directory would give both shifts one adapter's model ids, and the shift
289
- holding the wrong adapter fails at the vendor API on its first order.
290
-
291
- **Use `OWENLOOP_CONFIG_DIR` for this, not `XDG_CONFIG_HOME`.** Both resolve the
292
- settings file, and `OWENLOOP_CONFIG_DIR` wins — but `XDG_CONFIG_HOME` is a
293
- machine-wide contract that `gh`, `git`, `gcloud`, `npm`, and most of the rest of
294
- a developer's toolchain also read, and a shift spreads its ENTIRE environment
295
- into every worker it dispatches, which passes it on to every command step's
296
- child process. Scoping a shift with `XDG_CONFIG_HOME` therefore relocates the
297
- configuration of every tool the workflow's own scripts shell out to. Measured,
298
- not theorized: on one delivery run this stranded `gh`'s stored credential, and
299
- the workflow's merge gate spent its full 40-minute wall clock deferring on a CI
300
- probe that could not authenticate, followed by four consecutive merge failures
301
- reading `could not resolve a pull request handle for the branch`. Nothing was
302
- wrong with either script. `OWENLOOP_CONFIG_DIR` scopes owenloop and only
303
- owenloop.
304
-
305
- `OWENLOOP_CONFIG_DIR` names the owenloop config directory ITSELF — the directory
306
- that directly holds `settings.json`, `credentials.json`, and `allowed_signers`.
307
- No `owenloop` path segment is appended to it, unlike the `XDG_CONFIG_HOME` rung.
308
- It must be an ABSOLUTE path: a relative one would resolve against whatever
309
- working directory a step happens to have, and `workdirFrom` gives every step its
310
- own.
311
-
312
- Give each shift its own `--state-dir` as well. The state directory holds the
313
- control socket (`shift.sock`), and a second shift starting against a socket
314
- another shift already owns is refused.
315
-
316
- **`capabilityModels` — which model serves which capability.** The hub decides
317
- WHAT grade of work an order is; it composes the step's capability with the run's
318
- depth modifier and stamps the result on the order (`builder` at the `deep`
319
- modifier becomes `builder:deep`). It never decides which model serves that
320
- grade. That decision is local, and this map is where the operator makes it:
275
+ The shift advertises its start crews through worker → hub `serve_crews` and
276
+ its derived serving set through `serve_capabilities`. The latter is the raw
277
+ key union from the roster cascade (bare names and exact compounds are both
278
+ preserved), recomputed at startup and on the roughly 15-minute roster refresh;
279
+ it is not operator-set. **Today's hub ignores `serve_capabilities`; the
280
+ hub-side intersect ships separately.** The shift passes no crews to agent
281
+ workers. For a capability-bearing order, the worker resolves rosters only from
282
+ the hub-stamped `order.crews` list, in that stamped order. If the stamp is
283
+ missing, empty, malformed, or cannot be resolved locally, the worker refuses
284
+ and releases the order rather than falling back to the shift's start crews. The
285
+ complete strongest-first cascade for each stamped crew is: machine
286
+ `~/.owenloop/crews/<crew>.json`, machine
287
+ `~/.owenloop/settings.json` `roster`, the cached hub row for that crew, then
288
+ the cached hub org-global row. Hub rows live in a separate
289
+ `~/.owenloop/hub-rosters/` cache directory — never in the D5 trust
290
+ `~/.owenloop/grants/` directory. Each capability row is atomic:
291
+ the stronger layer replaces the weaker candidate array, and candidates are
292
+ tried in listed order. A step's `x.harness.id` is a policy constraint: a row
293
+ whose candidates do not include it is released as
294
+ `incompatible-harness-policy`; no available candidate is
295
+ `unresolvable-capability`.
296
+
297
+ The shift refreshes that hub cache at startup and periodically while parked;
298
+ `owenloop roster sync` is the manual repair path. Failed refreshes never stop a
299
+ shift or refuse an order: a missing or corrupt cache becomes an explicitly
300
+ reported absent layer and the machine rows keep routing. `owenloop roster show`
301
+ is offline by design, so it prints exactly the layers an `agent-run` child can
302
+ see, including fetch age and any lower-priority rows shadowed by a winner.
321
303
 
322
304
  ```json
323
305
  {
324
- "capabilityModels": {
325
- "builder:deep": { "model": "claude-opus-5", "effort": "xhigh" },
326
- "builder": { "model": "claude-sonnet-5", "effort": "high" },
327
- "wise": { "model": "claude-fable-5", "effort": "xhigh" }
306
+ "roster": {
307
+ "builder:deep": [
308
+ { "harness": "claude-code", "model": "claude-opus-5", "effort": "xhigh" },
309
+ { "harness": "codex", "model": "gpt-5.6-sol", "effort": "xhigh" }
310
+ ],
311
+ "builder": [
312
+ { "harness": "codex", "model": "gpt-5.6-terra", "effort": "high" }
313
+ ]
328
314
  }
329
315
  }
330
316
  ```
331
317
 
332
- Lookup runs two passes over the order's capabilities: every EXACT composed key
333
- first, then every BARE name part. `builder:deep` takes the first row above;
334
- `builder:express` has no exact row and falls back to the `builder` row.
335
- `effort` must be one of `low`, `medium`, `high`, `xhigh`, `max`. The model id is
336
- never checked against a list — owenloop keeps no registry of which models exist,
337
- so a model released after your owenloop build still works.
338
-
339
- A capability with no exact row and no bare row is REFUSED, not run on a default:
340
- the worker releases the claim, reports the refusal to the hub, and exits `1`. An
341
- order carrying no capabilities at all is not refused — it runs on the adapter's
342
- own default model, which is how capability-silent steps have always run.
343
-
344
- **Migrating from `tierMap` / `tierProfiles`.** Both keys are removed. A settings
345
- file that still contains either one fails to load with an error naming
346
- `capabilityModels`; the shift does not start. This is deliberate — a shift that
347
- ignored the old keys would have no capability map at all and would refuse every
348
- order it claimed, hours later and far from the cause. Rewrite the tier rungs as
349
- capability rows: whatever `tierProfiles.strongest` pointed at becomes the
350
- `{model, effort}` of your `:deep` rows, and whatever `standard` pointed at
351
- becomes the bare rows.
318
+ The array form is required even with one candidate. There is no migration path:
319
+ the retired key is rejected at settings load. Exact composed capability lookup
320
+ runs across the order's whole capability list before bare-name lookup, so an
321
+ exact row is never shadowed by an earlier bare row.
322
+
323
+ `~/.owenloop/config.json` and `~/.owenloop/settings.json` intentionally
324
+ remain separate. The control-plane `config.json` carries `hub`, is written by
325
+ `owenloop login`, and is read by `owenloop mcp`. The execution-plane
326
+ `settings.json` carries `hubOrigin` and the machine-global crew roster, is
327
+ written by `owenloop setup`, and is read by `owenloop work`. They answer
328
+ different callers and neither reads the other.
329
+
330
+ `owenloop roster show [crew]` prints the merged roster, every candidate's
331
+ winning-layer provenance, and every layer inspected (including an absent crew
332
+ file). `owenloop doctor` adds one line for each present crew roster file,
333
+ showing its found/absent layers and registered versus missing candidate
334
+ harnesses.
335
+
336
+ Crew names are data, not filesystem paths. A fresh safe crew keeps the literal
337
+ `~/.owenloop/crews/<crew>.json` filename for rollback compatibility. Unsafe or
338
+ too-wide names use the dedicated codec-only
339
+ `~/.owenloop/crews/.owenloop-machine-roster-codec-namespace-reserved-v1-ownership/`
340
+ directory: short names use a reversible `crew-hex--<lowercase-hex>.json` basename,
341
+ while names too wide for one filesystem component use a bounded
342
+ `crew-hex-hash--…` basename. The current codec's distinct `crew-hex--` prefix
343
+ and lowercase hexadecimal payload keep it disjoint from older base64url files
344
+ and stable on case-insensitive filesystems; explicitly owned older
345
+ `crew--<base64url>.json` files remain readable during migration. Every codec
346
+ file records its exact `crew` identity in
347
+ the JSON document, so a reversible basename alone can never claim an old
348
+ legacy file. Do not derive either filename by hand. The reserved directory
349
+ itself can be the prefix of a valid 64-character nested legacy crew name, so a
350
+ file inside it is codec storage only when its JSON `crew` identity reproduces
351
+ its codec basename; a shorter unowned child remains a legacy path. A complete
352
+ codec path is nevertheless too long to be a hub-valid legacy crew name.
353
+ Existing safe legacy
354
+ `<crew>.json` files — including names containing spaces, colons, percent
355
+ signs, Unicode, and (on POSIX) backslashes — plus any lexically contained
356
+ legacy tree such as `crews/foo/bar.json` for crew `foo/bar` — remain readable
357
+ and take precedence only when their on-disk spelling exactly matches the crew,
358
+ so `Delivery` and `delivery` cannot silently share one strongest layer on a
359
+ case-insensitive filesystem. The short-lived feature-branch directory
360
+ `.owenloop-encoded-rosters/` is treated as codec storage only when a file
361
+ declares the codec basename's exact `crew`; otherwise it remains a legacy
362
+ nested path. A literal crew name that spells an owned historical codec file is
363
+ distinct from that file's declared owner and receives its own current codec
364
+ path, never an alias of the historical strongest layer.
365
+ Routing probes only its requested crew paths. Doctor combines global file
366
+ diagnostics with the verified agent's crew list, so a malformed bounded hash
367
+ file is reported rather than silently disappearing. Traversal-shaped hub crew
368
+ names stay confined to the `crews/` directory.
352
369
 
353
370
  A clean start or `--once` completion exits `0`. `owenloop shift --help` also
354
371
  exits `0`. Runtime failures such as credential reads or socket/runtime setup
@@ -371,6 +388,17 @@ version loops sharing the directory are configured with different total or
371
388
  agent caps, each loop enforces its own configured limits under the shared lock.
372
389
  Use identical cap settings for every loop sharing a state directory.
373
390
 
391
+ Reconciliation uses that same lock and re-checks record identity before it
392
+ changes anything: an abandoned reservation must still match the observed
393
+ reservation token, a dead child must still have the observed PID, and a
394
+ persisted start gate must still match both the observed PID and gate token. If
395
+ another loop re-dispatches the same run while a stale scan is waiting for the
396
+ lock, the replacement record and gate are preserved and no `abandoned` or
397
+ `reaped` event is reported. Startup reconciliation defers briefly when the
398
+ lock is busy and the poll loop retries it. A worker exit notification releases
399
+ its PID record on every terminal outcome, including a clean exit with status
400
+ `0`; reconciliation remains the crash/restart backstop.
401
+
374
402
  Canonical `*.json` child and reservation records are capacity-bearing state.
375
403
  Missing records are benign, including a record that disappears between listing
376
404
  and read. A truncated, malformed, or unreadable canonical record is not benign:
@@ -429,7 +457,7 @@ either `exec` or `agent-run`:
429
457
  - `reaped`: `{ "type": "reaped", "workflow": "...", "run": "...", "kind": "exec", "pid": 123 }`
430
458
  - `failed`: `{ "type": "failed", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "message": "..." }`
431
459
  - `bundle-miss`: `{ "type": "bundle-miss", "workflow": "...", "def": "..." }` — a legacy order named a def with no cached bundle, so it was left for hub pickup
432
- - `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`
460
+ - `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.
433
461
  - `ended`: `{ "type": "ended" }`, delivered to a parked `next` when `shift end` explicitly shuts down the daemon
434
462
 
435
463
  Every event above is also appended to `<log-dir>/shift.log` as JSON Lines, which
@@ -474,11 +502,13 @@ owenloop shift status [--state-dir <p>]
474
502
  With a daemon, status exits `0` and prints:
475
503
 
476
504
  ```json
477
- { "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "attended_at": null, "started_at": 1738000000000 }
505
+ { "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "agent_ceiling": 2, "attended_at": null, "started_at": 1738000000000 }
478
506
  ```
479
507
 
480
- `attended_at` remains `null` until the first accepted `next` request. Without a
481
- daemon, status is still a successful question: it exits `0` and prints
508
+ `agent_ceiling` is the effective maximum number of `agent-run` children after
509
+ applying `--max-agents`, `--cap`, and `--exec-reserve`; command and exec work
510
+ may still use any free slot inside `cap`. `attended_at` remains `null` until the
511
+ first accepted `next` request. Without a daemon, status is still a successful question: it exits `0` and prints
482
512
  `{ "status": "no daemon", "socket": "<path>" }`. Invalid arguments exit `2`;
483
513
  other client/runtime errors exit `1`.
484
514
 
@@ -527,6 +557,28 @@ The execution settings file is `<config>/settings.json` (see
527
557
  | `release --session <id> [options]` | drain a session's held claims |
528
558
  | `settings` | print the resolved execution settings file |
529
559
  | `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
560
+ | `util modifier-init --default <value>` | print the requested modifier from `OWENLOOP_FEEDBACK`, else `OWENLOOP_MODIFIER`, else the required default |
561
+
562
+ ### `util modifier-init`
563
+
564
+ `owenloop util modifier-init --default <value>` is a deterministic helper for
565
+ a command step that produces a bound modifier artifact. It prints one value and
566
+ does no model or harness work. Its precedence is:
567
+
568
+ 1. the newest `reject` reason carrying `requested` in `OWENLOOP_FEEDBACK`;
569
+ 2. the current order modifier in `OWENLOOP_MODIFIER`;
570
+ 3. the required `--default` value.
571
+
572
+ The helper accepts a single-word result only. It reads feedback inline from
573
+ `OWENLOOP_FEEDBACK` or from the temporary path in `OWENLOOP_FEEDBACK_FILE`,
574
+ using the same 64 KiB threshold and collision rule as consumed inputs. Exit 0
575
+ prints the value; exit 2 is a usage error; exit 3 means the feedback could not
576
+ be parsed or the resolved value was invalid.
577
+
578
+ The helper prints the selected word as ordinary stdout. A command artifact is
579
+ submitted as the full `CommandReceipt`; if a workflow binds a field inside a
580
+ command payload, the command must emit the `##owenloop:payload##` JSON marker and
581
+ the bind must name that field (for example, `from: payload.value`).
530
582
 
531
583
  ### `work agent-run` — the only Step Agent dispatcher
532
584
 
@@ -549,8 +601,7 @@ An absent `x.harness.tools` field preserves the adapter's default tool surface;
549
601
  `tools: []` is an explicit empty allow-list. The two forms are not equivalent.
550
602
  Invalid reserved fields and overlapping `tools` / `disallowedTools` are refused.
551
603
  `owenloop work lint` runs the same common and adapter checks, but runtime
552
- preflight remains authoritative because `--harness` or `OWENLOOP_HARNESS` can
553
- select a different adapter after lint. See [Agent runner and harness policy](agent-runner.md)
604
+ preflight remains authoritative because roster availability and `--harness` can select a different adapter after lint. See [Agent runner and harness policy](agent-runner.md)
554
605
  for the capability matrix and the born-bound Owenloop control-plane exception.
555
606
 
556
607
  **Harness-session durability.** `agent-run` records the provider session in the
@@ -1354,7 +1405,7 @@ owenloop login --hub https://hub.example
1354
1405
  owenloop connect --hub https://hub.example
1355
1406
  owenloop push newhire-onboarding
1356
1407
  OWENLOOP_ACCOUNT=default owenloop work prepare newhire-onboarding --origin https://hub.example
1357
- OWENLOOP_HARNESS=codex owenloop shift start openai --origin https://hub.example --as default
1408
+ owenloop shift start openai --origin https://hub.example --as default
1358
1409
  ```
1359
1410
 
1360
1411
  Starting another run does not repeat installation, publication, preparation,
@@ -1386,6 +1437,17 @@ usage errors before credential or network access. The command does not claim,
1386
1437
  dispatch, close, or otherwise drive work—the standing Shift discovers the run
1387
1438
  through its normal crew inbox.
1388
1439
 
1440
+ `--scope <label>` is forwarded as the run's `scope`: a free routing label
1441
+ recorded on the instance, with no registry and no fixed set of values. Omit it
1442
+ and the run carries no scope. `--priority <low|normal|high>` is forwarded as the
1443
+ run's `priority`; omit it and the hub applies `normal`. A value outside
1444
+ `low|normal|high` is a local usage error before any credential or network
1445
+ access, not a forwarded request. Like `--crew`/`--title`, a bare
1446
+ `--scope`/`--priority` or a `--scope=`/`--priority=` is a local usage error.
1447
+ Both are recorded at start only and are never writable afterwards. Do not
1448
+ confuse `--scope` (this routing label) with `--scopes` on `agent new`/`setup`,
1449
+ which lists an agent token's authorization scopes.
1450
+
1389
1451
  ### `cancel` — stop a running instance
1390
1452
 
1391
1453
  `owenloop cancel <workflow>` sends `POST /api/cancel_run` and prints whether the
@@ -1420,6 +1482,8 @@ Three properties come from the hub verb, not from this command:
1420
1482
  `owenloop instance show <workflow>` sends `GET /api/status/:wf` and prints the
1421
1483
  instance's state: `done`, the `debts` it still owes, the steps that are
1422
1484
  `eligible` or `blocked`, the runs `inFlight`, and `defDrift`.
1485
+ It also prints the hub's liveness verdict as `instanceStatus` and `terminal`
1486
+ when the hub provides those fields.
1423
1487
 
1424
1488
  It answers the question no other local command can: **why is this run not
1425
1489
  moving?** Two of its fields are the entire diagnosis, and both are invisible
@@ -1433,6 +1497,13 @@ from the outside because each one looks exactly like an idle shift:
1433
1497
  never offered to anyone. Present only when something is actually parked;
1434
1498
  `getStatus` omits the field otherwise, and `instance show` omits it too rather
1435
1499
  than printing `[]`, which would read as "asked, and the answer is none."
1500
+ - **`instanceStatus` and `terminal`** — the hub's liveness verdict. `terminal: true`
1501
+ means the instance will receive no further dispatch; failed and
1502
+ cancelled instances can therefore be terminal even when `done` is false.
1503
+ A terminal instance also writes an advisory to stderr, while the JSON state
1504
+ remains on stdout. These fields are omitted when an older hub does not send
1505
+ them; an explicit `terminal: false` is preserved as the hub's affirmative
1506
+ live answer.
1436
1507
 
1437
1508
  Naming, because two obvious names were already taken by different commands:
1438
1509
 
@@ -1662,7 +1733,7 @@ credential above is verified and stored, `login` makes one more best-effort
1662
1733
  write: it records the hub origin it just authenticated against in
1663
1734
  `~/.owenloop/config.json` (`{"version": 1, "hub": "<origin>"}` — never a
1664
1735
  secret, just the origin). This file is separate from both the credential store
1665
- above and from `owenloop setup`'s `~/.config/owenloop/settings.json`; its only
1736
+ above and from `owenloop setup`'s `~/.owenloop/settings.json`; its only
1666
1737
  reader is `owenloop mcp`'s [origin resolution](#choosing-the-hub-origin),
1667
1738
  which needs to know your hub without enumerating the credential store (the
1668
1739
  Keychain and external-command backends can't be listed at all — see below). A
@@ -2065,6 +2136,237 @@ needs a translation step.
2065
2136
  | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
2066
2137
  | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
2067
2138
 
2139
+ ## Routing
2140
+
2141
+ `owenloop routing` reads and edits the hub's **live routing** state — what the
2142
+ hub did when it tried to reach a crew, and the operator's standing instructions
2143
+ for what to do when it cannot. [Routing](routing.md) is the conceptual guide;
2144
+ this section is the command surface.
2145
+
2146
+ **Three different objects share the word "routing". They are not
2147
+ interchangeable:**
2148
+
2149
+ | object | what it is | where it lives | which command |
2150
+ |---|---|---|---|
2151
+ | **capability route** | a `(capability, crew)` **binding** — the row that grants a crew the right to be offered that capability's work | `capability_routes` on the hub org | [`capability bind`/`unbind`/`list`](#capability-routes) |
2152
+ | **capability reroute rule** | an ordered operator statement — "when `<capability>` has no live crew binding, offer it as `<target>` instead" | `capability_reroutes` on the hub org | `routing rule list`/`add`/`rm` |
2153
+ | **routing alert** | an immutable **event row** the hub wrote when it held, rerouted, waited or fell back | `routing_alerts` on the hub org | `routing alerts`, and `routing show` for one run |
2154
+
2155
+ **A reroute rule is not a binding.** It names no crew, grants nobody access, and
2156
+ has no live/dangling distinction. It only says which *other capability name* the
2157
+ hub may substitute — and the substitution only reaches a crew if that target
2158
+ capability has a live binding of its own. Adding a reroute rule can therefore
2159
+ never widen who may claim work by itself; the widening, if any, already exists in
2160
+ `capability_routes`.
2161
+
2162
+ **A `binding-gap` alert means the hub HELD an offer** because its compound
2163
+ capability (`<capability>:<modifier>`, e.g. `build:express`) had no live crew
2164
+ binding, and it found no usable reroute target either. Holding is the deliberate
2165
+ default — the hub no longer silently falls back to the bare capability name — so
2166
+ these alerts are the record of work that is waiting rather than work that ran on
2167
+ the wrong grade. See [Routing §9b](routing.md#9b-the-new-rule-what-is-being-built).
2168
+
2169
+ ### `routing alerts`
2170
+
2171
+ `GET /api/routing_alerts`, authenticated as your **human** credential. Lists the
2172
+ org's routing alerts. An org that has never held, rerouted, waited or fallen
2173
+ back is a normal success (exit 0) with an empty `alerts` array.
2174
+
2175
+ **The array order is the hub's answer and is never re-sorted here, and the two
2176
+ orderings are different:**
2177
+
2178
+ - **No `--workflow`** — an org-wide inbox, **newest first**. This is the "what is
2179
+ wrong right now" view.
2180
+ - **`--workflow <wf>`** — one run's alerts, **oldest first**. This is a
2181
+ chronological timeline: hold, then wait, then reroute, in the order the hub
2182
+ decided them.
2183
+
2184
+ Passing `--workflow` is what flips the ordering, so a script that pages through
2185
+ both must not assume one direction. The value is echoed back on stdout as
2186
+ `workflow` precisely so a reader can tell the two views apart without
2187
+ re-inspecting argv.
2188
+
2189
+ `--limit <n>` caps how many rows the hub returns. Omit it and the hub applies
2190
+ its own default page size. The hub **silently ignores** a limit it cannot use (a
2191
+ non-integer, zero, or a negative) and answers with its default instead — so the
2192
+ CLI rejects a `--limit` that is not a number **before** any request, rather than
2193
+ reporting a page size you never asked for.
2194
+
2195
+ A row's `modifier`, `step` and `detail` are legitimately `null` — an org-level
2196
+ event carrying no step or no modifier is a real state, not a defect — and they
2197
+ are printed as `null` rather than dropped. `detail` is an opaque per-kind
2198
+ metadata string the CLI forwards verbatim and never parses.
2199
+
2200
+ ### `routing show <workflow>`
2201
+
2202
+ `GET /api/run_routing/<workflow>`, authenticated as your **human** credential.
2203
+ Prints the complete routing picture for ONE hub run: its modifier, its wait
2204
+ policy, its own alerts, its resolution reports (which rule matched for each step)
2205
+ and its escalations.
2206
+
2207
+ **This is not the local `show` command.** `owenloop show <wf>` dumps the raw
2208
+ artifacts of a **local** instance out of the local sqlite database and never
2209
+ touches a hub. `owenloop routing show <workflow>` takes a **hub** workflow id and
2210
+ reads hub state. They share four letters and nothing else.
2211
+
2212
+ `modifier` is **omitted entirely** for a run started without one. The key's
2213
+ absence is how stdout says "no modifier" — an empty string is never printed,
2214
+ because a modifier named nothing is not a state the hub can hold.
2215
+
2216
+ **An unknown or foreign workflow id gets a generic error today.** The hub's verb
2217
+ raises an untyped error for a run this org does not own or that does not exist,
2218
+ and its edge maps that to `HTTP 500` with the message `internal server error`.
2219
+ The CLI prints whatever message the hub sends, so a future typed `404` will
2220
+ surface as a useful sentence with no change here — but do not read today's
2221
+ `internal server error` as a hub defect; it is what "no such run for you" looks
2222
+ like on this endpoint right now.
2223
+
2224
+ `resolutionReports` and `escalations` belong to adjacent subsystems. Their rows
2225
+ are checked to be objects and then forwarded **verbatim**, so a field added on
2226
+ the hub widens what this command prints instead of breaking it.
2227
+
2228
+ ### `routing rule list`
2229
+
2230
+ `GET /api/capability_reroutes`, authenticated as your **human** credential. Lists
2231
+ the org's reroute rules. An org with no rules is a normal success (exit 0) with
2232
+ an empty `reroutes` array.
2233
+
2234
+ **The array order is semantic: it is the order the hub TRIES the substitutions
2235
+ in**, and it is never re-sorted here. Rows are grouped by source `capability` and
2236
+ ascending `position` within each group, so the first row for a capability is the
2237
+ first target the hub attempts. Re-sorting this list client-side — even
2238
+ alphabetically, even "for readability" — would misreport which substitution
2239
+ actually happens.
2240
+
2241
+ ### `routing rule add <capability> <target>`
2242
+
2243
+ `POST /api/add_capability_reroute`, authenticated as your **human** credential;
2244
+ requires the **admin** role on the hub. Adds one ordered rule: when
2245
+ `<capability>` has no live crew binding, the hub may offer the work as
2246
+ `<target>` instead.
2247
+
2248
+ The CLI performs no client-side validation of either argument — the hub is the
2249
+ enforcement of record. It rejects a rule whose `capability` and `target` are
2250
+ equal (`400 capability_reroute_invalid`), and the CLI surfaces that message
2251
+ verbatim.
2252
+
2253
+ **`--position <n>` sets the rule's rank among the rules for that same
2254
+ `<capability>`,** counting from `0` — lower is tried first. **Omitting
2255
+ `--position` APPENDS** the rule after the source capability's existing rules. The
2256
+ flag is omitted from the request body entirely when you do not pass it; sending
2257
+ `0` would mean "try this first", which is a different instruction.
2258
+
2259
+ **Adding is idempotent per `(capability, target)` pair.** Re-adding a pair that
2260
+ already exists is a normal success — the hub answers `200` with `alreadyPresent:
2261
+ true` and changes nothing (the original row keeps its position and timestamp).
2262
+ `ruleCount` reports how many rules the source capability has after the write.
2263
+
2264
+ Chains are resolved **by the hub**, not by this CLI and not by the engine: if
2265
+ `a → b` and `b → c` both exist, the hub walks the chain and hands the engine one
2266
+ final substitution.
2267
+
2268
+ ### `routing rule rm <capability> <target>`
2269
+
2270
+ `POST /api/remove_capability_reroute`, authenticated as your **human**
2271
+ credential; requires the **admin** role on the hub. Removes the ONE
2272
+ `(capability, target)` rule you name. `<target>` is **required**: a capability
2273
+ may have several reroute rules, so a capability-only removal would delete more
2274
+ than you asked for.
2275
+
2276
+ **`rm` is idempotent, and unlike `add` it cannot fail on a bad pair.** Removing a
2277
+ rule that is not there is a normal success — the hub answers `200` with
2278
+ `removed: false` rather than a `404` — and the CLI prints a full document plus a
2279
+ stderr line saying nothing was removed. A script can call `routing rule rm`
2280
+ unconditionally without first checking whether the rule exists.
2281
+
2282
+ **Removing the last rule for a capability makes it HOLD again.** `remainingTargets:
2283
+ []` on stdout is that signal, and stderr says so in words: with no rule left, an
2284
+ offer for that capability with no live crew binding waits instead of
2285
+ substituting. Nothing is lost — the held work resumes as soon as a crew binds
2286
+ the capability or a rule is added back.
2287
+
2288
+ ### Flags, hub resolution, output and exits
2289
+
2290
+ **Flags.** `--hub <url>` on every subcommand; `--workflow <wf>` and `--limit <n>`
2291
+ on `routing alerts`; `--position <n>` on `routing rule add` (plus the global
2292
+ `--db`/`--defs`). The allowlist is per top-level command, so `--position` on
2293
+ `routing alerts` is accepted and ignored rather than rejected — the same
2294
+ looseness `crew list` has with `--kind`.
2295
+
2296
+ **Which hub gets acted on (`--hub`).** Resolution is the same narrow ladder
2297
+ `capability bind` uses, and for the same reason — a reroute rule written against
2298
+ the wrong org moves in-flight work and is not undone by a retry:
2299
+
2300
+ 1. `--hub <origin>` if given (normalized the same way as everywhere else).
2301
+ 2. Otherwise the **one** hub your credential *file* stores — if exactly one is
2302
+ present, it's used.
2303
+ 3. Otherwise the command **exits 2** naming both remedies (pass `--hub`, or log
2304
+ in to exactly one hub); when more than one hub is stored their origins are
2305
+ listed back so you can pick.
2306
+
2307
+ This does **not** fall back to `OWENLOOP_HUB` or the built-in default hub, and
2308
+ hub enumeration is **file-store only**: the keychain and the external-command
2309
+ backend cannot list their entries, so on such a machine step 2 cannot enumerate
2310
+ the store and you must pass `--hub`.
2311
+
2312
+ **Printed JSON.** stdout is exactly one whitelisted JSON document per
2313
+ invocation, built from named fields — never a raw hub body — so `| jq` always
2314
+ works. Human progress lines (the two `routing rule rm` warnings) go to stderr
2315
+ only.
2316
+
2317
+ | subcommand | stdout |
2318
+ |---|---|
2319
+ | `routing alerts` | `{ "ok": true, "hub": "<origin>", "workflow": "wf_1", "alerts": [ { "id": "ral_1", "at": 1738000000000, "workflow": "wf_1", "kind": "binding-gap", "capability": "build:express", "modifier": "express", "step": "builder", "detail": null } ] }` |
2320
+ | `routing show` | `{ "ok": true, "hub": "<origin>", "workflow": "wf_1", "defName": "delivery", "modifier": "express", "waitPolicy": { "wait": "forever" }, "alerts": [ … ], "resolutionReports": [ … ], "escalations": [ … ] }` |
2321
+ | `routing rule list` | `{ "ok": true, "hub": "<origin>", "reroutes": [ { "capability": "build:express", "target": "build:standard", "position": 0, "createdAt": 1738000000000 } ] }` |
2322
+ | `routing rule add` | `{ "ok": true, "hub": "<origin>", "capability": "build:express", "target": "build:standard", "position": 0, "alreadyPresent": false, "ruleCount": 2 }` |
2323
+ | `routing rule rm` | `{ "ok": true, "hub": "<origin>", "capability": "build:express", "target": "build:standard", "removed": true, "remainingTargets": ["build"] }` |
2324
+
2325
+ Every field carries the **hub's own name**, verbatim — the same words its audit
2326
+ log and the web console use — so correlating stdout against them never needs a
2327
+ translation step.
2328
+
2329
+ - `workflow` (`routing alerts`) — present **only** when you passed `--workflow`,
2330
+ so its presence alone means the list is scoped and oldest-first. An empty
2331
+ `--workflow ''` is rejected as a usage error rather than sent, because the hub
2332
+ treats an empty value as absent and would answer org-wide under a stdout
2333
+ claiming a filter.
2334
+ - `kind` (`routing alerts`, `routing show`) — the hub's own event name
2335
+ (`binding-gap`, `reroute`, and others). It is forwarded verbatim and
2336
+ deliberately **not** narrowed to a fixed set, so a kind the hub adds later
2337
+ prints rather than breaks the command.
2338
+ - `modifier` (`routing show`) — **absent**, not `null`, for a run started without
2339
+ a modifier. On an alert row the same field IS `null`-able, because an alert
2340
+ that concerns no modified capability is a real event.
2341
+ - `waitPolicy` (`routing show`) — `{ "wait": "forever" }`, or
2342
+ `{ "wait": "<duration>", "then": "fallback" }` for a timed policy. `then` is
2343
+ absent on the forever form.
2344
+ - `position` (`routing rule list`, `routing rule add`) — the rule's rank among
2345
+ the rules for the same source capability, from `0`; lower is tried first. On
2346
+ `routing rule add` it is the rank the **hub** stored, which is routinely one
2347
+ you never typed, because omitting `--position` appends.
2348
+ - `alreadyPresent` (`routing rule add`) — was this exact `(capability, target)`
2349
+ pair already a rule before the call? `false` means the call created it.
2350
+ - `ruleCount` (`routing rule add`) — how many reroute rules the source capability
2351
+ has after the write.
2352
+ - `removed` (`routing rule rm`) — did this call actually remove a rule? `false`
2353
+ is the tolerant "it was never there" case, not an error.
2354
+ - `remainingTargets` (`routing rule rm`) — the targets the capability can still
2355
+ be substituted with. `[]` means the capability now **HOLDS** whenever it has no
2356
+ live crew binding: `jq '.remainingTargets | length == 0'`.
2357
+ - `capability` and `target` are the values the **hub** echoed back, not your
2358
+ argv: if the hub normalized either, stdout tells the truth about what was
2359
+ stored.
2360
+
2361
+ **Exit codes.**
2362
+
2363
+ | code | meaning |
2364
+ |---|---|
2365
+ | `0` | the alerts, run routing or rules were listed; the rule was added (or was already present); the rule was removed (or was already absent) |
2366
+ | `1` | usage error (an unknown subcommand, a missing `<workflow>`/`<capability>`/`<target>`, a non-numeric `--limit`, an empty `--workflow`) or a runtime or hub error — a self-referential rule, a `403` for a non-admin, an unknown workflow (see `routing show` above), a malformed response, or a network timeout |
2367
+ | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
2368
+ | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
2369
+
2068
2370
  ## Crews
2069
2371
 
2070
2372
  A **crew** is an org-scoped queue that agent work is stamped to. Every hub org
@@ -2208,7 +2510,7 @@ lines (the tolerant-false notices, the transfer summary) go to stderr only.
2208
2510
 
2209
2511
  ## `setup` — onboard a machine
2210
2512
 
2211
- `owenloop setup` is the one-shot onboarding command. It runs seven ordered steps.
2513
+ `owenloop setup` is the one-shot onboarding command. It runs eight ordered steps.
2212
2514
  Depending on the machine state, setup may store the human credential, mint or
2213
2515
  rekey and store a Scoped Identity credential, ensure the three principal
2214
2516
  signing keys, relay a signed machine enrollment grant, and write only
@@ -2235,7 +2537,15 @@ plugin version already installed performs no plugin writes. The steps:
2235
2537
  5. **execution settings** — write only `hubOrigin` into the execution settings
2236
2538
  file so the local Step Agent talks to this hub, preserving every other key
2237
2539
  (skipped when `hubOrigin` already matches).
2238
- 6. **plugin** — probe and converge the bundled `owenloop` plugin separately
2540
+ 6. **crew rosters** — for every crew known to the verified or newly minted
2541
+ Scoped Identity, materialize a local strongest-layer skeleton at its resolved
2542
+ `crews/<crew>.json` path. Each new file contains a descriptive `note`, its
2543
+ exact `crew` identity when needed by the bounded filename codec, and
2544
+ `"roster": {}`, so the machine initially inherits the weaker settings and
2545
+ hub layers. Setup never overwrites an existing acceptable crew-roster file:
2546
+ it reports that file as skipped and leaves its bytes untouched. If setup does
2547
+ not know any crews for the identity, it records a non-fatal noted result.
2548
+ 7. **plugin** — probe and converge the bundled `owenloop` plugin separately
2239
2549
  for Claude Code and Codex. When the installed plugin is missing or its
2240
2550
  version differs from the CLI package, setup adds the bundled marketplace
2241
2551
  when needed and installs or updates the plugin. Claude Code uses
@@ -2246,10 +2556,10 @@ plugin version already installed performs no plugin writes. The steps:
2246
2556
  **Non-fatal:** a missing harness or failed convergence is reported as
2247
2557
  `noted` and never fails setup. If the bundled marketplace root is
2248
2558
  unavailable, setup prints manual commands instead.
2249
- 7. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
2559
+ 8. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
2250
2560
  the same surfaces, whose result becomes setup's exit code.
2251
2561
 
2252
- Progress lines (the `[n/7]` headers and `✓`/`✗` marks) go to **stderr**; the
2562
+ Progress lines (the `[n/8]` headers and `✓`/`✗` marks) go to **stderr**; the
2253
2563
  final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
2254
2564
  **stdout**.
2255
2565
 
@@ -2539,7 +2849,7 @@ or set, not from inference.
2539
2849
 
2540
2850
  ### Tools
2541
2851
 
2542
- The server exposes 17 baseline tools mirroring the hub's own MCP toolset, plus
2852
+ The server exposes 20 baseline tools mirroring the hub's own MCP toolset, plus
2543
2853
  `create_agent`, plus four [crew](#crews) tools (`list_crews`, `create_crew`,
2544
2854
  `add_crew_member`, `remove_crew_member`) that do not mirror the hub's own MCP
2545
2855
  toolset. Each baseline tool's result is the hub REST response as one text
@@ -2547,11 +2857,12 @@ block; a non-2xx response comes back as an error result.
2547
2857
 
2548
2858
  | tool | what it does |
2549
2859
  |---|---|
2550
- | `whats_next` | tick a workflow and get the next work order(s), or the inbox of started instances |
2860
+ | `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 |
2551
2861
  | `submit` | submit a work order output |
2552
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` |
2553
2864
  | `provide_input` | answer a human gate — provide a value for a seeded/owed input |
2554
- | `start_run` | create a new instance from a definition name |
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`) |
2555
2866
  | `create_workflow` | parse + load a workflow def YAML (the authoring hard gate) |
2556
2867
  | `get_workflow` | fetch one loaded definition |
2557
2868
  | `list_workflows` | names, titles, step counts, and def hash/version of every loaded def |
@@ -2561,8 +2872,10 @@ block; a non-2xx response comes back as an error result.
2561
2872
  | `release` | give back a claim so its order is re-offered without waiting out the reap TTL |
2562
2873
  | `publish_event` | publish an event against a contract, starting one run per matched subscription |
2563
2874
  | `list_subscriptions` | the org's contract subscriptions |
2564
- | `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 |
2875
+ | `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 |
2565
2876
  | `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 |
2877
+ | `get_rosters` | read the org-global and per-crew capability rosters available to this principal |
2878
+ | `list_harness_models` | read the org's registered harnesses, models, and supported efforts |
2566
2879
  | `wake` | cheap "has anything changed since cursor X" pre-check for a polling loop |
2567
2880
  | `create_agent` | create a NEW Scoped Identity and store its credential locally — **never returns the token** |
2568
2881
  | `list_crews` | list the org's crews, each with its member rows inline — a plain passthrough, no filtering |
@@ -2580,6 +2893,19 @@ message is surfaced verbatim; error bodies never carry tokens). If the store
2580
2893
  write fails, the result says so and tells you to revoke/re-key the agent from
2581
2894
  the console.
2582
2895
 
2896
+ `start_run`'s `scope` has one default the CLI does not have: when the caller
2897
+ supplies no `scope`, the server fills in the session's repository name, taken
2898
+ from the `origin` remote's URL (its last path segment, trailing `.git`
2899
+ removed) — `owenloop` for
2900
+ `https://github.com/typicalday/owenloop.git`. It is read from the remote rather
2901
+ than the directory name so that every worktree of one repo reports the same
2902
+ scope. It is a default, never an override: an explicitly supplied `scope` is
2903
+ always forwarded unchanged. When no repository name can be determined — not a
2904
+ git checkout, no `origin` remote, an unparseable URL — the server sends no
2905
+ `scope` at all rather than guessing a label. Two repositories with the same
2906
+ name under different owners therefore share a scope; pass an explicit `scope`
2907
+ to tell them apart.
2908
+
2583
2909
  **The four crew tools** (`list_crews`, `create_crew`, `add_crew_member`,
2584
2910
  `remove_crew_member`) cover the same four operations as the [`crew` CLI
2585
2911
  family](#crews) — `crew list`, `crew new`, `crew member add`, `crew member
@@ -2649,7 +2975,8 @@ interactively.
2649
2975
 
2650
2976
  The [`examples/workflows`](../examples/workflows) folder has a workflow per
2651
2977
  idea: [`delivery`](../examples/workflows/delivery.yaml) (a review knock-back
2652
- loop), [`ship`](../examples/workflows/ship.yaml) (delivery grown up: the full
2978
+ loop — a teaching example, not the production line),
2979
+ [`ship`](../examples/workflows/ship.yaml) (delivery grown up: the full
2653
2980
  production line with provisioned workspaces, an adversarial reviewer, a doc
2654
2981
  pass, and teardown owned as a step),
2655
2982
  [`research`](../examples/workflows/research.yaml) (collections),
@@ -2683,7 +3010,7 @@ wf=$(owenloop create delivery \
2683
3010
  run=$(owenloop tick $wf | jq -r '.orders[0].run') # claim the planner job
2684
3011
  owenloop green $wf $run plan --value '{"plan":"…"}' # report its output
2685
3012
 
2686
- owenloop status $wf # owed / eligible / blocked / done
3013
+ owenloop status $wf # done / debts / eligible / blocked / pending / inFlight
2687
3014
  ```
2688
3015
 
2689
3016
  **A knock-back.** When the reviewer's job comes up, instead of greening its
@@ -2696,7 +3023,9 @@ owenloop reject $wf pr --by reviewer --text "tests are missing"
2696
3023
  That re-arms `builder` with the reason attached to its next job. Do it past
2697
3024
  `builder`'s `maxAttempts` and `pr` **stalls** — owenloop stops re-arming it
2698
3025
  and waits for a human. `owenloop retry $wf pr --text "use the new fixture"`
2699
- clears the stall and resets the counter.
3026
+ clears the stall and resets the counter. `retry --text` is also the answer
3027
+ path for a step that escalated with `ask`; pass `--hub <url>` to answer an
3028
+ ask on a hub-hosted run.
2700
3029
 
2701
3030
  ## `reap`, `runs`, and `status.inFlight` — observing and clearing in-flight work
2702
3031
 
@@ -2749,6 +3078,12 @@ refuses it. The result JSON is always written to stdout; the human-readable
2749
3078
  reason goes to stderr. A successful call exits 0 — a Step Agent should treat a
2750
3079
  non-zero exit as a failure, not a success.
2751
3080
 
3081
+ For a bound modifier artifact, local `reject` also accepts
3082
+ `--requested <modifier>`. The engine checks that the requested value is one of
3083
+ the workflow's declared modifiers and carries it in the artifact's next reason
3084
+ thread, where a deterministic producer such as `util modifier-init` can read it.
3085
+ The flag is only valid for an artifact bound to `modifier`.
3086
+
2752
3087
  ## What a job looks like
2753
3088
 
2754
3089
  `tick` returns `{ workflow, orders, reaped }`. Each order is a **reference
@@ -2769,6 +3104,7 @@ them.
2769
3104
  "inputs": ["plan"],
2770
3105
  "outputs": ["pr"],
2771
3106
  "worker": "command", // the authored step's executor:, mapped verbatim (absent = 'agent')
3107
+ "modifier": "standard", // modifier used for this offer; absent when unmodified
2772
3108
  "consumes": { "plan": { /* the accepted input value */ } },
2773
3109
  "owes": [ // the feedback channel
2774
3110
  { "path": "pr", "judgmentRejects": 2, "schemaRejects": 0,
@@ -2782,7 +3118,7 @@ A worker first **resolves the reference**: the `(defDigest, step, key)`
2782
3118
  boundary maps the order to the exact authored instructions from the worker's
2783
3119
  trusted local definition source — the same resolver the embedded engine and
2784
3120
  the CLI use. Resolution returns the authored `prompt` (with
2785
- `${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}`
3121
+ `${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MODIFIER}`/`${MAX_ATTEMPTS}`
2786
3122
  materialized), the authored `command` if the step has one, and nothing
2787
3123
  fabricated. If the worker's source does not know the digest — the definition
2788
3124
  was never delivered, or the current on-disk definition no longer matches the