owenloop 0.4.1 → 0.5.1

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 (282) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +182 -53
  3. package/bin/owenloop.mjs +50 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +176 -0
  5. package/dist/packages/work/src/agent/brief.js +197 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +141 -0
  7. package/dist/packages/work/src/agent/loop.js +669 -0
  8. package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
  9. package/dist/packages/work/src/agent/model-policy.js +138 -0
  10. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  11. package/dist/packages/work/src/agent/workdir.js +319 -0
  12. package/dist/packages/work/src/bundle/cache.d.ts +92 -0
  13. package/dist/packages/work/src/bundle/cache.js +338 -0
  14. package/dist/packages/work/src/bundle/fetch.d.ts +87 -0
  15. package/dist/packages/work/src/bundle/fetch.js +345 -0
  16. package/dist/packages/work/src/bundle/types.d.ts +164 -0
  17. package/dist/packages/work/src/bundle/types.js +1 -0
  18. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  19. package/dist/packages/work/src/consumed-verifier.js +205 -0
  20. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  21. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  22. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  23. package/dist/packages/work/src/credentials/reader.js +32 -0
  24. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  25. package/dist/packages/work/src/credentials/resolve.js +56 -0
  26. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  27. package/dist/packages/work/src/exec/instructions.js +323 -0
  28. package/dist/packages/work/src/exec/loop.d.ts +40 -0
  29. package/dist/packages/work/src/exec/loop.js +332 -0
  30. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  31. package/dist/packages/work/src/exec/payload.js +54 -0
  32. package/dist/packages/work/src/exec/receipt.d.ts +41 -0
  33. package/dist/packages/work/src/exec/receipt.js +32 -0
  34. package/dist/packages/work/src/exec/runner.d.ts +71 -0
  35. package/dist/packages/work/src/exec/runner.js +256 -0
  36. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  37. package/dist/packages/work/src/harness/child-env.js +134 -0
  38. package/dist/packages/work/src/harness/claude.d.ts +140 -0
  39. package/dist/packages/work/src/harness/claude.js +837 -0
  40. package/dist/packages/work/src/harness/codex.d.ts +111 -0
  41. package/dist/packages/work/src/harness/codex.js +1024 -0
  42. package/dist/packages/work/src/harness/contract.d.ts +308 -0
  43. package/dist/packages/work/src/harness/contract.js +32 -0
  44. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  45. package/dist/packages/work/src/harness/fake.js +91 -0
  46. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  47. package/dist/packages/work/src/harness/jsonrpc-stdio.js +351 -0
  48. package/dist/packages/work/src/harness/permissions.d.ts +75 -0
  49. package/dist/packages/work/src/harness/permissions.js +182 -0
  50. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  51. package/dist/packages/work/src/harness/registry.js +45 -0
  52. package/dist/packages/work/src/harness/session-store.d.ts +181 -0
  53. package/dist/packages/work/src/harness/session-store.js +523 -0
  54. package/dist/packages/work/src/harness/types.d.ts +29 -0
  55. package/dist/packages/work/src/harness/types.js +14 -0
  56. package/dist/packages/work/src/harnesses.d.ts +38 -0
  57. package/dist/packages/work/src/harnesses.js +38 -0
  58. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  59. package/dist/packages/work/src/hold/loop.js +23 -0
  60. package/dist/packages/work/src/hold/mcp.d.ts +75 -0
  61. package/dist/packages/work/src/hold/mcp.js +264 -0
  62. package/dist/packages/work/src/hub/client.d.ts +23 -0
  63. package/dist/packages/work/src/hub/client.js +91 -0
  64. package/dist/packages/work/src/hub/types.d.ts +326 -0
  65. package/dist/packages/work/src/hub/types.js +26 -0
  66. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  67. package/dist/packages/work/src/lease/loop.js +277 -0
  68. package/dist/packages/work/src/main.d.ts +1 -0
  69. package/dist/packages/work/src/main.js +48 -0
  70. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  71. package/dist/packages/work/src/mcp/server.js +320 -0
  72. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  73. package/dist/packages/work/src/owenloop-bin.js +18 -0
  74. package/dist/packages/work/src/roles/agent-run.d.ts +124 -0
  75. package/dist/packages/work/src/roles/agent-run.js +529 -0
  76. package/dist/packages/work/src/roles/exec.d.ts +48 -0
  77. package/dist/packages/work/src/roles/exec.js +228 -0
  78. package/dist/packages/work/src/roles/hold.d.ts +72 -0
  79. package/dist/packages/work/src/roles/hold.js +363 -0
  80. package/dist/packages/work/src/roles/join.d.ts +18 -0
  81. package/dist/packages/work/src/roles/join.js +204 -0
  82. package/dist/packages/work/src/roles/lint.d.ts +58 -0
  83. package/dist/packages/work/src/roles/lint.js +234 -0
  84. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  85. package/dist/packages/work/src/roles/prepare.js +249 -0
  86. package/dist/packages/work/src/roles/release.d.ts +48 -0
  87. package/dist/packages/work/src/roles/release.js +137 -0
  88. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  89. package/dist/packages/work/src/roles/sessions.js +180 -0
  90. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  91. package/dist/packages/work/src/roles/settings.js +71 -0
  92. package/dist/packages/work/src/roles/shift.d.ts +13 -0
  93. package/dist/packages/work/src/roles/shift.js +250 -0
  94. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  95. package/dist/packages/work/src/roles/signals.js +62 -0
  96. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  97. package/dist/packages/work/src/settings/provision.js +47 -0
  98. package/dist/packages/work/src/settings/settings.d.ts +136 -0
  99. package/dist/packages/work/src/settings/settings.js +155 -0
  100. package/dist/packages/work/src/shift/client.d.ts +24 -0
  101. package/dist/packages/work/src/shift/client.js +124 -0
  102. package/dist/packages/work/src/shift/loop.d.ts +131 -0
  103. package/dist/packages/work/src/shift/loop.js +751 -0
  104. package/dist/packages/work/src/shift/protocol.d.ts +95 -0
  105. package/dist/packages/work/src/shift/protocol.js +24 -0
  106. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  107. package/dist/packages/work/src/shift/routing.js +50 -0
  108. package/dist/packages/work/src/shift/runtime.d.ts +45 -0
  109. package/dist/packages/work/src/shift/runtime.js +337 -0
  110. package/dist/packages/work/src/shift/server.d.ts +23 -0
  111. package/dist/packages/work/src/shift/server.js +716 -0
  112. package/dist/packages/work/src/shift/spawn.d.ts +109 -0
  113. package/dist/packages/work/src/shift/spawn.js +158 -0
  114. package/dist/packages/work/src/shift/state.d.ts +79 -0
  115. package/dist/packages/work/src/shift/state.js +385 -0
  116. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  117. package/dist/packages/work/src/submit-proof.js +93 -0
  118. package/dist/packages/work/src/usage.d.ts +6 -0
  119. package/dist/packages/work/src/usage.js +175 -0
  120. package/dist/src/add.d.ts +189 -0
  121. package/dist/src/add.js +300 -0
  122. package/dist/src/archive.d.ts +97 -0
  123. package/dist/src/archive.js +591 -0
  124. package/dist/src/bundle/index.d.ts +64 -0
  125. package/dist/src/bundle/index.js +508 -0
  126. package/dist/src/bundle/manifest.d.ts +50 -0
  127. package/dist/src/bundle/manifest.js +435 -0
  128. package/dist/src/bundle/runtime.d.ts +26 -0
  129. package/dist/src/bundle/runtime.js +64 -0
  130. package/dist/src/bundle/tar.d.ts +62 -0
  131. package/dist/src/bundle/tar.js +238 -0
  132. package/dist/src/bundle/types.d.ts +105 -0
  133. package/dist/src/bundle/types.js +21 -0
  134. package/dist/{cli.d.ts → src/cli.d.ts} +92 -7
  135. package/dist/src/cli.js +5968 -0
  136. package/dist/{credentials.d.ts → src/credentials.d.ts} +22 -15
  137. package/dist/{credentials.js → src/credentials.js} +35 -31
  138. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  139. package/dist/src/crypto/allowed-signers.js +307 -0
  140. package/dist/src/crypto/canonical.d.ts +8 -0
  141. package/dist/src/crypto/canonical.js +92 -0
  142. package/dist/src/crypto/chain.d.ts +65 -0
  143. package/dist/src/crypto/chain.js +377 -0
  144. package/dist/src/crypto/dsse.d.ts +209 -0
  145. package/dist/src/crypto/dsse.js +282 -0
  146. package/dist/src/crypto/enrollment.d.ts +78 -0
  147. package/dist/src/crypto/enrollment.js +186 -0
  148. package/dist/src/crypto/index.d.ts +48 -0
  149. package/dist/src/crypto/index.js +44 -0
  150. package/dist/src/crypto/keys.d.ts +258 -0
  151. package/dist/src/crypto/keys.js +908 -0
  152. package/dist/src/crypto/org-root.d.ts +33 -0
  153. package/dist/src/crypto/org-root.js +78 -0
  154. package/dist/src/crypto/origin-rules.d.ts +56 -0
  155. package/dist/src/crypto/origin-rules.js +143 -0
  156. package/dist/src/crypto/policy-floor.d.ts +98 -0
  157. package/dist/src/crypto/policy-floor.js +353 -0
  158. package/dist/src/crypto/records.d.ts +316 -0
  159. package/dist/src/crypto/records.js +157 -0
  160. package/dist/src/crypto/scope.d.ts +49 -0
  161. package/dist/src/crypto/scope.js +83 -0
  162. package/dist/src/crypto/ssh.d.ts +171 -0
  163. package/dist/src/crypto/ssh.js +396 -0
  164. package/dist/src/crypto/submission.d.ts +33 -0
  165. package/dist/src/crypto/submission.js +47 -0
  166. package/dist/src/crypto/trust-roots.d.ts +29 -0
  167. package/dist/src/crypto/trust-roots.js +39 -0
  168. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  169. package/dist/src/crypto/verify-consumed.js +259 -0
  170. package/dist/src/crypto/verify-origin.d.ts +50 -0
  171. package/dist/src/crypto/verify-origin.js +151 -0
  172. package/dist/src/crypto/verify-publication.d.ts +60 -0
  173. package/dist/src/crypto/verify-publication.js +150 -0
  174. package/dist/{defs.d.ts → src/defs.d.ts} +24 -1
  175. package/dist/{defs.js → src/defs.js} +181 -61
  176. package/dist/{engine.d.ts → src/engine.d.ts} +105 -9
  177. package/dist/{engine.js → src/engine.js} +251 -47
  178. package/dist/{factory.d.ts → src/factory.d.ts} +16 -0
  179. package/dist/{factory.js → src/factory.js} +16 -4
  180. package/dist/src/global-config.d.ts +59 -0
  181. package/dist/src/global-config.js +84 -0
  182. package/dist/{hub.d.ts → src/hub.d.ts} +280 -31
  183. package/dist/{hub.js → src/hub.js} +493 -52
  184. package/dist/src/index.d.ts +47 -0
  185. package/dist/src/index.js +41 -0
  186. package/dist/src/install.d.ts +538 -0
  187. package/dist/src/install.js +1981 -0
  188. package/dist/src/lock.d.ts +38 -0
  189. package/dist/src/lock.js +325 -0
  190. package/dist/src/mcp/serve.d.ts +109 -0
  191. package/dist/{mcp → src/mcp}/serve.js +335 -75
  192. package/dist/{mcp → src/mcp}/server.d.ts +6 -9
  193. package/dist/{mcp → src/mcp}/server.js +18 -10
  194. package/dist/{model.d.ts → src/model.d.ts} +15 -0
  195. package/dist/{model.js → src/model.js} +112 -2
  196. package/dist/src/order-resolver.d.ts +184 -0
  197. package/dist/src/order-resolver.js +252 -0
  198. package/dist/src/package-version.d.ts +10 -0
  199. package/dist/src/package-version.js +42 -0
  200. package/dist/{paths.d.ts → src/paths.d.ts} +14 -1
  201. package/dist/{paths.js → src/paths.js} +18 -0
  202. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  203. package/dist/src/schemas/index.d.ts +1416 -0
  204. package/dist/src/schemas/index.js +31 -0
  205. package/dist/src/schemas/order.v1.schema.json +106 -0
  206. package/dist/src/schemas/origin.v1.schema.json +68 -0
  207. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  208. package/dist/src/schemas/publication.v1.schema.json +31 -0
  209. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  210. package/dist/src/schemas/submission.v1.schema.json +61 -0
  211. package/dist/src/store/def-source.d.ts +52 -0
  212. package/dist/src/store/def-source.js +335 -0
  213. package/dist/src/store/index-file.d.ts +69 -0
  214. package/dist/src/store/index-file.js +151 -0
  215. package/dist/src/store/index.d.ts +27 -0
  216. package/dist/src/store/index.js +22 -0
  217. package/dist/src/store/ingestor.d.ts +43 -0
  218. package/dist/src/store/ingestor.js +211 -0
  219. package/dist/src/store/install.d.ts +228 -0
  220. package/dist/src/store/install.js +555 -0
  221. package/dist/src/store/instruction-source.d.ts +49 -0
  222. package/dist/src/store/instruction-source.js +298 -0
  223. package/dist/src/store/origin-evidence.d.ts +21 -0
  224. package/dist/src/store/origin-evidence.js +66 -0
  225. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  226. package/dist/src/store/pre-commit-verifier.js +418 -0
  227. package/dist/src/store/resolve.d.ts +138 -0
  228. package/dist/src/store/resolve.js +363 -0
  229. package/dist/src/store/types.d.ts +288 -0
  230. package/dist/src/store/types.js +356 -0
  231. package/dist/{types.d.ts → src/types.d.ts} +58 -24
  232. package/dist/{untar.d.ts → src/untar.d.ts} +8 -23
  233. package/dist/src/untar.js +38 -0
  234. package/dist/{util.d.ts → src/util.d.ts} +3 -2
  235. package/dist/{util.js → src/util.js} +3 -2
  236. package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
  237. package/dist/{owenwork.js → src/work-settings.js} +27 -27
  238. package/docs/agent-runner.md +86 -0
  239. package/docs/authoring.md +150 -59
  240. package/docs/bundles.md +250 -0
  241. package/docs/cli.md +1758 -163
  242. package/docs/crypto.md +816 -0
  243. package/docs/design.md +374 -52
  244. package/docs/embedding.md +135 -27
  245. package/docs/wire-contracts.md +380 -0
  246. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  247. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  248. package/examples/workflows/judges/gate-sharpness.md +39 -0
  249. package/examples/workflows/judges/security.md +34 -0
  250. package/package.json +22 -8
  251. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  252. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  253. package/plugins/claude-code/plugin/.mcp.json +14 -0
  254. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  255. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  256. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  257. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  258. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  259. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  260. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  261. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  262. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  263. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  264. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  265. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  266. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  267. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  268. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
  269. package/dist/add.d.ts +0 -384
  270. package/dist/add.js +0 -834
  271. package/dist/cli.js +0 -3270
  272. package/dist/index.d.ts +0 -32
  273. package/dist/index.js +0 -23
  274. package/dist/lock.d.ts +0 -80
  275. package/dist/lock.js +0 -217
  276. package/dist/mcp/serve.d.ts +0 -84
  277. package/dist/untar.js +0 -164
  278. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  279. /package/dist/{schema.js → src/schema.js} +0 -0
  280. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  281. /package/dist/{store.js → src/store.js} +0 -0
  282. /package/dist/{types.js → src/types.js} +0 -0
package/docs/cli.md CHANGED
@@ -22,10 +22,10 @@ prints this usage and exits 0 without doing any work.
22
22
 
23
23
  Boolean flags (`--force`, `--dry-run`, `--all`, `--open`, `--terminal`,
24
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.
25
+ `--strict-inputs`, `--unsigned`, and the bare `--now` on `reap`) never take a
26
+ following value — the next token is always a positional or the next `--flag`,
27
+ never consumed as this flag's argument. Use `--flag=value` (e.g. `--now=<ms>`
28
+ on `tick`) for flags that do take a value.
29
29
 
30
30
  `owenloop check <def>` defaults to treating `seedOwed` inputs as provided
31
31
  (`assumeProvided: true`), so a def whose only initial gate is an unprovided
@@ -44,18 +44,37 @@ for the full breakdown.
44
44
  |---|---|
45
45
  | `defs` | list available workflow definitions |
46
46
  | `add <owner>/<repo>[@ref]` | fetch, validate, and install a repo's workflow defs from GitHub (public repos only) — see below |
47
- | `add --recover` | finish or undo a crash-interrupted install, offline — no network call — see below |
47
+ | `add <bundle.wnlp \| https://url> [--global]` | install a workflow bundle into the content-addressed store — project store under the defs dir by default, `<home>/.owenloop/workflows` with `--global` — see below |
48
+ | `add --recover [--global]` | finish or undo a crash-interrupted install, offline — no network call (`--global` recovers the global store) — see below |
49
+ | `bundle pack <source-dir> [--output <bundle.wnlp>]` | create a deterministic `.wnlp` package without opening the local store — see [Bundles](#bundles) |
50
+ | `bundle unpack <bundle.wnlp> <destination-dir>` | strictly validate and atomically extract a `.wnlp` package — see [Bundles](#bundles) |
51
+ | `bundle inspect <bundle.wnlp>` | strictly validate a `.wnlp` package and print its manifest and file metadata — see [Bundles](#bundles) |
52
+ | `bundle digest <bundle.wnlp>` | print the SHA-256 digest of the uncompressed canonical tar — see [Bundles](#bundles) |
48
53
  | `login [--hub <url>] [--with-token] [--as <slot>]` | authenticate the CLI against a hub — loopback OAuth, or `--with-token` from stdin — see [Hub](#hub-login--connect--push--logout) |
49
- | `connect [--hub <url>] [--as <slot>]` | bind this project to a hub (writes `.owenloop/hub.json`) and verify the credential |
50
- | `push [<defName>...] [--force] [--dry-run] [--as <slot>]` | publish local workflow defs to the bound hub (idempotent against the hub's own def hashes) |
54
+ | `connect [--hub <url>] [--as <slot>]` | verify a resolved hub credential and record an optional per-project override in `.owenloop/hub.json` |
55
+ | `push [<defName>...] [--bundle <bundle.wnlp>] [--force] [--dry-run] [--hub <url>] [--as <slot>]` | publish local workflow defs, or exact bundle-backed defs, to the safely resolved hub (idempotent against the hub's own def hashes) |
56
+ | `start <defName> [--provide name=json …] [--crew <name>] [--title <text>] [--hub <url>]` | start a published workflow on the bound hub with the human credential |
57
+ | `publish <source-dir> [--output <bundle.wnlp>] [--source <json>] [--unsigned] [--hub <url>]` | pack a canonical workflow bundle and publish a signed publication sidecar, with an optional signed origin sidecar, or an explicitly unsigned marker |
51
58
  | `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) |
59
+ | `agent new <name> [--crews <a,b>] [--scopes <a,b>] [--shift] [--hub <url>]` | mint a new Scoped Identity on the hub and store its token in slot `agent:<name>` — the token is never printed; `--shift` = `--scopes work,run` — see [Hub](#hub-login--connect--push--logout) |
60
+ | `capability bind <capability> <crew> [--hub <url>]` | add a crew to a workflow capability on the hub org — a capability may route to many crews (admin; human credential) — see [Capability routes](#capability-routes) |
61
+ | `capability unbind <capability> <crew> [--hub <url>]` | remove one `(capability, crew)` route — see [Capability routes](#capability-routes) |
62
+ | `capability list [--hub <url>]` | list the hub org's capability routes — see [Capability routes](#capability-routes) |
63
+ | `crew list [--hub <url>]` | list the hub org's crews with their members (includes the orphan crew once one exists) — see [Crews](#crews) |
64
+ | `crew new <name> --kind personal\|shared [--owner <memberId>] [--hub <url>]` | create a crew on the hub org (admin, or own personal crew; human credential) — see [Crews](#crews) |
65
+ | `crew rm <crewId> [--hub <url>]` | delete a crew; work stamped to it moves to the org's orphan crew — see [Crews](#crews) |
66
+ | `crew member add <crewId> <principalKind> <principalId> [--hub <url>]` | add a member or agent to a crew — see [Crews](#crews) |
67
+ | `crew member rm <crewId> <principalId> [--hub <url>]` | remove a principal from a crew — see [Crews](#crews) |
68
+ | `setup [--hub <url>] [--new-agent <name> \| --replace-agent <name>] [--crews <a,b>] [--scopes <a,b>] [--reuse-ssh-key <path>]` | onboard this machine: may store human and Scoped Identity credentials, ensure the three principal signing keys, relay the machine enrollment grant, write only execution-settings `hubOrigin`, and converge the bundled plugins for Claude Code and Codex — see [`setup`](#setup--onboard-a-machine) |
69
+ | `enrollments [--hub <url>]` | read and locally classify the hub's relayed machine enrollment grants; never creates keys or writes the roster — see [`enrollments`](#enrollments--inspect-machine-enrollment) |
54
70
  | `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
55
71
  | `mcp [--hub <url>]` | serve the hub control plane to a local MCP host over stdio — spawned by MCP hosts, not run by humans — see [`mcp`](#mcp--stdio-control-plane-server-for-mcp-hosts) |
72
+ | `shift start <crew...>`, `shift next`, `shift status`, `shift end` | run the foreground shift daemon and its local clients — see [`shift`](#shift--foreground-daemon-and-client) |
73
+ | `work <subcommand> [options]` | run the execution-side CLI companion — see [`work`](#work--execution-side-cli-companion) |
74
+ | `trust init\|grant\|revoke` | create and sign local enrollment trust records offline — see [`trust`](#trust--local-enrollment-trust) |
56
75
  | `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
57
76
  | `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 |
77
+ | `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
78
  | `reap <wf> [--now]` | run the reaper; `--now` forces every claim stale (TTL 0) — see below |
60
79
  | `runs <wf> [--open]` | list this instance's runs, joining claim state for open ones |
61
80
  | `status <wf>` | derived view: `done`, `debts`, `eligible`, `blocked`, `inFlight` |
@@ -73,6 +92,342 @@ for the full breakdown.
73
92
  | `delete <wf>` | delete an instance and all its rows |
74
93
  | `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
75
94
 
95
+ ## Bundles
96
+
97
+ Bundle commands are deliberately dispatched before the CLI opens the engine
98
+ store. `bundle pack`, `bundle inspect`, `bundle digest`, and `bundle unpack`
99
+ read or write only the paths named by the command; they do not create
100
+ `.owenloop/state.db`, contact a remote coordinator, or use workflow definitions
101
+ from `--defs`. Successful commands print one JSON object on stdout. Failures
102
+ print a diagnostic on stderr and exit nonzero.
103
+
104
+ ```text
105
+ owenloop bundle pack <source-dir> [--output <bundle.wnlp>]
106
+ owenloop bundle unpack <bundle.wnlp> <destination-dir>
107
+ owenloop bundle inspect <bundle.wnlp>
108
+ owenloop bundle digest <bundle.wnlp>
109
+ ```
110
+
111
+ `pack` requires a source directory containing root `bundle.yaml` and every
112
+ workflow path listed by the manifest's `workflows` map. The source manifest is
113
+ not modified. If `--output` is omitted,
114
+ the output is `<package-name>-<version>.wnlp` next to the source directory. An
115
+ explicit output path must be outside the source directory. A regular file at
116
+ the output path may be replaced; a directory or other non-regular path is
117
+ rejected.
118
+
119
+ A format-v2 source manifest may declare the optional closed `runtime` mapping
120
+ documented in [`docs/bundles.md`](bundles.md#runtime-compatibility). `pack`
121
+ validates the current Owenloop version and advertised features before loading
122
+ usable workflows. When the declaration is present, successful pack JSON includes
123
+ a `runtime` property with `minVersion` before canonically UTF-8-sorted
124
+ `features`. When the declaration is absent, pack JSON does not gain a `runtime`
125
+ property; existing output remains unchanged.
126
+
127
+ `inspect` performs bounded gzip inflation, strict POSIX/PAX tar validation,
128
+ manifest and runtime-admission validation, workflow validation, lock coverage
129
+ checks, and per-file integrity checks without extracting files. Inspect JSON's
130
+ `manifest` includes `runtime` only when the archive declares it. A malformed
131
+ runtime declaration fails with `MANIFEST_ERROR`; a valid declaration requiring
132
+ a newer version or unsupported feature fails with `RUNTIME_INCOMPATIBLE` and
133
+ install/upgrade guidance.
134
+
135
+ `digest` performs bounded inflation and returns the lowercase SHA-256 of the
136
+ exact uncompressed canonical tar; the gzip wrapper bytes are not the identity.
137
+ `digest` is identity-only: it does not parse the manifest and may therefore
138
+ succeed for a canonical bundle that this Owenloop process cannot inspect,
139
+ unpack, install, load, or execute.
140
+
141
+ `unpack` performs the complete `inspect` validation before creating anything.
142
+ The destination must be absent. Files are written into a fresh sibling staging
143
+ directory and the staging directory is renamed into place only after all files
144
+ are written. Existing symlinked destination ancestors are rejected.
145
+
146
+ The manifest and archive rules are documented in
147
+ [`docs/bundles.md`](bundles.md). The public in-process equivalents are
148
+ `packBundle`, `inspectBundle`, `digestBundle`, and `unpackBundle` from the
149
+ package barrel.
150
+
151
+ ## `shift` — foreground daemon and client
152
+
153
+ `owenloop shift` is the public local dispatch surface. `shift start` runs the
154
+ self-driven dispatch loop as a foreground process and listens on
155
+ `<stateDir>/shift.sock`. Each client connection carries one JSON-line request
156
+ and one JSON-line response. The daemon keeps polling and dispatching while no
157
+ `shift next` client is attached.
158
+
159
+ The public daemon transport is supported on macOS and Linux. Windows support is
160
+ explicitly limited to the direct `owenloop work shift` loop: the public
161
+ `owenloop shift start|next|status|end` daemon is unavailable because Windows
162
+ named-pipe transport has not been implemented. A Windows daemon start fails
163
+ with that diagnostic instead of treating a Unix-domain socket path as usable.
164
+
165
+ The `shift start` positional argument is a **crew** name. The routing API calls
166
+ that field a **crew**: `serve_crews` contains the selected crew names. Passing
167
+ `--all` maps to an empty `serve_crews` list, which means all crews available to
168
+ the Scoped Identity. Do not treat `attended_at` as a liveness signal: every
169
+ accepted `shift next` records attendance and makes the next presence ping due,
170
+ but attendance is advisory and observability-only. Attendance never changes
171
+ routing, dispatch, or lease behavior.
172
+
173
+ The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
174
+ `XDG_CONFIG_HOME` is set to a non-blank value; otherwise it is
175
+ `$HOME/.config/owenloop/settings.json`.
176
+
177
+ ### `shift start <crew...>`
178
+
179
+ ```text
180
+ owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
181
+ [--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]
182
+ [--cache-dir <p>] [--state-dir <p>]
183
+ ```
184
+
185
+ At least one named crew is required unless `--all` is present. `--all` and
186
+ named crews are mutually exclusive. Duplicate named crews collapse to one
187
+ entry before routing. The daemon owns one socket at a time; a second start
188
+ against the same socket is refused. There is no detach mode. `--once` performs
189
+ one loop sweep and exits instead of keeping the foreground daemon running.
190
+
191
+ | option | default and behavior |
192
+ |---|---|
193
+ | `--origin <url>` | use this hub origin; otherwise use `hubOrigin` from the execution settings file; there is no hub-origin fallback |
194
+ | `--as <account>` | use this Scoped Identity account; defaults to `default` |
195
+ | `--name <n>` | use this shift name; otherwise generate one from the host and current directory with a process/shift suffix |
196
+ | `--cap <n>` | dispatch capacity; precedence is flag, then `settings.dispatchCap`, then `3` |
197
+ | `--max-agents <n>` | concurrent agent limit; precedence is flag, then `settings.maxConcurrentAgents`, then `4` |
198
+ | `--poll-interval <ms>` | loop polling interval; defaults to `5000` milliseconds |
199
+ | `--once` | run one loop sweep and exit; without it, keep the daemon in the foreground |
200
+ | `--cache-dir <p>` | cache root; precedence is flag, then `OWENLOOP_CACHE_DIR`, then `settings.cacheDir`, then `$XDG_CACHE_HOME/owenloop`, then `$HOME/.cache/owenloop` |
201
+ | `--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 |
202
+
203
+ A clean start or `--once` completion exits `0`. `owenloop shift --help` also
204
+ exits `0`. Runtime failures such as credential reads or socket/runtime setup
205
+ exit `1`. Usage and
206
+ precondition failures — including no crew or `--all`, invalid flags, a missing
207
+ hub origin, or a missing Scoped Identity credential — exit `2`. The foreground
208
+ daemon's normal lifecycle line is written to stdout when it stays running;
209
+ diagnostics go to stderr.
210
+
211
+ **Dispatch-state safety.** Every current-version direct Shift loop that shares a
212
+ state directory serializes the capacity recheck and durable reservation under
213
+ the same `.dispatch.lock`. The lock is released before process spawn; the per-run
214
+ reservation carries the capacity slot through spawn and PID persistence. Two
215
+ current-version loops therefore cannot both consume the same last slot, and a
216
+ loop that loses the shared-capacity race keeps its already-claimed candidate in
217
+ its local queue. Older Shift loops that predate `.dispatch.lock` do not
218
+ participate in that boundary and must not share the state directory during the
219
+ upgrade. The state directory does not persist one canonical cap: if current-
220
+ version loops sharing the directory are configured with different total or
221
+ agent caps, each loop enforces its own configured limits under the shared lock.
222
+ Use identical cap settings for every loop sharing a state directory.
223
+
224
+ Canonical `*.json` child and reservation records are capacity-bearing state.
225
+ Missing records are benign, including a record that disappears between listing
226
+ and read. A truncated, malformed, or unreadable canonical record is not benign:
227
+ reconciliation fails closed, names the exact path, and disables dispatch until
228
+ an operator repairs the record or removes the record after verifying that no
229
+ child still owns the slot. Owenloop does not skip corrupt records and guess that
230
+ capacity is free. Reconciliation also cancels a reservation when the worker has
231
+ removed its gate after the worker's monotonic two-minute wait, regardless of the
232
+ persisted wall-clock age. A reservation timestamp later than the current wall
233
+ clock is cancelled along with its closed start gate.
234
+
235
+ Persisted reservation age still uses wall time because a monotonic instant cannot
236
+ be reconstructed after a host restart. A smaller backward clock adjustment that
237
+ leaves `reservedAt` in the past can therefore prolong a reservation whose gate
238
+ still exists, such as a parent crash before spawn. The reservation remains
239
+ capacity-bearing until wall time reaches the age limit or an operator verifies
240
+ that no child can start and removes the record and gate. This limitation cannot
241
+ allow provider or command work past the gate: a spawned child independently
242
+ removes the gate and exits after its monotonic two-minute wait.
243
+
244
+ ### `shift next [--wait <seconds>]`
245
+
246
+ ```text
247
+ owenloop shift next [--wait <seconds>] [--state-dir <p>]
248
+ ```
249
+
250
+ `--wait` accepts a finite, non-negative number of seconds and defaults to `90`.
251
+ `--state-dir` selects the daemon socket. Only one `next` call may be parked at
252
+ a time. A second parked call returns this error and exits `1`:
253
+
254
+ ```text
255
+ whats_next is already parked — one park at a time (cancel it or wait for it to return)
256
+ ```
257
+
258
+ When a `next` request is accepted, the daemon stamps `attended_at`. The call
259
+ returns promptly when an event is queued, the wait expires, or the shift
260
+ explicitly ends. A normal timeout exits `0` and prints the current capacity
261
+ object, for example `{ "cap": 3, "free": 3, "running": 0, "events": [] }`.
262
+ Successful responses use the same capacity shape and may include queued event
263
+ objects. For `dispatched`, `reaped`, and `failed`, `kind` is either `exec` or
264
+ `agent-run`:
265
+
266
+ - `dispatched`: `{ "type": "dispatched", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "pid": 123 }`
267
+ - `reaped`: `{ "type": "reaped", "workflow": "...", "run": "...", "kind": "exec", "pid": 123 }`
268
+ - `failed`: `{ "type": "failed", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "message": "..." }`
269
+ - `ended`: `{ "type": "ended" }`, delivered to a parked `next` when `shift end` explicitly shuts down the daemon
270
+
271
+ `gate` is a reserved protocol shape for a future local representation of a
272
+ pending hub gate. Production code does not construct live hub gate events yet;
273
+ the local FIFO test and drill scope are recorded in
274
+ [`packages/work/test/shift-walkthrough.manual.md`](../packages/work/test/shift-walkthrough.manual.md).
275
+
276
+ If no daemon is listening, `next` exits `1` and prints the exact start guidance:
277
+
278
+ ```text
279
+ no shift daemon at <stateDir>/shift.sock — start one with: owenloop shift start <crew…>
280
+ ```
281
+
282
+ Invalid arguments exit `2`. Other client or daemon runtime failures exit `1`.
283
+ All successful client output is one JSON object on stdout; diagnostics are on
284
+ stderr.
285
+
286
+ ### `shift status [--state-dir <path>]`
287
+
288
+ ```text
289
+ owenloop shift status [--state-dir <p>]
290
+ ```
291
+
292
+ With a daemon, status exits `0` and prints:
293
+
294
+ ```json
295
+ { "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "attended_at": null, "started_at": 1738000000000 }
296
+ ```
297
+
298
+ `attended_at` remains `null` until the first accepted `next` request. Without a
299
+ daemon, status is still a successful question: it exits `0` and prints
300
+ `{ "status": "no daemon", "socket": "<path>" }`. Invalid arguments exit `2`;
301
+ other client/runtime errors exit `1`.
302
+
303
+ ### `shift end [--state-dir <path>]`
304
+
305
+ ```text
306
+ owenloop shift end [--state-dir <p>]
307
+ ```
308
+
309
+ An explicit end stops the loop, resolves an in-flight `next` with an `ended`
310
+ event, sends the final presence update with `attended_at` omitted so the hub
311
+ clears the attendance stamp, closes the socket, and prints
312
+ `{ "ok": true, "ended": true }` with exit `0`. Detached `exec` and `agent-run`
313
+ children remain alive to finish under their own leases. Signal shutdown (for
314
+ example, Ctrl-C) stops the daemon but does not synthesize the `ended` event or
315
+ perform the explicit attendance-clearing update.
316
+
317
+ If no daemon is listening, `end` exits `1` with the same start guidance as
318
+ `next`. Invalid arguments exit `2`; other client/runtime errors exit `1`.
319
+
320
+ ## `work` — execution-side CLI companion
321
+
322
+ The execution-side commands ship in the same `owenloop` npm package and use the
323
+ same `owenloop` binary. Replace the old separate `owenwork` invocation directly:
324
+
325
+ ```text
326
+ owenwork <subcommand> ... → owenloop work <subcommand> ...
327
+ ```
328
+
329
+ The transplanted subcommand names remain. The standing Shift daemon is
330
+ only the root `owenloop shift` command; `owenloop work` has no standing-daemon alias.
331
+ `hold --mcp` remains because the machine-attached hold mount still exists.
332
+ Run `owenloop work --help` for the full role-specific usage.
333
+
334
+ The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
335
+ `XDG_CONFIG_HOME` is set to a non-blank value; otherwise it is
336
+ `$HOME/.config/owenloop/settings.json`.
337
+
338
+ | subcommand | what it does |
339
+ |---|---|
340
+ | `hold --order <id> [options]` | hold an order with a heartbeating lease |
341
+ | `exec <order-id> [options]` | run a command order in a self-leasing loop |
342
+ | `agent-run <order-id> [options]` | host an agent order's Step Agent in a harness and self-leasing loop |
343
+ | `prepare <workflow> [--origin <url>]` | fetch, cache, and normalize step specs |
344
+ | `lint <workflow-name \| path>` | lint `x.harness` option bags in a workflow definition |
345
+ | `sessions [--all] [--json]` | list recorded harness sessions and how to reopen them |
346
+ | `release --session <id> [options]` | drain a session's held claims |
347
+ | `settings` | print the resolved execution settings file |
348
+ | `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
349
+
350
+ ### `work agent-run` — the only Step Agent dispatcher
351
+
352
+ `owenloop work agent-run` is the only supported way to dispatch an agent order.
353
+ The command resolves the verified local workflow definition, applies the final
354
+ `--harness` / environment / step harness selection, and checks every
355
+ `x.harness` restriction before cold start or resume. An unsupported restriction
356
+ starts no provider process, prints each exact refusal, releases the claim, and
357
+ exits `1`.
358
+
359
+ The Codex adapter refuses explicit `filesystem: read-only` and
360
+ `filesystem: workspace-write` before starting or resuming `codex app-server`.
361
+ The refusal is intentional: Codex configuration layers outside the thread
362
+ sandbox prevent the adapter from proving either neutral filesystem boundary.
363
+ Use the Claude Code adapter for the enforceable read-only/Owenloop-only policy,
364
+ or omit `filesystem` / declare `filesystem: unrestricted` only when the workflow
365
+ accepts the corresponding Codex behavior.
366
+
367
+ An absent `x.harness.tools` field preserves the adapter's default tool surface;
368
+ `tools: []` is an explicit empty allow-list. The two forms are not equivalent.
369
+ Invalid reserved fields and overlapping `tools` / `disallowedTools` are refused.
370
+ `owenloop work lint` runs the same common and adapter checks, but runtime
371
+ preflight remains authoritative because `--harness` or `OWENLOOP_HARNESS` can
372
+ select a different adapter after lint. See [Agent runner and harness policy](agent-runner.md)
373
+ for the capability matrix and the born-bound Owenloop control-plane exception.
374
+
375
+ **Harness-session durability.** `agent-run` records the provider session in the
376
+ machine-local `sessions.jsonl` log. The `active` row is a safety-critical gate:
377
+ the complete row and its trailing newline are written and fsynced before a
378
+ cold-start adapter may begin provider work or a resumed adapter may deliver new
379
+ feedback. Creating the log also fsyncs the containing directory where the
380
+ platform supports directory fsync. If the active append or fsync fails,
381
+ `agent-run` tears down the provider session, releases the order exactly once,
382
+ skips confirmation, writes no later lifecycle row, and exits with
383
+ `session-store-failed`. Later `turn-ended`, `submitted`, and `dead` rows keep
384
+ ordinary append durability; losing one causes conservative replay or retirement,
385
+ not unrecorded provider work. Compaction fsyncs the replacement before rename
386
+ and fsyncs the directory after rename so a successful compaction preserves a
387
+ previously durable active row.
388
+
389
+ ## `trust` — local enrollment trust
390
+
391
+ The `trust` commands create the local enrollment root and signed enrollment
392
+ records. The commands are offline: they do not contact a hub or other remote
393
+ coordinator, and the remote side cannot create, sign, or endorse these records.
394
+ The org root is stored separately from `PrincipalKeyManager` at the injected
395
+ configuration root described in [Signing and key storage](crypto.md#enrollment-chains-attenuation-and-revocation).
396
+
397
+ ```text
398
+ owenloop trust init [--force]
399
+ owenloop trust grant --key <pubkey-path> --principal <human|machine|agent>:<id> \
400
+ [--pools a,b|*] [--labels a,b|*] [--namespaces a,b|*] \
401
+ [--delegate no|<n>|unbounded] [--signing-key <path>] [--output <file>]
402
+ owenloop trust revoke --key <SHA256:…> --principal <kind>:<id> \
403
+ [--reason <text>] [--effective-from <epochMs>] \
404
+ [--signing-key <path>] [--output <file>]
405
+ ```
406
+
407
+ - `trust init` generates an Ed25519 org-root key pair under the local config
408
+ directory. The containing directory is `0700`, the private key is `0600`,
409
+ and the public key is `0644`. Existing root files are refused unless
410
+ `--force` is supplied. The command prints paths and status, never private key
411
+ bytes.
412
+ - `trust grant` reads an Ed25519 public key from `--key`, assigns it to the
413
+ `--principal`, and signs an `EnrollmentGrantRecord`. Each scope axis defaults
414
+ to an empty array (deny by default); `--delegate` defaults to `no`. The
415
+ signing key defaults to the local org root unless `--signing-key` is given.
416
+ The signed DSSE envelope is written to `--output`, or to the local roster
417
+ directory using a SHA-256 hash of the enrolled key ID as its filename.
418
+ - `trust revoke` signs a `RevocationRecord` for the `SHA256:…` key in `--key`.
419
+ The signing key defaults to the local org root. Without `--effective-from`,
420
+ the cut starts at issuance. With an earlier `--effective-from`, the CLI
421
+ derives `backdated: true`; the flag is never accepted as an independent
422
+ boolean. The signed envelope is written to `--output`, or to the local
423
+ revocations directory using a SHA-256 hash of the revoked key ID.
424
+
425
+ These commands print one JSON result on success. They refuse malformed
426
+ principals, fingerprints, scope lists, delegation values, and timestamps before
427
+ performing the related filesystem or signing work. Trust records are only
428
+ local inputs to the chain validator; transporting a signed envelope is a
429
+ separate concern.
430
+
76
431
  ## `add` — installing shared workflow defs from GitHub
77
432
 
78
433
  `owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
@@ -235,8 +590,8 @@ bounded — it only loads folders named by the fail-closed-validated
235
590
 
236
591
  - **Only under the default defs dir.** An explicit `--defs`/`OWENLOOP_DEFS` is
237
592
  operator intent to target a literal dir and keeps the pure-scan behavior with
238
- no fold-in — the rule is "was an override given", so even
239
- `OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
593
+ no installed-def or CAS-store fold-in — the rule is "was an override given",
594
+ so even `OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
240
595
  Pointing `--defs` straight at an install folder
241
596
  (`--defs workflows/<owner>-<repo>-<hash>`) still works exactly as before.
242
597
  - **Precedence.** Project-local (top-level) defs win over installed defs; among
@@ -256,13 +611,13 @@ ref) surfaces as a 404 from the sha-resolve step.
256
611
  **Trust model — what `add` does and does not protect.** Installing a package
257
612
  executes nothing at install time: `add` only fetches, validates, and writes
258
613
  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
614
+ whatever privileges the host process and its dispatcher grant their Step Agents.
615
+ owenloop itself never executes a step body — `executor:`/`command:` are opaque
616
+ fields it carries through untouched and never shells out (see [What owenloop is
262
617
  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
618
+ [`docs/authoring.md`](authoring.md#executor--declaring-the-executor)) — so the
619
+ real risk surface is the Shift or Step Agent you point at these defs: the
620
+ prompts and `command:` strings that ship in a package are handed to Step Agents that
266
621
  typically run with your full local privileges. **Install only sources you
267
622
  trust.**
268
623
 
@@ -280,7 +635,7 @@ install *step* — staged all-or-nothing validation with an atomic swap, path
280
635
  containment (including symlink-aware `bodyFile` checks), and archive resource
281
636
  bounds — not the def *content* that later executes. `add` validates a def's
282
637
  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.
638
+ body will do once a Step Agent runs it. That trust decision stays yours.
284
639
 
285
640
  **Untrusted-archive safety.** `add` treats the fetched repo as untrusted and
286
641
  refuses the whole install (nothing written) on any of these:
@@ -301,14 +656,501 @@ refuses the whole install (nothing written) on any of these:
301
656
  buffered into memory (the extraction limits above still re-check the size once
302
657
  the bytes are in hand).
303
658
  - **Request timeouts.** The sha-resolve fetch times out after 30s and the
304
- tarball download after 5 min, each surfacing as a friendly error.
659
+ tarball download after 5 min, each surfacing as a friendly error. The
660
+ bundle route applies the same 256 MiB cap and 5 min timeout to its file
661
+ read and URL fetch (see the next section).
662
+
663
+ ## `add` with bundles — the content-addressed workflow store
664
+
665
+ `owenloop add <owner>/<repo>[@ref]` (the previous section) installs
666
+ GitHub repos by name into `<defsDir>/<owner>-<repo>-<hash>/`. The **bundle**
667
+ route is a separate, content-addressed installation path for `.wnlp` workflow
668
+ bundles:
669
+
670
+ ```text
671
+ owenloop add widget.wnlp # install into the PROJECT store
672
+ owenloop add ./packs/widget.wnlp --global # install into the GLOBAL store
673
+ owenloop add https://example.com/widget.wnlp
674
+ owenloop add --recover [--global] # offline crash recovery (per root)
675
+ ```
676
+
677
+ The source is classified before anything else: `owner/repo[@ref]` keeps the
678
+ GitHub route byte-for-byte unchanged; a path ending in `.wnlp` is a bundle
679
+ file; an `http:`/`https:` URL is a bundle URL. Any other URL scheme
680
+ (`ftp:`, `file:`, …) is refused — never a silent fallback. `--global` applies
681
+ only to `.wnlp` bundle sources; a GitHub source with `--global` is refused
682
+ before any network request. The source string is origin data only (diagnostics
683
+ and messages); it is never joined into a filesystem path and never part of a
684
+ bundle's identity. Identity comes from the bundle's own
685
+ `namespace/name@version` coordinate and its canonical content digest.
686
+
687
+ **The `.wnlp` route requires two adapters and fails closed without them.**
688
+ Bundle ingestion (unpacking, manifest integrity, canonical digest,
689
+ coordinate) and pre-commit verification are separate modules with no
690
+ permissive fallback: with either adapter missing, `add` refuses with a named
691
+ error before any staging, journal, or index write. The default CLI binds both
692
+ production adapters. The pre-commit verifier consumes the publication sidecars
693
+ written by `publish` and applies the local `defPolicy` before the object or index
694
+ commit. Hosts that provide both adapters can install real `.wnlp` output from
695
+ `packBundle`; use the `publish` command to create the `.wnlp` bundle plus a
696
+ signed or explicitly unsigned sidecar.
697
+
698
+ ### Definition publication policy
699
+
700
+ `defPolicy` is the local execution and installation policy for workflow
701
+ publication signatures. The settings file is
702
+ `$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is non-blank,
703
+ otherwise `$HOME/.config/owenloop/settings.json`. To set the policy in the
704
+ settings file, write a JSON object such as:
705
+
706
+ ```json
707
+ {
708
+ "defPolicy": "enforce"
709
+ }
710
+ ```
711
+
712
+ For a one-off CLI invocation, set `OWENLOOP_DEF_POLICY` in the environment, for
713
+ example `OWENLOOP_DEF_POLICY=enforce owenloop add widget.wnlp`. The local
714
+ precedence is explicit host-provided policy, then `OWENLOOP_DEF_POLICY`, then
715
+ the settings file, then the built-in default `warn`. An invalid environment or
716
+ settings-file value fails loudly; it never degrades to `off`.
717
+
718
+ When a host supplies an already-verified organization policy floor through the
719
+ `policyFloor` option seam, the floor is applied **after** that local precedence.
720
+ `unsignedDefs: warn` raises the minimum to `warn`; `unsignedDefs: refuse` raises
721
+ the minimum to `enforce`; the effective policy is the stricter of local policy
722
+ and the floor. **Therefore, local `off` no longer means “no enforcement” when a
723
+ verified org floor is present.** A local operator cannot use `off` to opt out of
724
+ a verified floor. A missing, malformed, unsigned, wrongly signed, or
725
+ under-scoped floor leaves the local policy unchanged.
726
+
727
+ The current CLI and production configuration do not load or verify a floor.
728
+ `policyFloor` is an injection seam only, so this feature is inert until a host
729
+ wires floor loading and verification into that seam.
730
+
731
+ The policy applies at install time and again at execution time. The following
732
+ table describes the local policy result before any verified floor is applied.
733
+ The table uses these verdicts:
734
+
735
+ - `verified` — the publication sidecar verifies against the bundle digest and a
736
+ signer in the local trust root.
737
+ - `unsigned` — the bundle has no publication signature (including an explicit
738
+ `.wnlp.unsigned` sidecar).
739
+ - `unverifiable` — verification could not be completed, such as when the trust
740
+ root is missing or malformed.
741
+ - `invalid` — a present publication signature fails verification, including a
742
+ digest or signer mismatch.
743
+
744
+ | publication verdict | `enforce` | `warn` | `off` |
745
+ |---|---|---|---|
746
+ | `verified` | Install succeeds; agent and command execution proceed. | Install succeeds; agent and command execution proceed. | Install succeeds; agent and command execution proceed. |
747
+ | `unsigned` or `unverifiable` | Install refuses; agent and command execution refuse. | Install warns to stderr and succeeds; agent execution warns and proceeds; command execution refuses. | Install succeeds silently; agent execution proceeds silently; command execution refuses. |
748
+ | `invalid` | Install refuses; agent and command execution refuse. | Install refuses; agent and command execution refuse. | Install refuses; agent and command execution refuse. |
749
+
750
+ **Command-worker hard rule.** A `worker: command` order requires full
751
+ enforcement in every policy value, including `off`: the definition must be
752
+ verified, the enrollment chain must be verified, and the signer scope must be
753
+ checked. `off` does not disable command-worker enforcement. `warn` and `off`
754
+ never allow an unsigned, unverifiable, or invalid definition to reach the
755
+ shell. The command check runs before the policy value is read, and a refusal
756
+ uses the normal `InstructionRefusal` path so the lease stops before command
757
+ execution. A policy floor cannot relax this gate; the gate also fails closed
758
+ regardless of any floor. If an execution host has no publication verifier
759
+ configured, the definition is `unverifiable`; command workers therefore refuse
760
+ rather than treating installed bytes as published trust.
761
+
762
+ ### Consume-side artifact policy
763
+
764
+ `artifactPolicy` controls how agent and MCP drivers handle absent evidence and
765
+ missing local prerequisites for signed dynamic artifact values. Supplied but
766
+ invalid evidence always refuses; the policy is a scalar with the same values as
767
+ `defPolicy`: `enforce`, `warn`, or `off`. The precedence is explicit host
768
+ option, then `OWENLOOP_ARTIFACT_POLICY`, then the `artifactPolicy` key in the
769
+ execution settings file, then the built-in default `warn`.
770
+
771
+ For example, the settings file can contain:
772
+
773
+ ```json
774
+ {
775
+ "artifactPolicy": "enforce"
776
+ }
777
+ ```
305
778
 
306
- ## Hub (`login` / `connect` / `push` / `logout`)
779
+ A one-off invocation can set
780
+ `OWENLOOP_ARTIFACT_POLICY=enforce owenloop work agent-run <order-id>`.
781
+ Invalid values fail loudly; an invalid value never becomes `off`.
782
+
783
+ The consuming driver verifies each delivered value against its serialized DSSE
784
+ submission proof, the signed value digest and version, the locally anchored
785
+ producer enrollment chain, revocations, and any supplied consuming demand's
786
+ scope. A missing proof is not the same as invalid evidence. Dynamic values and
787
+ rejection reasons remain on the wire; the driver verifies those values and
788
+ refuses the whole order on failure rather than dropping only one path.
789
+
790
+ A valid historical proof is not enough to establish the version claimed for the
791
+ current delivery. Ordinary consumed artifacts bind the signed version to the
792
+ claim-time version in `consumedFingerprint`; owed rejection reasons bind to the
793
+ owed claim-time version. If that authoritative expected version is absent, the
794
+ verdict is `unverifiable`, never `verified`, even when the signature, value
795
+ digest, and enrollment chain all verify. The policy table therefore applies
796
+ without a hidden exception: `enforce` refuses that artifact, `warn` warns and
797
+ admits it, and `off` admits it without calling the proof verified. The
798
+ command-worker hard rule below still refuses it under every policy.
799
+
800
+ The current production `exec`, `agent-run`, and `hold` roles do not supply a
801
+ pool, label, or namespace demand. `OrderPacket` has no such demand field to
802
+ derive, so production consume gates enforce the enrollment chain, attenuation,
803
+ and revocation checks but do not apply a demand-dependent `scopePermits`
804
+ restriction. A caller that supplies a demand through the verifier seam gets the
805
+ full scope check. This limitation is a named follow-up.
806
+
807
+ | consumed-evidence verdict | `artifactPolicy=enforce` | `artifactPolicy=warn` | `artifactPolicy=off` |
808
+ |---|---|---|---|
809
+ | `verified` | admit | admit | admit |
810
+ | `absent` | refuse | warn and admit | admit |
811
+ | `unverifiable` | refuse | warn and admit | admit |
812
+ | `invalid` | refuse | refuse | refuse |
813
+
814
+ A refusal is an actionable integrity event. The refusal names the failed link
815
+ and artifact, using names such as `no-proof`, `signature`, `value-digest`,
816
+ `version`, `chain`, `scope`, or `prerequisite`, and includes the workflow, run,
817
+ and step. The driver refuses the whole order; operators must not suppress the
818
+ message or continue with a manually stripped packet.
819
+
820
+ The policy floor's `unsignedArtifacts: warn` value raises the local minimum to
821
+ `artifactPolicy=warn`; `unsignedArtifacts: refuse` raises it to `enforce`. A
822
+ verified floor is merged after local precedence, so local `off` cannot weaken
823
+ the floor.
824
+
825
+ **Command-worker hard rule.** A `worker: command` order refuses `absent`,
826
+ `unverifiable`, and `invalid` consumed evidence regardless of `artifactPolicy`,
827
+ including `off`. The consume-side gate runs before origin or artifact policy
828
+ lookup and before a shell command is built or passed to `/bin/sh -c`. A command
829
+ worker must have a configured consume-side verifier; an unverified dynamic value
830
+ must never reach the shell. Agent prompt rendering and MCP `get_order` likewise
831
+ fail closed when dynamic data exists but no verifier is configured. The driver
832
+ samples the consumer's injected clock once per complete gate invocation; a
833
+ revocation effective at `effectiveFrom <= at` makes a previously consumable
834
+ artifact unconsumable on a later invocation.
835
+
836
+ ### Definition origin policy
837
+
838
+ `originRules` is a separate namespace-scoped provenance policy. A signed file
839
+ publication may include `<bundle>.origin.dsse`; installation verifies that
840
+ sidecar against the local `allowed_signers` root and retains the exact bytes at
841
+ `<store-root>/.owenloop/origins/<digest>.dsse`. Execution re-verifies the
842
+ retained evidence against the current trust root. Only a `verified` origin
843
+ verdict is retained. A bundle carrying only `<bundle>.origin.dsse` — with
844
+ neither a publication `.dsse` nor an unsigned marker — is refused at install for
845
+ every origin-policy value, including `off`. `publish` never emits that shape;
846
+ `--unsigned` removes both sidecars. A hub or other remote coordinator may relay
847
+ the sidecar, but never authors or supplies the origin rule.
848
+
849
+ The origin mode uses the same policy values as `defPolicy` — `enforce`, `warn`,
850
+ and `off` — and follows the same scalar precedence: explicit host option,
851
+ `OWENLOOP_ORIGIN_POLICY`, settings-file `originPolicy`, then `warn`. These are
852
+ not trust modes: `Seamless`, `Strict`, and `Paranoid` are a separate axis;
853
+ `Seamless` maps to `warn`, `Strict` maps to `enforce`, and `off` is a local
854
+ operator escape hatch with no trust-mode equivalent. The rule map has no
855
+ environment-variable spelling: explicit host `originRules`, then settings-file
856
+ `originRules`, then an empty map. A namespace with no matching rule has no origin
857
+ requirement. A malformed rule map is a named settings error, not an empty-policy
858
+ fallback.
859
+
860
+ Rules accept exact namespaces (`prod`), namespace prefixes (`prod*`), and
861
+ trailing `/*` sugar (`prod/*`, equivalent to `prod`). `*` and `*/*` are
862
+ catch-all rules. Exact matches beat prefixes; the longest prefix wins; keys
863
+ that normalize to equal specificity, such as `prod` and `prod/*`, are rejected.
864
+ Rule values are minimum provenance strengths, ordered `git` > `console` >
865
+ `agent`; therefore a `console` rule accepts verified `git` and `console`
866
+ origins, and an `agent` rule accepts all three. `any` imposes no requirement.
867
+
868
+ Origin verdicts remain distinct:
869
+
870
+ - `verified` has a strength and is checked against the selected minimum.
871
+ - `absent` means no origin bytes are available. For a signed file publication,
872
+ this means no sidecar was recorded. Unsigned publications and non-file install
873
+ sources also produce `absent`, but those definitions structurally cannot carry
874
+ an origin; those cases must not be described as “no origin was recorded.”
875
+ - `unverifiable` means a prerequisite such as the trust root is unavailable.
876
+ - `invalid` means present origin evidence failed verification and is refused at
877
+ every origin mode, including `off`.
878
+
879
+ For a matched rule, the local origin mode behaves as follows:
880
+
881
+ | origin verdict | `originPolicy=enforce` | `originPolicy=warn` | `originPolicy=off` |
882
+ |---|---|---|---|
883
+ | `verified` meeting the minimum | Install and execution succeed. | Install and execution succeed. | Install and execution succeed. |
884
+ | `verified` weaker than the minimum | Install refuses; execution refuses. | Install warns and succeeds; execution warns and proceeds. | Install and execution proceed silently. |
885
+ | `absent` or `unverifiable` | Install refuses; execution refuses. | Install warns and succeeds; execution warns and proceeds. | Install and execution proceed silently. |
886
+ | `invalid` | Install refuses; execution refuses. | Install refuses; execution refuses. | Install refuses; execution refuses. |
887
+
888
+ The table applies only when a rule matches. During execution, the driver
889
+ recovers the namespace by reverse-scanning project and global store indexes for
890
+ the bundle digest. Equivalent requirements deduplicate. Different requirements
891
+ produce a named ambiguity refusal. If no coordinate is indexed, `enforce`
892
+ refuses, `warn` warns, and `off` proceeds. With an empty `originRules` map, the
893
+ default resolver still invokes the origin verifier once per order, but skips the
894
+ expensive index reverse-scan; invalid retained origin evidence still refuses.
895
+
896
+ A verified policy floor maps `originRules: advisory` to minimum
897
+ `originPolicy=warn` and `originRules: enforced` to minimum
898
+ `originPolicy=enforce`. The origin floor is parallel to the publication floor;
899
+ it does not alter `defPolicy`.
900
+
901
+ **Origin policy never relaxes the command-worker hard rule.** A
902
+ `worker: command` order must pass the publication verification gate first, even
903
+ when `defPolicy=off`, and only then runs the origin check. Unsigned,
904
+ unverifiable, or invalid publication evidence never reaches the shell. An
905
+ origin mode of `off` and every policy-floor preset leave that gate unchanged.
906
+
907
+ The local SSHSIG trust root is
908
+ `$XDG_CONFIG_HOME/owenloop/allowed_signers`, or
909
+ `$HOME/.config/owenloop/allowed_signers` when `XDG_CONFIG_HOME` is blank. A
910
+ missing or malformed trust root is `unverifiable`, not `unsigned`.
911
+
912
+ ### The two store roots
913
+
914
+ A store root holds exactly this layout:
915
+
916
+ ```text
917
+ <root>/
918
+ index.json # coordinate → {digest, pinned, workflows?} index
919
+ objects/
920
+ sha256/
921
+ <64-hex-content-digest>/ # one immutable object per digest
922
+ … # the bundle's files
923
+ .owenloop/ # per-root lock + crash journal
924
+ add.lock
925
+ add.journal
926
+ .owenloop-staging/ # transient staging (cleared on exit)
927
+ ```
928
+
929
+ - **Project store root** = the resolved defs directory itself (`--defs`,
930
+ `OWENLOOP_DEFS`, or `./workflows`). The project's pins are reviewable in
931
+ git there, and the nested `objects/sha256/<digest>/` layout stays below
932
+ the def loader's scan depth.
933
+ - **Global store root** = `<home>/.owenloop/workflows`. `--global` selects it;
934
+ it cannot be combined with `--defs` (the global store has a fixed
935
+ home-directory location, so an override would only create ambiguity —
936
+ refused with a clear message). The global root is never used by the
937
+ GitHub route.
938
+
939
+ **Injected home requirement.** `<home>` is the first non-blank value from the
940
+ caller-injected `HOME` and `USERPROFILE` environment variables (`HOME` wins).
941
+ The `.wnlp` bundle route uses the same injected home for its default external
942
+ recovery-marker directory, `<home>/.owenloop/recovery-markers`, even when the
943
+ bundle targets the project store. If neither variable is supplied, bundle
944
+ installation refuses before any object or index commit; it never falls back to
945
+ the process user's ambient home. `add --recover --global` has the same
946
+ requirement. Project recovery of a v2 fresh-install journal also refuses when
947
+ its recovery marker requires a home and neither variable is supplied.
948
+
949
+ Every object path derives ONLY from its validated digest (lowercase 64-hex).
950
+ Coordinates, source strings, and version text never join into a path.
951
+
952
+ ### What an install does, in order
953
+
954
+ 1. Read the bundle bytes (file or URL) *before* taking the lock — a slow
955
+ download never holds the project lock. A local `.wnlp` must be a bounded
956
+ regular file: missing, symlinked, non-regular, or over the 256 MiB cap
957
+ (checked before *and* after the read) is refused naming the path as
958
+ given. A URL fetch uses the same 5 min timeout, refuses redirects
959
+ (`redirect: 'error'`) instead of following them silently, and streams
960
+ through the same bounded reader.
961
+ 2. Acquire the canonical root lock at `<root>/.owenloop/add.lock`. A GitHub
962
+ install also retains its legacy cwd-derived lock for compatibility and, when
963
+ the resolved `--defs` root differs from that cwd, acquires both locks in a
964
+ fixed order. The canonical lock makes bundle installs from different cwd
965
+ values serialize when they target one shared `--defs` root; the additional
966
+ GitHub lock keeps the legacy route compatible.
967
+ 3. Recover a prior interrupted install (before clearing staging — the
968
+ backups a rollback needs live under the staging root).
969
+ 4. Reread and validate the index **inside** the lock (a corrupt index is a
970
+ hard error, never a silent reset).
971
+ 5. Ingest via the bundle adapter: unpack into staging, check manifest
972
+ integrity and runtime compatibility, compute the canonical digest, and
973
+ extract the full coordinate. The runtime check uses Owenloop's production
974
+ package version and advertised feature set. A tampered, malformed, or
975
+ runtime-incompatible bundle stops here — staging debris only, nothing
976
+ committed.
977
+ 6. Validate the staged tree with the engine's strict pass — the exact bytes
978
+ that will be committed (parse/lint/validate/bounded `check` + the strict
979
+ cross-def backstop). For a real `.wnlp`, validation parses `bundle.yaml`
980
+ through the same runtime-admission boundary and loads every workflow path
981
+ listed in its `workflows` map; the package manifest itself is not treated as
982
+ a workflow definition. Any problem refuses the whole install and prints
983
+ every reason.
984
+ 7. Run the pre-commit verifier (after content validation, before any swap or
985
+ index write). A rejection commits nothing.
986
+ 8. Write the `applying` crash journal (v2 — its commit-point evidence is the
987
+ hash of the post-install index bytes).
988
+ 9. Atomically swap the staged object into `objects/sha256/<digest>`
989
+ (retaining any displaced content on the commit handle), then harden it
990
+ in place: canonical `0644` files become read-only `0444`, canonical `0755`
991
+ files become read/execute-only `0555`, and directories become non-writable
992
+ `0555`. Hardening preserves the executable distinction needed for canonical
993
+ object reconstruction. Hardening is defense in depth, not the integrity proof
994
+ — verification reconstructs the complete canonical tar, including
995
+ `bundle.yaml`, and matches its SHA-256 digest to the object path. A hardening
996
+ failure rolls the swap back; a partially hardened object is never committed.
997
+ If the digest's object already exists, the install verifies the existing
998
+ object through the ingest adapter and commits an index-only change instead
999
+ (dedupe) — a corrupt or runtime-incompatible existing object is a hard
1000
+ integrity error, never replaced and never fallen through.
1001
+ 10. Atomically write `index.json` — the **durable commit point**. Past here
1002
+ a crash rolls forward; before it, everything rolls back. An index-write
1003
+ failure rolls the directory state back and leaves the previous object
1004
+ and index exactly as they were.
1005
+ 11. Advance the journal to `finalizing`, discard the retained backup and
1006
+ staging, remove the journal, release the lock.
1007
+
1008
+ On success `add` prints the structured result:
1009
+
1010
+ ```jsonc
1011
+ {
1012
+ "ok": true,
1013
+ "source": "widget.wnlp", // or the URL
1014
+ "level": "project", // or "global"
1015
+ "coordinate": "acme/widget@1.0.0",
1016
+ "digest": "<64-hex>",
1017
+ "workflows": ["delivery", "init"], // every workflow name in the bundle, sorted
1018
+ "objectPath": "<root>/objects/sha256/<64-hex>",
1019
+ "installed": true // false when deduplicated
1020
+ }
1021
+ ```
307
1022
 
308
- These four commands publish local workflow defs to a hosted **hub** (default
309
- `https://api.owenloop.com`; override per-command with `--hub <url>` or the
310
- `OWENLOOP_HUB` env var). They are the only network-bound commands besides
311
- `add`, and they talk only to endpoints the hub exposes today — no new
1023
+ **Conflict and re-install.** An existing coordinate at a DIFFERENT digest is
1024
+ a conflict error — no implicit retarget; the original digest is retained and
1025
+ nothing is written. An existing coordinate at the SAME digest deduplicates
1026
+ (`installed: false`), verifying the existing object before trusting it.
1027
+
1028
+ **Crash recovery** is the same two-phase discipline as the GitHub route,
1029
+ generalized: the v2 journal's commit-point test compares the hash of the
1030
+ current `index.json` bytes against the journal's recorded metadata hash
1031
+ (route-neutral — no GitHub ledger involved). A fresh v2 install also writes a
1032
+ single-use external recovery marker under the user's recovery-marker directory
1033
+ (default `<home>/.owenloop/recovery-markers`, derived from the injected home
1034
+ described above) before the applying journal. If a crash leaves the destination
1035
+ present with no staging or backup, recovery
1036
+ discards that destination only when the marker exactly matches the store root,
1037
+ destination segments, staging id, and `hadDest: false`; a missing or mismatched
1038
+ marker refuses and preserves the destination and journal. `add --recover --global`
1039
+ runs the store's recovery standalone against the global root with no network
1040
+ and prints `{"ok":true,"recovered":false|true,"outcome":…}` exactly
1041
+ like the project variant. A v1 (GitHub-schema) journal found at the global root
1042
+ is refused fail-closed — there is no ledger there to vouch for it — and a
1043
+ journal recorded against a *different* store root is refused rather than
1044
+ trusting its absolute path. Refusals leave the journal in place as evidence.
1045
+
1046
+ ### Resolving what is installed — two separate APIs
1047
+
1048
+ Resolution is deliberately split so execution code cannot accidentally call
1049
+ human-name resolution. Both are library APIs (exported from the package
1050
+ root); every successful resolution verifies the object through the ingest
1051
+ adapter before returning a path — permissions and object shape on disk are
1052
+ defense in depth, not an integrity proof.
1053
+
1054
+ - **Digest resolution (execution).** `resolveWorkflowDigest({digest,
1055
+ projectRoot?, globalRoot, verifier})` — digest only; no index and no
1056
+ workflow name participate. The project object path is tested first when a
1057
+ project root exists; an ABSENT project object may fall through to global,
1058
+ but a PRESENT project object that fails its type probe or verification is
1059
+ a hard integrity error — project tampering is never hidden by falling back
1060
+ to a valid global copy. When both levels hold the same digest, ONE result
1061
+ comes back (level `project`, with presence metadata), not two candidates.
1062
+ Absent at both levels ⇒ `object-missing` integrity error.
1063
+ - **Coordinate resolution (human/CLI).** `resolveWorkflowCoordinate({coordinate,
1064
+ projectRoot?, globalRoot, verifier})` reads BOTH indexes, fail-closed (a
1065
+ corrupt index is a hard error, never silently empty). No entry at either
1066
+ level ⇒ a structured **not-found** error. A project entry wins whenever it
1067
+ exists, even when the global index maps the same coordinate to a different
1068
+ digest; global is the fallback only when project has no match. An index entry
1069
+ whose selected object is missing or corrupt is an integrity error, never a
1070
+ returned path.
1071
+
1072
+ **Calls resolution for installed bundle workflows.** In the default CLI context
1073
+ (no explicit `--defs`/`OWENLOOP_DEFS`), `defs`/`create`/`tick` load CAS workflows
1074
+ from the project and global bundle-store indexes in addition to filesystem defs
1075
+ and the GitHub `add` ledger. A CAS workflow is addressable by the qualified
1076
+ `<package>/<workflow>` name, so a project-local or `add`-installed workflow can
1077
+ call it explicitly. A bare call from a CAS-loaded workflow resolves a sibling
1078
+ from the same bundle digest first; if no sibling has that name, ordinary flat
1079
+ lookup remains available. Bare CAS names are not registered globally, so a
1080
+ workflow in bundle A cannot accidentally call a same-named workflow from bundle
1081
+ B.
1082
+
1083
+ The precedence is explicit: project-local definitions win first, then
1084
+ GitHub-`add` installed definitions, then CAS definitions under qualified keys.
1085
+ Within the CAS layer, exactly one installed bundle holds the unqualified
1086
+ `<package>/<workflow>` name, chosen by two rules in order and never by install
1087
+ order:
1088
+
1089
+ 1. **Level.** If any candidate is named by the *project* index, only project
1090
+ candidates compete. A project pin of `pkg@0.1.0` therefore beats a global
1091
+ install of `pkg@0.9.9`. This holds even when the project's own object bytes
1092
+ are missing and were served by exact-digest fallback from the global store —
1093
+ the index that names the object decides, not where the bytes were read.
1094
+ 2. **Version.** Among the survivors, the highest canonical SemVer precedence
1095
+ wins (SemVer §11, so `0.1.10` beats `0.1.2` and `1.0.0` beats `1.0.0-rc.1`).
1096
+
1097
+ A canonical SemVer version never loses to a non-SemVer one. If two or more
1098
+ candidates compete and *none* carries a canonical SemVer version, the selection
1099
+ **fails closed**: the unqualified name is left unregistered and a warning names
1100
+ the versions involved, because there is no defined precedence to pick by. Call an
1101
+ exact `<namespace>/<name>@<version>` coordinate in that case. A single
1102
+ non-SemVer version still holds its name — there is nothing to order.
1103
+
1104
+ The refusal warning names only the versions that actually competed. A version
1105
+ dropped by rule 1 is reported separately as never having competed, since it lost
1106
+ on level and was never judged on its version at all. For the same reason,
1107
+ precedence warnings say `project-indexed` / `global-indexed`: precedence follows
1108
+ the index that named the object, whereas a registration's reported level is the
1109
+ store its verified bytes came from, and the two differ under exact-digest
1110
+ fallback.
1111
+
1112
+ Every version that did not win remains reachable under its digest-scoped key, so
1113
+ an already-pinned execution cannot be retargeted, and every exact
1114
+ `<namespace>/<name>@<version>` coordinate always resolves to its own object
1115
+ regardless of which version currently holds the unqualified name.
1116
+ A corrupt CAS index, object, or workflow is skipped with a warning during
1117
+ read-side discovery, so it does not make `status` fail. A running workflow keeps
1118
+ the definition snapshot from its creation (§28), including the CAS bundle
1119
+ provenance used for sibling lookup; installing a newer bundle therefore does not
1120
+ retarget an existing parent instance. The bundle spawn-time pin check compares
1121
+ canonical bundle digests and records a rejected `calls:` debt instead of running
1122
+ a mismatched child.
1123
+
1124
+ Store roots and object directories are probed with `lstat`, never `stat`:
1125
+ a symlink or non-directory squatting at a root, an index path, or an object
1126
+ path is refused outright, and reads never follow a link outside the
1127
+ intended tree.
1128
+
1129
+ **GitHub-route compatibility.** The bundle route changes nothing about
1130
+ `add <owner>/<repo>[@ref]`: the same inputs reach the same parser, the
1131
+ `<owner>-<repo>-<hash>` namespace is untouched, `.owenloop/installed.json`
1132
+ keeps its schema and validation, and an explicit `--defs`/`OWENLOOP_DEFS`
1133
+ still installs through a symlinked defs dir (operator intent). The legacy
1134
+ GitHub repository route installs workflow YAML rather than a format-v2
1135
+ `bundle.yaml`; therefore the GitHub route does not carry or enforce the `.wnlp`
1136
+ runtime compatibility declaration and does not provide the `.wnlp` runtime
1137
+ admission guarantee. Use a `.wnlp` bundle when the publisher must declare a
1138
+ minimum Owenloop version or required runtime features.
1139
+
1140
+ The routes share the canonical resolved-store lock, while the GitHub route
1141
+ retains its legacy cwd-derived lock and journal for compatibility. Recovery
1142
+ checks both journal locations and dispatches by journal version; a v2 store
1143
+ journal uses `index.json` metadata and a v1 GitHub journal uses
1144
+ `installed.json` ledger corroboration.
1145
+
1146
+ ## Hub (`login` / `connect` / `push` / `start` / `publish` / `logout`)
1147
+
1148
+ These commands authenticate, publish, and start workflows on a hosted **hub** (default
1149
+ `https://api.owenloop.com`). `login` and `logout` retain the generic resolver:
1150
+ `--hub <url>` → `OWENLOOP_HUB` → the built-in `DEFAULT_HUB`. `connect`, `push`,
1151
+ and `publish` use the safer publishing ladder below and never consult
1152
+ `OWENLOOP_HUB` or guess `DEFAULT_HUB`. They are the only network-bound commands
1153
+ besides `add`, and they talk only to endpoints the hub exposes today — no new
312
1154
  service-side surface. The hub URL is normalized to its origin
313
1155
  (`scheme://host[:port]`); path/query are dropped. `https` is required for
314
1156
  every hub origin except the loopback hosts (`127.0.0.1`, `::1`, `localhost`),
@@ -322,6 +1164,74 @@ bounce credentials or workflow YAML to another origin (same-origin validation
322
1164
  covers only the initial URL; a redirect would otherwise re-send the request body
323
1165
  cross-origin).
324
1166
 
1167
+ ### The small hosted-workflow path
1168
+
1169
+ Setup is durable. Authenticate and bind the project once, publish or update a
1170
+ definition when its content changes, prepare that published version for the
1171
+ execution account, and keep one crew-scoped Shift running:
1172
+
1173
+ ```bash
1174
+ owenloop login --hub https://hub.example
1175
+ owenloop connect --hub https://hub.example
1176
+ owenloop push newhire-onboarding
1177
+ OWENLOOP_ACCOUNT=default owenloop work prepare newhire-onboarding --origin https://hub.example
1178
+ OWENLOOP_HARNESS=codex owenloop shift start openai --origin https://hub.example --as default
1179
+ ```
1180
+
1181
+ Starting another run does not repeat installation, publication, preparation,
1182
+ or Shift setup. From the connected project it is one public control-plane
1183
+ command; repeat `--provide name=json` for seeded human inputs:
1184
+
1185
+ ```bash
1186
+ owenloop start newhire-onboarding \
1187
+ --crew openai \
1188
+ --provide 'signed_docs={"acknowledged":true}' \
1189
+ --provide 'hardware_choice={"laptop":"MacBook Pro"}'
1190
+ ```
1191
+
1192
+ `start` always uses the human credential. The standing Shift uses the
1193
+ `agent:default` credential selected by `--as default`. With no project binding,
1194
+ `start --hub <url>` is accepted explicitly; with neither a binding nor `--hub`,
1195
+ it refuses instead of falling through to `OWENLOOP_HUB` or the production
1196
+ default. If both a binding and `--hub` exist they must agree.
1197
+
1198
+ ### `start` — start a published workflow
1199
+
1200
+ `owenloop start <defName>` sends `POST /api/start_run` and prints the new
1201
+ workflow id, its initial status, and the steps whose default crew was stamped or
1202
+ whose capability routes were validated. `--crew <name>` selects the crew for
1203
+ steps that declare no capability; capability-bearing steps continue to use
1204
+ their live hub bindings. `--title <text>` is display-only. Both `--crew` and
1205
+ `--title` require non-empty values; bare flags and `--crew=`/`--title=` are local
1206
+ usage errors before credential or network access. The command does not claim,
1207
+ dispatch, close, or otherwise drive work—the standing Shift discovers the run
1208
+ through its normal crew inbox.
1209
+
1210
+ **Publishing hub resolution.** `connect`, `push`, and `publish` resolve their
1211
+ target in this order:
1212
+
1213
+ 1. An explicit `--hub <origin>` always wins.
1214
+ 2. `.owenloop/hub.json`, when present, is the project override.
1215
+ 3. Global machine state supplies one unambiguous candidate:
1216
+ - with the file credential backend, exactly one origin containing a valid
1217
+ human-slot credential is selected automatically;
1218
+ - Keychain and external-command credential backends cannot enumerate their
1219
+ origins, so the validated `hubOrigin` in
1220
+ `$XDG_CONFIG_HOME/owenloop/settings.json` (or
1221
+ `~/.config/owenloop/settings.json`) is used, and the requested credential
1222
+ slot must exist there before the command proceeds.
1223
+ 4. If nothing safe resolves, the command exits 2 without network or publication
1224
+ output effects.
1225
+
1226
+ More than one file-backed origin is also an exit-2 ambiguity: the error lists
1227
+ the origins in deterministic order and asks for `--hub <origin>` or
1228
+ `owenloop connect --hub <origin>`. A non-enumerable backend with no settings
1229
+ `hubOrigin` names the exact settings path and asks for the same explicit
1230
+ choice. `owenloop setup` populates that non-secret settings field. `OWENLOOP_HUB`
1231
+ and `DEFAULT_HUB` are intentionally excluded from the publishing ladder because
1232
+ an ambient guess can target the wrong hub organization; ambiguous or missing
1233
+ resolution fails closed instead of choosing one.
1234
+
325
1235
  **Request timeouts.** Every hub call — OAuth discovery, client registration,
326
1236
  code exchange, token refresh, `whoami`, the workflow list, and each push — is
327
1237
  bounded by a 30s deadline; a stalled hub surfaces as a friendly `hub did not
@@ -397,28 +1307,66 @@ can read (only read) a stored credential through the same backend logic via the
397
1307
  package's exported `readStoredCredential` — see
398
1308
  [Embedding](embedding.md#whats-exported).
399
1309
 
1310
+ The macOS `security` adapter treats exit status 44 (`errSecItemNotFound`) as the
1311
+ only absence result: lookup returns no credential, and deletion succeeds
1312
+ idempotently (running the same deletion again changes nothing). Every other
1313
+ numeric status, signal termination, or command-start failure is a fatal backend
1314
+ error. Lookup and logout stop at that error; Owenloop neither reports success
1315
+ nor falls through to or deletes a file-store credential. Mapped errors name only
1316
+ the operation and backend failure class, never the service, account, credential,
1317
+ or stdin command.
1318
+
400
1319
  **Serializing writes (`credentials.lock`).** A store write — a refreshed OAuth
401
- token, or a `login`/`logout` that stores or deletes a slot — is serialized by a
402
- lockfile at `credentials.lock`, a sibling of `credentials.json` in the config
403
- dir (created for the keychain backend too, since the race it closes is
404
- backend-independent). The concern is a token-refresh race: two owenloop
405
- processes hitting an expiring OAuth token at once would each POST a refresh and
406
- each persist, and because refresh tokens rotate, the second write clobbers the
407
- first with a token whose refresh link is already spent — silently killing the
408
- credential. Under the lock a process re-reads the slot after acquiring it and,
409
- if another process already refreshed, **adopts** that fresh token instead of
410
- refreshing again — one network refresh, one write, no lost token. The lock
411
- matters only for OAuth refresh and store/delete; read paths and the external-
412
- command mode (which never writes the local store) do not take it. Staleness is
413
- liveness-based: a lock held by a dead same-host process is reclaimed at once, an
414
- unparseable or pid-less lockfile is reclaimed once older than the ~30s TTL, and
415
- a lock held by a live process is never age-reclaimed. If the lock can't be
416
- acquired within the wait budget the CLI fails loudly (`another owenloop process
417
- is using the credential store … — timed out waiting after Ns`) rather than
418
- refreshing unlocked. Three test knobs override the timings:
419
- `OWENLOOP_CRED_LOCK_WAIT_MS` (default 45000), `OWENLOOP_CRED_LOCK_STALE_MS`
420
- (default 30000), and `OWENLOOP_CRED_LOCK_POLL_MS` (default 100). No token value
421
- ever appears in the lockfile or the timeout message.
1320
+ token, or a `login`/`logout` that stores or deletes a slot — is serialized by the
1321
+ logical `credentials.lock` guard and the persistent SQLite lock database at
1322
+ `credentials.lock.sqlite-v2`, both siblings of `credentials.json` in the config
1323
+ dir (created for the keychain backend too, since the race the lock closes is
1324
+ backend-independent). The concern is a token-refresh
1325
+ race: two owenloop processes hitting an expiring OAuth token at once would each
1326
+ POST a refresh and each persist, and because refresh tokens rotate, the second
1327
+ write clobbers the first with a token whose refresh link is already spent —
1328
+ silently killing the credential. Under the lock a process re-reads the slot
1329
+ after acquiring it and, if another process already refreshed, **adopts** that
1330
+ fresh token instead of refreshing again — one network refresh, one write, no
1331
+ lost token. The lock matters only for OAuth refresh and store/delete; read paths
1332
+ and the external-command mode (which never writes the local store) do not take
1333
+ it.
1334
+
1335
+ SQLite owns exclusion through a `BEGIN IMMEDIATE` transaction tied to the live
1336
+ database connection. Release, normal process exit, and process crash close that
1337
+ connection and release the operating-system lock. Owenloop deliberately keeps
1338
+ the SQLite database path after release; Owenloop never deletes or replaces the
1339
+ path. A sibling `credentials.lock.owner.json` contains only diagnostic process
1340
+ metadata and does not determine ownership. If the lock cannot be acquired within
1341
+ the wait budget, the CLI fails loudly (`another owenloop process is using the
1342
+ credential store … — timed out waiting after Ns`) rather than refreshing
1343
+ unlocked. `OWENLOOP_CRED_LOCK_WAIT_MS` (default 45000) and
1344
+ `OWENLOOP_CRED_LOCK_POLL_MS` (default 100) override the wait behavior.
1345
+ `OWENLOOP_CRED_LOCK_STALE_MS` is accepted for compatibility but no longer causes
1346
+ pathname deletion. No token value appears in either lock file or the timeout
1347
+ message.
1348
+
1349
+ **Lock-file upgrade boundary.** The logical lock pathname, such as
1350
+ `credentials.lock`, remains a permanent, parseable JSON compatibility guard.
1351
+ The new SQLite lock database lives at `<logical-lock-path>.sqlite-v2`; for the
1352
+ credential store, that path is `credentials.lock.sqlite-v2`. A new client first
1353
+ holds SQLite's `BEGIN IMMEDIATE` transaction and then installs the guard at the
1354
+ old pathname with an exclusive create. The guard carries an impossible operating-
1355
+ system hostname, so a pre-SQLite client treats the guard as a live foreign-host
1356
+ owner and never age-reclaims it. An already-running old holder can release its
1357
+ ordinary JSON lock normally; the waiting new client then installs the guard and
1358
+ closes the one-way upgrade boundary. Old clients remain blocked after every new-
1359
+ client release or crash, while new clients continue to exclude one another
1360
+ through SQLite.
1361
+
1362
+ Release and crash cleanup close only the SQLite transaction. Owenloop never
1363
+ deletes, renames, or replaces either the permanent guard or the versioned SQLite
1364
+ database during normal lock lifecycle. A corrupt, partial, old-owner, or pre-
1365
+ boundary SQLite file already present at the logical legacy pathname fails closed:
1366
+ stop the relevant processes, verify that no old or pre-boundary process still
1367
+ owns that pathname, remove the legacy pathname manually, and let one upgraded
1368
+ client install the permanent guard. Routine stale-age or PID reclamation is no
1369
+ longer used, and `OWENLOOP_CRED_LOCK_STALE_MS` cannot weaken the boundary.
422
1370
 
423
1371
  **Supplying the credential from your own tooling.** If your secrets live in a
424
1372
  secret manager, or you run on a host with no keychain, set
@@ -460,14 +1408,35 @@ it — a `401` there means the credential is never written to disk. On success
460
1408
  `orgId`, `identity`, and `email` when the hub returns one), read straight from
461
1409
  `whoami`.
462
1410
 
1411
+ **Recording the hub for `owenloop mcp` (`~/.owenloop/config.json`).** After the
1412
+ credential above is verified and stored, `login` makes one more best-effort
1413
+ write: it records the hub origin it just authenticated against in
1414
+ `~/.owenloop/config.json` (`{"version": 1, "hub": "<origin>"}` — never a
1415
+ secret, just the origin). This file is separate from both the credential store
1416
+ above and from `owenloop setup`'s `~/.config/owenloop/settings.json`; its only
1417
+ reader is `owenloop mcp`'s [origin resolution](#choosing-the-hub-origin),
1418
+ which needs to know your hub without enumerating the credential store (the
1419
+ Keychain and external-command backends can't be listed at all — see below). A
1420
+ failure to write this file is a **warning** printed to stderr, never a fatal
1421
+ error and never blocking `login` itself, since the credential is already
1422
+ safely stored by the time this write is attempted. Logging into a second hub
1423
+ overwrites this file — "last login wins" — so if you routinely switch between
1424
+ hubs, pass `--hub` explicitly to `owenloop mcp` (or set `OWENLOOP_HUB`) rather
1425
+ than relying on whichever `login` ran most recently.
1426
+
463
1427
  ### `connect` — bind a project to a hub
464
1428
 
465
- `owenloop connect` writes `.owenloop/hub.json` recording which hub this project
466
- publishes to, after re-verifying the stored credential against `GET
467
- /api/whoami`. Run `login` first. The JSON reports the same org/identity fields
468
- as `login`; re-connecting to the **same** origin reports no `switchedFrom`,
469
- switching to a **different** hub reports `switchedFrom: <old origin>` and
470
- rebinds the project to the new one.
1429
+ `owenloop connect` resolves a target through the publishing ladder, re-verifies
1430
+ the stored credential against `GET /api/whoami`, and writes
1431
+ `.owenloop/hub.json`. Run `login` first. With no `--hub`, an existing binding
1432
+ remains the target; an unbound project uses the unambiguous global fallback.
1433
+ An explicit `--hub` creates or replaces the project override, which is useful
1434
+ for multi-org or multi-hub repositories. `connect` is optional for the ordinary
1435
+ single-hub happy path, not a prerequisite for `push` or `publish`.
1436
+
1437
+ The JSON reports the same org/identity fields as `login`; re-connecting to the
1438
+ **same** origin reports no `switchedFrom`, switching to a **different** hub
1439
+ reports `switchedFrom: <old origin>` and rebinds the project to the new one.
471
1440
 
472
1441
  A symlinked project `.owenloop` directory is refused with a clear error rather
473
1442
  than followed: a hostile checkout cannot ship `.owenloop -> /elsewhere` to
@@ -477,16 +1446,40 @@ guarantee). The same refusal covers the default `state.db` FILE (and its SQLite
477
1446
  file would otherwise redirect the store's writes, since SQLite follows file
478
1447
  symlinks.
479
1448
 
480
- ### `push` — publish local defs to the bound hub
1449
+ ### `push` — publish local defs to the resolved hub
481
1450
 
482
1451
  `owenloop push [<defName>...]` publishes the project's workflow defs (all of
483
- them, or just the named ones) to the hub the project is `connect`ed to. It
1452
+ them, or just the named ones) to the hub selected by the publishing ladder.
1453
+ `--hub` overrides a project binding for that invocation without rewriting it;
1454
+ otherwise the project override wins over global state. An unbound project with
1455
+ one file-backed human credential therefore needs no setup step. Ambiguous or
1456
+ missing candidates exit 2 as described above, and `OWENLOOP_HUB`/
1457
+ `DEFAULT_HUB` never participate. `push` never writes a project binding. It
484
1458
  reuses the **exact** all-or-nothing validation gate `add` uses — lint, validate,
485
1459
  and a bounded `check` — across every selected def before a single byte is sent;
486
1460
  any definite defect aborts the whole push. stdout is machine-parseable JSON;
487
1461
  the human-readable diff (`+ new`, `~ changed`, `= unchanged`, `! failed`) goes
488
1462
  to stderr.
489
1463
 
1464
+ `owenloop push --bundle <bundle.wnlp> [<defName>...]` is the executable,
1465
+ bundle-backed form. The exact archive is inspected and becomes the definition
1466
+ source; checkout files are ignored. Push requires exactly one adjacent
1467
+ publication sidecar produced by `owenloop publish` (`.dsse` or `.unsigned`),
1468
+ accepts an optional `.origin.dsse`, uploads those content-addressed objects,
1469
+ then calls `create_workflow` with the archive's canonical digest. This is what
1470
+ makes the hub stamp reference orders with a digest that execution hosts can
1471
+ resolve from their installed bundle store. Because a reference order identifies
1472
+ its executable instructions only by bundle digest plus step name, every workflow
1473
+ definition in the complete archive must use distinct step names. `push --bundle`
1474
+ refuses an archive when two definitions share a step name, even when positional
1475
+ arguments select only one of those definitions; the refusal happens before any
1476
+ bundle, evidence, or workflow-version write. Bundle mode conservatively sends
1477
+ each selected `create_workflow` request even when its YAML hash is unchanged,
1478
+ because the workflow listing does not expose the latest bundle identity; the
1479
+ hub's `(yaml, bundle digest)` idempotency decides whether to version-forward or
1480
+ return `noop`. `--dry-run` validates the archive and sidecars and performs only
1481
+ the read-only server diff—no bundle, sidecar, or definition is uploaded.
1482
+
490
1483
  **Idempotency is server-side truth, not a client ledger.** `push` fetches the
491
1484
  hub's own view of every def (`GET /api/workflows`, which reports each def's
492
1485
  `hash`) and diffs local content against it directly — there is no
@@ -508,6 +1501,15 @@ batch: the current def is recorded as `failed`, the not-yet-attempted remainder
508
1501
  is reported under a `skipped` output key, and any `Retry-After` the hub sent is
509
1502
  surfaced in the error.
510
1503
 
1504
+ Selected definitions are published in topological `calls:` order. If a selected
1505
+ dependency fails or is skipped, Owenloop sends no `create_workflow` request for
1506
+ its selected dependents; each dependent is added to `skipped`, names its failed
1507
+ or skipped dependencies in sorted order, and becomes unsuccessful so the skip
1508
+ propagates transitively. Independent selected definitions continue publishing.
1509
+ A locally `unchanged` dependency and a server `noop` dependency both count as
1510
+ successful, so either result permits the dependent to publish. Dependency
1511
+ matching covers bare names and same-package-qualified names in a bundle.
1512
+
511
1513
  The def hash is computed by re-parsing the raw YAML with no checkout-specific
512
1514
  `baseDir` — the same canonicalization the hub applies — so it's portable
513
1515
  across checkouts and machines by construction: a fresh clone at a different
@@ -528,13 +1530,66 @@ def isn't round-trippable. A def using `bodyFile:` is refused the same way
528
1530
  resolve the external file against once the YAML leaves this machine. Inline
529
1531
  both before pushing.
530
1532
 
1533
+ ### `publish` — pack and publish a workflow bundle
1534
+
1535
+ ```text
1536
+ owenloop publish <source-dir> [--output <bundle.wnlp>] [--source <json>] [--unsigned] [--hub <origin>]
1537
+ ```
1538
+
1539
+ `publish` is separate from both [`bundle pack`](#bundles) and [`push`](#push--publish-local-defs-to-the-resolved-hub). It packs one source directory with the same deterministic `packBundle` implementation as `bundle pack`, then publishes the bundle beside a local publication sidecar and, optionally, a signed origin sidecar. A project binding is optional; when present it supplies the project-specific author-key origin unless `--hub` overrides it.
1540
+
1541
+ The author-key origin comes from the same publishing ladder as `connect` and
1542
+ `push`: `--hub` wins, a project binding overrides global state, one file-backed
1543
+ human origin resolves automatically, and a non-enumerable backend uses the
1544
+ validated execution-settings `hubOrigin` only when the human credential exists.
1545
+ An ambiguous or absent candidate exits 2 before signing, packing, or output
1546
+ writes. `publish` never writes `.owenloop/hub.json`, consults `OWENLOOP_HUB`, or
1547
+ guesses `DEFAULT_HUB`.
1548
+
1549
+ Signed publication is the default. In signed mode, `publish` requires the human principal signing key for the resolved hub. Run `owenloop setup` before the first signed publication. `publish` never creates or repairs a signing key: an older key store that already contains the key but lacks the non-secret `<hash>.ref` pointer must be repaired by a setup run, whose `ensure` step backfills the pointer without regenerating or replacing the private key. If the author-key reference or key record is missing, `publish` fails and suggests `owenloop setup` or the explicit unsigned mode; the command does not silently downgrade to unsigned output.
1550
+
1551
+ In signed mode, `publish` confirms the existing key and probes the signer before `packBundle` runs, then signs the publication record before any bundle or sidecar is written. A signing failure therefore leaves no half-published artifact. The signature covers a DSSE publication record whose `digest` is the lowercase SHA-256 digest of the uncompressed canonical tar inside the `.wnlp` file. When `--source <json>` is supplied, the command signs a separate origin record with the same signer and digest, then writes `<output>.origin.dsse` beside the publication sidecar. The remote hub is not involved in this local signing operation and never produces or completes either signature.
1552
+
1553
+ `--source` is signer-supplied provenance, not a hub-derived label. The JSON value must be one of these closed forms:
1554
+
1555
+ - `{"kind":"git","repo":"<repo>","commit":"<40- or 64-hex commit SHA>"}`;
1556
+ - `{"kind":"console","user":"<authoring user>"}`, which requires a client-side signing ceremony; or
1557
+ - `{"kind":"agent","agent":"<agent identity>","session":"<session>"}`.
1558
+
1559
+ The origin record is part of the signed content. The hub or another relay stores and relays the signed record but cannot write, derive, default, or stamp an origin value. `attesterKeyId` in the record is only a candidate-selection hint; verification cross-checks the hint against the signer that produced the verified signature. `--source` cannot be combined with `--unsigned`. The CLI currently rejects the `console` form because that form requires a client-side signing ceremony rather than this command's local signing path.
1560
+
1561
+ `--unsigned` is an explicit opt-in. Unsigned mode still packs the canonical bundle, but writes an unauthenticated author-intent marker rather than a DSSE envelope. Anyone can write such a marker; consumers must treat missing and unverifiable signatures as unsigned regardless of whether the marker is present. Publication and unsigned sidecars are mutually exclusive:
1562
+
1563
+ - signed mode writes `<output>.wnlp.dsse` and removes a stale `<output>.wnlp.unsigned`;
1564
+ - `--unsigned` writes `<output>.wnlp.unsigned` and removes a stale `<output>.wnlp.dsse`.
1565
+
1566
+ A signed publish without `--source` removes a stale `<output>.origin.dsse`. Unsigned mode also removes a stale origin sidecar because an unsigned origin would only be an unsigned label.
1567
+
1568
+ The output defaults to `<package-name>-<version>.wnlp` next to the source directory. `--output` must name a path outside the source directory. Existing regular output and sidecar files may be replaced; directories and other non-regular paths are rejected.
1569
+
1570
+ Successful invocations print exactly one machine-readable JSON object to stdout. Signed output without an origin has this shape:
1571
+
1572
+ ```json
1573
+ {
1574
+ "ok": true,
1575
+ "bundle": "/absolute/path/report-1.2.0.wnlp",
1576
+ "digest": "<64 lowercase hex characters>",
1577
+ "name": "report",
1578
+ "version": "1.2.0",
1579
+ "signed": true,
1580
+ "envelope": "/absolute/path/report-1.2.0.wnlp.dsse"
1581
+ }
1582
+ ```
1583
+
1584
+ When `--source` is supplied, signed output also includes `"origin": "/absolute/path/report-1.2.0.wnlp.origin.dsse"`. Unsigned output has the same `ok`, `bundle`, `digest`, `name`, and `version` fields, with `"signed": false` and `"marker": "/absolute/path/report-1.2.0.wnlp.unsigned"` instead of `envelope`. Diagnostics and failures go to stderr and exit nonzero. `bundle pack` and `push` are unchanged by this command.
1585
+
531
1586
  Exact-match redirect URIs (no RFC 8252 variable-port allowance) and no
532
1587
  device-code grant remain recorded follow-ups on the service, not gaps in the
533
1588
  CLI.
534
1589
 
535
1590
  ### `agent new` — mint an agent token into a slot
536
1591
 
537
- `owenloop agent new <name>` mints a new agent identity on the hub (`POST
1592
+ `owenloop agent new <name>` mints a new Scoped Identity on the hub (`POST
538
1593
  /api/mint_agent_token`, authenticated as your **human** credential) and stores
539
1594
  the returned `olp_` token in the local credential slot `agent:<name>` — the same
540
1595
  slot `login --as agent:<name>` writes and `push --as agent:<name>` reads. Use it
@@ -544,9 +1599,10 @@ happen in one step, and you never handle the secret.
544
1599
  **The token is never printed.** The minted `olp_` token goes process → store
545
1600
  only — it never appears on stdout, stderr, in an error, or in a log (identity
546
1601
  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,
1602
+ **non-secret** fields only: `hub`, `name`, `slot`, `crews` (the resolved crew
1603
+ names), `scopes` (the minted token's scopes — `["work"]` by default, or whatever
1604
+ `--scopes`/`--shift` selected), `storage` (`keychain` | `file`), `agentId` (the
1605
+ Scoped Identity's id), and `tokenId` (a revocation handle). To use the Scoped Identity afterwards,
550
1606
  pass `--as agent:<name>` to `connect`/`push`; to revoke it, use its `tokenId`
551
1607
  on the hub.
552
1608
 
@@ -562,77 +1618,406 @@ minting on the wrong org is not undone by a retry:
562
1618
 
563
1619
  Unlike other commands this does **not** fall back to `OWENLOOP_HUB` or the
564
1620
  built-in default hub — silently defaulting a mint would risk minting on the
565
- production hub while you're logged into a dev one. Note that hub enumeration is
566
- **file-store only** (shared with `owenloop mcp`): the keychain and the
567
- external-command backend cannot list their entries, so on such a machine step 2
568
- cannot enumerate the store and you must pass `--hub`.
569
-
570
- **`--pools <a,b>`.** A comma-separated list of pool names the token is granted
1621
+ production hub while you're logged into a dev one. This is deliberately
1622
+ stricter than [`owenloop mcp`'s origin resolution](#choosing-the-hub-origin):
1623
+ `mcp` exposes both reads and writes, including `create_agent` (which mints and
1624
+ stores an agent token), `create_workflow`, `publish_event`, `submit`,
1625
+ `stage_enrollment`, and crew mutations. The default remains acceptable for
1626
+ `mcp` because each tool call authenticates against the resolved origin; when no
1627
+ human credential exists there, the existing `loginHint` surfaces the origin
1628
+ and asks for `owenloop login --hub <origin>` before the tool-specific action
1629
+ runs. If a credential does exist at an unintended origin and `create_agent`
1630
+ mints there, the stored agent token is revocable; `--hub` and `OWENLOOP_HUB`
1631
+ remain available when the operator wants to avoid inference. `agent new`
1632
+ **mints** a new credential directly, a side effect a retry cannot undo, so it
1633
+ stops at step 3 instead of ever guessing. Note that hub enumeration itself is
1634
+ **file-store only**: the keychain and the external-command backend cannot list
1635
+ their entries, so on such a machine step 2 cannot enumerate the store and you
1636
+ must pass `--hub`.
1637
+
1638
+ **`--crews <a,b>`.** A comma-separated list of crew names the token is granted
571
1639
  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
1640
+ the minter's personal crew; `--crews ""` (or `--crews ,`) is a usage error. Crew
573
1641
  names are validated by the hub, not the client.
574
1642
 
1643
+ **`--scopes <a,b>` / `--shift`.** A comma-separated list of scopes the minted
1644
+ token carries (trimmed, empties dropped). Omit both flags to mint **work-only**
1645
+ (the default). `--shift` is shorthand for `--scopes work,run` — the identity
1646
+ a service account needs to both serve and *start* runs. The two flags are
1647
+ mutually exclusive (`--scopes … --shift` together is a usage error), and
1648
+ `--scopes ""` (or `--scopes ,`) is a usage error. Scope names are validated by
1649
+ the hub, not the client.
1650
+
575
1651
  **A configured external credential command blocks the mint.** If
576
1652
  `OWENLOOP_CREDENTIAL_COMMAND` is set, that command — not the local store —
577
1653
  supplies credentials for the hub, so `agent new` refuses up front (it has
578
1654
  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.
1655
+ This check, the name validation, the empty-`--crews` check, the empty-`--scopes`
1656
+ check, and the `--scopes`/`--shift` mutual-exclusivity check all run
1657
+ **before** any network call, so a refusal never mints a server-side token first
1658
+ — a mint that then failed to store would burn the agent name permanently.
582
1659
 
583
1660
  **Exit codes.**
584
1661
 
585
1662
  | code | meaning |
586
1663
  |---|---|
587
1664
  | `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 |
1665
+ | `1` | generic failure — invalid or already-taken name, crew/shape rejection, network timeout, or a token that minted but couldn't be stored |
589
1666
  | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
590
1667
  | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
591
1668
 
592
- ## `setup` — converge a machine's install
1669
+ ## Capability routes
1670
+
1671
+ A **capability route** maps a workflow-def **capability** (a logical capability tag a
1672
+ def author writes, like `gpu` or `repo-access`) to a **crew** on one hub org.
1673
+ Def authors write capabilities; an org admin binds each capability to at least one crew.
1674
+ That indirection is what keeps deployment facts out of portable defs — see
1675
+ [`capabilities:`](authoring.md#capabilities--logical-capability-tags) in the authoring guide
1676
+ for the step-side declaration.
1677
+
1678
+ **A route is one `(capability, crew)` PAIR, and a capability may bind MANY crews.** The
1679
+ 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
1680
+ to three crews appears as three rows. A **dangling route** is one whose crew
1681
+ row was deleted; it survives in the table, routes nothing, and never widens
1682
+ access. A capability with **zero live routes** is **parked**: its steps wait.
1683
+
1684
+ **Resolution is live.** `start_run` only *checks* that every capability a run's steps
1685
+ use is currently bound — it stamps no crew for a capability-routed step. Every later
1686
+ routing decision (which Shift is offered the step, and whether a claim is
1687
+ allowed) re-reads the route table as it stands at that moment.
1688
+
1689
+ **These edits take effect on work already in flight.**
1690
+
1691
+ - **Adding.** Running `capability bind` on a capability that is **already bound** ADDS the
1692
+ named crew — it never displaces a crew already bound. Adding widens who can
1693
+ serve the capability, live at the next poll of every in-flight run using it. Re-adding
1694
+ a pair that is already there is a normal success, not an error (`alreadyRouted:
1695
+ true`).
1696
+ - **Removing.** Running `capability unbind` removes exactly ONE pair. If the capability still
1697
+ has other live routes, it simply routes to a narrower set and nothing pauses.
1698
+ If the removal takes away the **last live** route, the capability is **parked**:
1699
+ the in-flight steps that use it are offered to no Shift and accept no
1700
+ claim — until it is bound again. Nothing is lost; the work resumes on re-bind.
1701
+ `remainingCrewIds: []` on stdout is that signal, and stderr says so in words.
1702
+ - **Retargeting is two acts, not one.** There is no retarget command: add the new
1703
+ crew, then remove the old one. Each is separately audited on the hub, and in
1704
+ between **BOTH** crews serve the capability. The CLI deliberately does not chain the
1705
+ two for you — the intermediate state is a real state an operator may want to sit
1706
+ in, and collapsing it would hide a widened access window.
1707
+
1708
+ A capability route is **not** the project↔hub binding `owenloop connect` writes to
1709
+ `.owenloop/hub.json` — that one records which hub *this project directory*
1710
+ publishes to; a capability route is an org-scoped capability→crew row on the hub.
1711
+
1712
+ ### `capability bind <capability> <crew>`
1713
+
1714
+ `POST /api/add_capability_route`, authenticated as your **human** credential;
1715
+ requires the **admin** role on the hub. ADDS the crew named `<crew>` to
1716
+ `<capability>`'s routes. `<crew>` is a crew **name** — the hub resolves it to a crew
1717
+ id; the CLI does no crew lookup and performs no client-side validation of either
1718
+ argument (the hub is the enforcement of record).
1719
+
1720
+ **Adding is idempotent per pair.** Re-adding a `(capability, crew)` pair that is
1721
+ already bound is a normal success — the hub answers `200` with `alreadyRouted:
1722
+ true` and changes nothing (the original row keeps its creator and timestamp).
1723
+ `routedCrewCount` reports how many **live** crews the capability binds after the write.
1724
+
1725
+ ### `capability unbind <capability> <crew>`
1726
+
1727
+ `POST /api/remove_capability_route`, authenticated as your **human** credential;
1728
+ requires the **admin** role on the hub. Removes the ONE `(capability, crew)` route
1729
+ you name. `<crew>` is **required**: a capability may bind many crews, so a capability-only
1730
+ removal would unbind more than you asked for.
1731
+
1732
+ `<crew>` accepts the crew's **name**, or its raw **`crew_id`**. The raw-id form
1733
+ is the only way to remove a **dangling** route — one whose crew row was
1734
+ deleted, so there is no name left to resolve. `capability list` shows such a row
1735
+ with `crewName: null`; take its `crewId` from there.
1736
+
1737
+ **`rm` is idempotent.** Removing a pair that is **not** bound is a normal
1738
+ success — the hub answers `200` with `removed: false` rather than a `404` — and
1739
+ the CLI prints a full document plus a stderr line saying nothing was removed. A
1740
+ script can call `capability unbind` unconditionally without branching on whether the
1741
+ pair was bound. On that tolerant path `crewId` is `null`, because the argument
1742
+ matched neither a live crew name nor one of the capability's own rows.
1743
+
1744
+ **Removing the last live route parks the capability**, and stderr says so. See
1745
+ "These edits take effect on work already in flight" above.
1746
+
1747
+ ### `capability list`
1748
+
1749
+ `GET /api/capability_routes`, authenticated as your **human** credential. Lists the
1750
+ org's routes, ONE row per `(capability, crew)` pair ordered by capability then crew id —
1751
+ so a capability bound to several crews appears as several rows. An org with no
1752
+ routes yet is a normal success (exit 0) with an empty `routes` array.
1753
+
1754
+ A row whose `crewName` is `null` is a **dangling route**: the crew it names was
1755
+ deleted. Such a row routes nothing and never widens access, and it is shown
1756
+ rather than hidden precisely so you can clean it up — remove it with `capability unbind
1757
+ <capability> <crewId>`.
1758
+
1759
+ **Flags.** `--hub <url>` only (plus the global `--db`/`--defs`).
1760
+
1761
+ **Which hub gets acted on (`--hub`).** Resolution is deliberately narrow — the
1762
+ same stance `agent new` takes, because a route written against the wrong org
1763
+ is not undone by a retry, and under live resolution it also moves in-flight
1764
+ work:
593
1765
 
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:
1766
+ 1. `--hub <origin>` if given (normalized the same way as everywhere else).
1767
+ 2. Otherwise the **one** hub your credential *file* stores — if exactly one is
1768
+ present, it's used.
1769
+ 3. Otherwise the command **exits 2** naming both remedies (pass `--hub`, or log
1770
+ in to exactly one hub); when more than one hub is stored their origins are
1771
+ listed back so you can pick.
1772
+
1773
+ This does **not** fall back to `OWENLOOP_HUB` or the built-in default hub. Note
1774
+ that hub enumeration is **file-store only**: the keychain and the
1775
+ external-command backend cannot list their entries, so on such a machine step 2
1776
+ cannot enumerate the store and you must pass `--hub`.
1777
+
1778
+ **Printed JSON.** stdout is exactly one whitelisted JSON document per
1779
+ invocation, built from named fields — never a raw hub body — so `| jq` always
1780
+ works. Human progress lines (the two `capability unbind` warnings) go to stderr only.
1781
+
1782
+ | subcommand | stdout |
1783
+ |---|---|
1784
+ | `capability bind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crew": "ml-crew", "alreadyRouted": false, "routedCrewCount": 2 }` |
1785
+ | `capability unbind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crewId": "crw_1", "removed": true, "remainingCrewIds": ["crw_2"] }` |
1786
+ | `capability list` | `{ "ok": true, "hub": "<origin>", "routes": [ { "capability": "gpu", "crewId": "crw_1", "crewName": "ml-crew", "createdBy": "u_1", "createdAt": 1738000000000 } ] }` |
1787
+
1788
+ Every added field carries the **hub's own name**, verbatim — the same words its
1789
+ audit log and the web console use — so correlating stdout against them never
1790
+ needs a translation step.
1791
+
1792
+ - `alreadyRouted` (`capability bind`) — was this exact `(capability, crew)` pair already
1793
+ bound before the call? `false` means the pair was created by it.
1794
+ - `routedCrewCount` (`capability bind`) — how many **live** crews the capability binds
1795
+ after the write. A dangling route routes nothing and is not counted.
1796
+ - `removed` (`capability unbind`) — did this call actually remove a pair? `false` is the
1797
+ tolerant "it was never bound" case, not an error.
1798
+ - `remainingCrewIds` (`capability unbind`) — the **live** crews the capability still binds.
1799
+ `[]` means the capability is now **parked**: `jq '.remainingCrewIds | length == 0'`.
1800
+ It can be `[]` while a dangling row survives, because such a row routes nothing.
1801
+ - `crewId` (`capability unbind`) — the crew the hub resolved your `<crew>` argument to.
1802
+ It is `null` on the tolerant `removed: false` path, where the argument matched
1803
+ neither a live crew name nor one of the capability's own route rows. `capability unbind`
1804
+ never prints a crew *name*: `remove_capability_route` does not return one, and
1805
+ inventing one from argv would not be the hub's answer.
1806
+ - `capability` and `crew` (`capability bind`) are the values the **hub** echoed back, not
1807
+ your argv: if the hub normalized either, stdout tells the truth about what was
1808
+ stored.
1809
+
1810
+ **Exit codes.**
1811
+
1812
+ | code | meaning |
1813
+ |---|---|
1814
+ | `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 |
1815
+ | `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 |
1816
+ | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
1817
+ | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
1818
+
1819
+ ## Crews
1820
+
1821
+ A **crew** is an org-scoped queue that agent work is stamped to. Every hub org
1822
+ can have, in addition to any crews an admin creates, one **orphan crew** (name
1823
+ `orphan:unrouted`, `kind: "orphan"`) that the hub itself owns as the landing
1824
+ zone for work whose crew was deleted out from under it. It is materialized
1825
+ **lazily**, the first time a crew holding stamped work is deleted — an org
1826
+ that has never deleted a crew with stamped work has no orphan crew at all, and
1827
+ `crew list` shows none. Once it exists, `crew list` includes it — it is
1828
+ marked, never hidden, via a derived `orphan: true` boolean on its row (see the
1829
+ Printed JSON table below).
1830
+
1831
+ This family is independent of [capability routes](#capability-routes): a capability routes
1832
+ to a crew by *name*, and a crew is where agent work actually queues. Deleting a
1833
+ crew a capability still points at does not error — the capability's routing simply
1834
+ resolves nowhere useful until it is rebound.
1835
+
1836
+ ### `crew list`
1837
+
1838
+ `GET /api/crews`, authenticated as your **human** credential. Lists the org's
1839
+ crews, each with its member rows (`principalKind`/`principalId`/`addedBy`/
1840
+ `addedAt`). An org with no crews at all — including one that has never
1841
+ materialized an orphan crew — is still a normal success (exit 0) with an empty
1842
+ `crews` array.
1843
+
1844
+ ### `crew new <name> --kind personal|shared [--owner <memberId>]`
1845
+
1846
+ `POST /api/create_crew`, authenticated as your **human** credential; requires
1847
+ the **admin** role on the hub, **or** — for `--kind personal --owner
1848
+ <memberId>` where `<memberId>` is the caller's own member id — no admin role
1849
+ at all: a human may self-service additional personal crews for themself
1850
+ without being an admin (`assertPoolMutationAllowed`, hub-core
1851
+ `manage-crews.ts:211-214`). Every other combination (a `shared` crew, or a
1852
+ `personal` crew owned by someone else) still requires admin. `--kind` is **required** but its value is
1853
+ forwarded to the hub **verbatim and unvalidated** — the hub is the enforcement
1854
+ of record for which kind values are legal (today `personal`/`shared`; `orphan`
1855
+ is reserved for the hub's own crew). `--owner <memberId>` is optional and is
1856
+ omitted from the request body entirely when not given — a `personal` crew
1857
+ with no owner is the hub's own error to raise, not a client-side rule
1858
+ duplicated here.
1859
+
1860
+ ### `crew rm <crewId>`
1861
+
1862
+ `POST /api/delete_crew`, authenticated as your **human** credential; requires
1863
+ the **admin** role on the hub for every crew kind, including a personal one —
1864
+ `deletePool` bypasses the self-service gate that `crew new`/`crew member
1865
+ add`/`crew member rm` use, and is admin-only unconditionally
1866
+ (`manage-crews.ts:629`). Deletes the crew. The crew's **membership rows are
1867
+ deleted outright, not moved** — `deleteAllPoolMembers` (`manage-crews.ts:706`)
1868
+ runs unconditionally in the same transaction, whether or not any stamps
1869
+ transfer; `membersRemoved` on stdout is a count of those deletions, since the
1870
+ orphan crew's own membership is derived (always the org's current admins) and
1871
+ cannot accept arbitrary members. Only the crew's **run stamps and
1872
+ queued/running work** move to the org's orphan crew — memberships are never
1873
+ among what moves.
1874
+
1875
+ **`rm` is idempotent.** Deleting a `<crewId>` that does not exist is a normal
1876
+ success — the hub answers `200` with `deleted: false` rather than a `404` —
1877
+ and the CLI prints this honestly (see below), plus a stderr line naming the
1878
+ crew id, rather than inventing an error.
1879
+
1880
+ **Like [`capability unbind`](#capability-unbind-capability-crew), `crew rm` prints its tolerant
1881
+ boolean on stdout** — `deleted` here, `removed` there. Both families report
1882
+ honestly whether the call actually changed anything, and both narrate the
1883
+ no-op case on stderr, so a script can branch on the boolean and a human reading
1884
+ the terminal is told in words.
1885
+
1886
+ **The transfer fields are present on stdout if and only if the wire sent
1887
+ them** — `membersRemoved`, `orphanCrewId`, `orphanCrewName`,
1888
+ `stampsTransferred`, `runsTransferred` (an array of run ids, not a count), and
1889
+ `runningRunsTransferred` (the subset still running, also an array) are never
1890
+ defaulted to `0`/`null`/`[]`. Their absence means nothing moved; their
1891
+ presence means a transfer happened, and stderr also gets a one-line human
1892
+ summary naming the destination crew.
1893
+
1894
+ ### `crew member add <crewId> <principalKind> <principalId>`
1895
+
1896
+ `POST /api/add_crew_member` authenticated as your **human** credential;
1897
+ requires the **admin** role on the hub, **or** the owner of the personal crew
1898
+ being acted on (same self-service carve-out as `crew new`, gated on the
1899
+ fetched crew row rather than the raw request — `manage-crews.ts:300`). Adds
1900
+ `<principalId>` (a member id or an agent id) to the crew as a
1901
+ `<principalKind>` (`member` or `agent`) member. `<principalKind>` is forwarded
1902
+ verbatim and unvalidated, same stance as `--kind` on `crew new`.
1903
+
1904
+ **The hub refuses this outright against the org's orphan crew, for every
1905
+ caller — including an admin.** `assertNotOrphanPool` (`manage-crews.ts:307`)
1906
+ throws before the add ever reaches the membership table, and it is a `400`,
1907
+ never a `403`: the refusal is identity-independent (true for every caller, not
1908
+ a permissions question), so a `403` would wrongly point the caller at their
1909
+ own role. The orphan crew's membership is derived — always the org's current
1910
+ admins, reconciled automatically on every membership change — and cannot be
1911
+ edited directly.
1912
+
1913
+ ### `crew member rm <crewId> <principalId>`
1914
+
1915
+ `POST /api/remove_crew_member`, authenticated as your **human** credential;
1916
+ requires the **admin** role on the hub, **or** the owner of the personal crew
1917
+ being acted on (`manage-crews.ts:356`). Removes `<principalId>` from the crew.
1918
+
1919
+ **`member rm` is idempotent**, mirroring `crew rm`: removing a principal that
1920
+ was never a member of `<crewId>` is a normal `200` with `removed: false`, never
1921
+ a `404`. The CLI prints `removed: false` on stdout and a stderr line naming
1922
+ the principal and crew, rather than treating it as an error.
1923
+
1924
+ **Same orphan-crew refusal as `crew member add`.** Targeting the orphan crew
1925
+ is a `400` here too (`assertNotOrphanPool`, `manage-crews.ts:363`), for every
1926
+ caller including an admin, and for the same reason: the membership is derived,
1927
+ not editable.
1928
+
1929
+ **Flags.** `--hub <url>` only (plus the global `--db`/`--defs`), except `crew
1930
+ new`, which also takes `--kind` (required) and `--owner` (optional).
1931
+
1932
+ **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
1933
+ exit 2 naming both remedies (and, on a multi-hub machine, listing the stored
1934
+ origins). No fallback to `OWENLOOP_HUB`
1935
+ or the built-in default hub; hub enumeration is file-store only.
1936
+
1937
+ **Printed JSON.** stdout is exactly one whitelisted JSON document per
1938
+ invocation — never a raw hub body — so `| jq` always works. Human-facing
1939
+ lines (the tolerant-false notices, the transfer summary) go to stderr only.
1940
+
1941
+ | subcommand | stdout |
1942
+ |---|---|
1943
+ | `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 } ] } ] }` |
1944
+ | `crew new` | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "name": "team-a", "kind": "shared", "ownerMemberId": null }` |
1945
+ | `crew rm` (no transfer) | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "deleted": true, "membersRemoved": 2 }` |
1946
+ | `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"] }` |
1947
+ | `crew rm` (unknown id) | `{ "ok": true, "hub": "<origin>", "crewId": "crw_bogus", "deleted": false }` |
1948
+ | `crew member add` | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "principalKind": "member", "principalId": "u_2" }` |
1949
+ | `crew member rm` | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "principalId": "u_2", "removed": true }` |
1950
+
1951
+ **Exit codes.**
1952
+
1953
+ | code | meaning |
1954
+ |---|---|
1955
+ | `0` | the crew/membership was listed, created, removed (or was already absent) |
1956
+ | `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 |
1957
+ | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
1958
+ | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
1959
+
1960
+ ## `setup` — onboard a machine
1961
+
1962
+ `owenloop setup` is the one-shot onboarding command. It runs seven ordered steps.
1963
+ Depending on the machine state, setup may store the human credential, mint or
1964
+ rekey and store a Scoped Identity credential, ensure the three principal
1965
+ signing keys, relay a signed machine enrollment grant, and write only
1966
+ `hubOrigin` in the execution settings file while preserving its other keys.
1967
+ The plugin step probes and, when needed, converges the bundled `owenloop` plugin
1968
+ for each available harness: Claude Code and Codex. Plugin convergence is
1969
+ non-fatal and setup continues when a harness is missing, the bundled marketplace
1970
+ root is unavailable, or a plugin command fails. A second run with the expected
1971
+ plugin version already installed performs no plugin writes. The steps:
599
1972
 
600
1973
  1. **inspect** — read-only report of what's already present (human credential,
601
- owenwork settings, `claude` on PATH, agent slots). No writes.
1974
+ execution settings, `claude` and `codex` on PATH, agent slots). No writes.
602
1975
  2. **human login** — verify the stored **human** credential, or run the same
603
1976
  loopback-OAuth browser flow as `owenloop login` when none is present or it no
604
1977
  longer verifies. This is the gate that makes step 3's mint/rekey legal.
605
1978
  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**
1979
+ hub and reuse it; otherwise **mint** a new Scoped Identity or **rekey**
607
1980
  (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).
611
- 5. **plugin** — check whether the Claude Code `owenloop` plugin is installed.
612
- **Non-fatal:** while the marketplace is unpublished this step only *prints*
613
- the manual install commands (`claude plugin marketplace add owenloop` then
614
- `claude plugin install owenloop@owenloop`); it never fails setup.
615
- 6. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
1981
+ [below](#choosing-the-scoped-identity-flow-a-vs-flow-b).
1982
+ 4. **signing keys** — ensure an Ed25519 signing key for each of the three local
1983
+ principals, in order: human, machine, agent. Details
1984
+ [below](#signing-keys-step-4). After key convergence, setup performs the
1985
+ enrollment relay sub-step described below.
1986
+ 5. **execution settings** — write only `hubOrigin` into the execution settings
1987
+ file so the local Step Agent talks to this hub, preserving every other key
1988
+ (skipped when `hubOrigin` already matches).
1989
+ 6. **plugin** — probe and converge the bundled `owenloop` plugin separately
1990
+ for Claude Code and Codex. When the installed plugin is missing or its
1991
+ version differs from the CLI package, setup adds the bundled marketplace
1992
+ when needed and installs or updates the plugin. Claude Code uses
1993
+ `claude plugin install` for a fresh install and `claude plugin update` for
1994
+ an existing plugin. Codex uses `codex plugin add owenloop@owenloop` for both
1995
+ fresh installs and upgrades; setup does not call
1996
+ `codex plugin marketplace upgrade`, which applies only to Git marketplaces.
1997
+ **Non-fatal:** a missing harness or failed convergence is reported as
1998
+ `noted` and never fails setup. If the bundled marketplace root is
1999
+ unavailable, setup prints manual commands instead.
2000
+ 7. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
616
2001
  the same surfaces, whose result becomes setup's exit code.
617
2002
 
618
- Progress lines (the `[n/6]` headers and `✓`/`✗` marks) go to **stderr**; the
2003
+ Progress lines (the `[n/7]` headers and `✓`/`✗` marks) go to **stderr**; the
619
2004
  final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
620
2005
  **stdout**.
621
2006
 
622
- ### Choosing the agent (Flow A vs Flow B)
2007
+ ### Choosing the Scoped Identity (Flow A vs Flow B)
623
2008
 
624
- When step 3 has to act (no reusable local agent slot), it decides *which* agent
2009
+ When step 3 has to act (no reusable local agent slot), it decides *which* Scoped Identity
625
2010
  to connect this machine to:
626
2011
 
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.
2012
+ - **Flow A — fresh org (no Scoped Identities on the hub):** setup asks you to
2013
+ **name** the Scoped Identity, prefilled with a sanitized form of the machine hostname.
629
2014
  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**)
2015
+ (1–64 chars) is accepted. It then **mints** that Scoped Identity.
2016
+ - **Flow B — org already has Scoped Identities (succession):** setup shows the existing
2017
+ Scoped Identities (each with its name, when it was **last active**, and its **crews**)
633
2018
  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
2019
+ existing Scoped Identity. Choosing **new** mints a fresh Scoped Identity; choosing **replace**
2020
+ **rekeys** the chosen Scoped Identity — which **revokes that Scoped Identity's current
636
2021
  credential**, so if it is still running elsewhere it will be disconnected
637
2022
  there.
638
2023
 
@@ -640,15 +2025,101 @@ to connect this machine to:
640
2025
  scripted or piped run) and step 3 needs to act, setup will not block on a
641
2026
  prompt — it errors unless you pre-decide with one of:
642
2027
 
643
- - `--new-agent <name>` — mint a new agent named `<name>` (skips Flow A's name
2028
+ - `--new-agent <name>` — mint a new Scoped Identity named `<name>` (skips Flow A's name
644
2029
  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.
2030
+ - `--replace-agent <name>` — rekey the existing Scoped Identity named `<name>` (skips the
2031
+ succession prompt); errors if no such Scoped Identity exists on the hub.
647
2032
 
648
- The two flags are mutually exclusive. `--pools <a,b>` applies **only** to a mint
2033
+ The two flags are mutually exclusive. `--crews <a,b>` applies **only** to a mint
649
2034
  (`--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).
2035
+ error, because rekeying preserves the Scoped Identity's existing crews (manage those in
2036
+ the console). `--scopes <a,b>` likewise applies **only** to a mint — it selects
2037
+ the minted token's scopes (default `work`); combining it with `--replace-agent`
2038
+ is a usage error, because rekeying preserves the Scoped Identity's existing scopes (mint a
2039
+ new Scoped Identity to change scopes). `setup` has no `--shift` shorthand — spell the
2040
+ scopes out with `--scopes work,run`.
2041
+
2042
+ ### Signing keys (step 4)
2043
+
2044
+ Step 4 ensures one Ed25519 signing key per local principal — human, machine,
2045
+ agent — keyed by `{ hub origin, kind, principal id }`. It is **idempotent**:
2046
+ an existing key reports `existing` and is never regenerated or rewritten. A
2047
+ second full setup run performs zero key writes.
2048
+
2049
+ **Storage backends.** The key record goes to the macOS Keychain
2050
+ (`security`), to Linux libsecret (`secret-tool`) when that binary is on
2051
+ `PATH`, and otherwise to a `0600` file under `$HOME/.owenloop/keys/` (both
2052
+ parent directories forced `0700`, symlinks refused). One backend is selected
2053
+ once and a failure is a hard error — there is never a fallback to another
2054
+ backend, because a fallback could mint a second, different key for the same
2055
+ principal. `OWENLOOP_NO_KEYCHAIN=1` forces the file backend. Private bytes
2056
+ never appear on argv or in setup output.
2057
+
2058
+ **`--reuse-ssh-key <path>`** records your own existing Ed25519 SSH key for the
2059
+ **human** principal instead of generating one. The candidate is validated with
2060
+ a non-secret sign/verify challenge before anything is recorded, and only its
2061
+ canonical path + public key are stored — the private key is never copied. It
2062
+ applies to the human key only (machine and agent always get generated keys),
2063
+ and it is a **hard conflict** when a human key already exists: setup keeps the
2064
+ existing key and errors rather than rotating (rotation is not part of this
2065
+ work package). A nonexistent path fails up front, before any browser opens.
2066
+
2067
+ **Secret-output guarantee.** Step 4 prints only `kind state (backend)` — e.g.
2068
+ `✓ signing keys: human created (macos-security), machine created (file), agent
2069
+ existing (macos-security)` — never key bytes, fingerprints, or secret-store
2070
+ values. The full storage and signing model is in
2071
+ [Signing and key storage](crypto.md).
2072
+
2073
+ ### Machine enrollment relay
2074
+
2075
+ After the three keys are ensured, setup tries to register the machine public key
2076
+ with the hub. The relay is deliberately subordinate to local key convergence:
2077
+
2078
+ 1. Read-only inspect the human signing key. If no human signing key is present,
2079
+ setup records `skipped` and performs no enrollment request.
2080
+ 2. `GET /api/enrollments` with the human credential. If the hub is unavailable,
2081
+ returns an unsupported status such as `404`, returns `500`, or returns an
2082
+ unusable response, setup records `noted` and continues.
2083
+ 3. If the machine public-key fingerprint is already present, setup records
2084
+ `skipped` and does not sign or POST a duplicate.
2085
+ 4. Otherwise, the human signing key signs an `EnrollmentGrantRecord` locally.
2086
+ The grant names the machine principal `{ kind: "machine", id: "local" }`,
2087
+ uses the default least-privilege machine scope, and sets `grantedBy` to the
2088
+ human public-key fingerprint.
2089
+ 5. `POST /api/enrollments` receives only `{ envelope }`, where `envelope` is the
2090
+ signed DSSE enrollment grant. The machine private key, human private key
2091
+ bytes, key-store values, and private-key paths never enter the request body.
2092
+ HTTP `409` means already registered and becomes `skipped`; other transport or
2093
+ hub failures become `noted` and do not undo local key creation.
2094
+
2095
+ The relay is idempotent (repeating the operation after the first successful
2096
+ registration changes nothing) and the hub is only a storage/relay endpoint. The
2097
+ hub does not create, sign, or endorse the grant.
2098
+
2099
+ ## `enrollments` — inspect machine enrollment
2100
+
2101
+ `owenloop enrollments [--hub <url>]` fetches the hub's relayed DSSE envelopes and
2102
+ verifies each entry locally. The command is read-only: it does not call key
2103
+ creation, does not sign a grant, and does not POST to the hub. The command uses
2104
+ the local `allowed_signers` trust root when one is configured.
2105
+
2106
+ The command prints `{ ok, hub, enrollments }` on stdout. Each entry has one of
2107
+ four verdicts:
2108
+
2109
+ | verdict | meaning |
2110
+ |---|---|
2111
+ | `enrolled` | the grant payload and DSSE signature are valid, the signer is in the local `allowed_signers` root, and an enrollment-chain validator approved the grant |
2112
+ | `unenrolled` | no envelope was supplied for the roster entry |
2113
+ | `unverifiable` | verification cannot establish trust, including a missing `allowed_signers` root or the D1 fail-closed state where no chain validator is installed |
2114
+ | `invalid` | the envelope, payload, schema, signer authorization, signature, or chain-validator result is invalid |
2115
+
2116
+ WP-D1 intentionally does not install an enrollment-chain validator. Therefore a
2117
+ well-formed, correctly signed D1 grant is reported as `unverifiable` until WP-D4
2118
+ installs the validator. This prevents a signature from being mistaken for proof
2119
+ that the grantor is enrolled.
2120
+
2121
+ A missing human credential is exit `3`; hub, malformed-response, and other
2122
+ runtime failures are exit `1`; successful classification is exit `0`.
652
2123
 
653
2124
  ### Hub resolution differs from `agent new`
654
2125
 
@@ -678,8 +2149,8 @@ the flagship command never opens a browser only to fail at the store.)
678
2149
  ### After setup
679
2150
 
680
2151
  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.
2152
+ reminder to run `owenloop work` with `OWENLOOP_ACCOUNT=<name>` so the Step Agent
2153
+ reads the right slot.
683
2154
 
684
2155
  **Exit codes.**
685
2156
 
@@ -687,7 +2158,7 @@ right slot.
687
2158
  |---|---|
688
2159
  | `0` | every step ended skipped/done/noted **and** doctor's core checks (1–5) passed |
689
2160
  | `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 |
2161
+ | 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
2162
 
692
2163
  ## `doctor` — check a machine's install
693
2164
 
@@ -708,23 +2179,31 @@ The checks, in order:
708
2179
  | 2 | human plane | that credential verifies live against the hub (`whoami`) | yes |
709
2180
  | 3 | agent slot | an `agent:<name>` credential is stored | yes |
710
2181
  | 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 |
712
- | 6 | plugin | the Claude Code `owenloop` plugin is installed | **no** (rendered only) |
2182
+ | 5 | execution settings | the settings file's `hubOrigin` matches this hub | yes |
2183
+ | 6 | plugin (claude-code) | the Claude Code `owenloop` plugin is installed at the package version | **no** (rendered only) |
2184
+ | 7 | plugin (codex) | the Codex `owenloop` plugin is installed at the package version | **no** (rendered only) |
2185
+
2186
+ The plugin checks also report the detected harness CLI version. An installed
2187
+ plugin whose version cannot be parsed is reported as `version unknown` and is
2188
+ not treated as a failure. A parsed plugin version that differs from the
2189
+ package version is reported as version skew with the remedy `run owenloop
2190
+ setup`. A missing harness reports that the harness is not on `PATH`; a missing
2191
+ plugin reports the harness-specific marketplace and install command.
713
2192
 
714
2193
  Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
715
2194
  <origin>`, re-run setup's Replace, and so on). doctor never short-circuits — a
716
- machine with no working human credential still renders lines 3–6, degrading
717
- honestly rather than dropping them.
2195
+ machine with no working human credential still renders the later checks,
2196
+ degrading honestly rather than dropping them.
718
2197
 
719
- **Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise. The
720
- plugin check (6) is *rendered* but does not affect the exit code while the
721
- marketplace is unpublished.
2198
+ **Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise. Both
2199
+ plugin checks (6–7) are *rendered* but do not affect the exit code.
722
2200
 
723
2201
  ## `mcp` — stdio control-plane server for MCP hosts
724
2202
 
725
2203
  `owenloop mcp` is a long-running server that exposes the hub's **human control
726
- plane** to a local MCP host (Claude Code, or any client that speaks MCP over
727
- stdio). This is the `owenloop-cli-mcp` surface: an MCP host spawns it as a
2204
+ plane** to a local MCP host (Claude Code, Codex, or any client that speaks MCP
2205
+ over stdio). The shipped Claude Code and Codex plugins launch this command from
2206
+ `PATH`. This is the `owenloop-cli-mcp` surface: an MCP host spawns it as a
728
2207
  subprocess — **you do not run it yourself at a prompt**. It reads
729
2208
  newline-delimited JSON-RPC 2.0 on stdin, translates each `tools/call` into one
730
2209
  authenticated HTTPS request to the hub's `/api/*` REST mirror, and writes the
@@ -737,34 +2216,84 @@ loopback listener. If no human credential is stored, a tool call returns an
737
2216
  error telling you to run `owenloop login --hub <origin>` in a terminal and retry
738
2217
  (see [Authentication and secrets](#authentication-and-secrets) below).
739
2218
 
2219
+ ### Plugin/CLI version alignment
2220
+
2221
+ The shipped Claude Code and Codex plugins launch `owenloop mcp` from `PATH` and
2222
+ carry the plugin version in `.mcp.json` as `OWENLOOP_PLUGIN_VERSION`. The MCP
2223
+ server compares that expected version with its own package version on every
2224
+ recognized `tools/call`. The comparison is strict equality: a mismatch returns
2225
+ a tool error that names both versions and says `Run: owenloop setup`. The
2226
+ server does not reject the MCP startup handshake, so the diagnostic reaches the
2227
+ model and the human instead of appearing only as a transport-closed error.
2228
+
2229
+ Each plugin also declares a `SessionStart` hook. The hook reads the plugin
2230
+ manifest version, sends an MCP `initialize` request to `owenloop mcp` using a
2231
+ non-routable probe origin, and reads `serverInfo.version`; the root CLI has no
2232
+ supported `owenloop --version` flag. The hook reports a missing CLI, an
2233
+ unparseable version, or a mismatch to stderr and always exits successfully, so
2234
+ a diagnostic cannot block session startup. Claude Code runs the hook after
2235
+ installation. Codex runs plugin hooks only after the user approves them in
2236
+ `/hooks`; if the user does not approve Codex hooks, the always-on MCP check
2237
+ still catches a version mismatch when a tool call is made.
2238
+
2239
+ If the versions differ, run `owenloop setup` and follow the printed plugin
2240
+ installation instructions before retrying the MCP tool call.
2241
+
740
2242
  ### Choosing the hub origin
741
2243
 
742
2244
  `owenloop mcp` binds to exactly one hub origin, resolved in this order:
743
2245
 
744
2246
  1. `--hub <url>` flag.
745
2247
  2. `OWENLOOP_HUB` env var.
746
- 3. If the **file** credential backend holds exactly ONE hub with a valid `human`
747
- credential, that hub is used.
748
- 4. Otherwise it exits `2` and prints why to stderr (nothing is written to
749
- stdout — stdout is the protocol channel).
750
-
751
- There is **no** silent default-hub fallback: a control-plane server must never
752
- bind to a hub you did not name. The exit-`2` messages name both remedies:
753
-
754
- - No hub credentials stored → `run \`owenloop login --hub <origin>\` first, or pass --hub <origin>`.
755
- - More than one hub stored → the message lists every stored origin and says `pass --hub <origin>`.
756
- - The credential store cannot be enumerated (macOS Keychain or an external
757
- credential command) → `pass --hub <origin> (or set OWENLOOP_HUB)`. Only the
758
- file backend can list stored origins, so on a Keychain-backed machine `mcp`
759
- effectively requires `--hub` or `OWENLOOP_HUB`.
760
-
761
- A malformed `--hub`/`OWENLOOP_HUB` value is a normal exit-`1` error, like every
762
- other command.
2248
+ 3. `~/.owenloop/config.json` — see below.
2249
+ 4. If the **file** credential backend holds exactly ONE hub with a valid
2250
+ `human` credential, that hub is used (kept for back-compat with installs
2251
+ from before step 3 existed).
2252
+ 5. The built-in **default hub**, `https://api.owenloop.com`.
2253
+
2254
+ Every inference rung after the first two **falls through silently** rather
2255
+ than stopping the server: a missing or corrupt config file, a `hub` value in
2256
+ it that doesn't parse as a valid origin, an unenumerable credential store
2257
+ (macOS Keychain or an external credential command — only the file backend can
2258
+ be listed at all), zero stored hubs, and more than one stored hub all just
2259
+ move on to the next rung. `owenloop mcp` never exits for an inferred-origin
2260
+ reason — this is deliberate: it is a long-running process spawned
2261
+ automatically by an MCP host on every session start, not a one-shot command a
2262
+ human is watching, so a hard stop here would silently break the plugin on any
2263
+ machine using the Keychain backend (the macOS default) unless the operator
2264
+ remembered to set `--hub` or `OWENLOOP_HUB` first.
2265
+
2266
+ The MCP surface is not read-only. It includes `create_agent`, which mints and
2267
+ stores a new agent token, plus state-changing tools such as `create_workflow`,
2268
+ `publish_event`, `submit`, `stage_enrollment`, and the crew mutations. The
2269
+ server still authenticates each tool call against the resolved origin. When no
2270
+ human credential exists at that origin, the first authenticated tool call
2271
+ returns `loginHint` with the origin and asks for `owenloop login --hub
2272
+ <origin>` before the tool-specific action runs. If a credential does exist at
2273
+ an unintended origin and `create_agent` mints there, the stored agent token is
2274
+ revocable; explicit `--hub` and `OWENLOOP_HUB` remain available to avoid
2275
+ inference. Contrast this with [`agent new`](#agent-new--mint-an-agent-token-into-a-slot),
2276
+ which **mints** a new credential directly and therefore stops rather than
2277
+ ever guessing — a wrong guess there is a side effect a retry cannot undo.
2278
+
2279
+ **`~/.owenloop/config.json`** is written by
2280
+ [`login`](#login--authenticate-the-cli-against-a-hub): a small, non-secret
2281
+ JSON file (`{"version": 1, "hub": "<origin>"}`) recording the hub `login` most
2282
+ recently authenticated against. It exists specifically so `mcp` can learn
2283
+ your hub without enumerating the credential store — see `login`'s own section
2284
+ for exactly when it's written and what happens if the write fails.
2285
+
2286
+ A malformed `--hub`/`OWENLOOP_HUB` value is still a normal exit-`1` error,
2287
+ like every other command — an explicit bad value is reported, never silently
2288
+ skipped, precisely because rungs 1–2 come from something the operator typed
2289
+ or set, not from inference.
763
2290
 
764
2291
  ### Tools
765
2292
 
766
2293
  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
2294
+ `create_agent`, plus four [crew](#crews) tools (`list_crews`, `create_crew`,
2295
+ `add_crew_member`, `remove_crew_member`) that do not mirror the hub's own MCP
2296
+ toolset. Each baseline tool's result is the hub REST response as one text
768
2297
  block; a non-2xx response comes back as an error result.
769
2298
 
770
2299
  | tool | what it does |
@@ -783,20 +2312,61 @@ block; a non-2xx response comes back as an error result.
783
2312
  | `release` | give back a claim so its order is re-offered without waiting out the reap TTL |
784
2313
  | `publish_event` | publish an event against a contract, starting one run per matched subscription |
785
2314
  | `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 |
2315
+ | `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 |
2316
+ | `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
2317
  | `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}`,
2318
+ | `create_agent` | create a NEW Scoped Identity and store its credential locally — **never returns the token** |
2319
+ | `list_crews` | list the org's crews, each with its member rows inline — a plain passthrough, no filtering |
2320
+ | `create_crew` | create a crew (`name`, `kind`, optional `ownerMemberId`) |
2321
+ | `add_crew_member` | add a member or agent principal to a crew |
2322
+ | `remove_crew_member` | remove a principal from a crew (tolerant: removing a non-member is a normal result, not an error) |
2323
+
2324
+ `create_agent {name, crews?, scopes?}` mints a fresh Scoped Identity on the hub
2325
+ with `work` scope by default; pass `scopes` (e.g. `["work","run"]`) to choose the
2326
+ minted token's scopes. It then writes the minted `olp_` token straight to this
2327
+ machine's credential store (slot `agent:<name>`). The token is **never** returned in the
2328
+ tool result, printed, or logged — the result is `{name, crews, stored: true}`,
795
2329
  built from scratch. It refuses a name that is already taken (the hub's error
796
2330
  message is surfaced verbatim; error bodies never carry tokens). If the store
797
2331
  write fails, the result says so and tells you to revoke/re-key the agent from
798
2332
  the console.
799
2333
 
2334
+ **The four crew tools** (`list_crews`, `create_crew`, `add_crew_member`,
2335
+ `remove_crew_member`) cover the same four operations as the [`crew` CLI
2336
+ family](#crews) — `crew list`, `crew new`, `crew member add`, `crew member
2337
+ rm` — over the same `/api/*` routes and the same RBAC, but they are not an
2338
+ exact mirror of it: `crew rm` (crew deletion) has no MCP counterpart at all
2339
+ (see below), and where the CLI narrows each hub response into one
2340
+ whitelisted JSON document per invocation (`asPools`, `asPoolCreated`, etc.,
2341
+ so `| jq` always works), these MCP tools are plain passthroughs — the raw
2342
+ hub REST body maps straight to the tool result with no narrowing. Each
2343
+ argument schema deliberately has **no `enum`** on `kind`/`principalKind`,
2344
+ since the hub, not this client, is the enforcement of record for which
2345
+ values are legal.
2346
+
2347
+ Access is **not uniformly admin-only**: `create_crew`, `add_crew_member`, and
2348
+ `remove_crew_member` all carry the same self-service carve-out as their CLI
2349
+ counterparts — a human acting on a **personal crew they own** needs no admin
2350
+ role at all (`assertPoolMutationAllowed`); every other target (a `shared`
2351
+ crew, or a `personal` crew owned by someone else) still requires the admin
2352
+ role. `list_crews` is readable by any of `admin`/`author`/`operator`.
2353
+ `remove_crew_member` is **tolerant**: removing a principal that was never a
2354
+ member is a normal `200` result with `removed: false`, never a tool error.
2355
+ `add_crew_member` is **not** tolerant the same way — adding a principal that
2356
+ is already a member is a hub error, mapped to an `isError` result. Both
2357
+ `add_crew_member` and `remove_crew_member` refuse the org's orphan crew
2358
+ (`orphan:unrouted`) as a `400`, never a `403` — the refusal is
2359
+ identity-independent (it objects to the target crew, not the caller's role),
2360
+ since that crew's membership is derived from the org's current admins and
2361
+ cannot be edited directly.
2362
+
2363
+ **`delete_crew` is deliberately NOT a tool here.** Deleting a crew is a
2364
+ one-way-door operation gated admin-only unconditionally on the hub (unlike
2365
+ the other three verbs, which have the self-service carve-out above), and it
2366
+ was excluded from this MCP surface by design. `owenloop crew rm` on the CLI
2367
+ remains the only way to delete a crew; removing a single **member** (above)
2368
+ is a different, reversible operation and stays in scope for MCP.
2369
+
800
2370
  One further tool, `stage_enrollment`, is **conditionally** registered — it
801
2371
  appears only when the hub advertises the staging endpoint (or when
802
2372
  `OWENLOOP_MCP_ENROLLMENT=1` forces it on). It returns a join code the new agent
@@ -820,7 +2390,7 @@ interactively.
820
2390
 
821
2391
  | variable | effect |
822
2392
  |---|---|
823
- | `OWENLOOP_HUB` | hub origin when `--hub` is absent (rung 2 of origin resolution) |
2393
+ | `OWENLOOP_HUB` | development override for the hub origin (rung 2, above `~/.owenloop/config.json`) |
824
2394
  | `OWENLOOP_MCP_ENROLLMENT` | `1` forces `stage_enrollment` on, `0` off; unset = probe the hub |
825
2395
  | `OWENLOOP_MCP_PROBE_TIMEOUT_MS` | deadline for the `stage_enrollment` capability probe (default `3000`) |
826
2396
  | `OWENLOOP_HUB_TIMEOUT_MS` | per-request hub timeout (shared with the other hub commands) |
@@ -842,7 +2412,7 @@ codebase-advisor pipeline combining collections, a mid-flight human gate,
842
2412
  per-element knock-backs, and suffixed-reduce fan-ins). Each example's header
843
2413
  comment walks through its commands end to end.
844
2414
 
845
- Playing every worker yourself is the fastest way to internalize the loop.
2415
+ Playing every Step Agent yourself is the fastest way to internalize the loop.
846
2416
  Every command prints JSON, so the snippet below pipes through `jq`:
847
2417
 
848
2418
  ```sh
@@ -860,7 +2430,7 @@ owenloop defs # what workflows are available
860
2430
  wf=$(owenloop create delivery \
861
2431
  --provide proposal='{"text":"add dark mode"}' | jq -r .workflow)
862
2432
 
863
- # the worker loop: tick → run → report
2433
+ # the Step Agent loop: tick → run → report
864
2434
  run=$(owenloop tick $wf | jq -r '.orders[0].run') # claim the planner job
865
2435
  owenloop green $wf $run plan --value '{"plan":"…"}' # report its output
866
2436
 
@@ -887,7 +2457,7 @@ instead of waiting for the next tick. `owenloop reap <wf>` runs that same
887
2457
  cleanup on demand, applying the normal per-step/engine TTL rules — usually a
888
2458
  no-op (`{ reaped: 0, details: [] }`). `owenloop reap <wf> --now` is the admin
889
2459
  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
2460
+ how fresh its claim is, for reclaiming a Step Agent you know is dead without
891
2461
  waiting out the TTL. Reaping re-arms the task immediately, so **the run that
892
2462
  held the cleared lease can no longer commit** — its next `green`/`close` fails
893
2463
  with `run <id> no longer holds its lease (reaped or superseded)`, the same
@@ -927,13 +2497,18 @@ can be born-rejected too — a [judge's](authoring.md#judges--quality-gates-befo
927
2497
  verdict lands on a stale `submitted` version (a sibling judge already settled
928
2498
  it, the producer resubmitted, or a human bypassed it) and the CAS guard
929
2499
  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
2500
+ reason goes to stderr. A successful call exits 0 — a Step Agent should treat a
931
2501
  non-zero exit as a failure, not a success.
932
2502
 
933
2503
  ## What a job looks like
934
2504
 
935
- `tick` returns `{ workflow, orders, reaped }`. Each order is self-contained —
936
- a worker needs nothing else to do the work:
2505
+ `tick` returns `{ workflow, orders, reaped }`. Each order is a **reference
2506
+ packet**: it carries the routing fields and run-time context for the job — the
2507
+ run id, the captured input values, the owed outputs with their reason threads
2508
+ — plus a `defDigest` that names *which definition snapshot* holds the authored
2509
+ instructions. The instructions themselves (the step's `body:` prompt, any
2510
+ `command:` text) are **not** on the order, and `tick`/`order` never print
2511
+ them.
937
2512
 
938
2513
  ```jsonc
939
2514
  {
@@ -941,22 +2516,42 @@ a worker needs nothing else to do the work:
941
2516
  "workflow": "wf_…", // the instance this order belongs to — see deep tick below
942
2517
  "step": "builder", // which step this job is for
943
2518
  "key": "", // map jobs carry the element key + index
2519
+ "defDigest": "9f2c…", // identifies the definition snapshot to resolve instructions from
944
2520
  "inputs": ["plan"],
945
2521
  "outputs": ["pr"],
946
- "prompt": "…body with ${WORKFLOW}/${RUN}/${INDEX} filled in…",
2522
+ "worker": "command", // the authored step's executor:, mapped verbatim (absent = 'agent')
947
2523
  "consumes": { "plan": { /* the accepted input value */ } },
948
2524
  "owes": [ // the feedback channel
949
- { "path": "pr", "acceptance": "rejected", "judgmentRejects": 2, "schemaRejects": 0,
2525
+ { "path": "pr", "judgmentRejects": 2, "schemaRejects": 0,
950
2526
  "reasons": [ { "action": "reject", "kind": "judgment", "by": "reviewer",
951
2527
  "text": "tests are missing", "at": 0 } ] }
952
2528
  ]
953
2529
  }
954
2530
  ```
955
2531
 
956
- A worker reads `prompt` + `consumes` + `owes`, does the work, reports with
957
- `green` (or `emit`/`seal` for collections), then `close`s the job. The reject
958
- counts in `owes[]` let a workflow escalate on its own — e.g. switch to a
959
- stronger model after two rejections — before the engine stalls the step.
2532
+ A worker first **resolves the reference**: the `(defDigest, step, key)`
2533
+ boundary maps the order to the exact authored instructions from the worker's
2534
+ trusted local definition source — the same resolver the embedded engine and
2535
+ the CLI use. Resolution returns the authored `prompt` (with
2536
+ `${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}`
2537
+ materialized), the authored `command` if the step has one, and nothing
2538
+ fabricated. If the worker's source does not know the digest — the definition
2539
+ was never delivered, or the current on-disk definition no longer matches the
2540
+ pinned digest — resolution raises `UnknownDefDigestError`. If the digest is
2541
+ known but the referenced step is absent, resolution raises the distinct
2542
+ `UnknownInstructionError` and identifies the digest, step, and key. The worker
2543
+ must refuse either malformed reference rather than guess instructions by step
2544
+ name or fetch unverified text. Once resolved, the worker reads the resolved
2545
+ prompt + `consumes` + `owes`, does the work, reports with `green` (or
2546
+ `emit`/`seal` for collections), then `close`s the job. The reject counts in
2547
+ `owes[]` let a workflow escalate on its own — e.g. switch to a stronger model
2548
+ after two rejections — before the engine stalls the step.
2549
+
2550
+ Static authored text (prompts, commands) travels by digest reference; dynamic
2551
+ data — `consumes` values and the rejection `reasons` threads — stays on the
2552
+ order because it exists only for this run. A remote coordinator or transport
2553
+ that relays these packets never sees authored instruction text and never needs
2554
+ to: instructions resolve at the worker, from a source the worker trusts.
960
2555
 
961
2556
  **Deep tick and `order.workflow`.** `tick <wf>` is **deep by default**: it ticks
962
2557
  `<wf>` and then descends into every live `calls:` child, folding their orders
@@ -969,25 +2564,25 @@ is the earliest wake across all levels. A folded deferral in the deep result
969
2564
  carries its own `workflow` (absent = the root you ticked, present = a
970
2565
  descendant).
971
2566
 
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
2567
+ **Capability routing (`--capability`).** `tick <wf> --capability <l>` (repeatable) filters
2568
+ which steps this caller claims, but only steps that carry their own `capabilities:`
2569
+ are ever excluded: a step is deferred with reason `capability-mismatch` and left for
2570
+ another caller **only** when its `capabilities:` are non-empty and share no value with
2571
+ the filter you pass. A step with no `capabilities:` is claimed by every caller,
2572
+ filtered or not, and a tick that passes no `--capability` claims every eligible step
2573
+ regardless of capabilities. This is **routing, not
979
2574
  authorization**: any caller that can reach the database can tick without a
980
- filter and claim anything, so labels split work across cooperating
2575
+ filter and claim anything, so capabilities split work across cooperating
981
2576
  orchestrators, they never enforce a boundary. See
982
- [`labels:`](authoring.md#labels--routing-a-step-to-a-particular-tick-caller) in
2577
+ [`capabilities:`](authoring.md#capabilities--logical-capability-tags) in
983
2578
  the authoring guide for the step-side declaration and the starvation hazard to
984
2579
  watch for.
985
2580
 
986
2581
  **Child stalls on `status`.** `status <wf>`'s `calls:`-debt entries carry a
987
2582
  `child: { workflow, def, done, stalled, debts }` summary once a child has been
988
2583
  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
2584
+ Step Agent stuck at `maxAttempts` with no green outcome — the parent debt is blocked
2585
+ on stuck child work. This lets a Shift spot a wedged child from the parent
991
2586
  `status` alone, without separately walking into the child's own `status`.
992
2587
 
993
2588
  **`wait --until` is single-instance.** `wait <wf> --until eligible|done` polls