owenloop 0.4.0 → 0.5.0

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 (155) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +98 -25
  3. package/bin/owenloop.mjs +2 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +172 -0
  5. package/dist/packages/work/src/agent/brief.js +193 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +135 -0
  7. package/dist/packages/work/src/agent/loop.js +542 -0
  8. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  9. package/dist/packages/work/src/agent/workdir.js +319 -0
  10. package/dist/packages/work/src/bundle/cache.d.ts +90 -0
  11. package/dist/packages/work/src/bundle/cache.js +324 -0
  12. package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
  13. package/dist/packages/work/src/bundle/fetch.js +325 -0
  14. package/dist/packages/work/src/bundle/types.d.ts +160 -0
  15. package/dist/packages/work/src/bundle/types.js +1 -0
  16. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  17. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  18. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  19. package/dist/packages/work/src/credentials/reader.js +32 -0
  20. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  21. package/dist/packages/work/src/credentials/resolve.js +56 -0
  22. package/dist/packages/work/src/exec/loop.d.ts +29 -0
  23. package/dist/packages/work/src/exec/loop.js +215 -0
  24. package/dist/packages/work/src/exec/receipt.d.ts +38 -0
  25. package/dist/packages/work/src/exec/receipt.js +21 -0
  26. package/dist/packages/work/src/exec/runner.d.ts +65 -0
  27. package/dist/packages/work/src/exec/runner.js +185 -0
  28. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  29. package/dist/packages/work/src/harness/child-env.js +127 -0
  30. package/dist/packages/work/src/harness/claude.d.ts +128 -0
  31. package/dist/packages/work/src/harness/claude.js +635 -0
  32. package/dist/packages/work/src/harness/codex.d.ts +110 -0
  33. package/dist/packages/work/src/harness/codex.js +896 -0
  34. package/dist/packages/work/src/harness/contract.d.ts +283 -0
  35. package/dist/packages/work/src/harness/contract.js +32 -0
  36. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  37. package/dist/packages/work/src/harness/fake.js +90 -0
  38. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  39. package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
  40. package/dist/packages/work/src/harness/permissions.d.ts +62 -0
  41. package/dist/packages/work/src/harness/permissions.js +93 -0
  42. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  43. package/dist/packages/work/src/harness/registry.js +45 -0
  44. package/dist/packages/work/src/harness/session-store.d.ts +163 -0
  45. package/dist/packages/work/src/harness/session-store.js +319 -0
  46. package/dist/packages/work/src/harness/types.d.ts +29 -0
  47. package/dist/packages/work/src/harness/types.js +14 -0
  48. package/dist/packages/work/src/harnesses.d.ts +38 -0
  49. package/dist/packages/work/src/harnesses.js +38 -0
  50. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  51. package/dist/packages/work/src/hold/loop.js +23 -0
  52. package/dist/packages/work/src/hold/mcp.d.ts +55 -0
  53. package/dist/packages/work/src/hold/mcp.js +149 -0
  54. package/dist/packages/work/src/hub/client.d.ts +22 -0
  55. package/dist/packages/work/src/hub/client.js +78 -0
  56. package/dist/packages/work/src/hub/types.d.ts +290 -0
  57. package/dist/packages/work/src/hub/types.js +28 -0
  58. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  59. package/dist/packages/work/src/lease/loop.js +277 -0
  60. package/dist/packages/work/src/main.d.ts +1 -0
  61. package/dist/packages/work/src/main.js +48 -0
  62. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  63. package/dist/packages/work/src/mcp/server.js +320 -0
  64. package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
  65. package/dist/packages/work/src/roles/agent-run.js +447 -0
  66. package/dist/packages/work/src/roles/exec.d.ts +40 -0
  67. package/dist/packages/work/src/roles/exec.js +203 -0
  68. package/dist/packages/work/src/roles/hold.d.ts +68 -0
  69. package/dist/packages/work/src/roles/hold.js +324 -0
  70. package/dist/packages/work/src/roles/join.d.ts +18 -0
  71. package/dist/packages/work/src/roles/join.js +204 -0
  72. package/dist/packages/work/src/roles/lint.d.ts +59 -0
  73. package/dist/packages/work/src/roles/lint.js +200 -0
  74. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  75. package/dist/packages/work/src/roles/prepare.js +249 -0
  76. package/dist/packages/work/src/roles/release.d.ts +48 -0
  77. package/dist/packages/work/src/roles/release.js +137 -0
  78. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  79. package/dist/packages/work/src/roles/sessions.js +180 -0
  80. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  81. package/dist/packages/work/src/roles/settings.js +66 -0
  82. package/dist/packages/work/src/roles/shift.d.ts +12 -0
  83. package/dist/packages/work/src/roles/shift.js +228 -0
  84. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  85. package/dist/packages/work/src/roles/signals.js +62 -0
  86. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  87. package/dist/packages/work/src/settings/provision.js +47 -0
  88. package/dist/packages/work/src/settings/settings.d.ts +120 -0
  89. package/dist/packages/work/src/settings/settings.js +116 -0
  90. package/dist/packages/work/src/shift/client.d.ts +24 -0
  91. package/dist/packages/work/src/shift/client.js +124 -0
  92. package/dist/packages/work/src/shift/loop.d.ts +120 -0
  93. package/dist/packages/work/src/shift/loop.js +468 -0
  94. package/dist/packages/work/src/shift/protocol.d.ts +91 -0
  95. package/dist/packages/work/src/shift/protocol.js +24 -0
  96. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  97. package/dist/packages/work/src/shift/routing.js +50 -0
  98. package/dist/packages/work/src/shift/runtime.d.ts +43 -0
  99. package/dist/packages/work/src/shift/runtime.js +274 -0
  100. package/dist/packages/work/src/shift/server.d.ts +23 -0
  101. package/dist/packages/work/src/shift/server.js +716 -0
  102. package/dist/packages/work/src/shift/spawn.d.ts +86 -0
  103. package/dist/packages/work/src/shift/spawn.js +100 -0
  104. package/dist/packages/work/src/shift/state.d.ts +77 -0
  105. package/dist/packages/work/src/shift/state.js +162 -0
  106. package/dist/packages/work/src/usage.d.ts +6 -0
  107. package/dist/packages/work/src/usage.js +175 -0
  108. package/dist/{add.d.ts → src/add.d.ts} +12 -40
  109. package/dist/{add.js → src/add.js} +11 -176
  110. package/dist/src/cli.d.ts +147 -0
  111. package/dist/{cli.js → src/cli.js} +1643 -353
  112. package/dist/src/credentials.d.ts +280 -0
  113. package/dist/src/credentials.js +697 -0
  114. package/dist/{defs.js → src/defs.js} +59 -36
  115. package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
  116. package/dist/{engine.js → src/engine.js} +29 -20
  117. package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
  118. package/dist/{hub.js → src/hub.js} +531 -1
  119. package/dist/{index.d.ts → src/index.d.ts} +3 -1
  120. package/dist/{index.js → src/index.js} +2 -1
  121. package/dist/src/lock.d.ts +80 -0
  122. package/dist/src/lock.js +217 -0
  123. package/dist/src/mcp/serve.d.ts +85 -0
  124. package/dist/src/mcp/serve.js +702 -0
  125. package/dist/src/mcp/server.d.ts +132 -0
  126. package/dist/src/mcp/server.js +327 -0
  127. package/dist/{model.d.ts → src/model.d.ts} +59 -4
  128. package/dist/{model.js → src/model.js} +149 -22
  129. package/dist/{types.d.ts → src/types.d.ts} +66 -24
  130. package/dist/{util.d.ts → src/util.d.ts} +25 -0
  131. package/dist/{util.js → src/util.js} +26 -0
  132. package/dist/src/work-settings.d.ts +57 -0
  133. package/dist/src/work-settings.js +84 -0
  134. package/docs/authoring.md +102 -53
  135. package/docs/cli.md +883 -29
  136. package/docs/design.md +119 -45
  137. package/docs/embedding.md +39 -14
  138. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  139. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  140. package/examples/workflows/judges/gate-sharpness.md +39 -0
  141. package/examples/workflows/judges/security.md +34 -0
  142. package/package.json +17 -8
  143. package/dist/cli.d.ts +0 -83
  144. /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
  145. /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
  146. /package/dist/{factory.js → src/factory.js} +0 -0
  147. /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
  148. /package/dist/{paths.js → src/paths.js} +0 -0
  149. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  150. /package/dist/{schema.js → src/schema.js} +0 -0
  151. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  152. /package/dist/{store.js → src/store.js} +0 -0
  153. /package/dist/{types.js → src/types.js} +0 -0
  154. /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
  155. /package/dist/{untar.js → src/untar.js} +0 -0
package/docs/cli.md CHANGED
@@ -21,10 +21,22 @@ every command, as above. `--help` on any command (or bare `-h`/`help`)
21
21
  prints this usage and exits 0 without doing any work.
22
22
 
23
23
  Boolean flags (`--force`, `--dry-run`, `--all`, `--open`, `--terminal`,
24
- `--recursive`, `--with-token`, `--shallow`, `--assume-provided`, and the bare
25
- `--now` on `reap`) never take a following value — the next token is always a
26
- positional or the next `--flag`, never consumed as this flag's argument. Use
27
- `--flag=value` (e.g. `--now=<ms>` on `tick`) for flags that do take a value.
24
+ `--recursive`, `--with-token`, `--shallow`, `--assume-provided`,
25
+ `--strict-inputs`, and the bare `--now` on `reap`) never take a following
26
+ value — the next token is always a positional or the next `--flag`, never
27
+ consumed as this flag's argument. Use `--flag=value` (e.g. `--now=<ms>` on
28
+ `tick`) for flags that do take a value.
29
+
30
+ `owenloop check <def>` defaults to treating `seedOwed` inputs as provided
31
+ (`assumeProvided: true`), so a def whose only initial gate is an unprovided
32
+ seeded input no longer reports a false depth-0 `True deadlocks` and doesn't
33
+ exit nonzero for it. `--strict-inputs` opts back out to the previous
34
+ seedOwed-starts-owed behavior, and when that's the def's only blocker also
35
+ prints a one-line hint naming the responsible input(s). `--assume-provided`
36
+ is still accepted (never errors) but is now redundant with the default; if
37
+ both flags are passed, `--strict-inputs` wins. See
38
+ [`docs/design.md` §25](design.md#25-the-model-checker-owenloop-check--scope)
39
+ for the full breakdown.
28
40
 
29
41
  ## Commands
30
42
 
@@ -37,9 +49,23 @@ positional or the next `--flag`, never consumed as this flag's argument. Use
37
49
  | `connect [--hub <url>] [--as <slot>]` | bind this project to a hub (writes `.owenloop/hub.json`) and verify the credential |
38
50
  | `push [<defName>...] [--force] [--dry-run] [--as <slot>]` | publish local workflow defs to the bound hub (idempotent against the hub's own def hashes) |
39
51
  | `logout [--hub <url>] [--as <slot>]` | delete the stored credential for a hub |
52
+ | `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) |
53
+ | `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) |
54
+ | `capability unbind <capability> <crew> [--hub <url>]` | remove one `(capability, crew)` route — see [Capability routes](#capability-routes) |
55
+ | `capability list [--hub <url>]` | list the hub org's capability routes — see [Capability routes](#capability-routes) |
56
+ | `crew list [--hub <url>]` | list the hub org's crews with their members (includes the orphan crew once one exists) — see [Crews](#crews) |
57
+ | `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) |
58
+ | `crew rm <crewId> [--hub <url>]` | delete a crew; work stamped to it moves to the org's orphan crew — see [Crews](#crews) |
59
+ | `crew member add <crewId> <principalKind> <principalId> [--hub <url>]` | add a member or agent to a crew — see [Crews](#crews) |
60
+ | `crew member rm <crewId> <principalId> [--hub <url>]` | remove a principal from a crew — see [Crews](#crews) |
61
+ | `setup [--hub <url>] [--new-agent <name> \| --replace-agent <name>] [--crews <a,b>] [--scopes <a,b>]` | onboard this machine: may store human and Scoped Identity credentials, write only execution-settings `hubOrigin`, and after probing print missing-plugin commands instead of installing the plugin — see [`setup`](#setup--onboard-a-machine) |
62
+ | `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
63
+ | `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) |
64
+ | `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) |
65
+ | `work <subcommand> [options]` | run the execution-side CLI companion — see [`work`](#work--execution-side-cli-companion) |
40
66
  | `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
41
67
  | `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
42
- | `tick <wf> [--now=<ms>] [--shallow] [--label <l>]…` | claim and emit eligible **orders** (the jobs to run); deep by default — also descends into live `calls:` children (`--shallow` = this instance only); repeatable `--label` claims unlabeled steps plus matching-label steps — see below |
68
+ | `tick <wf> [--now=<ms>] [--shallow] [--capability <l>]…` | claim and emit eligible **orders** (the jobs to run); deep by default — also descends into live `calls:` children (`--shallow` = this instance only); repeatable `--capability` claims steps without capabilities plus matching-capability steps — see below |
43
69
  | `reap <wf> [--now]` | run the reaper; `--now` forces every claim stale (TTL 0) — see below |
44
70
  | `runs <wf> [--open]` | list this instance's runs, joining claim state for open ones |
45
71
  | `status <wf>` | derived view: `done`, `debts`, `eligible`, `blocked`, `inFlight` |
@@ -57,6 +83,166 @@ positional or the next `--flag`, never consumed as this flag's argument. Use
57
83
  | `delete <wf>` | delete an instance and all its rows |
58
84
  | `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
59
85
 
86
+ ## `shift` — foreground daemon and client
87
+
88
+ `owenloop shift` is the public local dispatch surface. `shift start` runs the
89
+ self-driven dispatch loop as a foreground process and listens on
90
+ `<stateDir>/shift.sock`. Each client connection carries one JSON-line request
91
+ and one JSON-line response. The daemon keeps polling and dispatching while no
92
+ `shift next` client is attached.
93
+
94
+ The `shift start` positional argument is a **crew** name. The routing API calls
95
+ that field a **crew**: `serve_crews` contains the selected crew names. Passing
96
+ `--all` maps to an empty `serve_crews` list, which means all crews available to
97
+ the Scoped Identity. Do not treat `attended_at` as a liveness signal: every
98
+ accepted `shift next` records attendance and makes the next presence ping due,
99
+ but attendance is advisory and observability-only. Attendance never changes
100
+ routing, dispatch, or lease behavior.
101
+
102
+ The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
103
+ `XDG_CONFIG_HOME` is set to a non-blank value; otherwise it is
104
+ `$HOME/.config/owenloop/settings.json`.
105
+
106
+ ### `shift start <crew...>`
107
+
108
+ ```text
109
+ owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
110
+ [--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]
111
+ [--cache-dir <p>] [--state-dir <p>]
112
+ ```
113
+
114
+ At least one named crew is required unless `--all` is present. `--all` and
115
+ named crews are mutually exclusive. Duplicate named crews collapse to one
116
+ entry before routing. The daemon owns one socket at a time; a second start
117
+ against the same socket is refused. There is no detach mode. `--once` performs
118
+ one loop sweep and exits instead of keeping the foreground daemon running.
119
+
120
+ | option | default and behavior |
121
+ |---|---|
122
+ | `--origin <url>` | use this hub origin; otherwise use `hubOrigin` from the execution settings file; there is no hub-origin fallback |
123
+ | `--as <account>` | use this Scoped Identity account; defaults to `default` |
124
+ | `--name <n>` | use this shift name; otherwise generate one from the host and current directory with a process/shift suffix |
125
+ | `--cap <n>` | dispatch capacity; precedence is flag, then `settings.dispatchCap`, then `3` |
126
+ | `--max-agents <n>` | concurrent agent limit; precedence is flag, then `settings.maxConcurrentAgents`, then `4` |
127
+ | `--poll-interval <ms>` | loop polling interval; defaults to `5000` milliseconds |
128
+ | `--once` | run one loop sweep and exit; without it, keep the daemon in the foreground |
129
+ | `--cache-dir <p>` | cache root; precedence is flag, then `OWENLOOP_CACHE_DIR`, then `settings.cacheDir`, then `$XDG_CACHE_HOME/owenloop`, then `$HOME/.cache/owenloop` |
130
+ | `--state-dir <p>` | socket and child-state root; precedence is flag, then `OWENLOOP_STATE_DIR`, then `settings.stateDir`, then `$XDG_STATE_HOME/owenloop/exec`, then `$HOME/.local/state/owenloop/exec`; the socket is `shift.sock` inside this directory |
131
+
132
+ A clean start or `--once` completion exits `0`. `owenloop shift --help` also
133
+ exits `0`. Runtime failures such as credential reads or socket/runtime setup
134
+ exit `1`. Usage and
135
+ precondition failures — including no crew or `--all`, invalid flags, a missing
136
+ hub origin, or a missing Scoped Identity credential — exit `2`. The foreground
137
+ daemon's normal lifecycle line is written to stdout when it stays running;
138
+ diagnostics go to stderr.
139
+
140
+ ### `shift next [--wait <seconds>]`
141
+
142
+ ```text
143
+ owenloop shift next [--wait <seconds>] [--state-dir <p>]
144
+ ```
145
+
146
+ `--wait` accepts a finite, non-negative number of seconds and defaults to `90`.
147
+ `--state-dir` selects the daemon socket. Only one `next` call may be parked at
148
+ a time. A second parked call returns this error and exits `1`:
149
+
150
+ ```text
151
+ whats_next is already parked — one park at a time (cancel it or wait for it to return)
152
+ ```
153
+
154
+ When a `next` request is accepted, the daemon stamps `attended_at`. The call
155
+ returns promptly when an event is queued, the wait expires, or the shift
156
+ explicitly ends. A normal timeout exits `0` and prints the current capacity
157
+ object, for example `{ "cap": 3, "free": 3, "running": 0, "events": [] }`.
158
+ Successful responses use the same capacity shape and may include queued event
159
+ objects. For `dispatched`, `reaped`, and `failed`, `kind` is either `exec` or
160
+ `agent-run`:
161
+
162
+ - `dispatched`: `{ "type": "dispatched", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "pid": 123 }`
163
+ - `reaped`: `{ "type": "reaped", "workflow": "...", "run": "...", "kind": "exec", "pid": 123 }`
164
+ - `failed`: `{ "type": "failed", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "message": "..." }`
165
+ - `ended`: `{ "type": "ended" }`, delivered to a parked `next` when `shift end` explicitly shuts down the daemon
166
+
167
+ `gate` is a reserved protocol shape for a future local representation of a
168
+ pending hub gate. Production code does not construct live hub gate events yet;
169
+ the local FIFO test and drill scope are recorded in
170
+ [`packages/work/test/shift-walkthrough.manual.md`](../packages/work/test/shift-walkthrough.manual.md).
171
+
172
+ If no daemon is listening, `next` exits `1` and prints the exact start guidance:
173
+
174
+ ```text
175
+ no shift daemon at <stateDir>/shift.sock — start one with: owenloop shift start <crew…>
176
+ ```
177
+
178
+ Invalid arguments exit `2`. Other client or daemon runtime failures exit `1`.
179
+ All successful client output is one JSON object on stdout; diagnostics are on
180
+ stderr.
181
+
182
+ ### `shift status [--state-dir <path>]`
183
+
184
+ ```text
185
+ owenloop shift status [--state-dir <p>]
186
+ ```
187
+
188
+ With a daemon, status exits `0` and prints:
189
+
190
+ ```json
191
+ { "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "attended_at": null, "started_at": 1738000000000 }
192
+ ```
193
+
194
+ `attended_at` remains `null` until the first accepted `next` request. Without a
195
+ daemon, status is still a successful question: it exits `0` and prints
196
+ `{ "status": "no daemon", "socket": "<path>" }`. Invalid arguments exit `2`;
197
+ other client/runtime errors exit `1`.
198
+
199
+ ### `shift end [--state-dir <path>]`
200
+
201
+ ```text
202
+ owenloop shift end [--state-dir <p>]
203
+ ```
204
+
205
+ An explicit end stops the loop, resolves an in-flight `next` with an `ended`
206
+ event, sends the final presence update with `attended_at` omitted so the hub
207
+ clears the attendance stamp, closes the socket, and prints
208
+ `{ "ok": true, "ended": true }` with exit `0`. Detached `exec` and `agent-run`
209
+ children remain alive to finish under their own leases. Signal shutdown (for
210
+ example, Ctrl-C) stops the daemon but does not synthesize the `ended` event or
211
+ perform the explicit attendance-clearing update.
212
+
213
+ If no daemon is listening, `end` exits `1` with the same start guidance as
214
+ `next`. Invalid arguments exit `2`; other client/runtime errors exit `1`.
215
+
216
+ ## `work` — execution-side CLI companion
217
+
218
+ The execution-side commands ship in the same `owenloop` npm package and use the
219
+ same `owenloop` binary. Replace the old separate `owenwork` invocation directly:
220
+
221
+ ```text
222
+ owenwork <subcommand> ... → owenloop work <subcommand> ...
223
+ ```
224
+
225
+ The transplanted subcommand names remain. The standing Shift daemon is
226
+ only the root `owenloop shift` command; `owenloop work` has no standing-daemon alias.
227
+ `hold --mcp` remains because the machine-attached hold mount still exists.
228
+ Run `owenloop work --help` for the full role-specific usage.
229
+
230
+ The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
231
+ `XDG_CONFIG_HOME` is set to a non-blank value; otherwise it is
232
+ `$HOME/.config/owenloop/settings.json`.
233
+
234
+ | subcommand | what it does |
235
+ |---|---|
236
+ | `hold --order <id> [options]` | hold an order with a heartbeating lease |
237
+ | `exec <order-id> [options]` | run a command order in a self-leasing loop |
238
+ | `agent-run <order-id> [options]` | host an agent order's Step Agent in a harness and self-leasing loop |
239
+ | `prepare <workflow> [--origin <url>]` | fetch, cache, and normalize step specs |
240
+ | `lint <workflow-name \| path>` | lint `x.harness` option bags in a workflow definition |
241
+ | `sessions [--all] [--json]` | list recorded harness sessions and how to reopen them |
242
+ | `release --session <id> [options]` | drain a session's held claims |
243
+ | `settings` | print the resolved execution settings file |
244
+ | `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
245
+
60
246
  ## `add` — installing shared workflow defs from GitHub
61
247
 
62
248
  `owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
@@ -240,13 +426,13 @@ ref) surfaces as a 404 from the sha-resolve step.
240
426
  **Trust model — what `add` does and does not protect.** Installing a package
241
427
  executes nothing at install time: `add` only fetches, validates, and writes
242
428
  YAML under the defs dir. But an installed def's steps *run* later, with
243
- whatever privileges the host process and its dispatcher grant their workers.
244
- owenloop itself never executes a step body — `worker:`/`command:` are opaque
245
- labels it carries through untouched and never shells out (see [What owenloop is
429
+ whatever privileges the host process and its dispatcher grant their Step Agents.
430
+ owenloop itself never executes a step body — `executor:`/`command:` are opaque
431
+ fields it carries through untouched and never shells out (see [What owenloop is
246
432
  not](../README.md#what-owenloop-is-not) and
247
- [`docs/authoring.md`](authoring.md#worker--declaring-the-executor)) — so the
248
- real risk surface is the conductor or worker you point at these defs: the
249
- prompts and `command:` strings that ship in a package are handed to agents that
433
+ [`docs/authoring.md`](authoring.md#executor--declaring-the-executor)) — so the
434
+ real risk surface is the Shift or Step Agent you point at these defs: the
435
+ prompts and `command:` strings that ship in a package are handed to Step Agents that
250
436
  typically run with your full local privileges. **Install only sources you
251
437
  trust.**
252
438
 
@@ -264,7 +450,7 @@ install *step* — staged all-or-nothing validation with an atomic swap, path
264
450
  containment (including symlink-aware `bodyFile` checks), and archive resource
265
451
  bounds — not the def *content* that later executes. `add` validates a def's
266
452
  structure and contains its paths; it does not sandbox or sanitize what a step
267
- body will do once a worker runs it. That trust decision stays yours.
453
+ body will do once a Step Agent runs it. That trust decision stays yours.
268
454
 
269
455
  **Untrusted-archive safety.** `add` treats the fetched repo as untrusted and
270
456
  refuses the whole install (nothing written) on any of these:
@@ -381,6 +567,29 @@ can read (only read) a stored credential through the same backend logic via the
381
567
  package's exported `readStoredCredential` — see
382
568
  [Embedding](embedding.md#whats-exported).
383
569
 
570
+ **Serializing writes (`credentials.lock`).** A store write — a refreshed OAuth
571
+ token, or a `login`/`logout` that stores or deletes a slot — is serialized by a
572
+ lockfile at `credentials.lock`, a sibling of `credentials.json` in the config
573
+ dir (created for the keychain backend too, since the race it closes is
574
+ backend-independent). The concern is a token-refresh race: two owenloop
575
+ processes hitting an expiring OAuth token at once would each POST a refresh and
576
+ each persist, and because refresh tokens rotate, the second write clobbers the
577
+ first with a token whose refresh link is already spent — silently killing the
578
+ credential. Under the lock a process re-reads the slot after acquiring it and,
579
+ if another process already refreshed, **adopts** that fresh token instead of
580
+ refreshing again — one network refresh, one write, no lost token. The lock
581
+ matters only for OAuth refresh and store/delete; read paths and the external-
582
+ command mode (which never writes the local store) do not take it. Staleness is
583
+ liveness-based: a lock held by a dead same-host process is reclaimed at once, an
584
+ unparseable or pid-less lockfile is reclaimed once older than the ~30s TTL, and
585
+ a lock held by a live process is never age-reclaimed. If the lock can't be
586
+ acquired within the wait budget the CLI fails loudly (`another owenloop process
587
+ is using the credential store … — timed out waiting after Ns`) rather than
588
+ refreshing unlocked. Three test knobs override the timings:
589
+ `OWENLOOP_CRED_LOCK_WAIT_MS` (default 45000), `OWENLOOP_CRED_LOCK_STALE_MS`
590
+ (default 30000), and `OWENLOOP_CRED_LOCK_POLL_MS` (default 100). No token value
591
+ ever appears in the lockfile or the timeout message.
592
+
384
593
  **Supplying the credential from your own tooling.** If your secrets live in a
385
594
  secret manager, or you run on a host with no keychain, set
386
595
  `OWENLOOP_CREDENTIAL_COMMAND` to a shell command line that prints a credential.
@@ -493,6 +702,651 @@ Exact-match redirect URIs (no RFC 8252 variable-port allowance) and no
493
702
  device-code grant remain recorded follow-ups on the service, not gaps in the
494
703
  CLI.
495
704
 
705
+ ### `agent new` — mint an agent token into a slot
706
+
707
+ `owenloop agent new <name>` mints a new Scoped Identity on the hub (`POST
708
+ /api/mint_agent_token`, authenticated as your **human** credential) and stores
709
+ the returned `olp_` token in the local credential slot `agent:<name>` — the same
710
+ slot `login --as agent:<name>` writes and `push --as agent:<name>` reads. Use it
711
+ to provision an agent token without pasting one by hand: the mint and the store
712
+ happen in one step, and you never handle the secret.
713
+
714
+ **The token is never printed.** The minted `olp_` token goes process → store
715
+ only — it never appears on stdout, stderr, in an error, or in a log (identity
716
+ model §6, "rule of gates"). The confirmation JSON is built from a whitelist of
717
+ **non-secret** fields only: `hub`, `name`, `slot`, `crews` (the resolved crew
718
+ names), `scopes` (the minted token's scopes — `["work"]` by default, or whatever
719
+ `--scopes`/`--shift` selected), `storage` (`keychain` | `file`), `agentId` (the
720
+ Scoped Identity's id), and `tokenId` (a revocation handle). To use the Scoped Identity afterwards,
721
+ pass `--as agent:<name>` to `connect`/`push`; to revoke it, use its `tokenId`
722
+ on the hub.
723
+
724
+ **Which hub gets minted on (`--hub`).** Resolution is deliberately narrow —
725
+ minting on the wrong org is not undone by a retry:
726
+
727
+ 1. `--hub <origin>` if given (normalized the same way as everywhere else).
728
+ 2. Otherwise the **one** hub your credential *file* stores — if exactly one is
729
+ present, it's used.
730
+ 3. Otherwise the command **exits 2** naming both remedies (pass `--hub`, or log
731
+ in to exactly one hub); when more than one hub is stored their origins are
732
+ listed back so you can pick.
733
+
734
+ Unlike other commands this does **not** fall back to `OWENLOOP_HUB` or the
735
+ built-in default hub — silently defaulting a mint would risk minting on the
736
+ production hub while you're logged into a dev one. Note that hub enumeration is
737
+ **file-store only** (shared with `owenloop mcp`): the keychain and the
738
+ external-command backend cannot list their entries, so on such a machine step 2
739
+ cannot enumerate the store and you must pass `--hub`.
740
+
741
+ **`--crews <a,b>`.** A comma-separated list of crew names the token is granted
742
+ on (trimmed, empties dropped). Omit the flag to let the hub default the token to
743
+ the minter's personal crew; `--crews ""` (or `--crews ,`) is a usage error. Crew
744
+ names are validated by the hub, not the client.
745
+
746
+ **`--scopes <a,b>` / `--shift`.** A comma-separated list of scopes the minted
747
+ token carries (trimmed, empties dropped). Omit both flags to mint **work-only**
748
+ (the default). `--shift` is shorthand for `--scopes work,run` — the identity
749
+ a service account needs to both serve and *start* runs. The two flags are
750
+ mutually exclusive (`--scopes … --shift` together is a usage error), and
751
+ `--scopes ""` (or `--scopes ,`) is a usage error. Scope names are validated by
752
+ the hub, not the client.
753
+
754
+ **A configured external credential command blocks the mint.** If
755
+ `OWENLOOP_CREDENTIAL_COMMAND` is set, that command — not the local store —
756
+ supplies credentials for the hub, so `agent new` refuses up front (it has
757
+ nowhere to write the minted token); unset the variable to use the local store.
758
+ This check, the name validation, the empty-`--crews` check, the empty-`--scopes`
759
+ check, and the `--scopes`/`--shift` mutual-exclusivity check all run
760
+ **before** any network call, so a refusal never mints a server-side token first
761
+ — a mint that then failed to store would burn the agent name permanently.
762
+
763
+ **Exit codes.**
764
+
765
+ | code | meaning |
766
+ |---|---|
767
+ | `0` | minted and stored |
768
+ | `1` | generic failure — invalid or already-taken name, crew/shape rejection, network timeout, or a token that minted but couldn't be stored |
769
+ | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
770
+ | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
771
+
772
+ ## Capability routes
773
+
774
+ A **capability route** maps a workflow-def **capability** (a logical capability tag a
775
+ def author writes, like `gpu` or `repo-access`) to a **crew** on one hub org.
776
+ Def authors write capabilities; an org admin binds each capability to at least one crew.
777
+ That indirection is what keeps deployment facts out of portable defs — see
778
+ [`capabilities:`](authoring.md#capabilities--logical-capability-tags) in the authoring guide
779
+ for the step-side declaration.
780
+
781
+ **A route is one `(capability, crew)` PAIR, and a capability may bind MANY crews.** The
782
+ pair is the unit that is created and destroyed: `capability bind` adds one, `capability unbind` removes one, and `capability list` returns one row per pair — so a capability bound
783
+ to three crews appears as three rows. A **dangling route** is one whose crew
784
+ row was deleted; it survives in the table, routes nothing, and never widens
785
+ access. A capability with **zero live routes** is **parked**: its steps wait.
786
+
787
+ **Resolution is live.** `start_run` only *checks* that every capability a run's steps
788
+ use is currently bound — it stamps no crew for a capability-routed step. Every later
789
+ routing decision (which Shift is offered the step, and whether a claim is
790
+ allowed) re-reads the route table as it stands at that moment.
791
+
792
+ **These edits take effect on work already in flight.**
793
+
794
+ - **Adding.** Running `capability bind` on a capability that is **already bound** ADDS the
795
+ named crew — it never displaces a crew already bound. Adding widens who can
796
+ serve the capability, live at the next poll of every in-flight run using it. Re-adding
797
+ a pair that is already there is a normal success, not an error (`alreadyRouted:
798
+ true`).
799
+ - **Removing.** Running `capability unbind` removes exactly ONE pair. If the capability still
800
+ has other live routes, it simply routes to a narrower set and nothing pauses.
801
+ If the removal takes away the **last live** route, the capability is **parked**:
802
+ the in-flight steps that use it are offered to no Shift and accept no
803
+ claim — until it is bound again. Nothing is lost; the work resumes on re-bind.
804
+ `remainingCrewIds: []` on stdout is that signal, and stderr says so in words.
805
+ - **Retargeting is two acts, not one.** There is no retarget command: add the new
806
+ crew, then remove the old one. Each is separately audited on the hub, and in
807
+ between **BOTH** crews serve the capability. The CLI deliberately does not chain the
808
+ two for you — the intermediate state is a real state an operator may want to sit
809
+ in, and collapsing it would hide a widened access window.
810
+
811
+ A capability route is **not** the project↔hub binding `owenloop connect` writes to
812
+ `.owenloop/hub.json` — that one records which hub *this project directory*
813
+ publishes to; a capability route is an org-scoped capability→crew row on the hub.
814
+
815
+ ### `capability bind <capability> <crew>`
816
+
817
+ `POST /api/add_capability_route`, authenticated as your **human** credential;
818
+ requires the **admin** role on the hub. ADDS the crew named `<crew>` to
819
+ `<capability>`'s routes. `<crew>` is a crew **name** — the hub resolves it to a crew
820
+ id; the CLI does no crew lookup and performs no client-side validation of either
821
+ argument (the hub is the enforcement of record).
822
+
823
+ **Adding is idempotent per pair.** Re-adding a `(capability, crew)` pair that is
824
+ already bound is a normal success — the hub answers `200` with `alreadyRouted:
825
+ true` and changes nothing (the original row keeps its creator and timestamp).
826
+ `routedCrewCount` reports how many **live** crews the capability binds after the write.
827
+
828
+ ### `capability unbind <capability> <crew>`
829
+
830
+ `POST /api/remove_capability_route`, authenticated as your **human** credential;
831
+ requires the **admin** role on the hub. Removes the ONE `(capability, crew)` route
832
+ you name. `<crew>` is **required**: a capability may bind many crews, so a capability-only
833
+ removal would unbind more than you asked for.
834
+
835
+ `<crew>` accepts the crew's **name**, or its raw **`crew_id`**. The raw-id form
836
+ is the only way to remove a **dangling** route — one whose crew row was
837
+ deleted, so there is no name left to resolve. `capability list` shows such a row
838
+ with `crewName: null`; take its `crewId` from there.
839
+
840
+ **`rm` is idempotent.** Removing a pair that is **not** bound is a normal
841
+ success — the hub answers `200` with `removed: false` rather than a `404` — and
842
+ the CLI prints a full document plus a stderr line saying nothing was removed. A
843
+ script can call `capability unbind` unconditionally without branching on whether the
844
+ pair was bound. On that tolerant path `crewId` is `null`, because the argument
845
+ matched neither a live crew name nor one of the capability's own rows.
846
+
847
+ **Removing the last live route parks the capability**, and stderr says so. See
848
+ "These edits take effect on work already in flight" above.
849
+
850
+ ### `capability list`
851
+
852
+ `GET /api/capability_routes`, authenticated as your **human** credential. Lists the
853
+ org's routes, ONE row per `(capability, crew)` pair ordered by capability then crew id —
854
+ so a capability bound to several crews appears as several rows. An org with no
855
+ routes yet is a normal success (exit 0) with an empty `routes` array.
856
+
857
+ A row whose `crewName` is `null` is a **dangling route**: the crew it names was
858
+ deleted. Such a row routes nothing and never widens access, and it is shown
859
+ rather than hidden precisely so you can clean it up — remove it with `capability unbind
860
+ <capability> <crewId>`.
861
+
862
+ **Flags.** `--hub <url>` only (plus the global `--db`/`--defs`).
863
+
864
+ **Which hub gets acted on (`--hub`).** Resolution is deliberately narrow — the
865
+ same stance `agent new` takes, because a route written against the wrong org
866
+ is not undone by a retry, and under live resolution it also moves in-flight
867
+ work:
868
+
869
+ 1. `--hub <origin>` if given (normalized the same way as everywhere else).
870
+ 2. Otherwise the **one** hub your credential *file* stores — if exactly one is
871
+ present, it's used.
872
+ 3. Otherwise the command **exits 2** naming both remedies (pass `--hub`, or log
873
+ in to exactly one hub); when more than one hub is stored their origins are
874
+ listed back so you can pick.
875
+
876
+ This does **not** fall back to `OWENLOOP_HUB` or the built-in default hub. Note
877
+ that hub enumeration is **file-store only**: the keychain and the
878
+ external-command backend cannot list their entries, so on such a machine step 2
879
+ cannot enumerate the store and you must pass `--hub`.
880
+
881
+ **Printed JSON.** stdout is exactly one whitelisted JSON document per
882
+ invocation, built from named fields — never a raw hub body — so `| jq` always
883
+ works. Human progress lines (the two `capability unbind` warnings) go to stderr only.
884
+
885
+ | subcommand | stdout |
886
+ |---|---|
887
+ | `capability bind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crew": "ml-crew", "alreadyRouted": false, "routedCrewCount": 2 }` |
888
+ | `capability unbind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crewId": "crw_1", "removed": true, "remainingCrewIds": ["crw_2"] }` |
889
+ | `capability list` | `{ "ok": true, "hub": "<origin>", "routes": [ { "capability": "gpu", "crewId": "crw_1", "crewName": "ml-crew", "createdBy": "u_1", "createdAt": 1738000000000 } ] }` |
890
+
891
+ Every added field carries the **hub's own name**, verbatim — the same words its
892
+ audit log and the web console use — so correlating stdout against them never
893
+ needs a translation step.
894
+
895
+ - `alreadyRouted` (`capability bind`) — was this exact `(capability, crew)` pair already
896
+ bound before the call? `false` means the pair was created by it.
897
+ - `routedCrewCount` (`capability bind`) — how many **live** crews the capability binds
898
+ after the write. A dangling route routes nothing and is not counted.
899
+ - `removed` (`capability unbind`) — did this call actually remove a pair? `false` is the
900
+ tolerant "it was never bound" case, not an error.
901
+ - `remainingCrewIds` (`capability unbind`) — the **live** crews the capability still binds.
902
+ `[]` means the capability is now **parked**: `jq '.remainingCrewIds | length == 0'`.
903
+ It can be `[]` while a dangling row survives, because such a row routes nothing.
904
+ - `crewId` (`capability unbind`) — the crew the hub resolved your `<crew>` argument to.
905
+ It is `null` on the tolerant `removed: false` path, where the argument matched
906
+ neither a live crew name nor one of the capability's own route rows. `capability unbind`
907
+ never prints a crew *name*: `remove_capability_route` does not return one, and
908
+ inventing one from argv would not be the hub's answer.
909
+ - `capability` and `crew` (`capability bind`) are the values the **hub** echoed back, not
910
+ your argv: if the hub normalized either, stdout tells the truth about what was
911
+ stored.
912
+
913
+ **Exit codes.**
914
+
915
+ | code | meaning |
916
+ |---|---|
917
+ | `0` | the crew was added to the capability (or was already bound), the route was removed (or was already absent), or the routes were listed |
918
+ | `1` | runtime or hub error — an unknown crew name (`capability bind` only; `capability unbind` answers a tolerant `removed: false` instead), a capability that fails the hub's name rules, a `403` for a non-admin, a malformed response, or a network timeout |
919
+ | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
920
+ | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
921
+
922
+ ## Crews
923
+
924
+ A **crew** is an org-scoped queue that agent work is stamped to. Every hub org
925
+ can have, in addition to any crews an admin creates, one **orphan crew** (name
926
+ `orphan:unrouted`, `kind: "orphan"`) that the hub itself owns as the landing
927
+ zone for work whose crew was deleted out from under it. It is materialized
928
+ **lazily**, the first time a crew holding stamped work is deleted — an org
929
+ that has never deleted a crew with stamped work has no orphan crew at all, and
930
+ `crew list` shows none. Once it exists, `crew list` includes it — it is
931
+ marked, never hidden, via a derived `orphan: true` boolean on its row (see the
932
+ Printed JSON table below).
933
+
934
+ This family is independent of [capability routes](#capability-routes): a capability routes
935
+ to a crew by *name*, and a crew is where agent work actually queues. Deleting a
936
+ crew a capability still points at does not error — the capability's routing simply
937
+ resolves nowhere useful until it is rebound.
938
+
939
+ ### `crew list`
940
+
941
+ `GET /api/crews`, authenticated as your **human** credential. Lists the org's
942
+ crews, each with its member rows (`principalKind`/`principalId`/`addedBy`/
943
+ `addedAt`). An org with no crews at all — including one that has never
944
+ materialized an orphan crew — is still a normal success (exit 0) with an empty
945
+ `crews` array.
946
+
947
+ ### `crew new <name> --kind personal|shared [--owner <memberId>]`
948
+
949
+ `POST /api/create_crew`, authenticated as your **human** credential; requires
950
+ the **admin** role on the hub, **or** — for `--kind personal --owner
951
+ <memberId>` where `<memberId>` is the caller's own member id — no admin role
952
+ at all: a human may self-service additional personal crews for themself
953
+ without being an admin (`assertPoolMutationAllowed`, hub-core
954
+ `manage-crews.ts:211-214`). Every other combination (a `shared` crew, or a
955
+ `personal` crew owned by someone else) still requires admin. `--kind` is **required** but its value is
956
+ forwarded to the hub **verbatim and unvalidated** — the hub is the enforcement
957
+ of record for which kind values are legal (today `personal`/`shared`; `orphan`
958
+ is reserved for the hub's own crew). `--owner <memberId>` is optional and is
959
+ omitted from the request body entirely when not given — a `personal` crew
960
+ with no owner is the hub's own error to raise, not a client-side rule
961
+ duplicated here.
962
+
963
+ ### `crew rm <crewId>`
964
+
965
+ `POST /api/delete_crew`, authenticated as your **human** credential; requires
966
+ the **admin** role on the hub for every crew kind, including a personal one —
967
+ `deletePool` bypasses the self-service gate that `crew new`/`crew member
968
+ add`/`crew member rm` use, and is admin-only unconditionally
969
+ (`manage-crews.ts:629`). Deletes the crew. The crew's **membership rows are
970
+ deleted outright, not moved** — `deleteAllPoolMembers` (`manage-crews.ts:706`)
971
+ runs unconditionally in the same transaction, whether or not any stamps
972
+ transfer; `membersRemoved` on stdout is a count of those deletions, since the
973
+ orphan crew's own membership is derived (always the org's current admins) and
974
+ cannot accept arbitrary members. Only the crew's **run stamps and
975
+ queued/running work** move to the org's orphan crew — memberships are never
976
+ among what moves.
977
+
978
+ **`rm` is idempotent.** Deleting a `<crewId>` that does not exist is a normal
979
+ success — the hub answers `200` with `deleted: false` rather than a `404` —
980
+ and the CLI prints this honestly (see below), plus a stderr line naming the
981
+ crew id, rather than inventing an error.
982
+
983
+ **Like [`capability unbind`](#capability-unbind-capability-crew), `crew rm` prints its tolerant
984
+ boolean on stdout** — `deleted` here, `removed` there. Both families report
985
+ honestly whether the call actually changed anything, and both narrate the
986
+ no-op case on stderr, so a script can branch on the boolean and a human reading
987
+ the terminal is told in words.
988
+
989
+ **The transfer fields are present on stdout if and only if the wire sent
990
+ them** — `membersRemoved`, `orphanCrewId`, `orphanCrewName`,
991
+ `stampsTransferred`, `runsTransferred` (an array of run ids, not a count), and
992
+ `runningRunsTransferred` (the subset still running, also an array) are never
993
+ defaulted to `0`/`null`/`[]`. Their absence means nothing moved; their
994
+ presence means a transfer happened, and stderr also gets a one-line human
995
+ summary naming the destination crew.
996
+
997
+ ### `crew member add <crewId> <principalKind> <principalId>`
998
+
999
+ `POST /api/add_crew_member` authenticated as your **human** credential;
1000
+ requires the **admin** role on the hub, **or** the owner of the personal crew
1001
+ being acted on (same self-service carve-out as `crew new`, gated on the
1002
+ fetched crew row rather than the raw request — `manage-crews.ts:300`). Adds
1003
+ `<principalId>` (a member id or an agent id) to the crew as a
1004
+ `<principalKind>` (`member` or `agent`) member. `<principalKind>` is forwarded
1005
+ verbatim and unvalidated, same stance as `--kind` on `crew new`.
1006
+
1007
+ **The hub refuses this outright against the org's orphan crew, for every
1008
+ caller — including an admin.** `assertNotOrphanPool` (`manage-crews.ts:307`)
1009
+ throws before the add ever reaches the membership table, and it is a `400`,
1010
+ never a `403`: the refusal is identity-independent (true for every caller, not
1011
+ a permissions question), so a `403` would wrongly point the caller at their
1012
+ own role. The orphan crew's membership is derived — always the org's current
1013
+ admins, reconciled automatically on every membership change — and cannot be
1014
+ edited directly.
1015
+
1016
+ ### `crew member rm <crewId> <principalId>`
1017
+
1018
+ `POST /api/remove_crew_member`, authenticated as your **human** credential;
1019
+ requires the **admin** role on the hub, **or** the owner of the personal crew
1020
+ being acted on (`manage-crews.ts:356`). Removes `<principalId>` from the crew.
1021
+
1022
+ **`member rm` is idempotent**, mirroring `crew rm`: removing a principal that
1023
+ was never a member of `<crewId>` is a normal `200` with `removed: false`, never
1024
+ a `404`. The CLI prints `removed: false` on stdout and a stderr line naming
1025
+ the principal and crew, rather than treating it as an error.
1026
+
1027
+ **Same orphan-crew refusal as `crew member add`.** Targeting the orphan crew
1028
+ is a `400` here too (`assertNotOrphanPool`, `manage-crews.ts:363`), for every
1029
+ caller including an admin, and for the same reason: the membership is derived,
1030
+ not editable.
1031
+
1032
+ **Flags.** `--hub <url>` only (plus the global `--db`/`--defs`), except `crew
1033
+ new`, which also takes `--kind` (required) and `--owner` (optional).
1034
+
1035
+ **Which hub gets acted on (`--hub`).** Identical resolution to the capability-route family: `--hub` if given, else the one hub your credential file stores, else
1036
+ exit 2 naming both remedies (and, on a multi-hub machine, listing the stored
1037
+ origins). No fallback to `OWENLOOP_HUB`
1038
+ or the built-in default hub; hub enumeration is file-store only.
1039
+
1040
+ **Printed JSON.** stdout is exactly one whitelisted JSON document per
1041
+ invocation — never a raw hub body — so `| jq` always works. Human-facing
1042
+ lines (the tolerant-false notices, the transfer summary) go to stderr only.
1043
+
1044
+ | subcommand | stdout |
1045
+ |---|---|
1046
+ | `crew list` | `{ "ok": true, "hub": "<origin>", "crews": [ { "id": "crw_1", "name": "team-a", "kind": "shared", "ownerMemberId": null, "createdBy": "u_1", "createdAt": 1738000000000, "orphan": false, "members": [ { "principalKind": "member", "principalId": "u_2", "addedBy": "u_1", "addedAt": 1738000000000 } ] } ] }` |
1047
+ | `crew new` | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "name": "team-a", "kind": "shared", "ownerMemberId": null }` |
1048
+ | `crew rm` (no transfer) | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "deleted": true, "membersRemoved": 2 }` |
1049
+ | `crew rm` (with transfer) | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "deleted": true, "membersRemoved": 2, "orphanCrewId": "crw_orphan", "orphanCrewName": "orphan:unrouted", "stampsTransferred": 5, "runsTransferred": ["run_1", "run_2"], "runningRunsTransferred": ["run_2"] }` |
1050
+ | `crew rm` (unknown id) | `{ "ok": true, "hub": "<origin>", "crewId": "crw_bogus", "deleted": false }` |
1051
+ | `crew member add` | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "principalKind": "member", "principalId": "u_2" }` |
1052
+ | `crew member rm` | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "principalId": "u_2", "removed": true }` |
1053
+
1054
+ **Exit codes.**
1055
+
1056
+ | code | meaning |
1057
+ |---|---|
1058
+ | `0` | the crew/membership was listed, created, removed (or was already absent) |
1059
+ | `1` | runtime or hub error — an unknown crew id on a member add/rm, a crew with active work refusing deletion, a `403` for a non-admin, a malformed response, or a network timeout |
1060
+ | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
1061
+ | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
1062
+
1063
+ ## `setup` — onboard a machine
1064
+
1065
+ `owenloop setup` is the one-shot onboarding command. It runs six ordered steps.
1066
+ Depending on the machine state, setup may store the human credential, mint or
1067
+ rekey and store a Scoped Identity credential, and write only `hubOrigin` in the
1068
+ execution settings file while preserving its other keys. The plugin step only
1069
+ probes whether the Claude Code plugin is installed; when the probe reports it
1070
+ missing, setup prints manual install commands but never runs those commands or
1071
+ installs the plugin. The steps:
1072
+
1073
+ 1. **inspect** — read-only report of what's already present (human credential,
1074
+ execution settings, `claude` on PATH, agent slots). No writes.
1075
+ 2. **human login** — verify the stored **human** credential, or run the same
1076
+ loopback-OAuth browser flow as `owenloop login` when none is present or it no
1077
+ longer verifies. This is the gate that makes step 3's mint/rekey legal.
1078
+ 3. **agent** — find a local `agent:<name>` slot that verifies live against the
1079
+ hub and reuse it; otherwise **mint** a new Scoped Identity or **rekey**
1080
+ (replace the credential of) an existing one. How the target is chosen is
1081
+ [below](#choosing-the-scoped-identity-flow-a-vs-flow-b).
1082
+ 4. **execution settings** — write only `hubOrigin` into the execution settings
1083
+ file so the local Step Agent talks to this hub, preserving every other key
1084
+ (skipped when `hubOrigin` already matches).
1085
+ 5. **plugin** — check whether the Claude Code `owenloop` plugin is installed.
1086
+ **Non-fatal:** while the marketplace is unpublished this step only *prints*
1087
+ the manual install commands (`claude plugin marketplace add owenloop` then
1088
+ `claude plugin install owenloop@owenloop`); it never fails setup.
1089
+ 6. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
1090
+ the same surfaces, whose result becomes setup's exit code.
1091
+
1092
+ Progress lines (the `[n/6]` headers and `✓`/`✗` marks) go to **stderr**; the
1093
+ final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
1094
+ **stdout**.
1095
+
1096
+ ### Choosing the Scoped Identity (Flow A vs Flow B)
1097
+
1098
+ When step 3 has to act (no reusable local agent slot), it decides *which* Scoped Identity
1099
+ to connect this machine to:
1100
+
1101
+ - **Flow A — fresh org (no Scoped Identities on the hub):** setup asks you to
1102
+ **name** the Scoped Identity, prefilled with a sanitized form of the machine hostname.
1103
+ The name is a suggestion — any label matching `[A-Za-z0-9][A-Za-z0-9._-]*`
1104
+ (1–64 chars) is accepted. It then **mints** that Scoped Identity.
1105
+ - **Flow B — org already has Scoped Identities (succession):** setup shows the existing
1106
+ Scoped Identities (each with its name, when it was **last active**, and its **crews**)
1107
+ and asks whether this is a *new* installation or one that *replaces* an
1108
+ existing Scoped Identity. Choosing **new** mints a fresh Scoped Identity; choosing **replace**
1109
+ **rekeys** the chosen Scoped Identity — which **revokes that Scoped Identity's current
1110
+ credential**, so if it is still running elsewhere it will be disconnected
1111
+ there.
1112
+
1113
+ **Non-interactive runs must pass a bypass flag.** When stdin is not a TTY (a
1114
+ scripted or piped run) and step 3 needs to act, setup will not block on a
1115
+ prompt — it errors unless you pre-decide with one of:
1116
+
1117
+ - `--new-agent <name>` — mint a new Scoped Identity named `<name>` (skips Flow A's name
1118
+ prompt and Flow B's succession prompt).
1119
+ - `--replace-agent <name>` — rekey the existing Scoped Identity named `<name>` (skips the
1120
+ succession prompt); errors if no such Scoped Identity exists on the hub.
1121
+
1122
+ The two flags are mutually exclusive. `--crews <a,b>` applies **only** to a mint
1123
+ (`--new-agent` or a fresh org); combining it with `--replace-agent` is a usage
1124
+ error, because rekeying preserves the Scoped Identity's existing crews (manage those in
1125
+ the console). `--scopes <a,b>` likewise applies **only** to a mint — it selects
1126
+ the minted token's scopes (default `work`); combining it with `--replace-agent`
1127
+ is a usage error, because rekeying preserves the Scoped Identity's existing scopes (mint a
1128
+ new Scoped Identity to change scopes). `setup` has no `--shift` shorthand — spell the
1129
+ scopes out with `--scopes work,run`.
1130
+
1131
+ ### Hub resolution differs from `agent new`
1132
+
1133
+ `setup` (and `doctor`) resolve the target hub like `agent new` with **one**
1134
+ deliberate difference: a brand-new machine with **no** stored hub falls back to
1135
+ the built-in **default hub** (printing a `targeting <hub>` notice to stderr)
1136
+ instead of exiting 2. That is safe here because the mint happens only *after*
1137
+ you sign in through that hub's own browser consent, and the target is printed
1138
+ first. Resolution order:
1139
+
1140
+ 1. `--hub <origin>` if given.
1141
+ 2. Otherwise the **one** hub your credential *file* stores, if exactly one is
1142
+ present.
1143
+ 3. More than one stored hub → **exit 2**, listing them so you can pass `--hub`.
1144
+ 4. Zero stored hubs (or a keychain/external backend that can't enumerate) →
1145
+ the **default hub**, with a printed notice.
1146
+
1147
+ ### A configured external credential command blocks setup
1148
+
1149
+ If `OWENLOOP_CREDENTIAL_COMMAND` is set, that command — not the local store —
1150
+ supplies this hub's credentials, so setup **refuses up front**, *before any
1151
+ browser opens*. Its human-login and agent-mint steps would write keys nobody
1152
+ reads; unset the variable to use `owenloop login` and the local store. (This is
1153
+ the same guard `agent new` applies, just moved ahead of the OAuth round-trip so
1154
+ the flagship command never opens a browser only to fail at the store.)
1155
+
1156
+ ### After setup
1157
+
1158
+ If the connected agent account is anything other than `default`, setup prints a
1159
+ reminder to run `owenloop work` with `OWENLOOP_ACCOUNT=<name>` so the Step Agent
1160
+ reads the right slot.
1161
+
1162
+ **Exit codes.**
1163
+
1164
+ | code | meaning |
1165
+ |---|---|
1166
+ | `0` | every step ended skipped/done/noted **and** doctor's core checks (1–5) passed |
1167
+ | `1` | setup ran but doctor's core checks did not all pass |
1168
+ | non-zero (thrown) | a hard failure — bad flags, unresolvable hub (2), 403 from the hub (setup needs an admin credential to manage Scoped Identities), a named `--replace-agent` that doesn't exist, or a configured external credential command |
1169
+
1170
+ ## `doctor` — check a machine's install
1171
+
1172
+ `owenloop doctor` is the **read-only** diagnostic behind setup's final step. It
1173
+ probes the same install surfaces and prints one `✓`/`✗` line per check to
1174
+ stderr, plus a `{ ok, hub, checks }` summary to stdout. It performs **no
1175
+ configuration writes** — no mint, rekey, slot create/delete, settings write, or
1176
+ browser. (The one unavoidable carve-out: verifying the human credential may
1177
+ rotate-and-persist an *expiring* human OAuth token, exactly as every authed
1178
+ command does — refreshing without persisting would strand the rotated refresh
1179
+ token and corrupt the install.)
1180
+
1181
+ The checks, in order:
1182
+
1183
+ | # | check | ✓ means | core |
1184
+ |---|---|---|---|
1185
+ | 1 | human credential | a human credential is stored for this hub | yes |
1186
+ | 2 | human plane | that credential verifies live against the hub (`whoami`) | yes |
1187
+ | 3 | agent slot | an `agent:<name>` credential is stored | yes |
1188
+ | 4 | agent plane | that agent credential verifies live against the hub | yes |
1189
+ | 5 | execution settings | the settings file's `hubOrigin` matches this hub | yes |
1190
+ | 6 | plugin | the Claude Code `owenloop` plugin is installed | **no** (rendered only) |
1191
+
1192
+ Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
1193
+ <origin>`, re-run setup's Replace, and so on). doctor never short-circuits — a
1194
+ machine with no working human credential still renders lines 3–6, degrading
1195
+ honestly rather than dropping them.
1196
+
1197
+ **Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise. The
1198
+ plugin check (6) is *rendered* but does not affect the exit code while the
1199
+ marketplace is unpublished.
1200
+
1201
+ ## `mcp` — stdio control-plane server for MCP hosts
1202
+
1203
+ `owenloop mcp` is a long-running server that exposes the hub's **human control
1204
+ plane** to a local MCP host (Claude Code, or any client that speaks MCP over
1205
+ stdio). This is the `owenloop-cli-mcp` surface: an MCP host spawns it as a
1206
+ subprocess — **you do not run it yourself at a prompt**. It reads
1207
+ newline-delimited JSON-RPC 2.0 on stdin, translates each `tools/call` into one
1208
+ authenticated HTTPS request to the hub's `/api/*` REST mirror, and writes the
1209
+ JSON-RPC reply on stdout. It runs until stdin closes (EOF), then exits `0`.
1210
+
1211
+ It authenticates as the logged-in **human**, using the same stored credential
1212
+ `login` writes and the same locked OAuth-refresh path the other hub commands
1213
+ use. It is never interactive: it never opens a browser and never starts a
1214
+ loopback listener. If no human credential is stored, a tool call returns an
1215
+ error telling you to run `owenloop login --hub <origin>` in a terminal and retry
1216
+ (see [Authentication and secrets](#authentication-and-secrets) below).
1217
+
1218
+ ### Choosing the hub origin
1219
+
1220
+ `owenloop mcp` binds to exactly one hub origin, resolved in this order:
1221
+
1222
+ 1. `--hub <url>` flag.
1223
+ 2. `OWENLOOP_HUB` env var.
1224
+ 3. If the **file** credential backend holds exactly ONE hub with a valid `human`
1225
+ credential, that hub is used.
1226
+ 4. Otherwise it exits `2` and prints why to stderr (nothing is written to
1227
+ stdout — stdout is the protocol channel).
1228
+
1229
+ There is **no** silent default-hub fallback: a control-plane server must never
1230
+ bind to a hub you did not name. The exit-`2` messages name both remedies:
1231
+
1232
+ - No hub credentials stored → `run \`owenloop login --hub <origin>\` first, or pass --hub <origin>`.
1233
+ - More than one hub stored → the message lists every stored origin and says `pass --hub <origin>`.
1234
+ - The credential store cannot be enumerated (macOS Keychain or an external
1235
+ credential command) → `pass --hub <origin> (or set OWENLOOP_HUB)`. Only the
1236
+ file backend can list stored origins, so on a Keychain-backed machine `mcp`
1237
+ effectively requires `--hub` or `OWENLOOP_HUB`.
1238
+
1239
+ A malformed `--hub`/`OWENLOOP_HUB` value is a normal exit-`1` error, like every
1240
+ other command.
1241
+
1242
+ ### Tools
1243
+
1244
+ The server exposes 17 baseline tools mirroring the hub's own MCP toolset, plus
1245
+ `create_agent`, plus four [crew](#crews) tools (`list_crews`, `create_crew`,
1246
+ `add_crew_member`, `remove_crew_member`) that do not mirror the hub's own MCP
1247
+ toolset. Each baseline tool's result is the hub REST response as one text
1248
+ block; a non-2xx response comes back as an error result.
1249
+
1250
+ | tool | what it does |
1251
+ |---|---|
1252
+ | `whats_next` | tick a workflow and get the next work order(s), or the inbox of started instances |
1253
+ | `submit` | submit a work order output |
1254
+ | `reject_artifact` | send an upstream artifact back to its producer with a reason |
1255
+ | `provide_input` | answer a human gate — provide a value for a seeded/owed input |
1256
+ | `start_run` | create a new instance from a definition name |
1257
+ | `create_workflow` | parse + load a workflow def YAML (the authoring hard gate) |
1258
+ | `get_workflow` | fetch one loaded definition |
1259
+ | `list_workflows` | names, titles, step counts, and def hash/version of every loaded def |
1260
+ | `get_status` | `engine.status` verbatim plus a plain-English rendering |
1261
+ | `heartbeat` | touch the liveness timestamp on an open run so it is not reaped mid-step |
1262
+ | `get_order` | re-fetch the persisted order packet and lease state for a run you hold |
1263
+ | `release` | give back a claim so its order is re-offered without waiting out the reap TTL |
1264
+ | `publish_event` | publish an event against a contract, starting one run per matched subscription |
1265
+ | `list_subscriptions` | the org's contract subscriptions |
1266
+ | `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 |
1267
+ | `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 |
1268
+ | `wake` | cheap "has anything changed since cursor X" pre-check for a polling loop |
1269
+ | `create_agent` | create a NEW Scoped Identity and store its credential locally — **never returns the token** |
1270
+ | `list_crews` | list the org's crews, each with its member rows inline — a plain passthrough, no filtering |
1271
+ | `create_crew` | create a crew (`name`, `kind`, optional `ownerMemberId`) |
1272
+ | `add_crew_member` | add a member or agent principal to a crew |
1273
+ | `remove_crew_member` | remove a principal from a crew (tolerant: removing a non-member is a normal result, not an error) |
1274
+
1275
+ `create_agent {name, crews?, scopes?}` mints a fresh Scoped Identity on the hub
1276
+ with `work` scope by default; pass `scopes` (e.g. `["work","run"]`) to choose the
1277
+ minted token's scopes. It then writes the minted `olp_` token straight to this
1278
+ machine's credential store (slot `agent:<name>`). The token is **never** returned in the
1279
+ tool result, printed, or logged — the result is `{name, crews, stored: true}`,
1280
+ built from scratch. It refuses a name that is already taken (the hub's error
1281
+ message is surfaced verbatim; error bodies never carry tokens). If the store
1282
+ write fails, the result says so and tells you to revoke/re-key the agent from
1283
+ the console.
1284
+
1285
+ **The four crew tools** (`list_crews`, `create_crew`, `add_crew_member`,
1286
+ `remove_crew_member`) cover the same four operations as the [`crew` CLI
1287
+ family](#crews) — `crew list`, `crew new`, `crew member add`, `crew member
1288
+ rm` — over the same `/api/*` routes and the same RBAC, but they are not an
1289
+ exact mirror of it: `crew rm` (crew deletion) has no MCP counterpart at all
1290
+ (see below), and where the CLI narrows each hub response into one
1291
+ whitelisted JSON document per invocation (`asPools`, `asPoolCreated`, etc.,
1292
+ so `| jq` always works), these MCP tools are plain passthroughs — the raw
1293
+ hub REST body maps straight to the tool result with no narrowing. Each
1294
+ argument schema deliberately has **no `enum`** on `kind`/`principalKind`,
1295
+ since the hub, not this client, is the enforcement of record for which
1296
+ values are legal.
1297
+
1298
+ Access is **not uniformly admin-only**: `create_crew`, `add_crew_member`, and
1299
+ `remove_crew_member` all carry the same self-service carve-out as their CLI
1300
+ counterparts — a human acting on a **personal crew they own** needs no admin
1301
+ role at all (`assertPoolMutationAllowed`); every other target (a `shared`
1302
+ crew, or a `personal` crew owned by someone else) still requires the admin
1303
+ role. `list_crews` is readable by any of `admin`/`author`/`operator`.
1304
+ `remove_crew_member` is **tolerant**: removing a principal that was never a
1305
+ member is a normal `200` result with `removed: false`, never a tool error.
1306
+ `add_crew_member` is **not** tolerant the same way — adding a principal that
1307
+ is already a member is a hub error, mapped to an `isError` result. Both
1308
+ `add_crew_member` and `remove_crew_member` refuse the org's orphan crew
1309
+ (`orphan:unrouted`) as a `400`, never a `403` — the refusal is
1310
+ identity-independent (it objects to the target crew, not the caller's role),
1311
+ since that crew's membership is derived from the org's current admins and
1312
+ cannot be edited directly.
1313
+
1314
+ **`delete_crew` is deliberately NOT a tool here.** Deleting a crew is a
1315
+ one-way-door operation gated admin-only unconditionally on the hub (unlike
1316
+ the other three verbs, which have the self-service carve-out above), and it
1317
+ was excluded from this MCP surface by design. `owenloop crew rm` on the CLI
1318
+ remains the only way to delete a crew; removing a single **member** (above)
1319
+ is a different, reversible operation and stays in scope for MCP.
1320
+
1321
+ One further tool, `stage_enrollment`, is **conditionally** registered — it
1322
+ appears only when the hub advertises the staging endpoint (or when
1323
+ `OWENLOOP_MCP_ENROLLMENT=1` forces it on). It returns a join code the new agent
1324
+ redeems; a join code is transferred authority, not a credential, so it is safe
1325
+ to surface in a tool result. When the endpoint is absent, the tool is hidden
1326
+ (fail-closed).
1327
+
1328
+ ### Authentication and secrets
1329
+
1330
+ Every tool call re-reads the stored `human` credential, refreshes it through the
1331
+ shared locked OAuth path if it is near expiry, and attaches it only as the
1332
+ `Authorization` header — the bearer never rides a tool result. Minted agent
1333
+ tokens (`create_agent`) are written to the local credential store and **never
1334
+ appear in any tool result, stderr line, or log**. If authentication fails
1335
+ (missing credential, refresh failure, or a final 401), the tool returns an error
1336
+ result whose text names the fix — run `owenloop login --hub <origin>` in a
1337
+ terminal — rather than prompting; the server itself never authenticates
1338
+ interactively.
1339
+
1340
+ ### Environment knobs
1341
+
1342
+ | variable | effect |
1343
+ |---|---|
1344
+ | `OWENLOOP_HUB` | hub origin when `--hub` is absent (rung 2 of origin resolution) |
1345
+ | `OWENLOOP_MCP_ENROLLMENT` | `1` forces `stage_enrollment` on, `0` off; unset = probe the hub |
1346
+ | `OWENLOOP_MCP_PROBE_TIMEOUT_MS` | deadline for the `stage_enrollment` capability probe (default `3000`) |
1347
+ | `OWENLOOP_HUB_TIMEOUT_MS` | per-request hub timeout (shared with the other hub commands) |
1348
+ | `OWENLOOP_CRED_LOCK_WAIT_MS` / `OWENLOOP_CRED_LOCK_POLL_MS` | credential-lock wait/poll knobs (shared) |
1349
+
496
1350
  ## Hand-driven walkthrough
497
1351
 
498
1352
  The [`examples/workflows`](../examples/workflows) folder has a workflow per
@@ -509,7 +1363,7 @@ codebase-advisor pipeline combining collections, a mid-flight human gate,
509
1363
  per-element knock-backs, and suffixed-reduce fan-ins). Each example's header
510
1364
  comment walks through its commands end to end.
511
1365
 
512
- Playing every worker yourself is the fastest way to internalize the loop.
1366
+ Playing every Step Agent yourself is the fastest way to internalize the loop.
513
1367
  Every command prints JSON, so the snippet below pipes through `jq`:
514
1368
 
515
1369
  ```sh
@@ -527,7 +1381,7 @@ owenloop defs # what workflows are available
527
1381
  wf=$(owenloop create delivery \
528
1382
  --provide proposal='{"text":"add dark mode"}' | jq -r .workflow)
529
1383
 
530
- # the worker loop: tick → run → report
1384
+ # the Step Agent loop: tick → run → report
531
1385
  run=$(owenloop tick $wf | jq -r '.orders[0].run') # claim the planner job
532
1386
  owenloop green $wf $run plan --value '{"plan":"…"}' # report its output
533
1387
 
@@ -554,7 +1408,7 @@ instead of waiting for the next tick. `owenloop reap <wf>` runs that same
554
1408
  cleanup on demand, applying the normal per-step/engine TTL rules — usually a
555
1409
  no-op (`{ reaped: 0, details: [] }`). `owenloop reap <wf> --now` is the admin
556
1410
  stand-down: it forces every currently-claimed task stale (TTL 0) regardless of
557
- how fresh its claim is, for reclaiming a worker you know is dead without
1411
+ how fresh its claim is, for reclaiming a Step Agent you know is dead without
558
1412
  waiting out the TTL. Reaping re-arms the task immediately, so **the run that
559
1413
  held the cleared lease can no longer commit** — its next `green`/`close` fails
560
1414
  with `run <id> no longer holds its lease (reaped or superseded)`, the same
@@ -594,13 +1448,13 @@ can be born-rejected too — a [judge's](authoring.md#judges--quality-gates-befo
594
1448
  verdict lands on a stale `submitted` version (a sibling judge already settled
595
1449
  it, the producer resubmitted, or a human bypassed it) and the CAS guard
596
1450
  refuses it. The result JSON is always written to stdout; the human-readable
597
- reason goes to stderr. A successful call exits 0 — a worker should treat a
1451
+ reason goes to stderr. A successful call exits 0 — a Step Agent should treat a
598
1452
  non-zero exit as a failure, not a success.
599
1453
 
600
1454
  ## What a job looks like
601
1455
 
602
1456
  `tick` returns `{ workflow, orders, reaped }`. Each order is self-contained —
603
- a worker needs nothing else to do the work:
1457
+ a Step Agent needs nothing else to do the work:
604
1458
 
605
1459
  ```jsonc
606
1460
  {
@@ -620,7 +1474,7 @@ a worker needs nothing else to do the work:
620
1474
  }
621
1475
  ```
622
1476
 
623
- A worker reads `prompt` + `consumes` + `owes`, does the work, reports with
1477
+ A Step Agent reads `prompt` + `consumes` + `owes`, does the work, reports with
624
1478
  `green` (or `emit`/`seal` for collections), then `close`s the job. The reject
625
1479
  counts in `owes[]` let a workflow escalate on its own — e.g. switch to a
626
1480
  stronger model after two rejections — before the engine stalls the step.
@@ -636,25 +1490,25 @@ is the earliest wake across all levels. A folded deferral in the deep result
636
1490
  carries its own `workflow` (absent = the root you ticked, present = a
637
1491
  descendant).
638
1492
 
639
- **Label routing (`--label`).** `tick <wf> --label <l>` (repeatable) filters
640
- which steps this caller claims, but only steps that carry their own `labels:`
641
- are ever excluded: a step is deferred with reason `label-mismatch` and left for
642
- another caller **only** when its `labels:` are non-empty and share no value with
643
- the filter you pass. A step with no `labels:` is claimed by every caller,
644
- filtered or not, and a tick that passes no `--label` claims every eligible step
645
- regardless of labels. This is **routing, not
1493
+ **Capability routing (`--capability`).** `tick <wf> --capability <l>` (repeatable) filters
1494
+ which steps this caller claims, but only steps that carry their own `capabilities:`
1495
+ are ever excluded: a step is deferred with reason `capability-mismatch` and left for
1496
+ another caller **only** when its `capabilities:` are non-empty and share no value with
1497
+ the filter you pass. A step with no `capabilities:` is claimed by every caller,
1498
+ filtered or not, and a tick that passes no `--capability` claims every eligible step
1499
+ regardless of capabilities. This is **routing, not
646
1500
  authorization**: any caller that can reach the database can tick without a
647
- filter and claim anything, so labels split work across cooperating
1501
+ filter and claim anything, so capabilities split work across cooperating
648
1502
  orchestrators, they never enforce a boundary. See
649
- [`labels:`](authoring.md#labels--routing-a-step-to-a-particular-tick-caller) in
1503
+ [`capabilities:`](authoring.md#capabilities--logical-capability-tags) in
650
1504
  the authoring guide for the step-side declaration and the starvation hazard to
651
1505
  watch for.
652
1506
 
653
1507
  **Child stalls on `status`.** `status <wf>`'s `calls:`-debt entries carry a
654
1508
  `child: { workflow, def, done, stalled, debts }` summary once a child has been
655
1509
  spawned. `child.stalled: true` means the child (or a grandchild below it) has a
656
- worker stuck at `maxAttempts` with no green outcome — the parent debt is blocked
657
- on stuck child work. This lets a conductor spot a wedged child from the parent
1510
+ Step Agent stuck at `maxAttempts` with no green outcome — the parent debt is blocked
1511
+ on stuck child work. This lets a Shift spot a wedged child from the parent
658
1512
  `status` alone, without separately walking into the child's own `status`.
659
1513
 
660
1514
  **`wait --until` is single-instance.** `wait <wf> --until eligible|done` polls