owenloop 0.5.0 → 0.5.2

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 (229) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +144 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +29 -4
  5. package/dist/packages/work/src/agent/brief.js +49 -4
  6. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  7. package/dist/packages/work/src/agent/capability-model.js +148 -0
  8. package/dist/packages/work/src/agent/loop.d.ts +56 -7
  9. package/dist/packages/work/src/agent/loop.js +166 -9
  10. package/dist/packages/work/src/bundle/cache.d.ts +7 -5
  11. package/dist/packages/work/src/bundle/cache.js +20 -6
  12. package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
  13. package/dist/packages/work/src/bundle/fetch.js +27 -7
  14. package/dist/packages/work/src/bundle/types.d.ts +8 -4
  15. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  16. package/dist/packages/work/src/consumed-verifier.js +205 -0
  17. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  18. package/dist/packages/work/src/exec/instructions.js +323 -0
  19. package/dist/packages/work/src/exec/loop.d.ts +29 -1
  20. package/dist/packages/work/src/exec/loop.js +313 -35
  21. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  22. package/dist/packages/work/src/exec/payload.js +54 -0
  23. package/dist/packages/work/src/exec/receipt.d.ts +9 -6
  24. package/dist/packages/work/src/exec/receipt.js +12 -1
  25. package/dist/packages/work/src/exec/runner.d.ts +7 -1
  26. package/dist/packages/work/src/exec/runner.js +84 -3
  27. package/dist/packages/work/src/harness/child-env.js +7 -0
  28. package/dist/packages/work/src/harness/claude.d.ts +20 -8
  29. package/dist/packages/work/src/harness/claude.js +260 -58
  30. package/dist/packages/work/src/harness/codex.d.ts +5 -4
  31. package/dist/packages/work/src/harness/codex.js +169 -41
  32. package/dist/packages/work/src/harness/contract.d.ts +36 -11
  33. package/dist/packages/work/src/harness/fake.js +1 -0
  34. package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
  35. package/dist/packages/work/src/harness/permissions.d.ts +16 -3
  36. package/dist/packages/work/src/harness/permissions.js +102 -13
  37. package/dist/packages/work/src/harness/session-store.d.ts +30 -10
  38. package/dist/packages/work/src/harness/session-store.js +317 -89
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +134 -12
  41. package/dist/packages/work/src/hub/client.d.ts +8 -1
  42. package/dist/packages/work/src/hub/client.js +15 -1
  43. package/dist/packages/work/src/hub/types.d.ts +137 -33
  44. package/dist/packages/work/src/hub/types.js +8 -10
  45. package/dist/packages/work/src/mcp/server.js +1 -1
  46. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  47. package/dist/packages/work/src/owenloop-bin.js +18 -0
  48. package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
  49. package/dist/packages/work/src/roles/agent-run.js +115 -34
  50. package/dist/packages/work/src/roles/exec.d.ts +8 -0
  51. package/dist/packages/work/src/roles/exec.js +27 -2
  52. package/dist/packages/work/src/roles/hold.d.ts +6 -0
  53. package/dist/packages/work/src/roles/hold.js +83 -13
  54. package/dist/packages/work/src/roles/lint.d.ts +3 -4
  55. package/dist/packages/work/src/roles/lint.js +41 -7
  56. package/dist/packages/work/src/roles/settings.js +19 -2
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +36 -2
  59. package/dist/packages/work/src/settings/settings.d.ts +70 -1
  60. package/dist/packages/work/src/settings/settings.js +90 -4
  61. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  62. package/dist/packages/work/src/shift/logretention.js +407 -0
  63. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  64. package/dist/packages/work/src/shift/logsink.js +98 -0
  65. package/dist/packages/work/src/shift/loop.d.ts +32 -4
  66. package/dist/packages/work/src/shift/loop.js +687 -166
  67. package/dist/packages/work/src/shift/protocol.d.ts +128 -1
  68. package/dist/packages/work/src/shift/protocol.js +14 -0
  69. package/dist/packages/work/src/shift/runtime.d.ts +16 -0
  70. package/dist/packages/work/src/shift/runtime.js +291 -5
  71. package/dist/packages/work/src/shift/server.d.ts +13 -0
  72. package/dist/packages/work/src/shift/server.js +61 -36
  73. package/dist/packages/work/src/shift/spawn.d.ts +115 -19
  74. package/dist/packages/work/src/shift/spawn.js +234 -30
  75. package/dist/packages/work/src/shift/state.d.ts +76 -49
  76. package/dist/packages/work/src/shift/state.js +350 -103
  77. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  78. package/dist/packages/work/src/shift/truncate.js +73 -0
  79. package/dist/packages/work/src/submit-proof.d.ts +61 -0
  80. package/dist/packages/work/src/submit-proof.js +119 -0
  81. package/dist/packages/work/src/submit-value.d.ts +48 -0
  82. package/dist/packages/work/src/submit-value.js +118 -0
  83. package/dist/packages/work/src/usage.d.ts +1 -1
  84. package/dist/packages/work/src/usage.js +11 -0
  85. package/dist/src/add.d.ts +64 -259
  86. package/dist/src/add.js +81 -615
  87. package/dist/src/archive.d.ts +97 -0
  88. package/dist/src/archive.js +591 -0
  89. package/dist/src/bundle/index.d.ts +64 -0
  90. package/dist/src/bundle/index.js +508 -0
  91. package/dist/src/bundle/manifest.d.ts +50 -0
  92. package/dist/src/bundle/manifest.js +435 -0
  93. package/dist/src/bundle/runtime.d.ts +26 -0
  94. package/dist/src/bundle/runtime.js +64 -0
  95. package/dist/src/bundle/tar.d.ts +62 -0
  96. package/dist/src/bundle/tar.js +238 -0
  97. package/dist/src/bundle/types.d.ts +105 -0
  98. package/dist/src/bundle/types.js +21 -0
  99. package/dist/src/capabilities.d.ts +93 -0
  100. package/dist/src/capabilities.js +101 -0
  101. package/dist/src/cli.d.ts +90 -20
  102. package/dist/src/cli.js +2421 -374
  103. package/dist/src/credentials.d.ts +4 -3
  104. package/dist/src/credentials.js +21 -19
  105. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  106. package/dist/src/crypto/allowed-signers.js +307 -0
  107. package/dist/src/crypto/canonical.d.ts +8 -0
  108. package/dist/src/crypto/canonical.js +92 -0
  109. package/dist/src/crypto/chain.d.ts +65 -0
  110. package/dist/src/crypto/chain.js +377 -0
  111. package/dist/src/crypto/dsse.d.ts +209 -0
  112. package/dist/src/crypto/dsse.js +282 -0
  113. package/dist/src/crypto/enrollment.d.ts +78 -0
  114. package/dist/src/crypto/enrollment.js +186 -0
  115. package/dist/src/crypto/index.d.ts +48 -0
  116. package/dist/src/crypto/index.js +44 -0
  117. package/dist/src/crypto/keys.d.ts +258 -0
  118. package/dist/src/crypto/keys.js +908 -0
  119. package/dist/src/crypto/org-root.d.ts +33 -0
  120. package/dist/src/crypto/org-root.js +78 -0
  121. package/dist/src/crypto/origin-rules.d.ts +56 -0
  122. package/dist/src/crypto/origin-rules.js +143 -0
  123. package/dist/src/crypto/policy-floor.d.ts +98 -0
  124. package/dist/src/crypto/policy-floor.js +353 -0
  125. package/dist/src/crypto/records.d.ts +319 -0
  126. package/dist/src/crypto/records.js +168 -0
  127. package/dist/src/crypto/scope.d.ts +49 -0
  128. package/dist/src/crypto/scope.js +83 -0
  129. package/dist/src/crypto/ssh.d.ts +171 -0
  130. package/dist/src/crypto/ssh.js +396 -0
  131. package/dist/src/crypto/submission.d.ts +33 -0
  132. package/dist/src/crypto/submission.js +47 -0
  133. package/dist/src/crypto/trust-roots.d.ts +29 -0
  134. package/dist/src/crypto/trust-roots.js +39 -0
  135. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  136. package/dist/src/crypto/verify-consumed.js +259 -0
  137. package/dist/src/crypto/verify-origin.d.ts +50 -0
  138. package/dist/src/crypto/verify-origin.js +151 -0
  139. package/dist/src/crypto/verify-publication.d.ts +60 -0
  140. package/dist/src/crypto/verify-publication.js +150 -0
  141. package/dist/src/defs.d.ts +24 -1
  142. package/dist/src/defs.js +335 -27
  143. package/dist/src/engine.d.ts +211 -6
  144. package/dist/src/engine.js +459 -59
  145. package/dist/src/factory.d.ts +16 -0
  146. package/dist/src/factory.js +16 -4
  147. package/dist/src/global-config.d.ts +59 -0
  148. package/dist/src/global-config.js +84 -0
  149. package/dist/src/hub.d.ts +102 -32
  150. package/dist/src/hub.js +147 -58
  151. package/dist/src/index.d.ts +19 -2
  152. package/dist/src/index.js +23 -2
  153. package/dist/src/install.d.ts +538 -0
  154. package/dist/src/install.js +1981 -0
  155. package/dist/src/lock.d.ts +15 -57
  156. package/dist/src/lock.js +251 -143
  157. package/dist/src/mcp/serve.d.ts +46 -22
  158. package/dist/src/mcp/serve.js +174 -44
  159. package/dist/src/mcp/server.js +12 -1
  160. package/dist/src/model.d.ts +51 -0
  161. package/dist/src/model.js +157 -1
  162. package/dist/src/order-resolver.d.ts +184 -0
  163. package/dist/src/order-resolver.js +252 -0
  164. package/dist/src/package-version.d.ts +10 -0
  165. package/dist/src/package-version.js +42 -0
  166. package/dist/src/paths.d.ts +14 -1
  167. package/dist/src/paths.js +18 -0
  168. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  169. package/dist/src/schemas/index.d.ts +1433 -0
  170. package/dist/src/schemas/index.js +31 -0
  171. package/dist/src/schemas/order.v1.schema.json +120 -0
  172. package/dist/src/schemas/origin.v1.schema.json +68 -0
  173. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  174. package/dist/src/schemas/publication.v1.schema.json +31 -0
  175. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  176. package/dist/src/schemas/submission.v1.schema.json +61 -0
  177. package/dist/src/store/def-source.d.ts +52 -0
  178. package/dist/src/store/def-source.js +335 -0
  179. package/dist/src/store/index-file.d.ts +69 -0
  180. package/dist/src/store/index-file.js +151 -0
  181. package/dist/src/store/index.d.ts +27 -0
  182. package/dist/src/store/index.js +22 -0
  183. package/dist/src/store/ingestor.d.ts +43 -0
  184. package/dist/src/store/ingestor.js +211 -0
  185. package/dist/src/store/install.d.ts +228 -0
  186. package/dist/src/store/install.js +555 -0
  187. package/dist/src/store/instruction-source.d.ts +49 -0
  188. package/dist/src/store/instruction-source.js +298 -0
  189. package/dist/src/store/origin-evidence.d.ts +21 -0
  190. package/dist/src/store/origin-evidence.js +66 -0
  191. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  192. package/dist/src/store/pre-commit-verifier.js +418 -0
  193. package/dist/src/store/resolve.d.ts +138 -0
  194. package/dist/src/store/resolve.js +363 -0
  195. package/dist/src/store/types.d.ts +288 -0
  196. package/dist/src/store/types.js +356 -0
  197. package/dist/src/store.d.ts +33 -1
  198. package/dist/src/store.js +57 -4
  199. package/dist/src/types.d.ts +146 -12
  200. package/dist/src/untar.d.ts +8 -23
  201. package/dist/src/untar.js +10 -136
  202. package/docs/agent-runner.md +86 -0
  203. package/docs/authoring.md +64 -6
  204. package/docs/bundles.md +350 -0
  205. package/docs/cli.md +1298 -106
  206. package/docs/crypto.md +832 -0
  207. package/docs/design.md +342 -20
  208. package/docs/embedding.md +132 -25
  209. package/docs/shift-logs.md +642 -0
  210. package/docs/wire-contracts.md +395 -0
  211. package/package.json +6 -1
  212. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  213. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  214. package/plugins/claude-code/plugin/.mcp.json +14 -0
  215. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  216. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  217. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  218. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  219. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  220. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  221. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  222. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  223. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  224. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  225. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  226. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  227. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  228. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  229. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -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,10 +44,17 @@ 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
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) |
53
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) |
@@ -58,11 +65,13 @@ for the full breakdown.
58
65
  | `crew rm <crewId> [--hub <url>]` | delete a crew; work stamped to it moves to the org's orphan crew — see [Crews](#crews) |
59
66
  | `crew member add <crewId> <principalKind> <principalId> [--hub <url>]` | add a member or agent to a crew — see [Crews](#crews) |
60
67
  | `crew member rm <crewId> <principalId> [--hub <url>]` | remove a principal from a crew — see [Crews](#crews) |
61
- | `setup [--hub <url>] [--new-agent <name> \| --replace-agent <name>] [--crews <a,b>] [--scopes <a,b>]` | onboard this machine: may store human and Scoped Identity credentials, write only execution-settings `hubOrigin`, and after probing print missing-plugin commands instead of installing the plugin — see [`setup`](#setup--onboard-a-machine) |
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) |
62
70
  | `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
63
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) |
64
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) |
65
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) |
66
75
  | `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
67
76
  | `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
68
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 |
@@ -83,6 +92,62 @@ for the full breakdown.
83
92
  | `delete <wf>` | delete an instance and all its rows |
84
93
  | `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
85
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
+
86
151
  ## `shift` — foreground daemon and client
87
152
 
88
153
  `owenloop shift` is the public local dispatch surface. `shift start` runs the
@@ -91,6 +156,12 @@ self-driven dispatch loop as a foreground process and listens on
91
156
  and one JSON-line response. The daemon keeps polling and dispatching while no
92
157
  `shift next` client is attached.
93
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
+
94
165
  The `shift start` positional argument is a **crew** name. The routing API calls
95
166
  that field a **crew**: `serve_crews` contains the selected crew names. Passing
96
167
  `--all` maps to an empty `serve_crews` list, which means all crews available to
@@ -108,7 +179,7 @@ The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
108
179
  ```text
109
180
  owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
110
181
  [--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]
111
- [--cache-dir <p>] [--state-dir <p>]
182
+ [--cache-dir <p>] [--state-dir <p>] [--log-dir <p>] [--log-max-age <ms>]
112
183
  ```
113
184
 
114
185
  At least one named crew is required unless `--all` is present. `--all` and
@@ -128,6 +199,92 @@ one loop sweep and exits instead of keeping the foreground daemon running.
128
199
  | `--once` | run one loop sweep and exit; without it, keep the daemon in the foreground |
129
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` |
130
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
+ | `--log-dir <p>` | where `shift.log` and each `<run>.log` are written; precedence is flag, then `OWENLOOP_SHIFT_LOG_DIR`, then `settings.shiftLogDir`, then the resolved state directory |
203
+ | `--log-max-age <ms>` | worker-log retention, swept once at startup; precedence is flag, then `OWENLOOP_SHIFT_LOG_MAX_AGE_MS`, then `settings.shiftLogMaxAgeMs`, then `1209600000` (14 days). `0` reaps every completed run's log at the next startup; there is no value that disables the sweep, and `shift.log` is never reaped |
204
+
205
+ **On-disk logs.** A running shift appends its dispatch record to
206
+ `<log-dir>/shift.log` as JSON Lines, and gives each dispatched worker's stdout
207
+ and stderr their own `<log-dir>/<run>.log`. Both files outlive the shift
208
+ process. A log directory that cannot be created costs the logs, never the
209
+ dispatch: the shift reports it once on stderr and serves with logging disabled.
210
+ Full field-by-field contract, retention rules, and uploader notes in
211
+ [`docs/shift-logs.md`](shift-logs.md).
212
+
213
+ **One harness per shift.** A shift has no per-order harness switch and no
214
+ `--harness` flag. It never puts `--harness` on a worker's command line; each
215
+ `agent-run` child resolves its own adapter, in this order:
216
+
217
+ 1. its own `--harness` flag — which a shift never supplies;
218
+ 2. `OWENLOOP_HARNESS` in the environment the child inherits, which is the
219
+ shift's environment;
220
+ 3. the `harness:` field on the verified step definition;
221
+ 4. the first registered adapter.
222
+
223
+ Rank 2 is the operator's control. Export `OWENLOOP_HARNESS` in the shell that
224
+ starts the shift and every agent order that shift dispatches runs on that
225
+ adapter. To run two adapters at once, start two shifts:
226
+
227
+ ```bash
228
+ OWENLOOP_HARNESS=claude-code XDG_CONFIG_HOME=~/.config/owenloop-shifts/claude owenloop shift start build --state-dir ~/.local/state/owenloop/claude
229
+ ```
230
+
231
+ ```bash
232
+ OWENLOOP_HARNESS=codex XDG_CONFIG_HOME=~/.config/owenloop-shifts/codex owenloop shift start build --state-dir ~/.local/state/owenloop/codex
233
+ ```
234
+
235
+ Both shifts may serve the SAME crew. The hub does not route by harness — it
236
+ offers an order to any shift whose crew is bound to the order's capability, and
237
+ whichever shift claims it first runs it on its own adapter.
238
+
239
+ **Per-shift `XDG_CONFIG_HOME` is not optional when the adapters differ.** The
240
+ settings file resolves from `XDG_CONFIG_HOME` (see above), and it carries
241
+ `capabilityModels` — a map of composed capability to `{model, effort}` whose
242
+ model ids are strings the SHIFT'S OWN adapter accepts. Two shifts on different
243
+ adapters need different model ids for the same capability, so they need
244
+ different settings files, so they need different `XDG_CONFIG_HOME` values. A
245
+ shared config directory would give both shifts one adapter's model ids, and the
246
+ shift holding the wrong adapter fails at the vendor API on its first order.
247
+
248
+ Give each shift its own `--state-dir` as well. The state directory holds the
249
+ control socket (`shift.sock`), and a second shift starting against a socket
250
+ another shift already owns is refused.
251
+
252
+ **`capabilityModels` — which model serves which capability.** The hub decides
253
+ WHAT grade of work an order is; it composes the step's capability with the run's
254
+ depth modifier and stamps the result on the order (`builder` at the `deep`
255
+ modifier becomes `builder:deep`). It never decides which model serves that
256
+ grade. That decision is local, and this map is where the operator makes it:
257
+
258
+ ```json
259
+ {
260
+ "capabilityModels": {
261
+ "builder:deep": { "model": "claude-opus-5", "effort": "xhigh" },
262
+ "builder": { "model": "claude-sonnet-5", "effort": "high" },
263
+ "wise": { "model": "claude-fable-5", "effort": "xhigh" }
264
+ }
265
+ }
266
+ ```
267
+
268
+ Lookup runs two passes over the order's capabilities: every EXACT composed key
269
+ first, then every BARE name part. `builder:deep` takes the first row above;
270
+ `builder:express` has no exact row and falls back to the `builder` row.
271
+ `effort` must be one of `low`, `medium`, `high`, `xhigh`, `max`. The model id is
272
+ never checked against a list — owenloop keeps no registry of which models exist,
273
+ so a model released after your owenloop build still works.
274
+
275
+ A capability with no exact row and no bare row is REFUSED, not run on a default:
276
+ the worker releases the claim, reports the refusal to the hub, and exits `1`. An
277
+ order carrying no capabilities at all is not refused — it runs on the adapter's
278
+ own default model, which is how capability-silent steps have always run.
279
+
280
+ **Migrating from `tierMap` / `tierProfiles`.** Both keys are removed. A settings
281
+ file that still contains either one fails to load with an error naming
282
+ `capabilityModels`; the shift does not start. This is deliberate — a shift that
283
+ ignored the old keys would have no capability map at all and would refuse every
284
+ order it claimed, hours later and far from the cause. Rewrite the tier rungs as
285
+ capability rows: whatever `tierProfiles.strongest` pointed at becomes the
286
+ `{model, effort}` of your `:deep` rows, and whatever `standard` pointed at
287
+ becomes the bare rows.
131
288
 
132
289
  A clean start or `--once` completion exits `0`. `owenloop shift --help` also
133
290
  exits `0`. Runtime failures such as credential reads or socket/runtime setup
@@ -137,6 +294,39 @@ hub origin, or a missing Scoped Identity credential — exit `2`. The foreground
137
294
  daemon's normal lifecycle line is written to stdout when it stays running;
138
295
  diagnostics go to stderr.
139
296
 
297
+ **Dispatch-state safety.** Every current-version direct Shift loop that shares a
298
+ state directory serializes the capacity recheck and durable reservation under
299
+ the same `.dispatch.lock`. The lock is released before process spawn; the per-run
300
+ reservation carries the capacity slot through spawn and PID persistence. Two
301
+ current-version loops therefore cannot both consume the same last slot, and a
302
+ loop that loses the shared-capacity race keeps its already-claimed candidate in
303
+ its local queue. Older Shift loops that predate `.dispatch.lock` do not
304
+ participate in that boundary and must not share the state directory during the
305
+ upgrade. The state directory does not persist one canonical cap: if current-
306
+ version loops sharing the directory are configured with different total or
307
+ agent caps, each loop enforces its own configured limits under the shared lock.
308
+ Use identical cap settings for every loop sharing a state directory.
309
+
310
+ Canonical `*.json` child and reservation records are capacity-bearing state.
311
+ Missing records are benign, including a record that disappears between listing
312
+ and read. A truncated, malformed, or unreadable canonical record is not benign:
313
+ reconciliation fails closed, names the exact path, and disables dispatch until
314
+ an operator repairs the record or removes the record after verifying that no
315
+ child still owns the slot. Owenloop does not skip corrupt records and guess that
316
+ capacity is free. Reconciliation also cancels a reservation when the worker has
317
+ removed its gate after the worker's monotonic two-minute wait, regardless of the
318
+ persisted wall-clock age. A reservation timestamp later than the current wall
319
+ clock is cancelled along with its closed start gate.
320
+
321
+ Persisted reservation age still uses wall time because a monotonic instant cannot
322
+ be reconstructed after a host restart. A smaller backward clock adjustment that
323
+ leaves `reservedAt` in the past can therefore prolong a reservation whose gate
324
+ still exists, such as a parent crash before spawn. The reservation remains
325
+ capacity-bearing until wall time reaches the age limit or an operator verifies
326
+ that no child can start and removes the record and gate. This limitation cannot
327
+ allow provider or command work past the gate: a spawned child independently
328
+ removes the gate and exits after its monotonic two-minute wait.
329
+
140
330
  ### `shift next [--wait <seconds>]`
141
331
 
142
332
  ```text
@@ -156,14 +346,46 @@ returns promptly when an event is queued, the wait expires, or the shift
156
346
  explicitly ends. A normal timeout exits `0` and prints the current capacity
157
347
  object, for example `{ "cap": 3, "free": 3, "running": 0, "events": [] }`.
158
348
  Successful responses use the same capacity shape and may include queued event
159
- objects. For `dispatched`, `reaped`, and `failed`, `kind` is either `exec` or
160
- `agent-run`:
349
+ objects.
350
+
351
+ **Every event carries the same three envelope fields**, in addition to whatever
352
+ its own `type` defines:
353
+
354
+ | field | meaning |
355
+ |---|---|
356
+ | `ts` | ISO-8601 UTC with milliseconds, e.g. `2026-08-13T18:04:11.412Z` |
357
+ | `shift` | the shift's human name — `clock_in` can change it between events |
358
+ | `shiftId` | `shf_<uuid>`, the shift process incarnation; stable for the process |
359
+
360
+ The envelope is omitted from the per-type examples below for brevity; it is
361
+ never omitted on the wire. For `dispatched`, `reaped`, and `failed`, `kind` is
362
+ either `exec` or `agent-run`:
161
363
 
162
364
  - `dispatched`: `{ "type": "dispatched", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "pid": 123 }`
163
365
  - `reaped`: `{ "type": "reaped", "workflow": "...", "run": "...", "kind": "exec", "pid": 123 }`
164
366
  - `failed`: `{ "type": "failed", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "message": "..." }`
367
+ - `bundle-miss`: `{ "type": "bundle-miss", "workflow": "...", "def": "..." }` — a legacy order named a def with no cached bundle, so it was left for hub pickup
368
+ - `order-dropped`: `{ "type": "order-dropped", "workflow": "...", "run": "...", "step": "...", "reason": "unsupported-worker", "message": "..." }` — the shift refused one order. Match on `reason` (`malformed-digest`, `malformed-worker`, `unsupported-worker`, `verification-failed`, `metadata-unavailable`); display `message`
165
369
  - `ended`: `{ "type": "ended" }`, delivered to a parked `next` when `shift end` explicitly shuts down the daemon
166
370
 
371
+ Every event above is also appended to `<log-dir>/shift.log` as JSON Lines, which
372
+ is how they survive the daemon. **Four further record types exist in
373
+ `shift.log` and are never delivered over the socket** — `parked`, `capacity`,
374
+ `hub-error`, and `event-queue-overflow`.
375
+
376
+ An idle `shift next` must block until there is work to report, and each of those
377
+ four would satisfy it with news that no work moved: a startup record, a report
378
+ that the shift is full, a failed call to the hub, or a record about the socket
379
+ queue itself. `parked` and `capacity` are also redundant on the wire — the
380
+ response above already carries live `cap`, `free`, and `running`, which is
381
+ exactly what a `capacity` record restates. `hub-error` is level-triggered at the
382
+ poll interval, so an unreachable hub would otherwise fill the 1000-slot socket
383
+ FIFO and evict the `dispatched`, `failed` and `reaped` records a parked client
384
+ is actually waiting for. In `shift.log`, which is append-only and unbounded, all
385
+ four are load-bearing: they are the only way to tell an idle shift from a
386
+ saturated one, and the only record of every failed hub call. See
387
+ [`docs/shift-logs.md`](shift-logs.md).
388
+
167
389
  `gate` is a reserved protocol shape for a future local representation of a
168
390
  pending hub gate. Production code does not construct live hub gate events yet;
169
391
  the local FIFO test and drill scope are recorded in
@@ -243,6 +465,87 @@ The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
243
465
  | `settings` | print the resolved execution settings file |
244
466
  | `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
245
467
 
468
+ ### `work agent-run` — the only Step Agent dispatcher
469
+
470
+ `owenloop work agent-run` is the only supported way to dispatch an agent order.
471
+ The command resolves the verified local workflow definition, applies the final
472
+ `--harness` / environment / step harness selection, and checks every
473
+ `x.harness` restriction before cold start or resume. An unsupported restriction
474
+ starts no provider process, prints each exact refusal, releases the claim, and
475
+ exits `1`.
476
+
477
+ The Codex adapter refuses explicit `filesystem: read-only` and
478
+ `filesystem: workspace-write` before starting or resuming `codex app-server`.
479
+ The refusal is intentional: Codex configuration layers outside the thread
480
+ sandbox prevent the adapter from proving either neutral filesystem boundary.
481
+ Use the Claude Code adapter for the enforceable read-only/Owenloop-only policy,
482
+ or omit `filesystem` / declare `filesystem: unrestricted` only when the workflow
483
+ accepts the corresponding Codex behavior.
484
+
485
+ An absent `x.harness.tools` field preserves the adapter's default tool surface;
486
+ `tools: []` is an explicit empty allow-list. The two forms are not equivalent.
487
+ Invalid reserved fields and overlapping `tools` / `disallowedTools` are refused.
488
+ `owenloop work lint` runs the same common and adapter checks, but runtime
489
+ preflight remains authoritative because `--harness` or `OWENLOOP_HARNESS` can
490
+ select a different adapter after lint. See [Agent runner and harness policy](agent-runner.md)
491
+ for the capability matrix and the born-bound Owenloop control-plane exception.
492
+
493
+ **Harness-session durability.** `agent-run` records the provider session in the
494
+ machine-local `sessions.jsonl` log. The `active` row is a safety-critical gate:
495
+ the complete row and its trailing newline are written and fsynced before a
496
+ cold-start adapter may begin provider work or a resumed adapter may deliver new
497
+ feedback. Creating the log also fsyncs the containing directory where the
498
+ platform supports directory fsync. If the active append or fsync fails,
499
+ `agent-run` tears down the provider session, releases the order exactly once,
500
+ skips confirmation, writes no later lifecycle row, and exits with
501
+ `session-store-failed`. Later `turn-ended`, `submitted`, and `dead` rows keep
502
+ ordinary append durability; losing one causes conservative replay or retirement,
503
+ not unrecorded provider work. Compaction fsyncs the replacement before rename
504
+ and fsyncs the directory after rename so a successful compaction preserves a
505
+ previously durable active row.
506
+
507
+ ## `trust` — local enrollment trust
508
+
509
+ The `trust` commands create the local enrollment root and signed enrollment
510
+ records. The commands are offline: they do not contact a hub or other remote
511
+ coordinator, and the remote side cannot create, sign, or endorse these records.
512
+ The org root is stored separately from `PrincipalKeyManager` at the injected
513
+ configuration root described in [Signing and key storage](crypto.md#enrollment-chains-attenuation-and-revocation).
514
+
515
+ ```text
516
+ owenloop trust init [--force]
517
+ owenloop trust grant --key <pubkey-path> --principal <human|machine|agent>:<id> \
518
+ [--pools a,b|*] [--labels a,b|*] [--namespaces a,b|*] \
519
+ [--delegate no|<n>|unbounded] [--signing-key <path>] [--output <file>]
520
+ owenloop trust revoke --key <SHA256:…> --principal <kind>:<id> \
521
+ [--reason <text>] [--effective-from <epochMs>] \
522
+ [--signing-key <path>] [--output <file>]
523
+ ```
524
+
525
+ - `trust init` generates an Ed25519 org-root key pair under the local config
526
+ directory. The containing directory is `0700`, the private key is `0600`,
527
+ and the public key is `0644`. Existing root files are refused unless
528
+ `--force` is supplied. The command prints paths and status, never private key
529
+ bytes.
530
+ - `trust grant` reads an Ed25519 public key from `--key`, assigns it to the
531
+ `--principal`, and signs an `EnrollmentGrantRecord`. Each scope axis defaults
532
+ to an empty array (deny by default); `--delegate` defaults to `no`. The
533
+ signing key defaults to the local org root unless `--signing-key` is given.
534
+ The signed DSSE envelope is written to `--output`, or to the local roster
535
+ directory using a SHA-256 hash of the enrolled key ID as its filename.
536
+ - `trust revoke` signs a `RevocationRecord` for the `SHA256:…` key in `--key`.
537
+ The signing key defaults to the local org root. Without `--effective-from`,
538
+ the cut starts at issuance. With an earlier `--effective-from`, the CLI
539
+ derives `backdated: true`; the flag is never accepted as an independent
540
+ boolean. The signed envelope is written to `--output`, or to the local
541
+ revocations directory using a SHA-256 hash of the revoked key ID.
542
+
543
+ These commands print one JSON result on success. They refuse malformed
544
+ principals, fingerprints, scope lists, delegation values, and timestamps before
545
+ performing the related filesystem or signing work. Trust records are only
546
+ local inputs to the chain validator; transporting a signed envelope is a
547
+ separate concern.
548
+
246
549
  ## `add` — installing shared workflow defs from GitHub
247
550
 
248
551
  `owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
@@ -405,8 +708,8 @@ bounded — it only loads folders named by the fail-closed-validated
405
708
 
406
709
  - **Only under the default defs dir.** An explicit `--defs`/`OWENLOOP_DEFS` is
407
710
  operator intent to target a literal dir and keeps the pure-scan behavior with
408
- no fold-in — the rule is "was an override given", so even
409
- `OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
711
+ no installed-def or CAS-store fold-in — the rule is "was an override given",
712
+ so even `OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
410
713
  Pointing `--defs` straight at an install folder
411
714
  (`--defs workflows/<owner>-<repo>-<hash>`) still works exactly as before.
412
715
  - **Precedence.** Project-local (top-level) defs win over installed defs; among
@@ -471,14 +774,501 @@ refuses the whole install (nothing written) on any of these:
471
774
  buffered into memory (the extraction limits above still re-check the size once
472
775
  the bytes are in hand).
473
776
  - **Request timeouts.** The sha-resolve fetch times out after 30s and the
474
- tarball download after 5 min, each surfacing as a friendly error.
777
+ tarball download after 5 min, each surfacing as a friendly error. The
778
+ bundle route applies the same 256 MiB cap and 5 min timeout to its file
779
+ read and URL fetch (see the next section).
780
+
781
+ ## `add` with bundles — the content-addressed workflow store
782
+
783
+ `owenloop add <owner>/<repo>[@ref]` (the previous section) installs
784
+ GitHub repos by name into `<defsDir>/<owner>-<repo>-<hash>/`. The **bundle**
785
+ route is a separate, content-addressed installation path for `.wnlp` workflow
786
+ bundles:
787
+
788
+ ```text
789
+ owenloop add widget.wnlp # install into the PROJECT store
790
+ owenloop add ./packs/widget.wnlp --global # install into the GLOBAL store
791
+ owenloop add https://example.com/widget.wnlp
792
+ owenloop add --recover [--global] # offline crash recovery (per root)
793
+ ```
794
+
795
+ The source is classified before anything else: `owner/repo[@ref]` keeps the
796
+ GitHub route byte-for-byte unchanged; a path ending in `.wnlp` is a bundle
797
+ file; an `http:`/`https:` URL is a bundle URL. Any other URL scheme
798
+ (`ftp:`, `file:`, …) is refused — never a silent fallback. `--global` applies
799
+ only to `.wnlp` bundle sources; a GitHub source with `--global` is refused
800
+ before any network request. The source string is origin data only (diagnostics
801
+ and messages); it is never joined into a filesystem path and never part of a
802
+ bundle's identity. Identity comes from the bundle's own
803
+ `namespace/name@version` coordinate and its canonical content digest.
804
+
805
+ **The `.wnlp` route requires two adapters and fails closed without them.**
806
+ Bundle ingestion (unpacking, manifest integrity, canonical digest,
807
+ coordinate) and pre-commit verification are separate modules with no
808
+ permissive fallback: with either adapter missing, `add` refuses with a named
809
+ error before any staging, journal, or index write. The default CLI binds both
810
+ production adapters. The pre-commit verifier consumes the publication sidecars
811
+ written by `publish` and applies the local `defPolicy` before the object or index
812
+ commit. Hosts that provide both adapters can install real `.wnlp` output from
813
+ `packBundle`; use the `publish` command to create the `.wnlp` bundle plus a
814
+ signed or explicitly unsigned sidecar.
815
+
816
+ ### Definition publication policy
817
+
818
+ `defPolicy` is the local execution and installation policy for workflow
819
+ publication signatures. The settings file is
820
+ `$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is non-blank,
821
+ otherwise `$HOME/.config/owenloop/settings.json`. To set the policy in the
822
+ settings file, write a JSON object such as:
823
+
824
+ ```json
825
+ {
826
+ "defPolicy": "enforce"
827
+ }
828
+ ```
829
+
830
+ For a one-off CLI invocation, set `OWENLOOP_DEF_POLICY` in the environment, for
831
+ example `OWENLOOP_DEF_POLICY=enforce owenloop add widget.wnlp`. The local
832
+ precedence is explicit host-provided policy, then `OWENLOOP_DEF_POLICY`, then
833
+ the settings file, then the built-in default `warn`. An invalid environment or
834
+ settings-file value fails loudly; it never degrades to `off`.
835
+
836
+ When a host supplies an already-verified organization policy floor through the
837
+ `policyFloor` option seam, the floor is applied **after** that local precedence.
838
+ `unsignedDefs: warn` raises the minimum to `warn`; `unsignedDefs: refuse` raises
839
+ the minimum to `enforce`; the effective policy is the stricter of local policy
840
+ and the floor. **Therefore, local `off` no longer means “no enforcement” when a
841
+ verified org floor is present.** A local operator cannot use `off` to opt out of
842
+ a verified floor. A missing, malformed, unsigned, wrongly signed, or
843
+ under-scoped floor leaves the local policy unchanged.
844
+
845
+ The current CLI and production configuration do not load or verify a floor.
846
+ `policyFloor` is an injection seam only, so this feature is inert until a host
847
+ wires floor loading and verification into that seam.
848
+
849
+ The policy applies at install time and again at execution time. The following
850
+ table describes the local policy result before any verified floor is applied.
851
+ The table uses these verdicts:
852
+
853
+ - `verified` — the publication sidecar verifies against the bundle digest and a
854
+ signer in the local trust root.
855
+ - `unsigned` — the bundle has no publication signature (including an explicit
856
+ `.wnlp.unsigned` sidecar).
857
+ - `unverifiable` — verification could not be completed, such as when the trust
858
+ root is missing or malformed.
859
+ - `invalid` — a present publication signature fails verification, including a
860
+ digest or signer mismatch.
861
+
862
+ | publication verdict | `enforce` | `warn` | `off` |
863
+ |---|---|---|---|
864
+ | `verified` | Install succeeds; agent and command execution proceed. | Install succeeds; agent and command execution proceed. | Install succeeds; agent and command execution proceed. |
865
+ | `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. |
866
+ | `invalid` | Install refuses; agent and command execution refuse. | Install refuses; agent and command execution refuse. | Install refuses; agent and command execution refuse. |
867
+
868
+ **Command-worker hard rule.** A `worker: command` order requires full
869
+ enforcement in every policy value, including `off`: the definition must be
870
+ verified, the enrollment chain must be verified, and the signer scope must be
871
+ checked. `off` does not disable command-worker enforcement. `warn` and `off`
872
+ never allow an unsigned, unverifiable, or invalid definition to reach the
873
+ shell. The command check runs before the policy value is read, and a refusal
874
+ uses the normal `InstructionRefusal` path so the lease stops before command
875
+ execution. A policy floor cannot relax this gate; the gate also fails closed
876
+ regardless of any floor. If an execution host has no publication verifier
877
+ configured, the definition is `unverifiable`; command workers therefore refuse
878
+ rather than treating installed bytes as published trust.
879
+
880
+ ### Consume-side artifact policy
881
+
882
+ `artifactPolicy` controls how agent and MCP drivers handle absent evidence and
883
+ missing local prerequisites for signed dynamic artifact values. Supplied but
884
+ invalid evidence always refuses; the policy is a scalar with the same values as
885
+ `defPolicy`: `enforce`, `warn`, or `off`. The precedence is explicit host
886
+ option, then `OWENLOOP_ARTIFACT_POLICY`, then the `artifactPolicy` key in the
887
+ execution settings file, then the built-in default `warn`.
888
+
889
+ For example, the settings file can contain:
890
+
891
+ ```json
892
+ {
893
+ "artifactPolicy": "enforce"
894
+ }
895
+ ```
896
+
897
+ A one-off invocation can set
898
+ `OWENLOOP_ARTIFACT_POLICY=enforce owenloop work agent-run <order-id>`.
899
+ Invalid values fail loudly; an invalid value never becomes `off`.
900
+
901
+ The consuming driver verifies each delivered value against its serialized DSSE
902
+ submission proof, the signed value digest and version, the locally anchored
903
+ producer enrollment chain, revocations, and any supplied consuming demand's
904
+ scope. A missing proof is not the same as invalid evidence. Dynamic values and
905
+ rejection reasons remain on the wire; the driver verifies those values and
906
+ refuses the whole order on failure rather than dropping only one path.
907
+
908
+ A valid historical proof is not enough to establish the version claimed for the
909
+ current delivery. Ordinary consumed artifacts bind the signed version to the
910
+ claim-time version in `consumedFingerprint`; owed rejection reasons bind to the
911
+ owed claim-time version. If that authoritative expected version is absent, the
912
+ verdict is `unverifiable`, never `verified`, even when the signature, value
913
+ digest, and enrollment chain all verify. The policy table therefore applies
914
+ without a hidden exception: `enforce` refuses that artifact, `warn` warns and
915
+ admits it, and `off` admits it without calling the proof verified. The
916
+ command-worker hard rule below still refuses it under every policy.
917
+
918
+ The current production `exec`, `agent-run`, and `hold` roles do not supply a
919
+ pool, label, or namespace demand. `OrderPacket` has no such demand field to
920
+ derive, so production consume gates enforce the enrollment chain, attenuation,
921
+ and revocation checks but do not apply a demand-dependent `scopePermits`
922
+ restriction. A caller that supplies a demand through the verifier seam gets the
923
+ full scope check. This limitation is a named follow-up.
924
+
925
+ | consumed-evidence verdict | `artifactPolicy=enforce` | `artifactPolicy=warn` | `artifactPolicy=off` |
926
+ |---|---|---|---|
927
+ | `verified` | admit | admit | admit |
928
+ | `absent` | refuse | warn and admit | admit |
929
+ | `unverifiable` | refuse | warn and admit | admit |
930
+ | `invalid` | refuse | refuse | refuse |
931
+
932
+ A refusal is an actionable integrity event. The refusal names the failed link
933
+ and artifact, using names such as `no-proof`, `signature`, `value-digest`,
934
+ `version`, `chain`, `scope`, or `prerequisite`, and includes the workflow, run,
935
+ and step. The driver refuses the whole order; operators must not suppress the
936
+ message or continue with a manually stripped packet.
937
+
938
+ The policy floor's `unsignedArtifacts: warn` value raises the local minimum to
939
+ `artifactPolicy=warn`; `unsignedArtifacts: refuse` raises it to `enforce`. A
940
+ verified floor is merged after local precedence, so local `off` cannot weaken
941
+ the floor.
942
+
943
+ **Command-worker hard rule.** A `worker: command` order refuses `absent`,
944
+ `unverifiable`, and `invalid` consumed evidence regardless of `artifactPolicy`,
945
+ including `off`. The consume-side gate runs before origin or artifact policy
946
+ lookup and before a shell command is built or passed to `/bin/sh -c`. A command
947
+ worker must have a configured consume-side verifier; an unverified dynamic value
948
+ must never reach the shell. Agent prompt rendering and MCP `get_order` likewise
949
+ fail closed when dynamic data exists but no verifier is configured. The driver
950
+ samples the consumer's injected clock once per complete gate invocation; a
951
+ revocation effective at `effectiveFrom <= at` makes a previously consumable
952
+ artifact unconsumable on a later invocation.
953
+
954
+ ### Definition origin policy
955
+
956
+ `originRules` is a separate namespace-scoped provenance policy. A signed file
957
+ publication may include `<bundle>.origin.dsse`; installation verifies that
958
+ sidecar against the local `allowed_signers` root and retains the exact bytes at
959
+ `<store-root>/.owenloop/origins/<digest>.dsse`. Execution re-verifies the
960
+ retained evidence against the current trust root. Only a `verified` origin
961
+ verdict is retained. A bundle carrying only `<bundle>.origin.dsse` — with
962
+ neither a publication `.dsse` nor an unsigned marker — is refused at install for
963
+ every origin-policy value, including `off`. `publish` never emits that shape;
964
+ `--unsigned` removes both sidecars. A hub or other remote coordinator may relay
965
+ the sidecar, but never authors or supplies the origin rule.
966
+
967
+ The origin mode uses the same policy values as `defPolicy` — `enforce`, `warn`,
968
+ and `off` — and follows the same scalar precedence: explicit host option,
969
+ `OWENLOOP_ORIGIN_POLICY`, settings-file `originPolicy`, then `warn`. These are
970
+ not trust modes: `Seamless`, `Strict`, and `Paranoid` are a separate axis;
971
+ `Seamless` maps to `warn`, `Strict` maps to `enforce`, and `off` is a local
972
+ operator escape hatch with no trust-mode equivalent. The rule map has no
973
+ environment-variable spelling: explicit host `originRules`, then settings-file
974
+ `originRules`, then an empty map. A namespace with no matching rule has no origin
975
+ requirement. A malformed rule map is a named settings error, not an empty-policy
976
+ fallback.
977
+
978
+ Rules accept exact namespaces (`prod`), namespace prefixes (`prod*`), and
979
+ trailing `/*` sugar (`prod/*`, equivalent to `prod`). `*` and `*/*` are
980
+ catch-all rules. Exact matches beat prefixes; the longest prefix wins; keys
981
+ that normalize to equal specificity, such as `prod` and `prod/*`, are rejected.
982
+ Rule values are minimum provenance strengths, ordered `git` > `console` >
983
+ `agent`; therefore a `console` rule accepts verified `git` and `console`
984
+ origins, and an `agent` rule accepts all three. `any` imposes no requirement.
985
+
986
+ Origin verdicts remain distinct:
987
+
988
+ - `verified` has a strength and is checked against the selected minimum.
989
+ - `absent` means no origin bytes are available. For a signed file publication,
990
+ this means no sidecar was recorded. Unsigned publications and non-file install
991
+ sources also produce `absent`, but those definitions structurally cannot carry
992
+ an origin; those cases must not be described as “no origin was recorded.”
993
+ - `unverifiable` means a prerequisite such as the trust root is unavailable.
994
+ - `invalid` means present origin evidence failed verification and is refused at
995
+ every origin mode, including `off`.
996
+
997
+ For a matched rule, the local origin mode behaves as follows:
998
+
999
+ | origin verdict | `originPolicy=enforce` | `originPolicy=warn` | `originPolicy=off` |
1000
+ |---|---|---|---|
1001
+ | `verified` meeting the minimum | Install and execution succeed. | Install and execution succeed. | Install and execution succeed. |
1002
+ | `verified` weaker than the minimum | Install refuses; execution refuses. | Install warns and succeeds; execution warns and proceeds. | Install and execution proceed silently. |
1003
+ | `absent` or `unverifiable` | Install refuses; execution refuses. | Install warns and succeeds; execution warns and proceeds. | Install and execution proceed silently. |
1004
+ | `invalid` | Install refuses; execution refuses. | Install refuses; execution refuses. | Install refuses; execution refuses. |
1005
+
1006
+ The table applies only when a rule matches. During execution, the driver
1007
+ recovers the namespace by reverse-scanning project and global store indexes for
1008
+ the bundle digest. Equivalent requirements deduplicate. Different requirements
1009
+ produce a named ambiguity refusal. If no coordinate is indexed, `enforce`
1010
+ refuses, `warn` warns, and `off` proceeds. With an empty `originRules` map, the
1011
+ default resolver still invokes the origin verifier once per order, but skips the
1012
+ expensive index reverse-scan; invalid retained origin evidence still refuses.
1013
+
1014
+ A verified policy floor maps `originRules: advisory` to minimum
1015
+ `originPolicy=warn` and `originRules: enforced` to minimum
1016
+ `originPolicy=enforce`. The origin floor is parallel to the publication floor;
1017
+ it does not alter `defPolicy`.
1018
+
1019
+ **Origin policy never relaxes the command-worker hard rule.** A
1020
+ `worker: command` order must pass the publication verification gate first, even
1021
+ when `defPolicy=off`, and only then runs the origin check. Unsigned,
1022
+ unverifiable, or invalid publication evidence never reaches the shell. An
1023
+ origin mode of `off` and every policy-floor preset leave that gate unchanged.
1024
+
1025
+ The local SSHSIG trust root is
1026
+ `$XDG_CONFIG_HOME/owenloop/allowed_signers`, or
1027
+ `$HOME/.config/owenloop/allowed_signers` when `XDG_CONFIG_HOME` is blank. A
1028
+ missing or malformed trust root is `unverifiable`, not `unsigned`.
1029
+
1030
+ ### The two store roots
1031
+
1032
+ A store root holds exactly this layout:
1033
+
1034
+ ```text
1035
+ <root>/
1036
+ index.json # coordinate → {digest, pinned, workflows?} index
1037
+ objects/
1038
+ sha256/
1039
+ <64-hex-content-digest>/ # one immutable object per digest
1040
+ … # the bundle's files
1041
+ .owenloop/ # per-root lock + crash journal
1042
+ add.lock
1043
+ add.journal
1044
+ .owenloop-staging/ # transient staging (cleared on exit)
1045
+ ```
475
1046
 
476
- ## Hub (`login` / `connect` / `push` / `logout`)
1047
+ - **Project store root** = the resolved defs directory itself (`--defs`,
1048
+ `OWENLOOP_DEFS`, or `./workflows`). The project's pins are reviewable in
1049
+ git there, and the nested `objects/sha256/<digest>/` layout stays below
1050
+ the def loader's scan depth.
1051
+ - **Global store root** = `<home>/.owenloop/workflows`. `--global` selects it;
1052
+ it cannot be combined with `--defs` (the global store has a fixed
1053
+ home-directory location, so an override would only create ambiguity —
1054
+ refused with a clear message). The global root is never used by the
1055
+ GitHub route.
1056
+
1057
+ **Injected home requirement.** `<home>` is the first non-blank value from the
1058
+ caller-injected `HOME` and `USERPROFILE` environment variables (`HOME` wins).
1059
+ The `.wnlp` bundle route uses the same injected home for its default external
1060
+ recovery-marker directory, `<home>/.owenloop/recovery-markers`, even when the
1061
+ bundle targets the project store. If neither variable is supplied, bundle
1062
+ installation refuses before any object or index commit; it never falls back to
1063
+ the process user's ambient home. `add --recover --global` has the same
1064
+ requirement. Project recovery of a v2 fresh-install journal also refuses when
1065
+ its recovery marker requires a home and neither variable is supplied.
1066
+
1067
+ Every object path derives ONLY from its validated digest (lowercase 64-hex).
1068
+ Coordinates, source strings, and version text never join into a path.
1069
+
1070
+ ### What an install does, in order
1071
+
1072
+ 1. Read the bundle bytes (file or URL) *before* taking the lock — a slow
1073
+ download never holds the project lock. A local `.wnlp` must be a bounded
1074
+ regular file: missing, symlinked, non-regular, or over the 256 MiB cap
1075
+ (checked before *and* after the read) is refused naming the path as
1076
+ given. A URL fetch uses the same 5 min timeout, refuses redirects
1077
+ (`redirect: 'error'`) instead of following them silently, and streams
1078
+ through the same bounded reader.
1079
+ 2. Acquire the canonical root lock at `<root>/.owenloop/add.lock`. A GitHub
1080
+ install also retains its legacy cwd-derived lock for compatibility and, when
1081
+ the resolved `--defs` root differs from that cwd, acquires both locks in a
1082
+ fixed order. The canonical lock makes bundle installs from different cwd
1083
+ values serialize when they target one shared `--defs` root; the additional
1084
+ GitHub lock keeps the legacy route compatible.
1085
+ 3. Recover a prior interrupted install (before clearing staging — the
1086
+ backups a rollback needs live under the staging root).
1087
+ 4. Reread and validate the index **inside** the lock (a corrupt index is a
1088
+ hard error, never a silent reset).
1089
+ 5. Ingest via the bundle adapter: unpack into staging, check manifest
1090
+ integrity and runtime compatibility, compute the canonical digest, and
1091
+ extract the full coordinate. The runtime check uses Owenloop's production
1092
+ package version and advertised feature set. A tampered, malformed, or
1093
+ runtime-incompatible bundle stops here — staging debris only, nothing
1094
+ committed.
1095
+ 6. Validate the staged tree with the engine's strict pass — the exact bytes
1096
+ that will be committed (parse/lint/validate/bounded `check` + the strict
1097
+ cross-def backstop). For a real `.wnlp`, validation parses `bundle.yaml`
1098
+ through the same runtime-admission boundary and loads every workflow path
1099
+ listed in its `workflows` map; the package manifest itself is not treated as
1100
+ a workflow definition. Any problem refuses the whole install and prints
1101
+ every reason.
1102
+ 7. Run the pre-commit verifier (after content validation, before any swap or
1103
+ index write). A rejection commits nothing.
1104
+ 8. Write the `applying` crash journal (v2 — its commit-point evidence is the
1105
+ hash of the post-install index bytes).
1106
+ 9. Atomically swap the staged object into `objects/sha256/<digest>`
1107
+ (retaining any displaced content on the commit handle), then harden it
1108
+ in place: canonical `0644` files become read-only `0444`, canonical `0755`
1109
+ files become read/execute-only `0555`, and directories become non-writable
1110
+ `0555`. Hardening preserves the executable distinction needed for canonical
1111
+ object reconstruction. Hardening is defense in depth, not the integrity proof
1112
+ — verification reconstructs the complete canonical tar, including
1113
+ `bundle.yaml`, and matches its SHA-256 digest to the object path. A hardening
1114
+ failure rolls the swap back; a partially hardened object is never committed.
1115
+ If the digest's object already exists, the install verifies the existing
1116
+ object through the ingest adapter and commits an index-only change instead
1117
+ (dedupe) — a corrupt or runtime-incompatible existing object is a hard
1118
+ integrity error, never replaced and never fallen through.
1119
+ 10. Atomically write `index.json` — the **durable commit point**. Past here
1120
+ a crash rolls forward; before it, everything rolls back. An index-write
1121
+ failure rolls the directory state back and leaves the previous object
1122
+ and index exactly as they were.
1123
+ 11. Advance the journal to `finalizing`, discard the retained backup and
1124
+ staging, remove the journal, release the lock.
1125
+
1126
+ On success `add` prints the structured result:
477
1127
 
478
- These four commands publish local workflow defs to a hosted **hub** (default
479
- `https://api.owenloop.com`; override per-command with `--hub <url>` or the
480
- `OWENLOOP_HUB` env var). They are the only network-bound commands besides
481
- `add`, and they talk only to endpoints the hub exposes today — no new
1128
+ ```jsonc
1129
+ {
1130
+ "ok": true,
1131
+ "source": "widget.wnlp", // or the URL
1132
+ "level": "project", // or "global"
1133
+ "coordinate": "acme/widget@1.0.0",
1134
+ "digest": "<64-hex>",
1135
+ "workflows": ["delivery", "init"], // every workflow name in the bundle, sorted
1136
+ "objectPath": "<root>/objects/sha256/<64-hex>",
1137
+ "installed": true // false when deduplicated
1138
+ }
1139
+ ```
1140
+
1141
+ **Conflict and re-install.** An existing coordinate at a DIFFERENT digest is
1142
+ a conflict error — no implicit retarget; the original digest is retained and
1143
+ nothing is written. An existing coordinate at the SAME digest deduplicates
1144
+ (`installed: false`), verifying the existing object before trusting it.
1145
+
1146
+ **Crash recovery** is the same two-phase discipline as the GitHub route,
1147
+ generalized: the v2 journal's commit-point test compares the hash of the
1148
+ current `index.json` bytes against the journal's recorded metadata hash
1149
+ (route-neutral — no GitHub ledger involved). A fresh v2 install also writes a
1150
+ single-use external recovery marker under the user's recovery-marker directory
1151
+ (default `<home>/.owenloop/recovery-markers`, derived from the injected home
1152
+ described above) before the applying journal. If a crash leaves the destination
1153
+ present with no staging or backup, recovery
1154
+ discards that destination only when the marker exactly matches the store root,
1155
+ destination segments, staging id, and `hadDest: false`; a missing or mismatched
1156
+ marker refuses and preserves the destination and journal. `add --recover --global`
1157
+ runs the store's recovery standalone against the global root with no network
1158
+ and prints `{"ok":true,"recovered":false|true,"outcome":…}` exactly
1159
+ like the project variant. A v1 (GitHub-schema) journal found at the global root
1160
+ is refused fail-closed — there is no ledger there to vouch for it — and a
1161
+ journal recorded against a *different* store root is refused rather than
1162
+ trusting its absolute path. Refusals leave the journal in place as evidence.
1163
+
1164
+ ### Resolving what is installed — two separate APIs
1165
+
1166
+ Resolution is deliberately split so execution code cannot accidentally call
1167
+ human-name resolution. Both are library APIs (exported from the package
1168
+ root); every successful resolution verifies the object through the ingest
1169
+ adapter before returning a path — permissions and object shape on disk are
1170
+ defense in depth, not an integrity proof.
1171
+
1172
+ - **Digest resolution (execution).** `resolveWorkflowDigest({digest,
1173
+ projectRoot?, globalRoot, verifier})` — digest only; no index and no
1174
+ workflow name participate. The project object path is tested first when a
1175
+ project root exists; an ABSENT project object may fall through to global,
1176
+ but a PRESENT project object that fails its type probe or verification is
1177
+ a hard integrity error — project tampering is never hidden by falling back
1178
+ to a valid global copy. When both levels hold the same digest, ONE result
1179
+ comes back (level `project`, with presence metadata), not two candidates.
1180
+ Absent at both levels ⇒ `object-missing` integrity error.
1181
+ - **Coordinate resolution (human/CLI).** `resolveWorkflowCoordinate({coordinate,
1182
+ projectRoot?, globalRoot, verifier})` reads BOTH indexes, fail-closed (a
1183
+ corrupt index is a hard error, never silently empty). No entry at either
1184
+ level ⇒ a structured **not-found** error. A project entry wins whenever it
1185
+ exists, even when the global index maps the same coordinate to a different
1186
+ digest; global is the fallback only when project has no match. An index entry
1187
+ whose selected object is missing or corrupt is an integrity error, never a
1188
+ returned path.
1189
+
1190
+ **Calls resolution for installed bundle workflows.** In the default CLI context
1191
+ (no explicit `--defs`/`OWENLOOP_DEFS`), `defs`/`create`/`tick` load CAS workflows
1192
+ from the project and global bundle-store indexes in addition to filesystem defs
1193
+ and the GitHub `add` ledger. A CAS workflow is addressable by the qualified
1194
+ `<package>/<workflow>` name, so a project-local or `add`-installed workflow can
1195
+ call it explicitly. A bare call from a CAS-loaded workflow resolves a sibling
1196
+ from the same bundle digest first; if no sibling has that name, ordinary flat
1197
+ lookup remains available. Bare CAS names are not registered globally, so a
1198
+ workflow in bundle A cannot accidentally call a same-named workflow from bundle
1199
+ B.
1200
+
1201
+ The precedence is explicit: project-local definitions win first, then
1202
+ GitHub-`add` installed definitions, then CAS definitions under qualified keys.
1203
+ Within the CAS layer, exactly one installed bundle holds the unqualified
1204
+ `<package>/<workflow>` name, chosen by two rules in order and never by install
1205
+ order:
1206
+
1207
+ 1. **Level.** If any candidate is named by the *project* index, only project
1208
+ candidates compete. A project pin of `pkg@0.1.0` therefore beats a global
1209
+ install of `pkg@0.9.9`. This holds even when the project's own object bytes
1210
+ are missing and were served by exact-digest fallback from the global store —
1211
+ the index that names the object decides, not where the bytes were read.
1212
+ 2. **Version.** Among the survivors, the highest canonical SemVer precedence
1213
+ wins (SemVer §11, so `0.1.10` beats `0.1.2` and `1.0.0` beats `1.0.0-rc.1`).
1214
+
1215
+ A canonical SemVer version never loses to a non-SemVer one. If two or more
1216
+ candidates compete and *none* carries a canonical SemVer version, the selection
1217
+ **fails closed**: the unqualified name is left unregistered and a warning names
1218
+ the versions involved, because there is no defined precedence to pick by. Call an
1219
+ exact `<namespace>/<name>@<version>` coordinate in that case. A single
1220
+ non-SemVer version still holds its name — there is nothing to order.
1221
+
1222
+ The refusal warning names only the versions that actually competed. A version
1223
+ dropped by rule 1 is reported separately as never having competed, since it lost
1224
+ on level and was never judged on its version at all. For the same reason,
1225
+ precedence warnings say `project-indexed` / `global-indexed`: precedence follows
1226
+ the index that named the object, whereas a registration's reported level is the
1227
+ store its verified bytes came from, and the two differ under exact-digest
1228
+ fallback.
1229
+
1230
+ Every version that did not win remains reachable under its digest-scoped key, so
1231
+ an already-pinned execution cannot be retargeted, and every exact
1232
+ `<namespace>/<name>@<version>` coordinate always resolves to its own object
1233
+ regardless of which version currently holds the unqualified name.
1234
+ A corrupt CAS index, object, or workflow is skipped with a warning during
1235
+ read-side discovery, so it does not make `status` fail. A running workflow keeps
1236
+ the definition snapshot from its creation (§28), including the CAS bundle
1237
+ provenance used for sibling lookup; installing a newer bundle therefore does not
1238
+ retarget an existing parent instance. The bundle spawn-time pin check compares
1239
+ canonical bundle digests and records a rejected `calls:` debt instead of running
1240
+ a mismatched child.
1241
+
1242
+ Store roots and object directories are probed with `lstat`, never `stat`:
1243
+ a symlink or non-directory squatting at a root, an index path, or an object
1244
+ path is refused outright, and reads never follow a link outside the
1245
+ intended tree.
1246
+
1247
+ **GitHub-route compatibility.** The bundle route changes nothing about
1248
+ `add <owner>/<repo>[@ref]`: the same inputs reach the same parser, the
1249
+ `<owner>-<repo>-<hash>` namespace is untouched, `.owenloop/installed.json`
1250
+ keeps its schema and validation, and an explicit `--defs`/`OWENLOOP_DEFS`
1251
+ still installs through a symlinked defs dir (operator intent). The legacy
1252
+ GitHub repository route installs workflow YAML rather than a format-v2
1253
+ `bundle.yaml`; therefore the GitHub route does not carry or enforce the `.wnlp`
1254
+ runtime compatibility declaration and does not provide the `.wnlp` runtime
1255
+ admission guarantee. Use a `.wnlp` bundle when the publisher must declare a
1256
+ minimum Owenloop version or required runtime features.
1257
+
1258
+ The routes share the canonical resolved-store lock, while the GitHub route
1259
+ retains its legacy cwd-derived lock and journal for compatibility. Recovery
1260
+ checks both journal locations and dispatches by journal version; a v2 store
1261
+ journal uses `index.json` metadata and a v1 GitHub journal uses
1262
+ `installed.json` ledger corroboration.
1263
+
1264
+ ## Hub (`login` / `connect` / `push` / `start` / `publish` / `logout`)
1265
+
1266
+ These commands authenticate, publish, and start workflows on a hosted **hub** (default
1267
+ `https://api.owenloop.com`). `login` and `logout` retain the generic resolver:
1268
+ `--hub <url>` → `OWENLOOP_HUB` → the built-in `DEFAULT_HUB`. `connect`, `push`,
1269
+ and `publish` use the safer publishing ladder below and never consult
1270
+ `OWENLOOP_HUB` or guess `DEFAULT_HUB`. They are the only network-bound commands
1271
+ besides `add`, and they talk only to endpoints the hub exposes today — no new
482
1272
  service-side surface. The hub URL is normalized to its origin
483
1273
  (`scheme://host[:port]`); path/query are dropped. `https` is required for
484
1274
  every hub origin except the loopback hosts (`127.0.0.1`, `::1`, `localhost`),
@@ -492,6 +1282,74 @@ bounce credentials or workflow YAML to another origin (same-origin validation
492
1282
  covers only the initial URL; a redirect would otherwise re-send the request body
493
1283
  cross-origin).
494
1284
 
1285
+ ### The small hosted-workflow path
1286
+
1287
+ Setup is durable. Authenticate and bind the project once, publish or update a
1288
+ definition when its content changes, prepare that published version for the
1289
+ execution account, and keep one crew-scoped Shift running:
1290
+
1291
+ ```bash
1292
+ owenloop login --hub https://hub.example
1293
+ owenloop connect --hub https://hub.example
1294
+ owenloop push newhire-onboarding
1295
+ OWENLOOP_ACCOUNT=default owenloop work prepare newhire-onboarding --origin https://hub.example
1296
+ OWENLOOP_HARNESS=codex owenloop shift start openai --origin https://hub.example --as default
1297
+ ```
1298
+
1299
+ Starting another run does not repeat installation, publication, preparation,
1300
+ or Shift setup. From the connected project it is one public control-plane
1301
+ command; repeat `--provide name=json` for seeded human inputs:
1302
+
1303
+ ```bash
1304
+ owenloop start newhire-onboarding \
1305
+ --crew openai \
1306
+ --provide 'signed_docs={"acknowledged":true}' \
1307
+ --provide 'hardware_choice={"laptop":"MacBook Pro"}'
1308
+ ```
1309
+
1310
+ `start` always uses the human credential. The standing Shift uses the
1311
+ `agent:default` credential selected by `--as default`. With no project binding,
1312
+ `start --hub <url>` is accepted explicitly; with neither a binding nor `--hub`,
1313
+ it refuses instead of falling through to `OWENLOOP_HUB` or the production
1314
+ default. If both a binding and `--hub` exist they must agree.
1315
+
1316
+ ### `start` — start a published workflow
1317
+
1318
+ `owenloop start <defName>` sends `POST /api/start_run` and prints the new
1319
+ workflow id, its initial status, and the steps whose default crew was stamped or
1320
+ whose capability routes were validated. `--crew <name>` selects the crew for
1321
+ steps that declare no capability; capability-bearing steps continue to use
1322
+ their live hub bindings. `--title <text>` is display-only. Both `--crew` and
1323
+ `--title` require non-empty values; bare flags and `--crew=`/`--title=` are local
1324
+ usage errors before credential or network access. The command does not claim,
1325
+ dispatch, close, or otherwise drive work—the standing Shift discovers the run
1326
+ through its normal crew inbox.
1327
+
1328
+ **Publishing hub resolution.** `connect`, `push`, and `publish` resolve their
1329
+ target in this order:
1330
+
1331
+ 1. An explicit `--hub <origin>` always wins.
1332
+ 2. `.owenloop/hub.json`, when present, is the project override.
1333
+ 3. Global machine state supplies one unambiguous candidate:
1334
+ - with the file credential backend, exactly one origin containing a valid
1335
+ human-slot credential is selected automatically;
1336
+ - Keychain and external-command credential backends cannot enumerate their
1337
+ origins, so the validated `hubOrigin` in
1338
+ `$XDG_CONFIG_HOME/owenloop/settings.json` (or
1339
+ `~/.config/owenloop/settings.json`) is used, and the requested credential
1340
+ slot must exist there before the command proceeds.
1341
+ 4. If nothing safe resolves, the command exits 2 without network or publication
1342
+ output effects.
1343
+
1344
+ More than one file-backed origin is also an exit-2 ambiguity: the error lists
1345
+ the origins in deterministic order and asks for `--hub <origin>` or
1346
+ `owenloop connect --hub <origin>`. A non-enumerable backend with no settings
1347
+ `hubOrigin` names the exact settings path and asks for the same explicit
1348
+ choice. `owenloop setup` populates that non-secret settings field. `OWENLOOP_HUB`
1349
+ and `DEFAULT_HUB` are intentionally excluded from the publishing ladder because
1350
+ an ambient guess can target the wrong hub organization; ambiguous or missing
1351
+ resolution fails closed instead of choosing one.
1352
+
495
1353
  **Request timeouts.** Every hub call — OAuth discovery, client registration,
496
1354
  code exchange, token refresh, `whoami`, the workflow list, and each push — is
497
1355
  bounded by a 30s deadline; a stalled hub surfaces as a friendly `hub did not
@@ -567,28 +1425,66 @@ can read (only read) a stored credential through the same backend logic via the
567
1425
  package's exported `readStoredCredential` — see
568
1426
  [Embedding](embedding.md#whats-exported).
569
1427
 
1428
+ The macOS `security` adapter treats exit status 44 (`errSecItemNotFound`) as the
1429
+ only absence result: lookup returns no credential, and deletion succeeds
1430
+ idempotently (running the same deletion again changes nothing). Every other
1431
+ numeric status, signal termination, or command-start failure is a fatal backend
1432
+ error. Lookup and logout stop at that error; Owenloop neither reports success
1433
+ nor falls through to or deletes a file-store credential. Mapped errors name only
1434
+ the operation and backend failure class, never the service, account, credential,
1435
+ or stdin command.
1436
+
570
1437
  **Serializing writes (`credentials.lock`).** A store write — a refreshed OAuth
571
- token, or a `login`/`logout` that stores or deletes a slot — is serialized by a
572
- lockfile at `credentials.lock`, a sibling of `credentials.json` in the config
573
- dir (created for the keychain backend too, since the race it closes is
574
- backend-independent). The concern is a token-refresh race: two owenloop
575
- processes hitting an expiring OAuth token at once would each POST a refresh and
576
- each persist, and because refresh tokens rotate, the second write clobbers the
577
- first with a token whose refresh link is already spent — silently killing the
578
- credential. Under the lock a process re-reads the slot after acquiring it and,
579
- if another process already refreshed, **adopts** that fresh token instead of
580
- refreshing again — one network refresh, one write, no lost token. The lock
581
- matters only for OAuth refresh and store/delete; read paths and the external-
582
- command mode (which never writes the local store) do not take it. Staleness is
583
- liveness-based: a lock held by a dead same-host process is reclaimed at once, an
584
- unparseable or pid-less lockfile is reclaimed once older than the ~30s TTL, and
585
- a lock held by a live process is never age-reclaimed. If the lock can't be
586
- acquired within the wait budget the CLI fails loudly (`another owenloop process
587
- is using the credential store … — timed out waiting after Ns`) rather than
588
- refreshing unlocked. Three test knobs override the timings:
589
- `OWENLOOP_CRED_LOCK_WAIT_MS` (default 45000), `OWENLOOP_CRED_LOCK_STALE_MS`
590
- (default 30000), and `OWENLOOP_CRED_LOCK_POLL_MS` (default 100). No token value
591
- ever appears in the lockfile or the timeout message.
1438
+ token, or a `login`/`logout` that stores or deletes a slot — is serialized by the
1439
+ logical `credentials.lock` guard and the persistent SQLite lock database at
1440
+ `credentials.lock.sqlite-v2`, both siblings of `credentials.json` in the config
1441
+ dir (created for the keychain backend too, since the race the lock closes is
1442
+ backend-independent). The concern is a token-refresh
1443
+ race: two owenloop processes hitting an expiring OAuth token at once would each
1444
+ POST a refresh and each persist, and because refresh tokens rotate, the second
1445
+ write clobbers the first with a token whose refresh link is already spent —
1446
+ silently killing the credential. Under the lock a process re-reads the slot
1447
+ after acquiring it and, if another process already refreshed, **adopts** that
1448
+ fresh token instead of refreshing again — one network refresh, one write, no
1449
+ lost token. The lock matters only for OAuth refresh and store/delete; read paths
1450
+ and the external-command mode (which never writes the local store) do not take
1451
+ it.
1452
+
1453
+ SQLite owns exclusion through a `BEGIN IMMEDIATE` transaction tied to the live
1454
+ database connection. Release, normal process exit, and process crash close that
1455
+ connection and release the operating-system lock. Owenloop deliberately keeps
1456
+ the SQLite database path after release; Owenloop never deletes or replaces the
1457
+ path. A sibling `credentials.lock.owner.json` contains only diagnostic process
1458
+ metadata and does not determine ownership. If the lock cannot be acquired within
1459
+ the wait budget, the CLI fails loudly (`another owenloop process is using the
1460
+ credential store … — timed out waiting after Ns`) rather than refreshing
1461
+ unlocked. `OWENLOOP_CRED_LOCK_WAIT_MS` (default 45000) and
1462
+ `OWENLOOP_CRED_LOCK_POLL_MS` (default 100) override the wait behavior.
1463
+ `OWENLOOP_CRED_LOCK_STALE_MS` is accepted for compatibility but no longer causes
1464
+ pathname deletion. No token value appears in either lock file or the timeout
1465
+ message.
1466
+
1467
+ **Lock-file upgrade boundary.** The logical lock pathname, such as
1468
+ `credentials.lock`, remains a permanent, parseable JSON compatibility guard.
1469
+ The new SQLite lock database lives at `<logical-lock-path>.sqlite-v2`; for the
1470
+ credential store, that path is `credentials.lock.sqlite-v2`. A new client first
1471
+ holds SQLite's `BEGIN IMMEDIATE` transaction and then installs the guard at the
1472
+ old pathname with an exclusive create. The guard carries an impossible operating-
1473
+ system hostname, so a pre-SQLite client treats the guard as a live foreign-host
1474
+ owner and never age-reclaims it. An already-running old holder can release its
1475
+ ordinary JSON lock normally; the waiting new client then installs the guard and
1476
+ closes the one-way upgrade boundary. Old clients remain blocked after every new-
1477
+ client release or crash, while new clients continue to exclude one another
1478
+ through SQLite.
1479
+
1480
+ Release and crash cleanup close only the SQLite transaction. Owenloop never
1481
+ deletes, renames, or replaces either the permanent guard or the versioned SQLite
1482
+ database during normal lock lifecycle. A corrupt, partial, old-owner, or pre-
1483
+ boundary SQLite file already present at the logical legacy pathname fails closed:
1484
+ stop the relevant processes, verify that no old or pre-boundary process still
1485
+ owns that pathname, remove the legacy pathname manually, and let one upgraded
1486
+ client install the permanent guard. Routine stale-age or PID reclamation is no
1487
+ longer used, and `OWENLOOP_CRED_LOCK_STALE_MS` cannot weaken the boundary.
592
1488
 
593
1489
  **Supplying the credential from your own tooling.** If your secrets live in a
594
1490
  secret manager, or you run on a host with no keychain, set
@@ -630,14 +1526,35 @@ it — a `401` there means the credential is never written to disk. On success
630
1526
  `orgId`, `identity`, and `email` when the hub returns one), read straight from
631
1527
  `whoami`.
632
1528
 
1529
+ **Recording the hub for `owenloop mcp` (`~/.owenloop/config.json`).** After the
1530
+ credential above is verified and stored, `login` makes one more best-effort
1531
+ write: it records the hub origin it just authenticated against in
1532
+ `~/.owenloop/config.json` (`{"version": 1, "hub": "<origin>"}` — never a
1533
+ secret, just the origin). This file is separate from both the credential store
1534
+ above and from `owenloop setup`'s `~/.config/owenloop/settings.json`; its only
1535
+ reader is `owenloop mcp`'s [origin resolution](#choosing-the-hub-origin),
1536
+ which needs to know your hub without enumerating the credential store (the
1537
+ Keychain and external-command backends can't be listed at all — see below). A
1538
+ failure to write this file is a **warning** printed to stderr, never a fatal
1539
+ error and never blocking `login` itself, since the credential is already
1540
+ safely stored by the time this write is attempted. Logging into a second hub
1541
+ overwrites this file — "last login wins" — so if you routinely switch between
1542
+ hubs, pass `--hub` explicitly to `owenloop mcp` (or set `OWENLOOP_HUB`) rather
1543
+ than relying on whichever `login` ran most recently.
1544
+
633
1545
  ### `connect` — bind a project to a hub
634
1546
 
635
- `owenloop connect` writes `.owenloop/hub.json` recording which hub this project
636
- publishes to, after re-verifying the stored credential against `GET
637
- /api/whoami`. Run `login` first. The JSON reports the same org/identity fields
638
- as `login`; re-connecting to the **same** origin reports no `switchedFrom`,
639
- switching to a **different** hub reports `switchedFrom: <old origin>` and
640
- rebinds the project to the new one.
1547
+ `owenloop connect` resolves a target through the publishing ladder, re-verifies
1548
+ the stored credential against `GET /api/whoami`, and writes
1549
+ `.owenloop/hub.json`. Run `login` first. With no `--hub`, an existing binding
1550
+ remains the target; an unbound project uses the unambiguous global fallback.
1551
+ An explicit `--hub` creates or replaces the project override, which is useful
1552
+ for multi-org or multi-hub repositories. `connect` is optional for the ordinary
1553
+ single-hub happy path, not a prerequisite for `push` or `publish`.
1554
+
1555
+ The JSON reports the same org/identity fields as `login`; re-connecting to the
1556
+ **same** origin reports no `switchedFrom`, switching to a **different** hub
1557
+ reports `switchedFrom: <old origin>` and rebinds the project to the new one.
641
1558
 
642
1559
  A symlinked project `.owenloop` directory is refused with a clear error rather
643
1560
  than followed: a hostile checkout cannot ship `.owenloop -> /elsewhere` to
@@ -647,16 +1564,40 @@ guarantee). The same refusal covers the default `state.db` FILE (and its SQLite
647
1564
  file would otherwise redirect the store's writes, since SQLite follows file
648
1565
  symlinks.
649
1566
 
650
- ### `push` — publish local defs to the bound hub
1567
+ ### `push` — publish local defs to the resolved hub
651
1568
 
652
1569
  `owenloop push [<defName>...]` publishes the project's workflow defs (all of
653
- them, or just the named ones) to the hub the project is `connect`ed to. It
1570
+ them, or just the named ones) to the hub selected by the publishing ladder.
1571
+ `--hub` overrides a project binding for that invocation without rewriting it;
1572
+ otherwise the project override wins over global state. An unbound project with
1573
+ one file-backed human credential therefore needs no setup step. Ambiguous or
1574
+ missing candidates exit 2 as described above, and `OWENLOOP_HUB`/
1575
+ `DEFAULT_HUB` never participate. `push` never writes a project binding. It
654
1576
  reuses the **exact** all-or-nothing validation gate `add` uses — lint, validate,
655
1577
  and a bounded `check` — across every selected def before a single byte is sent;
656
1578
  any definite defect aborts the whole push. stdout is machine-parseable JSON;
657
1579
  the human-readable diff (`+ new`, `~ changed`, `= unchanged`, `! failed`) goes
658
1580
  to stderr.
659
1581
 
1582
+ `owenloop push --bundle <bundle.wnlp> [<defName>...]` is the executable,
1583
+ bundle-backed form. The exact archive is inspected and becomes the definition
1584
+ source; checkout files are ignored. Push requires exactly one adjacent
1585
+ publication sidecar produced by `owenloop publish` (`.dsse` or `.unsigned`),
1586
+ accepts an optional `.origin.dsse`, uploads those content-addressed objects,
1587
+ then calls `create_workflow` with the archive's canonical digest. This is what
1588
+ makes the hub stamp reference orders with a digest that execution hosts can
1589
+ resolve from their installed bundle store. Because a reference order identifies
1590
+ its executable instructions only by bundle digest plus step name, every workflow
1591
+ definition in the complete archive must use distinct step names. `push --bundle`
1592
+ refuses an archive when two definitions share a step name, even when positional
1593
+ arguments select only one of those definitions; the refusal happens before any
1594
+ bundle, evidence, or workflow-version write. Bundle mode conservatively sends
1595
+ each selected `create_workflow` request even when its YAML hash is unchanged,
1596
+ because the workflow listing does not expose the latest bundle identity; the
1597
+ hub's `(yaml, bundle digest)` idempotency decides whether to version-forward or
1598
+ return `noop`. `--dry-run` validates the archive and sidecars and performs only
1599
+ the read-only server diff—no bundle, sidecar, or definition is uploaded.
1600
+
660
1601
  **Idempotency is server-side truth, not a client ledger.** `push` fetches the
661
1602
  hub's own view of every def (`GET /api/workflows`, which reports each def's
662
1603
  `hash`) and diffs local content against it directly — there is no
@@ -678,6 +1619,15 @@ batch: the current def is recorded as `failed`, the not-yet-attempted remainder
678
1619
  is reported under a `skipped` output key, and any `Retry-After` the hub sent is
679
1620
  surfaced in the error.
680
1621
 
1622
+ Selected definitions are published in topological `calls:` order. If a selected
1623
+ dependency fails or is skipped, Owenloop sends no `create_workflow` request for
1624
+ its selected dependents; each dependent is added to `skipped`, names its failed
1625
+ or skipped dependencies in sorted order, and becomes unsuccessful so the skip
1626
+ propagates transitively. Independent selected definitions continue publishing.
1627
+ A locally `unchanged` dependency and a server `noop` dependency both count as
1628
+ successful, so either result permits the dependent to publish. Dependency
1629
+ matching covers bare names and same-package-qualified names in a bundle.
1630
+
681
1631
  The def hash is computed by re-parsing the raw YAML with no checkout-specific
682
1632
  `baseDir` — the same canonicalization the hub applies — so it's portable
683
1633
  across checkouts and machines by construction: a fresh clone at a different
@@ -698,6 +1648,59 @@ def isn't round-trippable. A def using `bodyFile:` is refused the same way
698
1648
  resolve the external file against once the YAML leaves this machine. Inline
699
1649
  both before pushing.
700
1650
 
1651
+ ### `publish` — pack and publish a workflow bundle
1652
+
1653
+ ```text
1654
+ owenloop publish <source-dir> [--output <bundle.wnlp>] [--source <json>] [--unsigned] [--hub <origin>]
1655
+ ```
1656
+
1657
+ `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.
1658
+
1659
+ The author-key origin comes from the same publishing ladder as `connect` and
1660
+ `push`: `--hub` wins, a project binding overrides global state, one file-backed
1661
+ human origin resolves automatically, and a non-enumerable backend uses the
1662
+ validated execution-settings `hubOrigin` only when the human credential exists.
1663
+ An ambiguous or absent candidate exits 2 before signing, packing, or output
1664
+ writes. `publish` never writes `.owenloop/hub.json`, consults `OWENLOOP_HUB`, or
1665
+ guesses `DEFAULT_HUB`.
1666
+
1667
+ 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.
1668
+
1669
+ 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.
1670
+
1671
+ `--source` is signer-supplied provenance, not a hub-derived label. The JSON value must be one of these closed forms:
1672
+
1673
+ - `{"kind":"git","repo":"<repo>","commit":"<40- or 64-hex commit SHA>"}`;
1674
+ - `{"kind":"console","user":"<authoring user>"}`, which requires a client-side signing ceremony; or
1675
+ - `{"kind":"agent","agent":"<agent identity>","session":"<session>"}`.
1676
+
1677
+ 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.
1678
+
1679
+ `--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:
1680
+
1681
+ - signed mode writes `<output>.wnlp.dsse` and removes a stale `<output>.wnlp.unsigned`;
1682
+ - `--unsigned` writes `<output>.wnlp.unsigned` and removes a stale `<output>.wnlp.dsse`.
1683
+
1684
+ 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.
1685
+
1686
+ 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.
1687
+
1688
+ Successful invocations print exactly one machine-readable JSON object to stdout. Signed output without an origin has this shape:
1689
+
1690
+ ```json
1691
+ {
1692
+ "ok": true,
1693
+ "bundle": "/absolute/path/report-1.2.0.wnlp",
1694
+ "digest": "<64 lowercase hex characters>",
1695
+ "name": "report",
1696
+ "version": "1.2.0",
1697
+ "signed": true,
1698
+ "envelope": "/absolute/path/report-1.2.0.wnlp.dsse"
1699
+ }
1700
+ ```
1701
+
1702
+ 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.
1703
+
701
1704
  Exact-match redirect URIs (no RFC 8252 variable-port allowance) and no
702
1705
  device-code grant remain recorded follow-ups on the service, not gaps in the
703
1706
  CLI.
@@ -733,10 +1736,22 @@ minting on the wrong org is not undone by a retry:
733
1736
 
734
1737
  Unlike other commands this does **not** fall back to `OWENLOOP_HUB` or the
735
1738
  built-in default hub — silently defaulting a mint would risk minting on the
736
- production hub while you're logged into a dev one. Note that hub enumeration is
737
- **file-store only** (shared with `owenloop mcp`): the keychain and the
738
- external-command backend cannot list their entries, so on such a machine step 2
739
- cannot enumerate the store and you must pass `--hub`.
1739
+ production hub while you're logged into a dev one. This is deliberately
1740
+ stricter than [`owenloop mcp`'s origin resolution](#choosing-the-hub-origin):
1741
+ `mcp` exposes both reads and writes, including `create_agent` (which mints and
1742
+ stores an agent token), `create_workflow`, `publish_event`, `submit`,
1743
+ `stage_enrollment`, and crew mutations. The default remains acceptable for
1744
+ `mcp` because each tool call authenticates against the resolved origin; when no
1745
+ human credential exists there, the existing `loginHint` surfaces the origin
1746
+ and asks for `owenloop login --hub <origin>` before the tool-specific action
1747
+ runs. If a credential does exist at an unintended origin and `create_agent`
1748
+ mints there, the stored agent token is revocable; `--hub` and `OWENLOOP_HUB`
1749
+ remain available when the operator wants to avoid inference. `agent new`
1750
+ **mints** a new credential directly, a side effect a retry cannot undo, so it
1751
+ stops at step 3 instead of ever guessing. Note that hub enumeration itself is
1752
+ **file-store only**: the keychain and the external-command backend cannot list
1753
+ their entries, so on such a machine step 2 cannot enumerate the store and you
1754
+ must pass `--hub`.
740
1755
 
741
1756
  **`--crews <a,b>`.** A comma-separated list of crew names the token is granted
742
1757
  on (trimmed, empties dropped). Omit the flag to let the hub default the token to
@@ -794,7 +1809,7 @@ allowed) re-reads the route table as it stands at that moment.
794
1809
  - **Adding.** Running `capability bind` on a capability that is **already bound** ADDS the
795
1810
  named crew — it never displaces a crew already bound. Adding widens who can
796
1811
  serve the capability, live at the next poll of every in-flight run using it. Re-adding
797
- a pair that is already there is a normal success, not an error (`alreadyRouted:
1812
+ a pair that is already there is a normal success, not an error (`alreadyBound:
798
1813
  true`).
799
1814
  - **Removing.** Running `capability unbind` removes exactly ONE pair. If the capability still
800
1815
  has other live routes, it simply routes to a narrower set and nothing pauses.
@@ -821,9 +1836,9 @@ id; the CLI does no crew lookup and performs no client-side validation of either
821
1836
  argument (the hub is the enforcement of record).
822
1837
 
823
1838
  **Adding is idempotent per pair.** Re-adding a `(capability, crew)` pair that is
824
- already bound is a normal success — the hub answers `200` with `alreadyRouted:
1839
+ already bound is a normal success — the hub answers `200` with `alreadyBound:
825
1840
  true` and changes nothing (the original row keeps its creator and timestamp).
826
- `routedCrewCount` reports how many **live** crews the capability binds after the write.
1841
+ `boundCrewCount` reports how many **live** crews the capability binds after the write.
827
1842
 
828
1843
  ### `capability unbind <capability> <crew>`
829
1844
 
@@ -884,7 +1899,7 @@ works. Human progress lines (the two `capability unbind` warnings) go to stderr
884
1899
 
885
1900
  | subcommand | stdout |
886
1901
  |---|---|
887
- | `capability bind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crew": "ml-crew", "alreadyRouted": false, "routedCrewCount": 2 }` |
1902
+ | `capability bind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crew": "ml-crew", "alreadyBound": false, "boundCrewCount": 2 }` |
888
1903
  | `capability unbind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crewId": "crw_1", "removed": true, "remainingCrewIds": ["crw_2"] }` |
889
1904
  | `capability list` | `{ "ok": true, "hub": "<origin>", "routes": [ { "capability": "gpu", "crewId": "crw_1", "crewName": "ml-crew", "createdBy": "u_1", "createdAt": 1738000000000 } ] }` |
890
1905
 
@@ -892,9 +1907,9 @@ Every added field carries the **hub's own name**, verbatim — the same words it
892
1907
  audit log and the web console use — so correlating stdout against them never
893
1908
  needs a translation step.
894
1909
 
895
- - `alreadyRouted` (`capability bind`) — was this exact `(capability, crew)` pair already
1910
+ - `alreadyBound` (`capability bind`) — was this exact `(capability, crew)` pair already
896
1911
  bound before the call? `false` means the pair was created by it.
897
- - `routedCrewCount` (`capability bind`) — how many **live** crews the capability binds
1912
+ - `boundCrewCount` (`capability bind`) — how many **live** crews the capability binds
898
1913
  after the write. A dangling route routes nothing and is not counted.
899
1914
  - `removed` (`capability unbind`) — did this call actually remove a pair? `false` is the
900
1915
  tolerant "it was never bound" case, not an error.
@@ -1062,16 +2077,19 @@ lines (the tolerant-false notices, the transfer summary) go to stderr only.
1062
2077
 
1063
2078
  ## `setup` — onboard a machine
1064
2079
 
1065
- `owenloop setup` is the one-shot onboarding command. It runs six ordered steps.
2080
+ `owenloop setup` is the one-shot onboarding command. It runs seven ordered steps.
1066
2081
  Depending on the machine state, setup may store the human credential, mint or
1067
- rekey and store a Scoped Identity credential, and write only `hubOrigin` in the
1068
- execution settings file while preserving its other keys. The plugin step only
1069
- probes whether the Claude Code plugin is installed; when the probe reports it
1070
- missing, setup prints manual install commands but never runs those commands or
1071
- installs the plugin. The steps:
2082
+ rekey and store a Scoped Identity credential, ensure the three principal
2083
+ signing keys, relay a signed machine enrollment grant, and write only
2084
+ `hubOrigin` in the execution settings file while preserving its other keys.
2085
+ The plugin step probes and, when needed, converges the bundled `owenloop` plugin
2086
+ for each available harness: Claude Code and Codex. Plugin convergence is
2087
+ non-fatal and setup continues when a harness is missing, the bundled marketplace
2088
+ root is unavailable, or a plugin command fails. A second run with the expected
2089
+ plugin version already installed performs no plugin writes. The steps:
1072
2090
 
1073
2091
  1. **inspect** — read-only report of what's already present (human credential,
1074
- execution settings, `claude` on PATH, agent slots). No writes.
2092
+ execution settings, `claude` and `codex` on PATH, agent slots). No writes.
1075
2093
  2. **human login** — verify the stored **human** credential, or run the same
1076
2094
  loopback-OAuth browser flow as `owenloop login` when none is present or it no
1077
2095
  longer verifies. This is the gate that makes step 3's mint/rekey legal.
@@ -1079,17 +2097,28 @@ installs the plugin. The steps:
1079
2097
  hub and reuse it; otherwise **mint** a new Scoped Identity or **rekey**
1080
2098
  (replace the credential of) an existing one. How the target is chosen is
1081
2099
  [below](#choosing-the-scoped-identity-flow-a-vs-flow-b).
1082
- 4. **execution settings** — write only `hubOrigin` into the execution settings
2100
+ 4. **signing keys** — ensure an Ed25519 signing key for each of the three local
2101
+ principals, in order: human, machine, agent. Details
2102
+ [below](#signing-keys-step-4). After key convergence, setup performs the
2103
+ enrollment relay sub-step described below.
2104
+ 5. **execution settings** — write only `hubOrigin` into the execution settings
1083
2105
  file so the local Step Agent talks to this hub, preserving every other key
1084
2106
  (skipped when `hubOrigin` already matches).
1085
- 5. **plugin** — check whether the Claude Code `owenloop` plugin is installed.
1086
- **Non-fatal:** while the marketplace is unpublished this step only *prints*
1087
- the manual install commands (`claude plugin marketplace add owenloop` then
1088
- `claude plugin install owenloop@owenloop`); it never fails setup.
1089
- 6. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
2107
+ 6. **plugin** — probe and converge the bundled `owenloop` plugin separately
2108
+ for Claude Code and Codex. When the installed plugin is missing or its
2109
+ version differs from the CLI package, setup adds the bundled marketplace
2110
+ when needed and installs or updates the plugin. Claude Code uses
2111
+ `claude plugin install` for a fresh install and `claude plugin update` for
2112
+ an existing plugin. Codex uses `codex plugin add owenloop@owenloop` for both
2113
+ fresh installs and upgrades; setup does not call
2114
+ `codex plugin marketplace upgrade`, which applies only to Git marketplaces.
2115
+ **Non-fatal:** a missing harness or failed convergence is reported as
2116
+ `noted` and never fails setup. If the bundled marketplace root is
2117
+ unavailable, setup prints manual commands instead.
2118
+ 7. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
1090
2119
  the same surfaces, whose result becomes setup's exit code.
1091
2120
 
1092
- Progress lines (the `[n/6]` headers and `✓`/`✗` marks) go to **stderr**; the
2121
+ Progress lines (the `[n/7]` headers and `✓`/`✗` marks) go to **stderr**; the
1093
2122
  final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
1094
2123
  **stdout**.
1095
2124
 
@@ -1128,6 +2157,88 @@ is a usage error, because rekeying preserves the Scoped Identity's existing scop
1128
2157
  new Scoped Identity to change scopes). `setup` has no `--shift` shorthand — spell the
1129
2158
  scopes out with `--scopes work,run`.
1130
2159
 
2160
+ ### Signing keys (step 4)
2161
+
2162
+ Step 4 ensures one Ed25519 signing key per local principal — human, machine,
2163
+ agent — keyed by `{ hub origin, kind, principal id }`. It is **idempotent**:
2164
+ an existing key reports `existing` and is never regenerated or rewritten. A
2165
+ second full setup run performs zero key writes.
2166
+
2167
+ **Storage backends.** The key record goes to the macOS Keychain
2168
+ (`security`), to Linux libsecret (`secret-tool`) when that binary is on
2169
+ `PATH`, and otherwise to a `0600` file under `$HOME/.owenloop/keys/` (both
2170
+ parent directories forced `0700`, symlinks refused). One backend is selected
2171
+ once and a failure is a hard error — there is never a fallback to another
2172
+ backend, because a fallback could mint a second, different key for the same
2173
+ principal. `OWENLOOP_NO_KEYCHAIN=1` forces the file backend. Private bytes
2174
+ never appear on argv or in setup output.
2175
+
2176
+ **`--reuse-ssh-key <path>`** records your own existing Ed25519 SSH key for the
2177
+ **human** principal instead of generating one. The candidate is validated with
2178
+ a non-secret sign/verify challenge before anything is recorded, and only its
2179
+ canonical path + public key are stored — the private key is never copied. It
2180
+ applies to the human key only (machine and agent always get generated keys),
2181
+ and it is a **hard conflict** when a human key already exists: setup keeps the
2182
+ existing key and errors rather than rotating (rotation is not part of this
2183
+ work package). A nonexistent path fails up front, before any browser opens.
2184
+
2185
+ **Secret-output guarantee.** Step 4 prints only `kind state (backend)` — e.g.
2186
+ `✓ signing keys: human created (macos-security), machine created (file), agent
2187
+ existing (macos-security)` — never key bytes, fingerprints, or secret-store
2188
+ values. The full storage and signing model is in
2189
+ [Signing and key storage](crypto.md).
2190
+
2191
+ ### Machine enrollment relay
2192
+
2193
+ After the three keys are ensured, setup tries to register the machine public key
2194
+ with the hub. The relay is deliberately subordinate to local key convergence:
2195
+
2196
+ 1. Read-only inspect the human signing key. If no human signing key is present,
2197
+ setup records `skipped` and performs no enrollment request.
2198
+ 2. `GET /api/enrollments` with the human credential. If the hub is unavailable,
2199
+ returns an unsupported status such as `404`, returns `500`, or returns an
2200
+ unusable response, setup records `noted` and continues.
2201
+ 3. If the machine public-key fingerprint is already present, setup records
2202
+ `skipped` and does not sign or POST a duplicate.
2203
+ 4. Otherwise, the human signing key signs an `EnrollmentGrantRecord` locally.
2204
+ The grant names the machine principal `{ kind: "machine", id: "local" }`,
2205
+ uses the default least-privilege machine scope, and sets `grantedBy` to the
2206
+ human public-key fingerprint.
2207
+ 5. `POST /api/enrollments` receives only `{ envelope }`, where `envelope` is the
2208
+ signed DSSE enrollment grant. The machine private key, human private key
2209
+ bytes, key-store values, and private-key paths never enter the request body.
2210
+ HTTP `409` means already registered and becomes `skipped`; other transport or
2211
+ hub failures become `noted` and do not undo local key creation.
2212
+
2213
+ The relay is idempotent (repeating the operation after the first successful
2214
+ registration changes nothing) and the hub is only a storage/relay endpoint. The
2215
+ hub does not create, sign, or endorse the grant.
2216
+
2217
+ ## `enrollments` — inspect machine enrollment
2218
+
2219
+ `owenloop enrollments [--hub <url>]` fetches the hub's relayed DSSE envelopes and
2220
+ verifies each entry locally. The command is read-only: it does not call key
2221
+ creation, does not sign a grant, and does not POST to the hub. The command uses
2222
+ the local `allowed_signers` trust root when one is configured.
2223
+
2224
+ The command prints `{ ok, hub, enrollments }` on stdout. Each entry has one of
2225
+ four verdicts:
2226
+
2227
+ | verdict | meaning |
2228
+ |---|---|
2229
+ | `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 |
2230
+ | `unenrolled` | no envelope was supplied for the roster entry |
2231
+ | `unverifiable` | verification cannot establish trust, including a missing `allowed_signers` root or the D1 fail-closed state where no chain validator is installed |
2232
+ | `invalid` | the envelope, payload, schema, signer authorization, signature, or chain-validator result is invalid |
2233
+
2234
+ WP-D1 intentionally does not install an enrollment-chain validator. Therefore a
2235
+ well-formed, correctly signed D1 grant is reported as `unverifiable` until WP-D4
2236
+ installs the validator. This prevents a signature from being mistaken for proof
2237
+ that the grantor is enrolled.
2238
+
2239
+ A missing human credential is exit `3`; hub, malformed-response, and other
2240
+ runtime failures are exit `1`; successful classification is exit `0`.
2241
+
1131
2242
  ### Hub resolution differs from `agent new`
1132
2243
 
1133
2244
  `setup` (and `doctor`) resolve the target hub like `agent new` with **one**
@@ -1187,22 +2298,30 @@ The checks, in order:
1187
2298
  | 3 | agent slot | an `agent:<name>` credential is stored | yes |
1188
2299
  | 4 | agent plane | that agent credential verifies live against the hub | yes |
1189
2300
  | 5 | execution settings | the settings file's `hubOrigin` matches this hub | yes |
1190
- | 6 | plugin | the Claude Code `owenloop` plugin is installed | **no** (rendered only) |
2301
+ | 6 | plugin (claude-code) | the Claude Code `owenloop` plugin is installed at the package version | **no** (rendered only) |
2302
+ | 7 | plugin (codex) | the Codex `owenloop` plugin is installed at the package version | **no** (rendered only) |
2303
+
2304
+ The plugin checks also report the detected harness CLI version. An installed
2305
+ plugin whose version cannot be parsed is reported as `version unknown` and is
2306
+ not treated as a failure. A parsed plugin version that differs from the
2307
+ package version is reported as version skew with the remedy `run owenloop
2308
+ setup`. A missing harness reports that the harness is not on `PATH`; a missing
2309
+ plugin reports the harness-specific marketplace and install command.
1191
2310
 
1192
2311
  Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
1193
2312
  <origin>`, re-run setup's Replace, and so on). doctor never short-circuits — a
1194
- machine with no working human credential still renders lines 3–6, degrading
1195
- honestly rather than dropping them.
2313
+ machine with no working human credential still renders the later checks,
2314
+ degrading honestly rather than dropping them.
1196
2315
 
1197
- **Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise. The
1198
- plugin check (6) is *rendered* but does not affect the exit code while the
1199
- marketplace is unpublished.
2316
+ **Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise. Both
2317
+ plugin checks (6–7) are *rendered* but do not affect the exit code.
1200
2318
 
1201
2319
  ## `mcp` — stdio control-plane server for MCP hosts
1202
2320
 
1203
2321
  `owenloop mcp` is a long-running server that exposes the hub's **human control
1204
- plane** to a local MCP host (Claude Code, or any client that speaks MCP over
1205
- stdio). This is the `owenloop-cli-mcp` surface: an MCP host spawns it as a
2322
+ plane** to a local MCP host (Claude Code, Codex, or any client that speaks MCP
2323
+ over stdio). The shipped Claude Code and Codex plugins launch this command from
2324
+ `PATH`. This is the `owenloop-cli-mcp` surface: an MCP host spawns it as a
1206
2325
  subprocess — **you do not run it yourself at a prompt**. It reads
1207
2326
  newline-delimited JSON-RPC 2.0 on stdin, translates each `tools/call` into one
1208
2327
  authenticated HTTPS request to the hub's `/api/*` REST mirror, and writes the
@@ -1215,29 +2334,77 @@ loopback listener. If no human credential is stored, a tool call returns an
1215
2334
  error telling you to run `owenloop login --hub <origin>` in a terminal and retry
1216
2335
  (see [Authentication and secrets](#authentication-and-secrets) below).
1217
2336
 
2337
+ ### Plugin/CLI version alignment
2338
+
2339
+ The shipped Claude Code and Codex plugins launch `owenloop mcp` from `PATH` and
2340
+ carry the plugin version in `.mcp.json` as `OWENLOOP_PLUGIN_VERSION`. The MCP
2341
+ server compares that expected version with its own package version on every
2342
+ recognized `tools/call`. The comparison is strict equality: a mismatch returns
2343
+ a tool error that names both versions and says `Run: owenloop setup`. The
2344
+ server does not reject the MCP startup handshake, so the diagnostic reaches the
2345
+ model and the human instead of appearing only as a transport-closed error.
2346
+
2347
+ Each plugin also declares a `SessionStart` hook. The hook reads the plugin
2348
+ manifest version, sends an MCP `initialize` request to `owenloop mcp` using a
2349
+ non-routable probe origin, and reads `serverInfo.version`; the root CLI has no
2350
+ supported `owenloop --version` flag. The hook reports a missing CLI, an
2351
+ unparseable version, or a mismatch to stderr and always exits successfully, so
2352
+ a diagnostic cannot block session startup. Claude Code runs the hook after
2353
+ installation. Codex runs plugin hooks only after the user approves them in
2354
+ `/hooks`; if the user does not approve Codex hooks, the always-on MCP check
2355
+ still catches a version mismatch when a tool call is made.
2356
+
2357
+ If the versions differ, run `owenloop setup` and follow the printed plugin
2358
+ installation instructions before retrying the MCP tool call.
2359
+
1218
2360
  ### Choosing the hub origin
1219
2361
 
1220
2362
  `owenloop mcp` binds to exactly one hub origin, resolved in this order:
1221
2363
 
1222
2364
  1. `--hub <url>` flag.
1223
2365
  2. `OWENLOOP_HUB` env var.
1224
- 3. If the **file** credential backend holds exactly ONE hub with a valid `human`
1225
- credential, that hub is used.
1226
- 4. Otherwise it exits `2` and prints why to stderr (nothing is written to
1227
- stdout — stdout is the protocol channel).
1228
-
1229
- There is **no** silent default-hub fallback: a control-plane server must never
1230
- bind to a hub you did not name. The exit-`2` messages name both remedies:
1231
-
1232
- - No hub credentials stored → `run \`owenloop login --hub <origin>\` first, or pass --hub <origin>`.
1233
- - More than one hub stored → the message lists every stored origin and says `pass --hub <origin>`.
1234
- - The credential store cannot be enumerated (macOS Keychain or an external
1235
- credential command) → `pass --hub <origin> (or set OWENLOOP_HUB)`. Only the
1236
- file backend can list stored origins, so on a Keychain-backed machine `mcp`
1237
- effectively requires `--hub` or `OWENLOOP_HUB`.
1238
-
1239
- A malformed `--hub`/`OWENLOOP_HUB` value is a normal exit-`1` error, like every
1240
- other command.
2366
+ 3. `~/.owenloop/config.json` — see below.
2367
+ 4. If the **file** credential backend holds exactly ONE hub with a valid
2368
+ `human` credential, that hub is used (kept for back-compat with installs
2369
+ from before step 3 existed).
2370
+ 5. The built-in **default hub**, `https://api.owenloop.com`.
2371
+
2372
+ Every inference rung after the first two **falls through silently** rather
2373
+ than stopping the server: a missing or corrupt config file, a `hub` value in
2374
+ it that doesn't parse as a valid origin, an unenumerable credential store
2375
+ (macOS Keychain or an external credential command — only the file backend can
2376
+ be listed at all), zero stored hubs, and more than one stored hub all just
2377
+ move on to the next rung. `owenloop mcp` never exits for an inferred-origin
2378
+ reason — this is deliberate: it is a long-running process spawned
2379
+ automatically by an MCP host on every session start, not a one-shot command a
2380
+ human is watching, so a hard stop here would silently break the plugin on any
2381
+ machine using the Keychain backend (the macOS default) unless the operator
2382
+ remembered to set `--hub` or `OWENLOOP_HUB` first.
2383
+
2384
+ The MCP surface is not read-only. It includes `create_agent`, which mints and
2385
+ stores a new agent token, plus state-changing tools such as `create_workflow`,
2386
+ `publish_event`, `submit`, `stage_enrollment`, and the crew mutations. The
2387
+ server still authenticates each tool call against the resolved origin. When no
2388
+ human credential exists at that origin, the first authenticated tool call
2389
+ returns `loginHint` with the origin and asks for `owenloop login --hub
2390
+ <origin>` before the tool-specific action runs. If a credential does exist at
2391
+ an unintended origin and `create_agent` mints there, the stored agent token is
2392
+ revocable; explicit `--hub` and `OWENLOOP_HUB` remain available to avoid
2393
+ inference. Contrast this with [`agent new`](#agent-new--mint-an-agent-token-into-a-slot),
2394
+ which **mints** a new credential directly and therefore stops rather than
2395
+ ever guessing — a wrong guess there is a side effect a retry cannot undo.
2396
+
2397
+ **`~/.owenloop/config.json`** is written by
2398
+ [`login`](#login--authenticate-the-cli-against-a-hub): a small, non-secret
2399
+ JSON file (`{"version": 1, "hub": "<origin>"}`) recording the hub `login` most
2400
+ recently authenticated against. It exists specifically so `mcp` can learn
2401
+ your hub without enumerating the credential store — see `login`'s own section
2402
+ for exactly when it's written and what happens if the write fails.
2403
+
2404
+ A malformed `--hub`/`OWENLOOP_HUB` value is still a normal exit-`1` error,
2405
+ like every other command — an explicit bad value is reported, never silently
2406
+ skipped, precisely because rungs 1–2 come from something the operator typed
2407
+ or set, not from inference.
1241
2408
 
1242
2409
  ### Tools
1243
2410
 
@@ -1341,7 +2508,7 @@ interactively.
1341
2508
 
1342
2509
  | variable | effect |
1343
2510
  |---|---|
1344
- | `OWENLOOP_HUB` | hub origin when `--hub` is absent (rung 2 of origin resolution) |
2511
+ | `OWENLOOP_HUB` | development override for the hub origin (rung 2, above `~/.owenloop/config.json`) |
1345
2512
  | `OWENLOOP_MCP_ENROLLMENT` | `1` forces `stage_enrollment` on, `0` off; unset = probe the hub |
1346
2513
  | `OWENLOOP_MCP_PROBE_TIMEOUT_MS` | deadline for the `stage_enrollment` capability probe (default `3000`) |
1347
2514
  | `OWENLOOP_HUB_TIMEOUT_MS` | per-request hub timeout (shared with the other hub commands) |
@@ -1453,8 +2620,13 @@ non-zero exit as a failure, not a success.
1453
2620
 
1454
2621
  ## What a job looks like
1455
2622
 
1456
- `tick` returns `{ workflow, orders, reaped }`. Each order is self-contained —
1457
- a Step Agent needs nothing else to do the work:
2623
+ `tick` returns `{ workflow, orders, reaped }`. Each order is a **reference
2624
+ packet**: it carries the routing fields and run-time context for the job — the
2625
+ run id, the captured input values, the owed outputs with their reason threads
2626
+ — plus a `defDigest` that names *which definition snapshot* holds the authored
2627
+ instructions. The instructions themselves (the step's `body:` prompt, any
2628
+ `command:` text) are **not** on the order, and `tick`/`order` never print
2629
+ them.
1458
2630
 
1459
2631
  ```jsonc
1460
2632
  {
@@ -1462,22 +2634,42 @@ a Step Agent needs nothing else to do the work:
1462
2634
  "workflow": "wf_…", // the instance this order belongs to — see deep tick below
1463
2635
  "step": "builder", // which step this job is for
1464
2636
  "key": "", // map jobs carry the element key + index
2637
+ "defDigest": "9f2c…", // identifies the definition snapshot to resolve instructions from
1465
2638
  "inputs": ["plan"],
1466
2639
  "outputs": ["pr"],
1467
- "prompt": "…body with ${WORKFLOW}/${RUN}/${INDEX} filled in…",
2640
+ "worker": "command", // the authored step's executor:, mapped verbatim (absent = 'agent')
1468
2641
  "consumes": { "plan": { /* the accepted input value */ } },
1469
2642
  "owes": [ // the feedback channel
1470
- { "path": "pr", "acceptance": "rejected", "judgmentRejects": 2, "schemaRejects": 0,
2643
+ { "path": "pr", "judgmentRejects": 2, "schemaRejects": 0,
1471
2644
  "reasons": [ { "action": "reject", "kind": "judgment", "by": "reviewer",
1472
2645
  "text": "tests are missing", "at": 0 } ] }
1473
2646
  ]
1474
2647
  }
1475
2648
  ```
1476
2649
 
1477
- A Step Agent reads `prompt` + `consumes` + `owes`, does the work, reports with
1478
- `green` (or `emit`/`seal` for collections), then `close`s the job. The reject
1479
- counts in `owes[]` let a workflow escalate on its own — e.g. switch to a
1480
- stronger model after two rejections — before the engine stalls the step.
2650
+ A worker first **resolves the reference**: the `(defDigest, step, key)`
2651
+ boundary maps the order to the exact authored instructions from the worker's
2652
+ trusted local definition source — the same resolver the embedded engine and
2653
+ the CLI use. Resolution returns the authored `prompt` (with
2654
+ `${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}`
2655
+ materialized), the authored `command` if the step has one, and nothing
2656
+ fabricated. If the worker's source does not know the digest — the definition
2657
+ was never delivered, or the current on-disk definition no longer matches the
2658
+ pinned digest — resolution raises `UnknownDefDigestError`. If the digest is
2659
+ known but the referenced step is absent, resolution raises the distinct
2660
+ `UnknownInstructionError` and identifies the digest, step, and key. The worker
2661
+ must refuse either malformed reference rather than guess instructions by step
2662
+ name or fetch unverified text. Once resolved, the worker reads the resolved
2663
+ prompt + `consumes` + `owes`, does the work, reports with `green` (or
2664
+ `emit`/`seal` for collections), then `close`s the job. The reject counts in
2665
+ `owes[]` let a workflow escalate on its own — e.g. switch to a stronger model
2666
+ after two rejections — before the engine stalls the step.
2667
+
2668
+ Static authored text (prompts, commands) travels by digest reference; dynamic
2669
+ data — `consumes` values and the rejection `reasons` threads — stays on the
2670
+ order because it exists only for this run. A remote coordinator or transport
2671
+ that relays these packets never sees authored instruction text and never needs
2672
+ to: instructions resolve at the worker, from a source the worker trusts.
1481
2673
 
1482
2674
  **Deep tick and `order.workflow`.** `tick <wf>` is **deep by default**: it ticks
1483
2675
  `<wf>` and then descends into every live `calls:` child, folding their orders