owenloop 0.4.1 → 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 (154) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +58 -31
  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/{cli.d.ts → src/cli.d.ts} +18 -3
  109. package/dist/{cli.js → src/cli.js} +770 -114
  110. package/dist/{credentials.d.ts → src/credentials.d.ts} +18 -12
  111. package/dist/{credentials.js → src/credentials.js} +14 -12
  112. package/dist/{defs.js → src/defs.js} +36 -36
  113. package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
  114. package/dist/{engine.js → src/engine.js} +14 -14
  115. package/dist/{hub.d.ts → src/hub.d.ts} +205 -10
  116. package/dist/{hub.js → src/hub.js} +370 -12
  117. package/dist/{index.d.ts → src/index.d.ts} +1 -1
  118. package/dist/{index.js → src/index.js} +1 -1
  119. package/dist/{mcp → src/mcp}/serve.d.ts +5 -4
  120. package/dist/{mcp → src/mcp}/serve.js +168 -31
  121. package/dist/{mcp → src/mcp}/server.d.ts +6 -9
  122. package/dist/{mcp → src/mcp}/server.js +6 -9
  123. package/dist/{model.js → src/model.js} +1 -1
  124. package/dist/{types.d.ts → src/types.d.ts} +18 -18
  125. package/dist/{util.d.ts → src/util.d.ts} +3 -2
  126. package/dist/{util.js → src/util.js} +3 -2
  127. package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
  128. package/dist/{owenwork.js → src/work-settings.js} +27 -27
  129. package/docs/authoring.md +93 -53
  130. package/docs/cli.md +597 -76
  131. package/docs/design.md +33 -33
  132. package/docs/embedding.md +10 -9
  133. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  134. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  135. package/examples/workflows/judges/gate-sharpness.md +39 -0
  136. package/examples/workflows/judges/security.md +34 -0
  137. package/package.json +17 -8
  138. /package/dist/{add.d.ts → src/add.d.ts} +0 -0
  139. /package/dist/{add.js → src/add.js} +0 -0
  140. /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
  141. /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
  142. /package/dist/{factory.js → src/factory.js} +0 -0
  143. /package/dist/{lock.d.ts → src/lock.d.ts} +0 -0
  144. /package/dist/{lock.js → src/lock.js} +0 -0
  145. /package/dist/{model.d.ts → src/model.d.ts} +0 -0
  146. /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
  147. /package/dist/{paths.js → src/paths.js} +0 -0
  148. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  149. /package/dist/{schema.js → src/schema.js} +0 -0
  150. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  151. /package/dist/{store.js → src/store.js} +0 -0
  152. /package/dist/{types.js → src/types.js} +0 -0
  153. /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
  154. /package/dist/{untar.js → src/untar.js} +0 -0
package/docs/cli.md CHANGED
@@ -49,13 +49,23 @@ for the full breakdown.
49
49
  | `connect [--hub <url>] [--as <slot>]` | bind this project to a hub (writes `.owenloop/hub.json`) and verify the credential |
50
50
  | `push [<defName>...] [--force] [--dry-run] [--as <slot>]` | publish local workflow defs to the bound hub (idempotent against the hub's own def hashes) |
51
51
  | `logout [--hub <url>] [--as <slot>]` | delete the stored credential for a hub |
52
- | `agent new <name> [--pools <a,b>] [--hub <url>]` | mint a new agent identity on the hub and store its token in slot `agent:<name>` — the token is never printed — see [Hub](#hub-login--connect--push--logout) |
53
- | `setup [--hub <url>] [--new-agent <name> \| --replace-agent <name>] [--pools <a,b>]` | converge this machine's install (human login, agent credential, owenwork settings, plugin) in one idempotent pass — see [`setup`](#setup--converge-a-machines-install) |
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) |
54
62
  | `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
55
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) |
56
66
  | `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
57
67
  | `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
58
- | `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 |
59
69
  | `reap <wf> [--now]` | run the reaper; `--now` forces every claim stale (TTL 0) — see below |
60
70
  | `runs <wf> [--open]` | list this instance's runs, joining claim state for open ones |
61
71
  | `status <wf>` | derived view: `done`, `debts`, `eligible`, `blocked`, `inFlight` |
@@ -73,6 +83,166 @@ for the full breakdown.
73
83
  | `delete <wf>` | delete an instance and all its rows |
74
84
  | `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
75
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
+
76
246
  ## `add` — installing shared workflow defs from GitHub
77
247
 
78
248
  `owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
@@ -256,13 +426,13 @@ ref) surfaces as a 404 from the sha-resolve step.
256
426
  **Trust model — what `add` does and does not protect.** Installing a package
257
427
  executes nothing at install time: `add` only fetches, validates, and writes
258
428
  YAML under the defs dir. But an installed def's steps *run* later, with
259
- whatever privileges the host process and its dispatcher grant their workers.
260
- owenloop itself never executes a step body — `worker:`/`command:` are opaque
261
- 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
262
432
  not](../README.md#what-owenloop-is-not) and
263
- [`docs/authoring.md`](authoring.md#worker--declaring-the-executor)) — so the
264
- real risk surface is the conductor or worker you point at these defs: the
265
- 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
266
436
  typically run with your full local privileges. **Install only sources you
267
437
  trust.**
268
438
 
@@ -280,7 +450,7 @@ install *step* — staged all-or-nothing validation with an atomic swap, path
280
450
  containment (including symlink-aware `bodyFile` checks), and archive resource
281
451
  bounds — not the def *content* that later executes. `add` validates a def's
282
452
  structure and contains its paths; it does not sandbox or sanitize what a step
283
- 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.
284
454
 
285
455
  **Untrusted-archive safety.** `add` treats the fetched repo as untrusted and
286
456
  refuses the whole install (nothing written) on any of these:
@@ -534,7 +704,7 @@ CLI.
534
704
 
535
705
  ### `agent new` — mint an agent token into a slot
536
706
 
537
- `owenloop agent new <name>` mints a new agent identity on the hub (`POST
707
+ `owenloop agent new <name>` mints a new Scoped Identity on the hub (`POST
538
708
  /api/mint_agent_token`, authenticated as your **human** credential) and stores
539
709
  the returned `olp_` token in the local credential slot `agent:<name>` — the same
540
710
  slot `login --as agent:<name>` writes and `push --as agent:<name>` reads. Use it
@@ -544,9 +714,10 @@ happen in one step, and you never handle the secret.
544
714
  **The token is never printed.** The minted `olp_` token goes process → store
545
715
  only — it never appears on stdout, stderr, in an error, or in a log (identity
546
716
  model §6, "rule of gates"). The confirmation JSON is built from a whitelist of
547
- **non-secret** fields only: `hub`, `name`, `slot`, `pools` (the resolved pool
548
- names), `scopes` (`["work"]`), `storage` (`keychain` | `file`), `agentId` (the
549
- agent's id), and `tokenId` (a revocation handle). To use the agent afterwards,
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,
550
721
  pass `--as agent:<name>` to `connect`/`push`; to revoke it, use its `tokenId`
551
722
  on the hub.
552
723
 
@@ -567,47 +738,350 @@ production hub while you're logged into a dev one. Note that hub enumeration is
567
738
  external-command backend cannot list their entries, so on such a machine step 2
568
739
  cannot enumerate the store and you must pass `--hub`.
569
740
 
570
- **`--pools <a,b>`.** A comma-separated list of pool names the token is granted
741
+ **`--crews <a,b>`.** A comma-separated list of crew names the token is granted
571
742
  on (trimmed, empties dropped). Omit the flag to let the hub default the token to
572
- the minter's personal pool; `--pools ""` (or `--pools ,`) is a usage error. Pool
743
+ the minter's personal crew; `--crews ""` (or `--crews ,`) is a usage error. Crew
573
744
  names are validated by the hub, not the client.
574
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
+
575
754
  **A configured external credential command blocks the mint.** If
576
755
  `OWENLOOP_CREDENTIAL_COMMAND` is set, that command — not the local store —
577
756
  supplies credentials for the hub, so `agent new` refuses up front (it has
578
757
  nowhere to write the minted token); unset the variable to use the local store.
579
- This check, the name validation, and the empty-`--pools` check all run **before**
580
- any network call, so a refusal never mints a server-side token first — a mint
581
- that then failed to store would burn the agent name permanently.
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.
582
762
 
583
763
  **Exit codes.**
584
764
 
585
765
  | code | meaning |
586
766
  |---|---|
587
767
  | `0` | minted and stored |
588
- | `1` | generic failure — invalid or already-taken name, pool/shape rejection, network timeout, or a token that minted but couldn't be 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 |
589
769
  | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
590
770
  | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
591
771
 
592
- ## `setup` — converge a machine's install
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:
593
868
 
594
- `owenloop setup` is the one-shot onboarding command. It brings a machine to a
595
- working install by converging six surfaces in order, each a **probe → (skip |
596
- act)** step — a step acts only when its probe fails, so a second run on an
597
- already-set-up machine performs **zero writes** (no store mutation, no settings
598
- write, no browser, no mint/rekey/register POST). The steps:
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:
599
1072
 
600
1073
  1. **inspect** — read-only report of what's already present (human credential,
601
- owenwork settings, `claude` on PATH, agent slots). No writes.
1074
+ execution settings, `claude` on PATH, agent slots). No writes.
602
1075
  2. **human login** — verify the stored **human** credential, or run the same
603
1076
  loopback-OAuth browser flow as `owenloop login` when none is present or it no
604
1077
  longer verifies. This is the gate that makes step 3's mint/rekey legal.
605
1078
  3. **agent** — find a local `agent:<name>` slot that verifies live against the
606
- hub and reuse it; otherwise **mint** a new agent identity or **rekey**
1079
+ hub and reuse it; otherwise **mint** a new Scoped Identity or **rekey**
607
1080
  (replace the credential of) an existing one. How the target is chosen is
608
- [below](#choosing-the-agent-flow-a-vs-flow-b).
609
- 4. **owenwork settings** — write `hubOrigin` into the owenwork settings file so
610
- the local worker talks to this hub (skipped when it already matches).
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).
611
1085
  5. **plugin** — check whether the Claude Code `owenloop` plugin is installed.
612
1086
  **Non-fatal:** while the marketplace is unpublished this step only *prints*
613
1087
  the manual install commands (`claude plugin marketplace add owenloop` then
@@ -619,20 +1093,20 @@ Progress lines (the `[n/6]` headers and `✓`/`✗` marks) go to **stderr**; the
619
1093
  final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
620
1094
  **stdout**.
621
1095
 
622
- ### Choosing the agent (Flow A vs Flow B)
1096
+ ### Choosing the Scoped Identity (Flow A vs Flow B)
623
1097
 
624
- When step 3 has to act (no reusable local agent slot), it decides *which* agent
1098
+ When step 3 has to act (no reusable local agent slot), it decides *which* Scoped Identity
625
1099
  to connect this machine to:
626
1100
 
627
- - **Flow A — fresh org (no agent identities on the hub):** setup asks you to
628
- **name** the agent, prefilled with a sanitized form of the machine hostname.
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.
629
1103
  The name is a suggestion — any label matching `[A-Za-z0-9][A-Za-z0-9._-]*`
630
- (1–64 chars) is accepted. It then **mints** that agent.
631
- - **Flow B — org already has agents (succession):** setup shows the existing
632
- agents (each with its name, when it was **last active**, and its **pools**)
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**)
633
1107
  and asks whether this is a *new* installation or one that *replaces* an
634
- existing agent. Choosing **new** mints a fresh agent; choosing **replace**
635
- **rekeys** the chosen agent — which **revokes that agent's current
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
636
1110
  credential**, so if it is still running elsewhere it will be disconnected
637
1111
  there.
638
1112
 
@@ -640,15 +1114,19 @@ to connect this machine to:
640
1114
  scripted or piped run) and step 3 needs to act, setup will not block on a
641
1115
  prompt — it errors unless you pre-decide with one of:
642
1116
 
643
- - `--new-agent <name>` — mint a new agent named `<name>` (skips Flow A's name
1117
+ - `--new-agent <name>` — mint a new Scoped Identity named `<name>` (skips Flow A's name
644
1118
  prompt and Flow B's succession prompt).
645
- - `--replace-agent <name>` — rekey the existing agent named `<name>` (skips the
646
- succession prompt); errors if no such agent exists on the hub.
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.
647
1121
 
648
- The two flags are mutually exclusive. `--pools <a,b>` applies **only** to a mint
1122
+ The two flags are mutually exclusive. `--crews <a,b>` applies **only** to a mint
649
1123
  (`--new-agent` or a fresh org); combining it with `--replace-agent` is a usage
650
- error, because rekeying preserves the agent's existing pools (manage those in
651
- the console).
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`.
652
1130
 
653
1131
  ### Hub resolution differs from `agent new`
654
1132
 
@@ -678,8 +1156,8 @@ the flagship command never opens a browser only to fail at the store.)
678
1156
  ### After setup
679
1157
 
680
1158
  If the connected agent account is anything other than `default`, setup prints a
681
- reminder to run owenwork with `OWENWORK_ACCOUNT=<name>` so the worker reads the
682
- right slot.
1159
+ reminder to run `owenloop work` with `OWENLOOP_ACCOUNT=<name>` so the Step Agent
1160
+ reads the right slot.
683
1161
 
684
1162
  **Exit codes.**
685
1163
 
@@ -687,7 +1165,7 @@ right slot.
687
1165
  |---|---|
688
1166
  | `0` | every step ended skipped/done/noted **and** doctor's core checks (1–5) passed |
689
1167
  | `1` | setup ran but doctor's core checks did not all pass |
690
- | non-zero (thrown) | a hard failure — bad flags, unresolvable hub (2), 403 from the hub (setup needs an admin credential to manage agents), a named `--replace-agent` that doesn't exist, or a configured external credential command |
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 |
691
1169
 
692
1170
  ## `doctor` — check a machine's install
693
1171
 
@@ -708,7 +1186,7 @@ The checks, in order:
708
1186
  | 2 | human plane | that credential verifies live against the hub (`whoami`) | yes |
709
1187
  | 3 | agent slot | an `agent:<name>` credential is stored | yes |
710
1188
  | 4 | agent plane | that agent credential verifies live against the hub | yes |
711
- | 5 | owenwork settings | the settings file's `hubOrigin` matches this hub | yes |
1189
+ | 5 | execution settings | the settings file's `hubOrigin` matches this hub | yes |
712
1190
  | 6 | plugin | the Claude Code `owenloop` plugin is installed | **no** (rendered only) |
713
1191
 
714
1192
  Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
@@ -764,7 +1242,9 @@ other command.
764
1242
  ### Tools
765
1243
 
766
1244
  The server exposes 17 baseline tools mirroring the hub's own MCP toolset, plus
767
- `create_agent`. Each baseline tool's result is the hub REST response as one text
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
768
1248
  block; a non-2xx response comes back as an error result.
769
1249
 
770
1250
  | tool | what it does |
@@ -783,20 +1263,61 @@ block; a non-2xx response comes back as an error result.
783
1263
  | `release` | give back a claim so its order is re-offered without waiting out the reap TTL |
784
1264
  | `publish_event` | publish an event against a contract, starting one run per matched subscription |
785
1265
  | `list_subscriptions` | the org's contract subscriptions |
786
- | `presence_ping` | register/refresh this conductor in the presence registry |
787
- | `list_conductors` | your principal's registered conductors and their online/offline state |
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 |
788
1268
  | `wake` | cheap "has anything changed since cursor X" pre-check for a polling loop |
789
- | `create_agent` | create a NEW agent identity and store its credential locally — **never returns the token** |
790
-
791
- `create_agent {name, pools?}` mints a fresh agent identity on the hub with
792
- `work` scope, then writes the minted `olp_` token straight to this machine's
793
- credential store (slot `agent:<name>`). The token is **never** returned in the
794
- tool result, printed, or logged — the result is `{name, pools, stored: true}`,
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}`,
795
1280
  built from scratch. It refuses a name that is already taken (the hub's error
796
1281
  message is surfaced verbatim; error bodies never carry tokens). If the store
797
1282
  write fails, the result says so and tells you to revoke/re-key the agent from
798
1283
  the console.
799
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
+
800
1321
  One further tool, `stage_enrollment`, is **conditionally** registered — it
801
1322
  appears only when the hub advertises the staging endpoint (or when
802
1323
  `OWENLOOP_MCP_ENROLLMENT=1` forces it on). It returns a join code the new agent
@@ -842,7 +1363,7 @@ codebase-advisor pipeline combining collections, a mid-flight human gate,
842
1363
  per-element knock-backs, and suffixed-reduce fan-ins). Each example's header
843
1364
  comment walks through its commands end to end.
844
1365
 
845
- 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.
846
1367
  Every command prints JSON, so the snippet below pipes through `jq`:
847
1368
 
848
1369
  ```sh
@@ -860,7 +1381,7 @@ owenloop defs # what workflows are available
860
1381
  wf=$(owenloop create delivery \
861
1382
  --provide proposal='{"text":"add dark mode"}' | jq -r .workflow)
862
1383
 
863
- # the worker loop: tick → run → report
1384
+ # the Step Agent loop: tick → run → report
864
1385
  run=$(owenloop tick $wf | jq -r '.orders[0].run') # claim the planner job
865
1386
  owenloop green $wf $run plan --value '{"plan":"…"}' # report its output
866
1387
 
@@ -887,7 +1408,7 @@ instead of waiting for the next tick. `owenloop reap <wf>` runs that same
887
1408
  cleanup on demand, applying the normal per-step/engine TTL rules — usually a
888
1409
  no-op (`{ reaped: 0, details: [] }`). `owenloop reap <wf> --now` is the admin
889
1410
  stand-down: it forces every currently-claimed task stale (TTL 0) regardless of
890
- 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
891
1412
  waiting out the TTL. Reaping re-arms the task immediately, so **the run that
892
1413
  held the cleared lease can no longer commit** — its next `green`/`close` fails
893
1414
  with `run <id> no longer holds its lease (reaped or superseded)`, the same
@@ -927,13 +1448,13 @@ can be born-rejected too — a [judge's](authoring.md#judges--quality-gates-befo
927
1448
  verdict lands on a stale `submitted` version (a sibling judge already settled
928
1449
  it, the producer resubmitted, or a human bypassed it) and the CAS guard
929
1450
  refuses it. The result JSON is always written to stdout; the human-readable
930
- 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
931
1452
  non-zero exit as a failure, not a success.
932
1453
 
933
1454
  ## What a job looks like
934
1455
 
935
1456
  `tick` returns `{ workflow, orders, reaped }`. Each order is self-contained —
936
- a worker needs nothing else to do the work:
1457
+ a Step Agent needs nothing else to do the work:
937
1458
 
938
1459
  ```jsonc
939
1460
  {
@@ -953,7 +1474,7 @@ a worker needs nothing else to do the work:
953
1474
  }
954
1475
  ```
955
1476
 
956
- A worker reads `prompt` + `consumes` + `owes`, does the work, reports with
1477
+ A Step Agent reads `prompt` + `consumes` + `owes`, does the work, reports with
957
1478
  `green` (or `emit`/`seal` for collections), then `close`s the job. The reject
958
1479
  counts in `owes[]` let a workflow escalate on its own — e.g. switch to a
959
1480
  stronger model after two rejections — before the engine stalls the step.
@@ -969,25 +1490,25 @@ is the earliest wake across all levels. A folded deferral in the deep result
969
1490
  carries its own `workflow` (absent = the root you ticked, present = a
970
1491
  descendant).
971
1492
 
972
- **Label routing (`--label`).** `tick <wf> --label <l>` (repeatable) filters
973
- which steps this caller claims, but only steps that carry their own `labels:`
974
- are ever excluded: a step is deferred with reason `label-mismatch` and left for
975
- another caller **only** when its `labels:` are non-empty and share no value with
976
- the filter you pass. A step with no `labels:` is claimed by every caller,
977
- filtered or not, and a tick that passes no `--label` claims every eligible step
978
- 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
979
1500
  authorization**: any caller that can reach the database can tick without a
980
- filter and claim anything, so labels split work across cooperating
1501
+ filter and claim anything, so capabilities split work across cooperating
981
1502
  orchestrators, they never enforce a boundary. See
982
- [`labels:`](authoring.md#labels--routing-a-step-to-a-particular-tick-caller) in
1503
+ [`capabilities:`](authoring.md#capabilities--logical-capability-tags) in
983
1504
  the authoring guide for the step-side declaration and the starvation hazard to
984
1505
  watch for.
985
1506
 
986
1507
  **Child stalls on `status`.** `status <wf>`'s `calls:`-debt entries carry a
987
1508
  `child: { workflow, def, done, stalled, debts }` summary once a child has been
988
1509
  spawned. `child.stalled: true` means the child (or a grandchild below it) has a
989
- worker stuck at `maxAttempts` with no green outcome — the parent debt is blocked
990
- 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
991
1512
  `status` alone, without separately walking into the child's own `status`.
992
1513
 
993
1514
  **`wait --until` is single-instance.** `wait <wf> --until eligible|done` polls