owenloop 0.5.8 → 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 (87) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +4 -2
  3. package/dist/packages/work/src/agent/loop.d.ts +23 -8
  4. package/dist/packages/work/src/agent/loop.js +48 -6
  5. package/dist/packages/work/src/consumed-verifier.js +6 -17
  6. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  7. package/dist/packages/work/src/exec/loop.js +181 -32
  8. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  9. package/dist/packages/work/src/exec/receipt.js +6 -6
  10. package/dist/packages/work/src/harness/claude.js +100 -0
  11. package/dist/packages/work/src/hub/client.d.ts +19 -4
  12. package/dist/packages/work/src/hub/client.js +7 -3
  13. package/dist/packages/work/src/hub/types.d.ts +84 -0
  14. package/dist/packages/work/src/main.js +1 -0
  15. package/dist/packages/work/src/roles/agent-run.js +19 -22
  16. package/dist/packages/work/src/roles/exec.js +2 -0
  17. package/dist/packages/work/src/roles/settings.js +2 -0
  18. package/dist/packages/work/src/roles/shift.js +14 -2
  19. package/dist/packages/work/src/roles/util.d.ts +1 -0
  20. package/dist/packages/work/src/roles/util.js +10 -0
  21. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  22. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  23. package/dist/packages/work/src/settings/roster.d.ts +84 -0
  24. package/dist/packages/work/src/settings/roster.js +364 -5
  25. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  26. package/dist/packages/work/src/settings/serving.js +79 -0
  27. package/dist/packages/work/src/settings/settings.d.ts +14 -1
  28. package/dist/packages/work/src/settings/settings.js +14 -0
  29. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  30. package/dist/packages/work/src/shift/loop.js +299 -51
  31. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  32. package/dist/packages/work/src/shift/runtime.d.ts +15 -0
  33. package/dist/packages/work/src/shift/runtime.js +94 -4
  34. package/dist/packages/work/src/shift/server.js +2 -0
  35. package/dist/packages/work/src/shift/spawn.d.ts +17 -2
  36. package/dist/packages/work/src/shift/spawn.js +16 -13
  37. package/dist/packages/work/src/shift/state.d.ts +29 -2
  38. package/dist/packages/work/src/shift/state.js +45 -15
  39. package/dist/packages/work/src/usage.d.ts +1 -1
  40. package/dist/packages/work/src/usage.js +7 -1
  41. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  42. package/dist/packages/work/src/util/modifier-init.js +73 -0
  43. package/dist/src/bundle/tar.d.ts +9 -4
  44. package/dist/src/bundle/tar.js +9 -4
  45. package/dist/src/capabilities.d.ts +6 -0
  46. package/dist/src/cli.d.ts +14 -1
  47. package/dist/src/cli.js +687 -75
  48. package/dist/src/config-dir.d.ts +1 -1
  49. package/dist/src/config-dir.js +1 -1
  50. package/dist/src/crypto/index.d.ts +1 -1
  51. package/dist/src/crypto/index.js +1 -1
  52. package/dist/src/crypto/org-root.d.ts +30 -12
  53. package/dist/src/crypto/org-root.js +162 -14
  54. package/dist/src/crypto/records.d.ts +2 -0
  55. package/dist/src/crypto/records.js +2 -0
  56. package/dist/src/defs.d.ts +6 -1
  57. package/dist/src/defs.js +203 -8
  58. package/dist/src/engine.d.ts +42 -7
  59. package/dist/src/engine.js +158 -16
  60. package/dist/src/index.d.ts +4 -4
  61. package/dist/src/index.js +2 -2
  62. package/dist/src/mcp/serve.d.ts +22 -0
  63. package/dist/src/mcp/serve.js +88 -8
  64. package/dist/src/model.d.ts +2 -0
  65. package/dist/src/model.js +32 -25
  66. package/dist/src/order-resolver.d.ts +1 -0
  67. package/dist/src/order-resolver.js +8 -1
  68. package/dist/src/schemas/index.d.ts +11 -0
  69. package/dist/src/schemas/order.v1.schema.json +7 -1
  70. package/dist/src/store.d.ts +5 -0
  71. package/dist/src/store.js +43 -8
  72. package/dist/src/types.d.ts +40 -3
  73. package/docs/authoring.md +90 -2
  74. package/docs/bundles.md +26 -2
  75. package/docs/cli.md +170 -28
  76. package/docs/crypto.md +19 -3
  77. package/docs/design.md +70 -1
  78. package/docs/routing.md +189 -34
  79. package/docs/shift-logs.md +20 -9
  80. package/docs/wire-contracts.md +50 -7
  81. package/examples/workflows/delivery.yaml +31 -14
  82. package/examples/workflows/ship.yaml +10 -2
  83. package/package.json +1 -1
  84. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  85. package/plugins/claude-code/plugin/.mcp.json +1 -1
  86. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  87. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
package/docs/cli.md CHANGED
@@ -53,7 +53,7 @@ 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) |
@@ -73,10 +73,17 @@ for the full breakdown.
73
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) |
74
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) |
75
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 merged **crew roster** and the provenance of every selected candidate layer |
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 |
77
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) |
78
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) |
79
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 |
80
87
  | `trust init\|grant\|revoke` | create and sign local enrollment trust records offline — see [`trust`](#trust--local-enrollment-trust) |
81
88
  | `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
82
89
  | `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
@@ -93,7 +100,7 @@ for the full breakdown.
93
100
  | `reject <wf> <path> --by <author> --text <msg>` | reject an output (re-arms its producer) |
94
101
  | `retract <wf> <path> --by <author> --text <msg>` | drop a collection member |
95
102
  | `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 |
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 |
97
104
  | `close <wf> <run> [--outcome ok\|no_work\|failed\|skipped] [--summary s]` | release a claimed job |
98
105
  | `delete <wf>` | delete an instance and all its rows |
99
106
  | `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
@@ -181,14 +188,14 @@ By default, the execution settings file is `$HOME/.owenloop/settings.json`.
181
188
  For test or throwaway isolation, `OWENLOOP_CONFIG_DIR` may name an absolute
182
189
  directory used verbatim; `XDG_CONFIG_HOME` is not consulted. In the paths below,
183
190
  `<config>` means the resolved owenloop config directory. The same directory
184
- holds `credentials.json`, `allowed_signers`, `org-root.pub`, `roster/`, and
191
+ holds `credentials.json`, `allowed_signers`, `org-root.pub`, `grants/`, and
185
192
  `revocations/`.
186
193
 
187
194
  ### `shift start <crew...>`
188
195
 
189
196
  ```text
190
197
  owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
191
- [--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]
192
199
  [--cache-dir <p>] [--state-dir <p>] [--log-dir <p>] [--log-max-age <ms>]
193
200
  [--work-root <dir>]...
194
201
  ```
@@ -206,6 +213,8 @@ one loop sweep and exits instead of keeping the foreground daemon running.
206
213
  | `--name <n>` | use this shift name; otherwise generate one from the host and current directory with a process/shift suffix |
207
214
  | `--cap <n>` | dispatch capacity; precedence is flag, then `settings.dispatchCap`, then `3` |
208
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. |
209
218
  | `--poll-interval <ms>` | loop polling interval; defaults to `5000` milliseconds |
210
219
  | `--once` | run one loop sweep and exit; without it, keep the daemon in the foreground |
211
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` |
@@ -254,25 +263,44 @@ directories an order is **allowed to name**. Neither derives from the other.
254
263
  owenloop shift start build --work-root ~/code --work-root /srv/work
255
264
  ```
256
265
 
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
266
+ **Crew roster selection.** A selected roster candidate decides
260
267
  the harness, model, and effort for an agent order. Its precedence is:
261
268
 
262
- 1. the first available candidate in the first matching crew roster;
269
+ 1. the first available candidate in the first matching crew roster named in
270
+ the hub-stamped `order.crews` sequence;
263
271
  2. `owenloop work agent-run --harness` (a local debug override);
264
272
  3. the verified step's `x.harness.id`;
265
273
  4. the first registered adapter.
266
274
 
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:
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:
270
291
  the stronger layer replaces the weaker candidate array, and candidates are
271
292
  tried in listed order. A step's `x.harness.id` is a policy constraint: a row
272
293
  whose candidates do not include it is released as
273
294
  `incompatible-harness-policy`; no available candidate is
274
295
  `unresolvable-capability`.
275
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.
303
+
276
304
  ```json
277
305
  {
278
306
  "roster": {
@@ -305,6 +333,40 @@ file). `owenloop doctor` adds one line for each present crew roster file,
305
333
  showing its found/absent layers and registered versus missing candidate
306
334
  harnesses.
307
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.
369
+
308
370
  A clean start or `--once` completion exits `0`. `owenloop shift --help` also
309
371
  exits `0`. Runtime failures such as credential reads or socket/runtime setup
310
372
  exit `1`. Usage and
@@ -326,6 +388,17 @@ version loops sharing the directory are configured with different total or
326
388
  agent caps, each loop enforces its own configured limits under the shared lock.
327
389
  Use identical cap settings for every loop sharing a state directory.
328
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
+
329
402
  Canonical `*.json` child and reservation records are capacity-bearing state.
330
403
  Missing records are benign, including a record that disappears between listing
331
404
  and read. A truncated, malformed, or unreadable canonical record is not benign:
@@ -384,7 +457,7 @@ either `exec` or `agent-run`:
384
457
  - `reaped`: `{ "type": "reaped", "workflow": "...", "run": "...", "kind": "exec", "pid": 123 }`
385
458
  - `failed`: `{ "type": "failed", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "message": "..." }`
386
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
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`
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.
388
461
  - `ended`: `{ "type": "ended" }`, delivered to a parked `next` when `shift end` explicitly shuts down the daemon
389
462
 
390
463
  Every event above is also appended to `<log-dir>/shift.log` as JSON Lines, which
@@ -429,11 +502,13 @@ owenloop shift status [--state-dir <p>]
429
502
  With a daemon, status exits `0` and prints:
430
503
 
431
504
  ```json
432
- { "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 }
433
506
  ```
434
507
 
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
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
437
512
  `{ "status": "no daemon", "socket": "<path>" }`. Invalid arguments exit `2`;
438
513
  other client/runtime errors exit `1`.
439
514
 
@@ -482,6 +557,28 @@ The execution settings file is `<config>/settings.json` (see
482
557
  | `release --session <id> [options]` | drain a session's held claims |
483
558
  | `settings` | print the resolved execution settings file |
484
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`).
485
582
 
486
583
  ### `work agent-run` — the only Step Agent dispatcher
487
584
 
@@ -1340,6 +1437,17 @@ usage errors before credential or network access. The command does not claim,
1340
1437
  dispatch, close, or otherwise drive work—the standing Shift discovers the run
1341
1438
  through its normal crew inbox.
1342
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
+
1343
1451
  ### `cancel` — stop a running instance
1344
1452
 
1345
1453
  `owenloop cancel <workflow>` sends `POST /api/cancel_run` and prints whether the
@@ -2402,7 +2510,7 @@ lines (the tolerant-false notices, the transfer summary) go to stderr only.
2402
2510
 
2403
2511
  ## `setup` — onboard a machine
2404
2512
 
2405
- `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.
2406
2514
  Depending on the machine state, setup may store the human credential, mint or
2407
2515
  rekey and store a Scoped Identity credential, ensure the three principal
2408
2516
  signing keys, relay a signed machine enrollment grant, and write only
@@ -2429,7 +2537,15 @@ plugin version already installed performs no plugin writes. The steps:
2429
2537
  5. **execution settings** — write only `hubOrigin` into the execution settings
2430
2538
  file so the local Step Agent talks to this hub, preserving every other key
2431
2539
  (skipped when `hubOrigin` already matches).
2432
- 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
2433
2549
  for Claude Code and Codex. When the installed plugin is missing or its
2434
2550
  version differs from the CLI package, setup adds the bundled marketplace
2435
2551
  when needed and installs or updates the plugin. Claude Code uses
@@ -2440,10 +2556,10 @@ plugin version already installed performs no plugin writes. The steps:
2440
2556
  **Non-fatal:** a missing harness or failed convergence is reported as
2441
2557
  `noted` and never fails setup. If the bundled marketplace root is
2442
2558
  unavailable, setup prints manual commands instead.
2443
- 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
2444
2560
  the same surfaces, whose result becomes setup's exit code.
2445
2561
 
2446
- 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
2447
2563
  final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
2448
2564
  **stdout**.
2449
2565
 
@@ -2733,7 +2849,7 @@ or set, not from inference.
2733
2849
 
2734
2850
  ### Tools
2735
2851
 
2736
- 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
2737
2853
  `create_agent`, plus four [crew](#crews) tools (`list_crews`, `create_crew`,
2738
2854
  `add_crew_member`, `remove_crew_member`) that do not mirror the hub's own MCP
2739
2855
  toolset. Each baseline tool's result is the hub REST response as one text
@@ -2741,11 +2857,12 @@ block; a non-2xx response comes back as an error result.
2741
2857
 
2742
2858
  | tool | what it does |
2743
2859
  |---|---|
2744
- | `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 |
2745
2861
  | `submit` | submit a work order output |
2746
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` |
2747
2864
  | `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 |
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`) |
2749
2866
  | `create_workflow` | parse + load a workflow def YAML (the authoring hard gate) |
2750
2867
  | `get_workflow` | fetch one loaded definition |
2751
2868
  | `list_workflows` | names, titles, step counts, and def hash/version of every loaded def |
@@ -2755,8 +2872,10 @@ block; a non-2xx response comes back as an error result.
2755
2872
  | `release` | give back a claim so its order is re-offered without waiting out the reap TTL |
2756
2873
  | `publish_event` | publish an event against a contract, starting one run per matched subscription |
2757
2874
  | `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 |
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 |
2759
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 |
2760
2879
  | `wake` | cheap "has anything changed since cursor X" pre-check for a polling loop |
2761
2880
  | `create_agent` | create a NEW Scoped Identity and store its credential locally — **never returns the token** |
2762
2881
  | `list_crews` | list the org's crews, each with its member rows inline — a plain passthrough, no filtering |
@@ -2774,6 +2893,19 @@ message is surfaced verbatim; error bodies never carry tokens). If the store
2774
2893
  write fails, the result says so and tells you to revoke/re-key the agent from
2775
2894
  the console.
2776
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
+
2777
2909
  **The four crew tools** (`list_crews`, `create_crew`, `add_crew_member`,
2778
2910
  `remove_crew_member`) cover the same four operations as the [`crew` CLI
2779
2911
  family](#crews) — `crew list`, `crew new`, `crew member add`, `crew member
@@ -2843,7 +2975,8 @@ interactively.
2843
2975
 
2844
2976
  The [`examples/workflows`](../examples/workflows) folder has a workflow per
2845
2977
  idea: [`delivery`](../examples/workflows/delivery.yaml) (a review knock-back
2846
- 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
2847
2980
  production line with provisioned workspaces, an adversarial reviewer, a doc
2848
2981
  pass, and teardown owned as a step),
2849
2982
  [`research`](../examples/workflows/research.yaml) (collections),
@@ -2877,7 +3010,7 @@ wf=$(owenloop create delivery \
2877
3010
  run=$(owenloop tick $wf | jq -r '.orders[0].run') # claim the planner job
2878
3011
  owenloop green $wf $run plan --value '{"plan":"…"}' # report its output
2879
3012
 
2880
- owenloop status $wf # owed / eligible / blocked / done
3013
+ owenloop status $wf # done / debts / eligible / blocked / pending / inFlight
2881
3014
  ```
2882
3015
 
2883
3016
  **A knock-back.** When the reviewer's job comes up, instead of greening its
@@ -2890,7 +3023,9 @@ owenloop reject $wf pr --by reviewer --text "tests are missing"
2890
3023
  That re-arms `builder` with the reason attached to its next job. Do it past
2891
3024
  `builder`'s `maxAttempts` and `pr` **stalls** — owenloop stops re-arming it
2892
3025
  and waits for a human. `owenloop retry $wf pr --text "use the new fixture"`
2893
- 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.
2894
3029
 
2895
3030
  ## `reap`, `runs`, and `status.inFlight` — observing and clearing in-flight work
2896
3031
 
@@ -2943,6 +3078,12 @@ refuses it. The result JSON is always written to stdout; the human-readable
2943
3078
  reason goes to stderr. A successful call exits 0 — a Step Agent should treat a
2944
3079
  non-zero exit as a failure, not a success.
2945
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
+
2946
3087
  ## What a job looks like
2947
3088
 
2948
3089
  `tick` returns `{ workflow, orders, reaped }`. Each order is a **reference
@@ -2963,6 +3104,7 @@ them.
2963
3104
  "inputs": ["plan"],
2964
3105
  "outputs": ["pr"],
2965
3106
  "worker": "command", // the authored step's executor:, mapped verbatim (absent = 'agent')
3107
+ "modifier": "standard", // modifier used for this offer; absent when unmodified
2966
3108
  "consumes": { "plan": { /* the accepted input value */ } },
2967
3109
  "owes": [ // the feedback channel
2968
3110
  { "path": "pr", "judgmentRejects": 2, "schemaRejects": 0,
@@ -2976,7 +3118,7 @@ A worker first **resolves the reference**: the `(defDigest, step, key)`
2976
3118
  boundary maps the order to the exact authored instructions from the worker's
2977
3119
  trusted local definition source — the same resolver the embedded engine and
2978
3120
  the CLI use. Resolution returns the authored `prompt` (with
2979
- `${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}`
3121
+ `${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MODIFIER}`/`${MAX_ATTEMPTS}`
2980
3122
  materialized), the authored `command` if the step has one, and nothing
2981
3123
  fabricated. If the worker's source does not know the digest — the definition
2982
3124
  was never delivered, or the current on-disk definition no longer matches the
package/docs/crypto.md CHANGED
@@ -70,7 +70,7 @@ child stderr is never interpolated into error text.
70
70
  | `machine` | the literal `"local"` |
71
71
  | `agent` | the agent identity id |
72
72
 
73
- `owenloop setup` step `[4/7] signing keys` ensures all three, in that order,
73
+ `owenloop setup` step `[4/8] signing keys` ensures all three, in that order,
74
74
  idempotently: a second run performs zero writes.
75
75
 
76
76
  **One backend is selected once and never error-fallback.** A fallback after a
@@ -719,16 +719,32 @@ layout is:
719
719
  ```text
720
720
  <config>/org-root.pub # public anchor, 0644
721
721
  <config>/org-root # private anchor, 0600
722
- <config>/roster/<sha256hex(keyid)>.grant.dsse
722
+ <config>/grants/<sha256hex(keyid)>.grant.dsse
723
723
  <config>/revocations/<sha256hex(keyid)>.revocation.dsse
724
724
  ```
725
725
 
726
726
  The root key is stored outside `PrincipalKeyManager` because the root is not a
727
727
  hub-scoped principal key. The containing directory is `0700`; the private root
728
- is never returned by the library or placed in an envelope. `loadRoster` and
728
+ is never returned by the library or placed in an envelope. `loadGrants` and
729
729
  `loadRevocations` return raw envelope bytes to the pure validator and refuse
730
730
  symlinked or non-regular files.
731
731
 
732
+ If `<config>/grants` has zero `*.grant.dsse` entries while the pre-rename
733
+ `<config>/roster` is a readable, non-symlink directory of regular files that
734
+ holds grants, owenloop refuses rather than treating the machine as unenrolled.
735
+ It never reads or moves that legacy directory. When `<config>/grants` is
736
+ absent, the shell-quoted remediation is structurally
737
+ `mv <config>/roster <config>/grants`; this whole-directory rename preserves
738
+ every accepted grant filename, including dot-prefixed names. When a grants path
739
+ already exists, the printed remediation is instead
740
+ `rmdir <config>/grants && mv <config>/roster <config>/grants`. It moves only if
741
+ that path is an empty real directory; otherwise `rmdir` fails without moving
742
+ anything, and the operator must inspect `<config>/grants` by hand before
743
+ retrying. In either case, restart running owenloop shift daemons after a
744
+ successful migration. If the legacy source is a file or symlink, cannot be
745
+ inspected, or contains a non-regular entry, owenloop prints no migration
746
+ command: repair the named source path by hand before retrying the migration.
747
+
732
748
  ## Admin-signed policy floors
733
749
 
734
750
  A policy floor is an org-wide minimum for local enforcement. An org admin signs
package/docs/design.md CHANGED
@@ -970,6 +970,13 @@ step's last owed submit is what closes it — so the reverse order made every
970
970
  reject from a single-owed-path step undeliverable. What follows the reject
971
971
  depends on the hub's own answer, in its `closed` field:
972
972
 
973
+ The payload reject's `text` starts with the script's reason. When the command
974
+ has a non-empty captured output tail, the worker appends a labeled
975
+ `--- command output (last N bytes) ---` section containing the last 4 KiB of
976
+ combined stdout-then-stderr output (lossy UTF-8, with trailing newlines
977
+ trimmed before counting bytes). An empty tail adds nothing, and the payload
978
+ marker line is retained. Judge rejects are not changed by this formatting.
979
+
973
980
  - `closed: true` — the rejected path was one of this firing's consumed inputs,
974
981
  so the hub closed the run `no_work`. The owed paths stay debts and the step
975
982
  re-fires against the rebuilt input. No receipt is submitted: an artifact
@@ -1682,7 +1689,7 @@ addressed by digest.
1682
1689
  record or throws the named refusal; `resolveOrder(order)` builds the
1683
1690
  `{defDigest, step, key}` ref from an order and additionally materializes the
1684
1691
  runtime placeholders in the resolved prompt — the same substitution
1685
- `${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}` that
1692
+ `${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MODIFIER}`/`${MAX_ATTEMPTS}` that
1686
1693
  `buildOrder` used to inline, moved whole to resolution time (unknown
1687
1694
  placeholders stay untouched; `MAX_ATTEMPTS` renders the `maxAttempts` metadata
1688
1695
  from the resolved instruction record). Substitution
@@ -1846,3 +1853,65 @@ path still requires a pre-commit verifier and remains fail-closed when that
1846
1853
  adapter is not provided. The ingestor and verifier are separate concerns:
1847
1854
  ingestion makes the bundle's verified object available, while the verifier
1848
1855
  decides whether the install may commit it.
1856
+
1857
+ ## §31 Cleanup on cancellation (`onCancel:`)
1858
+
1859
+ The engine's step grammar has a declarative cleanup marker:
1860
+
1861
+ ```yaml
1862
+ - name: deprovisioner
1863
+ consumes: [merge, workspace]
1864
+ onCancel:
1865
+ consumes: [workspace]
1866
+ ```
1867
+
1868
+ This is deliberately a new step key rather than another `on:` token.
1869
+
1870
+ | Existing key | What it means | Why it is not cleanup-on-cancel |
1871
+ |---|---|---|
1872
+ | `terminal: true` | A step's green is a destructive completion. | It says nothing about run lifecycle. |
1873
+ | `effect.onInvalidate` | Routes an already-green artifact after its inputs move. | Cancellation is not an input move. |
1874
+ | `on:` | Pure in-run firing vocabulary. | It has no lifecycle signal or per-trigger consume payload. |
1875
+ | `idleAfter:` | Duration sidecar for `on: [idle]`. | It is unrelated to cancellation. |
1876
+ | `x:` | Opaque extension map. | It cannot validate this declaration or catch typos. |
1877
+
1878
+ Finally, `on:` is evaluated by the clock-free, state-pure
1879
+ `eligibleFirings(ArtifactMap, TimeFacts)`; cancellation is neither artifact
1880
+ state nor a time fact, and `WorkflowData` has no instance status. It therefore
1881
+ cannot be a scheduler trigger in this package.
1882
+
1883
+ `onCancel:` is a mapping with exactly one required key, `consumes:`, a list of
1884
+ strings that may be empty. Every entry must be a unique stem from the owning
1885
+ step's own plain consumes. Map and reduce consumes have no key binding on a
1886
+ one-time cancellation firing and are refused. The key is refused on `calls:`
1887
+ steps by that grammar's smaller key allowlist. `allGreen` and `idle`
1888
+ evaluators may declare `onCancel:` only with an empty list because they cannot
1889
+ declare normal consumes. `terminal: true` together with `onCancel:` remains
1890
+ legal deliberately: the engine does not infer an author's cleanup policy.
1891
+
1892
+ `onCancel:` is inert in the standalone engine. It does not affect
1893
+ `eligibleFirings`, `modelCheck`, the forward cascade, or done-ness. A host
1894
+ with no cancellation concept loads a definition carrying it with no behavior
1895
+ change.
1896
+
1897
+ The control plane contract is:
1898
+
1899
+ > **`onCancel:` contract.** When the control plane cancels a run of instance `W`:
1900
+ >
1901
+ > 1. Resolve `W`'s def — `WorkflowData.defSnapshot` when pinned (§28), otherwise by name.
1902
+ > 2. Select the cleanup steps: `cancelCleanupSteps(def)` (exported from `owenloop`), i.e. every
1903
+ > step where `step.onCancel !== undefined`, in def order.
1904
+ > 3. For each such step `S`: if **every** stem in `S.onCancel.consumes` is green, dispatch an
1905
+ > order for `S` whose inputs are exactly those stems and their values. If any is not green,
1906
+ > `S` is not dispatchable — record that and do not block cancellation on it.
1907
+ > 4. `assertServableInstance` (`packages/hub-core/src/serving.ts`) must admit an order on a
1908
+ > `cancelled` instance **only** when that order is for a step selected in step 2. Every other
1909
+ > step stays refused, exactly as today.
1910
+ > 5. A step with no `onCancel:` is never dispatched after cancel — today's behaviour, unchanged.
1911
+ > 6. **Recommended, and the follow-on run's call to confirm:** hold the cancelled instance out of
1912
+ > its final closed state until each dispatched cleanup step's produces settle (green, or
1913
+ > exhausted per that step's `maxAttempts`). Closing immediately would reproduce the original
1914
+ > defect in a slower form — the order exists but nothing waits for it.
1915
+ > 7. `onCancel:` is inert in the standalone engine. `eligibleFirings`, `modelCheck`, the forward
1916
+ > cascade, and done-ness do not read it. A host with no cancellation concept loads and runs a
1917
+ > def carrying it with no behaviour change.