owenloop 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (211) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +137 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +8 -4
  5. package/dist/packages/work/src/agent/brief.js +7 -3
  6. package/dist/packages/work/src/agent/loop.d.ts +13 -7
  7. package/dist/packages/work/src/agent/loop.js +136 -9
  8. package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
  9. package/dist/packages/work/src/agent/model-policy.js +138 -0
  10. package/dist/packages/work/src/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 +12 -1
  20. package/dist/packages/work/src/exec/loop.js +137 -20
  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 +74 -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 +27 -9
  38. package/dist/packages/work/src/harness/session-store.js +271 -67
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +126 -11
  41. package/dist/packages/work/src/hub/client.d.ts +2 -1
  42. package/dist/packages/work/src/hub/client.js +14 -1
  43. package/dist/packages/work/src/hub/types.d.ts +69 -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 +116 -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 +4 -0
  53. package/dist/packages/work/src/roles/hold.js +44 -5
  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 +5 -0
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +23 -1
  59. package/dist/packages/work/src/settings/settings.d.ts +17 -1
  60. package/dist/packages/work/src/settings/settings.js +39 -0
  61. package/dist/packages/work/src/shift/loop.d.ts +14 -3
  62. package/dist/packages/work/src/shift/loop.js +447 -164
  63. package/dist/packages/work/src/shift/protocol.d.ts +4 -0
  64. package/dist/packages/work/src/shift/runtime.d.ts +2 -0
  65. package/dist/packages/work/src/shift/runtime.js +66 -3
  66. package/dist/packages/work/src/shift/spawn.d.ts +41 -18
  67. package/dist/packages/work/src/shift/spawn.js +89 -31
  68. package/dist/packages/work/src/shift/state.d.ts +53 -51
  69. package/dist/packages/work/src/shift/state.js +325 -102
  70. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  71. package/dist/packages/work/src/submit-proof.js +93 -0
  72. package/dist/src/add.d.ts +64 -259
  73. package/dist/src/add.js +81 -615
  74. package/dist/src/archive.d.ts +97 -0
  75. package/dist/src/archive.js +591 -0
  76. package/dist/src/bundle/index.d.ts +64 -0
  77. package/dist/src/bundle/index.js +508 -0
  78. package/dist/src/bundle/manifest.d.ts +50 -0
  79. package/dist/src/bundle/manifest.js +435 -0
  80. package/dist/src/bundle/runtime.d.ts +26 -0
  81. package/dist/src/bundle/runtime.js +64 -0
  82. package/dist/src/bundle/tar.d.ts +62 -0
  83. package/dist/src/bundle/tar.js +238 -0
  84. package/dist/src/bundle/types.d.ts +105 -0
  85. package/dist/src/bundle/types.js +21 -0
  86. package/dist/src/cli.d.ts +90 -20
  87. package/dist/src/cli.js +2407 -365
  88. package/dist/src/credentials.d.ts +4 -3
  89. package/dist/src/credentials.js +21 -19
  90. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  91. package/dist/src/crypto/allowed-signers.js +307 -0
  92. package/dist/src/crypto/canonical.d.ts +8 -0
  93. package/dist/src/crypto/canonical.js +92 -0
  94. package/dist/src/crypto/chain.d.ts +65 -0
  95. package/dist/src/crypto/chain.js +377 -0
  96. package/dist/src/crypto/dsse.d.ts +209 -0
  97. package/dist/src/crypto/dsse.js +282 -0
  98. package/dist/src/crypto/enrollment.d.ts +78 -0
  99. package/dist/src/crypto/enrollment.js +186 -0
  100. package/dist/src/crypto/index.d.ts +48 -0
  101. package/dist/src/crypto/index.js +44 -0
  102. package/dist/src/crypto/keys.d.ts +258 -0
  103. package/dist/src/crypto/keys.js +908 -0
  104. package/dist/src/crypto/org-root.d.ts +33 -0
  105. package/dist/src/crypto/org-root.js +78 -0
  106. package/dist/src/crypto/origin-rules.d.ts +56 -0
  107. package/dist/src/crypto/origin-rules.js +143 -0
  108. package/dist/src/crypto/policy-floor.d.ts +98 -0
  109. package/dist/src/crypto/policy-floor.js +353 -0
  110. package/dist/src/crypto/records.d.ts +316 -0
  111. package/dist/src/crypto/records.js +157 -0
  112. package/dist/src/crypto/scope.d.ts +49 -0
  113. package/dist/src/crypto/scope.js +83 -0
  114. package/dist/src/crypto/ssh.d.ts +171 -0
  115. package/dist/src/crypto/ssh.js +396 -0
  116. package/dist/src/crypto/submission.d.ts +33 -0
  117. package/dist/src/crypto/submission.js +47 -0
  118. package/dist/src/crypto/trust-roots.d.ts +29 -0
  119. package/dist/src/crypto/trust-roots.js +39 -0
  120. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  121. package/dist/src/crypto/verify-consumed.js +259 -0
  122. package/dist/src/crypto/verify-origin.d.ts +50 -0
  123. package/dist/src/crypto/verify-origin.js +151 -0
  124. package/dist/src/crypto/verify-publication.d.ts +60 -0
  125. package/dist/src/crypto/verify-publication.js +150 -0
  126. package/dist/src/defs.d.ts +24 -1
  127. package/dist/src/defs.js +145 -25
  128. package/dist/src/engine.d.ts +99 -3
  129. package/dist/src/engine.js +238 -34
  130. package/dist/src/factory.d.ts +16 -0
  131. package/dist/src/factory.js +16 -4
  132. package/dist/src/global-config.d.ts +59 -0
  133. package/dist/src/global-config.js +84 -0
  134. package/dist/src/hub.d.ts +75 -21
  135. package/dist/src/hub.js +123 -40
  136. package/dist/src/index.d.ts +17 -2
  137. package/dist/src/index.js +20 -2
  138. package/dist/src/install.d.ts +538 -0
  139. package/dist/src/install.js +1981 -0
  140. package/dist/src/lock.d.ts +15 -57
  141. package/dist/src/lock.js +251 -143
  142. package/dist/src/mcp/serve.d.ts +46 -22
  143. package/dist/src/mcp/serve.js +167 -44
  144. package/dist/src/mcp/server.js +12 -1
  145. package/dist/src/model.d.ts +15 -0
  146. package/dist/src/model.js +111 -1
  147. package/dist/src/order-resolver.d.ts +184 -0
  148. package/dist/src/order-resolver.js +252 -0
  149. package/dist/src/package-version.d.ts +10 -0
  150. package/dist/src/package-version.js +42 -0
  151. package/dist/src/paths.d.ts +14 -1
  152. package/dist/src/paths.js +18 -0
  153. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  154. package/dist/src/schemas/index.d.ts +1416 -0
  155. package/dist/src/schemas/index.js +31 -0
  156. package/dist/src/schemas/order.v1.schema.json +106 -0
  157. package/dist/src/schemas/origin.v1.schema.json +68 -0
  158. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  159. package/dist/src/schemas/publication.v1.schema.json +31 -0
  160. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  161. package/dist/src/schemas/submission.v1.schema.json +61 -0
  162. package/dist/src/store/def-source.d.ts +52 -0
  163. package/dist/src/store/def-source.js +335 -0
  164. package/dist/src/store/index-file.d.ts +69 -0
  165. package/dist/src/store/index-file.js +151 -0
  166. package/dist/src/store/index.d.ts +27 -0
  167. package/dist/src/store/index.js +22 -0
  168. package/dist/src/store/ingestor.d.ts +43 -0
  169. package/dist/src/store/ingestor.js +211 -0
  170. package/dist/src/store/install.d.ts +228 -0
  171. package/dist/src/store/install.js +555 -0
  172. package/dist/src/store/instruction-source.d.ts +49 -0
  173. package/dist/src/store/instruction-source.js +298 -0
  174. package/dist/src/store/origin-evidence.d.ts +21 -0
  175. package/dist/src/store/origin-evidence.js +66 -0
  176. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  177. package/dist/src/store/pre-commit-verifier.js +418 -0
  178. package/dist/src/store/resolve.d.ts +138 -0
  179. package/dist/src/store/resolve.js +363 -0
  180. package/dist/src/store/types.d.ts +288 -0
  181. package/dist/src/store/types.js +356 -0
  182. package/dist/src/types.d.ts +45 -11
  183. package/dist/src/untar.d.ts +8 -23
  184. package/dist/src/untar.js +10 -136
  185. package/docs/agent-runner.md +86 -0
  186. package/docs/authoring.md +57 -6
  187. package/docs/bundles.md +250 -0
  188. package/docs/cli.md +1171 -97
  189. package/docs/crypto.md +816 -0
  190. package/docs/design.md +342 -20
  191. package/docs/embedding.md +132 -25
  192. package/docs/wire-contracts.md +380 -0
  193. package/package.json +6 -1
  194. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  195. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  196. package/plugins/claude-code/plugin/.mcp.json +14 -0
  197. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  198. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  199. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  200. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  201. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  202. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  203. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  204. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  205. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  206. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  207. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  208. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  209. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  210. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  211. 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
@@ -137,6 +208,39 @@ hub origin, or a missing Scoped Identity credential — exit `2`. The foreground
137
208
  daemon's normal lifecycle line is written to stdout when it stays running;
138
209
  diagnostics go to stderr.
139
210
 
211
+ **Dispatch-state safety.** Every current-version direct Shift loop that shares a
212
+ state directory serializes the capacity recheck and durable reservation under
213
+ the same `.dispatch.lock`. The lock is released before process spawn; the per-run
214
+ reservation carries the capacity slot through spawn and PID persistence. Two
215
+ current-version loops therefore cannot both consume the same last slot, and a
216
+ loop that loses the shared-capacity race keeps its already-claimed candidate in
217
+ its local queue. Older Shift loops that predate `.dispatch.lock` do not
218
+ participate in that boundary and must not share the state directory during the
219
+ upgrade. The state directory does not persist one canonical cap: if current-
220
+ version loops sharing the directory are configured with different total or
221
+ agent caps, each loop enforces its own configured limits under the shared lock.
222
+ Use identical cap settings for every loop sharing a state directory.
223
+
224
+ Canonical `*.json` child and reservation records are capacity-bearing state.
225
+ Missing records are benign, including a record that disappears between listing
226
+ and read. A truncated, malformed, or unreadable canonical record is not benign:
227
+ reconciliation fails closed, names the exact path, and disables dispatch until
228
+ an operator repairs the record or removes the record after verifying that no
229
+ child still owns the slot. Owenloop does not skip corrupt records and guess that
230
+ capacity is free. Reconciliation also cancels a reservation when the worker has
231
+ removed its gate after the worker's monotonic two-minute wait, regardless of the
232
+ persisted wall-clock age. A reservation timestamp later than the current wall
233
+ clock is cancelled along with its closed start gate.
234
+
235
+ Persisted reservation age still uses wall time because a monotonic instant cannot
236
+ be reconstructed after a host restart. A smaller backward clock adjustment that
237
+ leaves `reservedAt` in the past can therefore prolong a reservation whose gate
238
+ still exists, such as a parent crash before spawn. The reservation remains
239
+ capacity-bearing until wall time reaches the age limit or an operator verifies
240
+ that no child can start and removes the record and gate. This limitation cannot
241
+ allow provider or command work past the gate: a spawned child independently
242
+ removes the gate and exits after its monotonic two-minute wait.
243
+
140
244
  ### `shift next [--wait <seconds>]`
141
245
 
142
246
  ```text
@@ -243,6 +347,87 @@ The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
243
347
  | `settings` | print the resolved execution settings file |
244
348
  | `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
245
349
 
350
+ ### `work agent-run` — the only Step Agent dispatcher
351
+
352
+ `owenloop work agent-run` is the only supported way to dispatch an agent order.
353
+ The command resolves the verified local workflow definition, applies the final
354
+ `--harness` / environment / step harness selection, and checks every
355
+ `x.harness` restriction before cold start or resume. An unsupported restriction
356
+ starts no provider process, prints each exact refusal, releases the claim, and
357
+ exits `1`.
358
+
359
+ The Codex adapter refuses explicit `filesystem: read-only` and
360
+ `filesystem: workspace-write` before starting or resuming `codex app-server`.
361
+ The refusal is intentional: Codex configuration layers outside the thread
362
+ sandbox prevent the adapter from proving either neutral filesystem boundary.
363
+ Use the Claude Code adapter for the enforceable read-only/Owenloop-only policy,
364
+ or omit `filesystem` / declare `filesystem: unrestricted` only when the workflow
365
+ accepts the corresponding Codex behavior.
366
+
367
+ An absent `x.harness.tools` field preserves the adapter's default tool surface;
368
+ `tools: []` is an explicit empty allow-list. The two forms are not equivalent.
369
+ Invalid reserved fields and overlapping `tools` / `disallowedTools` are refused.
370
+ `owenloop work lint` runs the same common and adapter checks, but runtime
371
+ preflight remains authoritative because `--harness` or `OWENLOOP_HARNESS` can
372
+ select a different adapter after lint. See [Agent runner and harness policy](agent-runner.md)
373
+ for the capability matrix and the born-bound Owenloop control-plane exception.
374
+
375
+ **Harness-session durability.** `agent-run` records the provider session in the
376
+ machine-local `sessions.jsonl` log. The `active` row is a safety-critical gate:
377
+ the complete row and its trailing newline are written and fsynced before a
378
+ cold-start adapter may begin provider work or a resumed adapter may deliver new
379
+ feedback. Creating the log also fsyncs the containing directory where the
380
+ platform supports directory fsync. If the active append or fsync fails,
381
+ `agent-run` tears down the provider session, releases the order exactly once,
382
+ skips confirmation, writes no later lifecycle row, and exits with
383
+ `session-store-failed`. Later `turn-ended`, `submitted`, and `dead` rows keep
384
+ ordinary append durability; losing one causes conservative replay or retirement,
385
+ not unrecorded provider work. Compaction fsyncs the replacement before rename
386
+ and fsyncs the directory after rename so a successful compaction preserves a
387
+ previously durable active row.
388
+
389
+ ## `trust` — local enrollment trust
390
+
391
+ The `trust` commands create the local enrollment root and signed enrollment
392
+ records. The commands are offline: they do not contact a hub or other remote
393
+ coordinator, and the remote side cannot create, sign, or endorse these records.
394
+ The org root is stored separately from `PrincipalKeyManager` at the injected
395
+ configuration root described in [Signing and key storage](crypto.md#enrollment-chains-attenuation-and-revocation).
396
+
397
+ ```text
398
+ owenloop trust init [--force]
399
+ owenloop trust grant --key <pubkey-path> --principal <human|machine|agent>:<id> \
400
+ [--pools a,b|*] [--labels a,b|*] [--namespaces a,b|*] \
401
+ [--delegate no|<n>|unbounded] [--signing-key <path>] [--output <file>]
402
+ owenloop trust revoke --key <SHA256:…> --principal <kind>:<id> \
403
+ [--reason <text>] [--effective-from <epochMs>] \
404
+ [--signing-key <path>] [--output <file>]
405
+ ```
406
+
407
+ - `trust init` generates an Ed25519 org-root key pair under the local config
408
+ directory. The containing directory is `0700`, the private key is `0600`,
409
+ and the public key is `0644`. Existing root files are refused unless
410
+ `--force` is supplied. The command prints paths and status, never private key
411
+ bytes.
412
+ - `trust grant` reads an Ed25519 public key from `--key`, assigns it to the
413
+ `--principal`, and signs an `EnrollmentGrantRecord`. Each scope axis defaults
414
+ to an empty array (deny by default); `--delegate` defaults to `no`. The
415
+ signing key defaults to the local org root unless `--signing-key` is given.
416
+ The signed DSSE envelope is written to `--output`, or to the local roster
417
+ directory using a SHA-256 hash of the enrolled key ID as its filename.
418
+ - `trust revoke` signs a `RevocationRecord` for the `SHA256:…` key in `--key`.
419
+ The signing key defaults to the local org root. Without `--effective-from`,
420
+ the cut starts at issuance. With an earlier `--effective-from`, the CLI
421
+ derives `backdated: true`; the flag is never accepted as an independent
422
+ boolean. The signed envelope is written to `--output`, or to the local
423
+ revocations directory using a SHA-256 hash of the revoked key ID.
424
+
425
+ These commands print one JSON result on success. They refuse malformed
426
+ principals, fingerprints, scope lists, delegation values, and timestamps before
427
+ performing the related filesystem or signing work. Trust records are only
428
+ local inputs to the chain validator; transporting a signed envelope is a
429
+ separate concern.
430
+
246
431
  ## `add` — installing shared workflow defs from GitHub
247
432
 
248
433
  `owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
@@ -405,8 +590,8 @@ bounded — it only loads folders named by the fail-closed-validated
405
590
 
406
591
  - **Only under the default defs dir.** An explicit `--defs`/`OWENLOOP_DEFS` is
407
592
  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.
593
+ no installed-def or CAS-store fold-in — the rule is "was an override given",
594
+ so even `OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
410
595
  Pointing `--defs` straight at an install folder
411
596
  (`--defs workflows/<owner>-<repo>-<hash>`) still works exactly as before.
412
597
  - **Precedence.** Project-local (top-level) defs win over installed defs; among
@@ -471,14 +656,501 @@ refuses the whole install (nothing written) on any of these:
471
656
  buffered into memory (the extraction limits above still re-check the size once
472
657
  the bytes are in hand).
473
658
  - **Request timeouts.** The sha-resolve fetch times out after 30s and the
474
- tarball download after 5 min, each surfacing as a friendly error.
659
+ tarball download after 5 min, each surfacing as a friendly error. The
660
+ bundle route applies the same 256 MiB cap and 5 min timeout to its file
661
+ read and URL fetch (see the next section).
662
+
663
+ ## `add` with bundles — the content-addressed workflow store
664
+
665
+ `owenloop add <owner>/<repo>[@ref]` (the previous section) installs
666
+ GitHub repos by name into `<defsDir>/<owner>-<repo>-<hash>/`. The **bundle**
667
+ route is a separate, content-addressed installation path for `.wnlp` workflow
668
+ bundles:
669
+
670
+ ```text
671
+ owenloop add widget.wnlp # install into the PROJECT store
672
+ owenloop add ./packs/widget.wnlp --global # install into the GLOBAL store
673
+ owenloop add https://example.com/widget.wnlp
674
+ owenloop add --recover [--global] # offline crash recovery (per root)
675
+ ```
676
+
677
+ The source is classified before anything else: `owner/repo[@ref]` keeps the
678
+ GitHub route byte-for-byte unchanged; a path ending in `.wnlp` is a bundle
679
+ file; an `http:`/`https:` URL is a bundle URL. Any other URL scheme
680
+ (`ftp:`, `file:`, …) is refused — never a silent fallback. `--global` applies
681
+ only to `.wnlp` bundle sources; a GitHub source with `--global` is refused
682
+ before any network request. The source string is origin data only (diagnostics
683
+ and messages); it is never joined into a filesystem path and never part of a
684
+ bundle's identity. Identity comes from the bundle's own
685
+ `namespace/name@version` coordinate and its canonical content digest.
686
+
687
+ **The `.wnlp` route requires two adapters and fails closed without them.**
688
+ Bundle ingestion (unpacking, manifest integrity, canonical digest,
689
+ coordinate) and pre-commit verification are separate modules with no
690
+ permissive fallback: with either adapter missing, `add` refuses with a named
691
+ error before any staging, journal, or index write. The default CLI binds both
692
+ production adapters. The pre-commit verifier consumes the publication sidecars
693
+ written by `publish` and applies the local `defPolicy` before the object or index
694
+ commit. Hosts that provide both adapters can install real `.wnlp` output from
695
+ `packBundle`; use the `publish` command to create the `.wnlp` bundle plus a
696
+ signed or explicitly unsigned sidecar.
697
+
698
+ ### Definition publication policy
699
+
700
+ `defPolicy` is the local execution and installation policy for workflow
701
+ publication signatures. The settings file is
702
+ `$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is non-blank,
703
+ otherwise `$HOME/.config/owenloop/settings.json`. To set the policy in the
704
+ settings file, write a JSON object such as:
705
+
706
+ ```json
707
+ {
708
+ "defPolicy": "enforce"
709
+ }
710
+ ```
711
+
712
+ For a one-off CLI invocation, set `OWENLOOP_DEF_POLICY` in the environment, for
713
+ example `OWENLOOP_DEF_POLICY=enforce owenloop add widget.wnlp`. The local
714
+ precedence is explicit host-provided policy, then `OWENLOOP_DEF_POLICY`, then
715
+ the settings file, then the built-in default `warn`. An invalid environment or
716
+ settings-file value fails loudly; it never degrades to `off`.
717
+
718
+ When a host supplies an already-verified organization policy floor through the
719
+ `policyFloor` option seam, the floor is applied **after** that local precedence.
720
+ `unsignedDefs: warn` raises the minimum to `warn`; `unsignedDefs: refuse` raises
721
+ the minimum to `enforce`; the effective policy is the stricter of local policy
722
+ and the floor. **Therefore, local `off` no longer means “no enforcement” when a
723
+ verified org floor is present.** A local operator cannot use `off` to opt out of
724
+ a verified floor. A missing, malformed, unsigned, wrongly signed, or
725
+ under-scoped floor leaves the local policy unchanged.
726
+
727
+ The current CLI and production configuration do not load or verify a floor.
728
+ `policyFloor` is an injection seam only, so this feature is inert until a host
729
+ wires floor loading and verification into that seam.
730
+
731
+ The policy applies at install time and again at execution time. The following
732
+ table describes the local policy result before any verified floor is applied.
733
+ The table uses these verdicts:
734
+
735
+ - `verified` — the publication sidecar verifies against the bundle digest and a
736
+ signer in the local trust root.
737
+ - `unsigned` — the bundle has no publication signature (including an explicit
738
+ `.wnlp.unsigned` sidecar).
739
+ - `unverifiable` — verification could not be completed, such as when the trust
740
+ root is missing or malformed.
741
+ - `invalid` — a present publication signature fails verification, including a
742
+ digest or signer mismatch.
743
+
744
+ | publication verdict | `enforce` | `warn` | `off` |
745
+ |---|---|---|---|
746
+ | `verified` | Install succeeds; agent and command execution proceed. | Install succeeds; agent and command execution proceed. | Install succeeds; agent and command execution proceed. |
747
+ | `unsigned` or `unverifiable` | Install refuses; agent and command execution refuse. | Install warns to stderr and succeeds; agent execution warns and proceeds; command execution refuses. | Install succeeds silently; agent execution proceeds silently; command execution refuses. |
748
+ | `invalid` | Install refuses; agent and command execution refuse. | Install refuses; agent and command execution refuse. | Install refuses; agent and command execution refuse. |
749
+
750
+ **Command-worker hard rule.** A `worker: command` order requires full
751
+ enforcement in every policy value, including `off`: the definition must be
752
+ verified, the enrollment chain must be verified, and the signer scope must be
753
+ checked. `off` does not disable command-worker enforcement. `warn` and `off`
754
+ never allow an unsigned, unverifiable, or invalid definition to reach the
755
+ shell. The command check runs before the policy value is read, and a refusal
756
+ uses the normal `InstructionRefusal` path so the lease stops before command
757
+ execution. A policy floor cannot relax this gate; the gate also fails closed
758
+ regardless of any floor. If an execution host has no publication verifier
759
+ configured, the definition is `unverifiable`; command workers therefore refuse
760
+ rather than treating installed bytes as published trust.
761
+
762
+ ### Consume-side artifact policy
763
+
764
+ `artifactPolicy` controls how agent and MCP drivers handle absent evidence and
765
+ missing local prerequisites for signed dynamic artifact values. Supplied but
766
+ invalid evidence always refuses; the policy is a scalar with the same values as
767
+ `defPolicy`: `enforce`, `warn`, or `off`. The precedence is explicit host
768
+ option, then `OWENLOOP_ARTIFACT_POLICY`, then the `artifactPolicy` key in the
769
+ execution settings file, then the built-in default `warn`.
770
+
771
+ For example, the settings file can contain:
772
+
773
+ ```json
774
+ {
775
+ "artifactPolicy": "enforce"
776
+ }
777
+ ```
778
+
779
+ A one-off invocation can set
780
+ `OWENLOOP_ARTIFACT_POLICY=enforce owenloop work agent-run <order-id>`.
781
+ Invalid values fail loudly; an invalid value never becomes `off`.
782
+
783
+ The consuming driver verifies each delivered value against its serialized DSSE
784
+ submission proof, the signed value digest and version, the locally anchored
785
+ producer enrollment chain, revocations, and any supplied consuming demand's
786
+ scope. A missing proof is not the same as invalid evidence. Dynamic values and
787
+ rejection reasons remain on the wire; the driver verifies those values and
788
+ refuses the whole order on failure rather than dropping only one path.
789
+
790
+ A valid historical proof is not enough to establish the version claimed for the
791
+ current delivery. Ordinary consumed artifacts bind the signed version to the
792
+ claim-time version in `consumedFingerprint`; owed rejection reasons bind to the
793
+ owed claim-time version. If that authoritative expected version is absent, the
794
+ verdict is `unverifiable`, never `verified`, even when the signature, value
795
+ digest, and enrollment chain all verify. The policy table therefore applies
796
+ without a hidden exception: `enforce` refuses that artifact, `warn` warns and
797
+ admits it, and `off` admits it without calling the proof verified. The
798
+ command-worker hard rule below still refuses it under every policy.
799
+
800
+ The current production `exec`, `agent-run`, and `hold` roles do not supply a
801
+ pool, label, or namespace demand. `OrderPacket` has no such demand field to
802
+ derive, so production consume gates enforce the enrollment chain, attenuation,
803
+ and revocation checks but do not apply a demand-dependent `scopePermits`
804
+ restriction. A caller that supplies a demand through the verifier seam gets the
805
+ full scope check. This limitation is a named follow-up.
806
+
807
+ | consumed-evidence verdict | `artifactPolicy=enforce` | `artifactPolicy=warn` | `artifactPolicy=off` |
808
+ |---|---|---|---|
809
+ | `verified` | admit | admit | admit |
810
+ | `absent` | refuse | warn and admit | admit |
811
+ | `unverifiable` | refuse | warn and admit | admit |
812
+ | `invalid` | refuse | refuse | refuse |
813
+
814
+ A refusal is an actionable integrity event. The refusal names the failed link
815
+ and artifact, using names such as `no-proof`, `signature`, `value-digest`,
816
+ `version`, `chain`, `scope`, or `prerequisite`, and includes the workflow, run,
817
+ and step. The driver refuses the whole order; operators must not suppress the
818
+ message or continue with a manually stripped packet.
819
+
820
+ The policy floor's `unsignedArtifacts: warn` value raises the local minimum to
821
+ `artifactPolicy=warn`; `unsignedArtifacts: refuse` raises it to `enforce`. A
822
+ verified floor is merged after local precedence, so local `off` cannot weaken
823
+ the floor.
824
+
825
+ **Command-worker hard rule.** A `worker: command` order refuses `absent`,
826
+ `unverifiable`, and `invalid` consumed evidence regardless of `artifactPolicy`,
827
+ including `off`. The consume-side gate runs before origin or artifact policy
828
+ lookup and before a shell command is built or passed to `/bin/sh -c`. A command
829
+ worker must have a configured consume-side verifier; an unverified dynamic value
830
+ must never reach the shell. Agent prompt rendering and MCP `get_order` likewise
831
+ fail closed when dynamic data exists but no verifier is configured. The driver
832
+ samples the consumer's injected clock once per complete gate invocation; a
833
+ revocation effective at `effectiveFrom <= at` makes a previously consumable
834
+ artifact unconsumable on a later invocation.
835
+
836
+ ### Definition origin policy
837
+
838
+ `originRules` is a separate namespace-scoped provenance policy. A signed file
839
+ publication may include `<bundle>.origin.dsse`; installation verifies that
840
+ sidecar against the local `allowed_signers` root and retains the exact bytes at
841
+ `<store-root>/.owenloop/origins/<digest>.dsse`. Execution re-verifies the
842
+ retained evidence against the current trust root. Only a `verified` origin
843
+ verdict is retained. A bundle carrying only `<bundle>.origin.dsse` — with
844
+ neither a publication `.dsse` nor an unsigned marker — is refused at install for
845
+ every origin-policy value, including `off`. `publish` never emits that shape;
846
+ `--unsigned` removes both sidecars. A hub or other remote coordinator may relay
847
+ the sidecar, but never authors or supplies the origin rule.
848
+
849
+ The origin mode uses the same policy values as `defPolicy` — `enforce`, `warn`,
850
+ and `off` — and follows the same scalar precedence: explicit host option,
851
+ `OWENLOOP_ORIGIN_POLICY`, settings-file `originPolicy`, then `warn`. These are
852
+ not trust modes: `Seamless`, `Strict`, and `Paranoid` are a separate axis;
853
+ `Seamless` maps to `warn`, `Strict` maps to `enforce`, and `off` is a local
854
+ operator escape hatch with no trust-mode equivalent. The rule map has no
855
+ environment-variable spelling: explicit host `originRules`, then settings-file
856
+ `originRules`, then an empty map. A namespace with no matching rule has no origin
857
+ requirement. A malformed rule map is a named settings error, not an empty-policy
858
+ fallback.
859
+
860
+ Rules accept exact namespaces (`prod`), namespace prefixes (`prod*`), and
861
+ trailing `/*` sugar (`prod/*`, equivalent to `prod`). `*` and `*/*` are
862
+ catch-all rules. Exact matches beat prefixes; the longest prefix wins; keys
863
+ that normalize to equal specificity, such as `prod` and `prod/*`, are rejected.
864
+ Rule values are minimum provenance strengths, ordered `git` > `console` >
865
+ `agent`; therefore a `console` rule accepts verified `git` and `console`
866
+ origins, and an `agent` rule accepts all three. `any` imposes no requirement.
867
+
868
+ Origin verdicts remain distinct:
869
+
870
+ - `verified` has a strength and is checked against the selected minimum.
871
+ - `absent` means no origin bytes are available. For a signed file publication,
872
+ this means no sidecar was recorded. Unsigned publications and non-file install
873
+ sources also produce `absent`, but those definitions structurally cannot carry
874
+ an origin; those cases must not be described as “no origin was recorded.”
875
+ - `unverifiable` means a prerequisite such as the trust root is unavailable.
876
+ - `invalid` means present origin evidence failed verification and is refused at
877
+ every origin mode, including `off`.
878
+
879
+ For a matched rule, the local origin mode behaves as follows:
880
+
881
+ | origin verdict | `originPolicy=enforce` | `originPolicy=warn` | `originPolicy=off` |
882
+ |---|---|---|---|
883
+ | `verified` meeting the minimum | Install and execution succeed. | Install and execution succeed. | Install and execution succeed. |
884
+ | `verified` weaker than the minimum | Install refuses; execution refuses. | Install warns and succeeds; execution warns and proceeds. | Install and execution proceed silently. |
885
+ | `absent` or `unverifiable` | Install refuses; execution refuses. | Install warns and succeeds; execution warns and proceeds. | Install and execution proceed silently. |
886
+ | `invalid` | Install refuses; execution refuses. | Install refuses; execution refuses. | Install refuses; execution refuses. |
887
+
888
+ The table applies only when a rule matches. During execution, the driver
889
+ recovers the namespace by reverse-scanning project and global store indexes for
890
+ the bundle digest. Equivalent requirements deduplicate. Different requirements
891
+ produce a named ambiguity refusal. If no coordinate is indexed, `enforce`
892
+ refuses, `warn` warns, and `off` proceeds. With an empty `originRules` map, the
893
+ default resolver still invokes the origin verifier once per order, but skips the
894
+ expensive index reverse-scan; invalid retained origin evidence still refuses.
895
+
896
+ A verified policy floor maps `originRules: advisory` to minimum
897
+ `originPolicy=warn` and `originRules: enforced` to minimum
898
+ `originPolicy=enforce`. The origin floor is parallel to the publication floor;
899
+ it does not alter `defPolicy`.
900
+
901
+ **Origin policy never relaxes the command-worker hard rule.** A
902
+ `worker: command` order must pass the publication verification gate first, even
903
+ when `defPolicy=off`, and only then runs the origin check. Unsigned,
904
+ unverifiable, or invalid publication evidence never reaches the shell. An
905
+ origin mode of `off` and every policy-floor preset leave that gate unchanged.
906
+
907
+ The local SSHSIG trust root is
908
+ `$XDG_CONFIG_HOME/owenloop/allowed_signers`, or
909
+ `$HOME/.config/owenloop/allowed_signers` when `XDG_CONFIG_HOME` is blank. A
910
+ missing or malformed trust root is `unverifiable`, not `unsigned`.
911
+
912
+ ### The two store roots
913
+
914
+ A store root holds exactly this layout:
915
+
916
+ ```text
917
+ <root>/
918
+ index.json # coordinate → {digest, pinned, workflows?} index
919
+ objects/
920
+ sha256/
921
+ <64-hex-content-digest>/ # one immutable object per digest
922
+ … # the bundle's files
923
+ .owenloop/ # per-root lock + crash journal
924
+ add.lock
925
+ add.journal
926
+ .owenloop-staging/ # transient staging (cleared on exit)
927
+ ```
475
928
 
476
- ## Hub (`login` / `connect` / `push` / `logout`)
929
+ - **Project store root** = the resolved defs directory itself (`--defs`,
930
+ `OWENLOOP_DEFS`, or `./workflows`). The project's pins are reviewable in
931
+ git there, and the nested `objects/sha256/<digest>/` layout stays below
932
+ the def loader's scan depth.
933
+ - **Global store root** = `<home>/.owenloop/workflows`. `--global` selects it;
934
+ it cannot be combined with `--defs` (the global store has a fixed
935
+ home-directory location, so an override would only create ambiguity —
936
+ refused with a clear message). The global root is never used by the
937
+ GitHub route.
938
+
939
+ **Injected home requirement.** `<home>` is the first non-blank value from the
940
+ caller-injected `HOME` and `USERPROFILE` environment variables (`HOME` wins).
941
+ The `.wnlp` bundle route uses the same injected home for its default external
942
+ recovery-marker directory, `<home>/.owenloop/recovery-markers`, even when the
943
+ bundle targets the project store. If neither variable is supplied, bundle
944
+ installation refuses before any object or index commit; it never falls back to
945
+ the process user's ambient home. `add --recover --global` has the same
946
+ requirement. Project recovery of a v2 fresh-install journal also refuses when
947
+ its recovery marker requires a home and neither variable is supplied.
948
+
949
+ Every object path derives ONLY from its validated digest (lowercase 64-hex).
950
+ Coordinates, source strings, and version text never join into a path.
951
+
952
+ ### What an install does, in order
953
+
954
+ 1. Read the bundle bytes (file or URL) *before* taking the lock — a slow
955
+ download never holds the project lock. A local `.wnlp` must be a bounded
956
+ regular file: missing, symlinked, non-regular, or over the 256 MiB cap
957
+ (checked before *and* after the read) is refused naming the path as
958
+ given. A URL fetch uses the same 5 min timeout, refuses redirects
959
+ (`redirect: 'error'`) instead of following them silently, and streams
960
+ through the same bounded reader.
961
+ 2. Acquire the canonical root lock at `<root>/.owenloop/add.lock`. A GitHub
962
+ install also retains its legacy cwd-derived lock for compatibility and, when
963
+ the resolved `--defs` root differs from that cwd, acquires both locks in a
964
+ fixed order. The canonical lock makes bundle installs from different cwd
965
+ values serialize when they target one shared `--defs` root; the additional
966
+ GitHub lock keeps the legacy route compatible.
967
+ 3. Recover a prior interrupted install (before clearing staging — the
968
+ backups a rollback needs live under the staging root).
969
+ 4. Reread and validate the index **inside** the lock (a corrupt index is a
970
+ hard error, never a silent reset).
971
+ 5. Ingest via the bundle adapter: unpack into staging, check manifest
972
+ integrity and runtime compatibility, compute the canonical digest, and
973
+ extract the full coordinate. The runtime check uses Owenloop's production
974
+ package version and advertised feature set. A tampered, malformed, or
975
+ runtime-incompatible bundle stops here — staging debris only, nothing
976
+ committed.
977
+ 6. Validate the staged tree with the engine's strict pass — the exact bytes
978
+ that will be committed (parse/lint/validate/bounded `check` + the strict
979
+ cross-def backstop). For a real `.wnlp`, validation parses `bundle.yaml`
980
+ through the same runtime-admission boundary and loads every workflow path
981
+ listed in its `workflows` map; the package manifest itself is not treated as
982
+ a workflow definition. Any problem refuses the whole install and prints
983
+ every reason.
984
+ 7. Run the pre-commit verifier (after content validation, before any swap or
985
+ index write). A rejection commits nothing.
986
+ 8. Write the `applying` crash journal (v2 — its commit-point evidence is the
987
+ hash of the post-install index bytes).
988
+ 9. Atomically swap the staged object into `objects/sha256/<digest>`
989
+ (retaining any displaced content on the commit handle), then harden it
990
+ in place: canonical `0644` files become read-only `0444`, canonical `0755`
991
+ files become read/execute-only `0555`, and directories become non-writable
992
+ `0555`. Hardening preserves the executable distinction needed for canonical
993
+ object reconstruction. Hardening is defense in depth, not the integrity proof
994
+ — verification reconstructs the complete canonical tar, including
995
+ `bundle.yaml`, and matches its SHA-256 digest to the object path. A hardening
996
+ failure rolls the swap back; a partially hardened object is never committed.
997
+ If the digest's object already exists, the install verifies the existing
998
+ object through the ingest adapter and commits an index-only change instead
999
+ (dedupe) — a corrupt or runtime-incompatible existing object is a hard
1000
+ integrity error, never replaced and never fallen through.
1001
+ 10. Atomically write `index.json` — the **durable commit point**. Past here
1002
+ a crash rolls forward; before it, everything rolls back. An index-write
1003
+ failure rolls the directory state back and leaves the previous object
1004
+ and index exactly as they were.
1005
+ 11. Advance the journal to `finalizing`, discard the retained backup and
1006
+ staging, remove the journal, release the lock.
1007
+
1008
+ On success `add` prints the structured result:
477
1009
 
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
1010
+ ```jsonc
1011
+ {
1012
+ "ok": true,
1013
+ "source": "widget.wnlp", // or the URL
1014
+ "level": "project", // or "global"
1015
+ "coordinate": "acme/widget@1.0.0",
1016
+ "digest": "<64-hex>",
1017
+ "workflows": ["delivery", "init"], // every workflow name in the bundle, sorted
1018
+ "objectPath": "<root>/objects/sha256/<64-hex>",
1019
+ "installed": true // false when deduplicated
1020
+ }
1021
+ ```
1022
+
1023
+ **Conflict and re-install.** An existing coordinate at a DIFFERENT digest is
1024
+ a conflict error — no implicit retarget; the original digest is retained and
1025
+ nothing is written. An existing coordinate at the SAME digest deduplicates
1026
+ (`installed: false`), verifying the existing object before trusting it.
1027
+
1028
+ **Crash recovery** is the same two-phase discipline as the GitHub route,
1029
+ generalized: the v2 journal's commit-point test compares the hash of the
1030
+ current `index.json` bytes against the journal's recorded metadata hash
1031
+ (route-neutral — no GitHub ledger involved). A fresh v2 install also writes a
1032
+ single-use external recovery marker under the user's recovery-marker directory
1033
+ (default `<home>/.owenloop/recovery-markers`, derived from the injected home
1034
+ described above) before the applying journal. If a crash leaves the destination
1035
+ present with no staging or backup, recovery
1036
+ discards that destination only when the marker exactly matches the store root,
1037
+ destination segments, staging id, and `hadDest: false`; a missing or mismatched
1038
+ marker refuses and preserves the destination and journal. `add --recover --global`
1039
+ runs the store's recovery standalone against the global root with no network
1040
+ and prints `{"ok":true,"recovered":false|true,"outcome":…}` exactly
1041
+ like the project variant. A v1 (GitHub-schema) journal found at the global root
1042
+ is refused fail-closed — there is no ledger there to vouch for it — and a
1043
+ journal recorded against a *different* store root is refused rather than
1044
+ trusting its absolute path. Refusals leave the journal in place as evidence.
1045
+
1046
+ ### Resolving what is installed — two separate APIs
1047
+
1048
+ Resolution is deliberately split so execution code cannot accidentally call
1049
+ human-name resolution. Both are library APIs (exported from the package
1050
+ root); every successful resolution verifies the object through the ingest
1051
+ adapter before returning a path — permissions and object shape on disk are
1052
+ defense in depth, not an integrity proof.
1053
+
1054
+ - **Digest resolution (execution).** `resolveWorkflowDigest({digest,
1055
+ projectRoot?, globalRoot, verifier})` — digest only; no index and no
1056
+ workflow name participate. The project object path is tested first when a
1057
+ project root exists; an ABSENT project object may fall through to global,
1058
+ but a PRESENT project object that fails its type probe or verification is
1059
+ a hard integrity error — project tampering is never hidden by falling back
1060
+ to a valid global copy. When both levels hold the same digest, ONE result
1061
+ comes back (level `project`, with presence metadata), not two candidates.
1062
+ Absent at both levels ⇒ `object-missing` integrity error.
1063
+ - **Coordinate resolution (human/CLI).** `resolveWorkflowCoordinate({coordinate,
1064
+ projectRoot?, globalRoot, verifier})` reads BOTH indexes, fail-closed (a
1065
+ corrupt index is a hard error, never silently empty). No entry at either
1066
+ level ⇒ a structured **not-found** error. A project entry wins whenever it
1067
+ exists, even when the global index maps the same coordinate to a different
1068
+ digest; global is the fallback only when project has no match. An index entry
1069
+ whose selected object is missing or corrupt is an integrity error, never a
1070
+ returned path.
1071
+
1072
+ **Calls resolution for installed bundle workflows.** In the default CLI context
1073
+ (no explicit `--defs`/`OWENLOOP_DEFS`), `defs`/`create`/`tick` load CAS workflows
1074
+ from the project and global bundle-store indexes in addition to filesystem defs
1075
+ and the GitHub `add` ledger. A CAS workflow is addressable by the qualified
1076
+ `<package>/<workflow>` name, so a project-local or `add`-installed workflow can
1077
+ call it explicitly. A bare call from a CAS-loaded workflow resolves a sibling
1078
+ from the same bundle digest first; if no sibling has that name, ordinary flat
1079
+ lookup remains available. Bare CAS names are not registered globally, so a
1080
+ workflow in bundle A cannot accidentally call a same-named workflow from bundle
1081
+ B.
1082
+
1083
+ The precedence is explicit: project-local definitions win first, then
1084
+ GitHub-`add` installed definitions, then CAS definitions under qualified keys.
1085
+ Within the CAS layer, exactly one installed bundle holds the unqualified
1086
+ `<package>/<workflow>` name, chosen by two rules in order and never by install
1087
+ order:
1088
+
1089
+ 1. **Level.** If any candidate is named by the *project* index, only project
1090
+ candidates compete. A project pin of `pkg@0.1.0` therefore beats a global
1091
+ install of `pkg@0.9.9`. This holds even when the project's own object bytes
1092
+ are missing and were served by exact-digest fallback from the global store —
1093
+ the index that names the object decides, not where the bytes were read.
1094
+ 2. **Version.** Among the survivors, the highest canonical SemVer precedence
1095
+ wins (SemVer §11, so `0.1.10` beats `0.1.2` and `1.0.0` beats `1.0.0-rc.1`).
1096
+
1097
+ A canonical SemVer version never loses to a non-SemVer one. If two or more
1098
+ candidates compete and *none* carries a canonical SemVer version, the selection
1099
+ **fails closed**: the unqualified name is left unregistered and a warning names
1100
+ the versions involved, because there is no defined precedence to pick by. Call an
1101
+ exact `<namespace>/<name>@<version>` coordinate in that case. A single
1102
+ non-SemVer version still holds its name — there is nothing to order.
1103
+
1104
+ The refusal warning names only the versions that actually competed. A version
1105
+ dropped by rule 1 is reported separately as never having competed, since it lost
1106
+ on level and was never judged on its version at all. For the same reason,
1107
+ precedence warnings say `project-indexed` / `global-indexed`: precedence follows
1108
+ the index that named the object, whereas a registration's reported level is the
1109
+ store its verified bytes came from, and the two differ under exact-digest
1110
+ fallback.
1111
+
1112
+ Every version that did not win remains reachable under its digest-scoped key, so
1113
+ an already-pinned execution cannot be retargeted, and every exact
1114
+ `<namespace>/<name>@<version>` coordinate always resolves to its own object
1115
+ regardless of which version currently holds the unqualified name.
1116
+ A corrupt CAS index, object, or workflow is skipped with a warning during
1117
+ read-side discovery, so it does not make `status` fail. A running workflow keeps
1118
+ the definition snapshot from its creation (§28), including the CAS bundle
1119
+ provenance used for sibling lookup; installing a newer bundle therefore does not
1120
+ retarget an existing parent instance. The bundle spawn-time pin check compares
1121
+ canonical bundle digests and records a rejected `calls:` debt instead of running
1122
+ a mismatched child.
1123
+
1124
+ Store roots and object directories are probed with `lstat`, never `stat`:
1125
+ a symlink or non-directory squatting at a root, an index path, or an object
1126
+ path is refused outright, and reads never follow a link outside the
1127
+ intended tree.
1128
+
1129
+ **GitHub-route compatibility.** The bundle route changes nothing about
1130
+ `add <owner>/<repo>[@ref]`: the same inputs reach the same parser, the
1131
+ `<owner>-<repo>-<hash>` namespace is untouched, `.owenloop/installed.json`
1132
+ keeps its schema and validation, and an explicit `--defs`/`OWENLOOP_DEFS`
1133
+ still installs through a symlinked defs dir (operator intent). The legacy
1134
+ GitHub repository route installs workflow YAML rather than a format-v2
1135
+ `bundle.yaml`; therefore the GitHub route does not carry or enforce the `.wnlp`
1136
+ runtime compatibility declaration and does not provide the `.wnlp` runtime
1137
+ admission guarantee. Use a `.wnlp` bundle when the publisher must declare a
1138
+ minimum Owenloop version or required runtime features.
1139
+
1140
+ The routes share the canonical resolved-store lock, while the GitHub route
1141
+ retains its legacy cwd-derived lock and journal for compatibility. Recovery
1142
+ checks both journal locations and dispatches by journal version; a v2 store
1143
+ journal uses `index.json` metadata and a v1 GitHub journal uses
1144
+ `installed.json` ledger corroboration.
1145
+
1146
+ ## Hub (`login` / `connect` / `push` / `start` / `publish` / `logout`)
1147
+
1148
+ These commands authenticate, publish, and start workflows on a hosted **hub** (default
1149
+ `https://api.owenloop.com`). `login` and `logout` retain the generic resolver:
1150
+ `--hub <url>` → `OWENLOOP_HUB` → the built-in `DEFAULT_HUB`. `connect`, `push`,
1151
+ and `publish` use the safer publishing ladder below and never consult
1152
+ `OWENLOOP_HUB` or guess `DEFAULT_HUB`. They are the only network-bound commands
1153
+ besides `add`, and they talk only to endpoints the hub exposes today — no new
482
1154
  service-side surface. The hub URL is normalized to its origin
483
1155
  (`scheme://host[:port]`); path/query are dropped. `https` is required for
484
1156
  every hub origin except the loopback hosts (`127.0.0.1`, `::1`, `localhost`),
@@ -492,6 +1164,74 @@ bounce credentials or workflow YAML to another origin (same-origin validation
492
1164
  covers only the initial URL; a redirect would otherwise re-send the request body
493
1165
  cross-origin).
494
1166
 
1167
+ ### The small hosted-workflow path
1168
+
1169
+ Setup is durable. Authenticate and bind the project once, publish or update a
1170
+ definition when its content changes, prepare that published version for the
1171
+ execution account, and keep one crew-scoped Shift running:
1172
+
1173
+ ```bash
1174
+ owenloop login --hub https://hub.example
1175
+ owenloop connect --hub https://hub.example
1176
+ owenloop push newhire-onboarding
1177
+ OWENLOOP_ACCOUNT=default owenloop work prepare newhire-onboarding --origin https://hub.example
1178
+ OWENLOOP_HARNESS=codex owenloop shift start openai --origin https://hub.example --as default
1179
+ ```
1180
+
1181
+ Starting another run does not repeat installation, publication, preparation,
1182
+ or Shift setup. From the connected project it is one public control-plane
1183
+ command; repeat `--provide name=json` for seeded human inputs:
1184
+
1185
+ ```bash
1186
+ owenloop start newhire-onboarding \
1187
+ --crew openai \
1188
+ --provide 'signed_docs={"acknowledged":true}' \
1189
+ --provide 'hardware_choice={"laptop":"MacBook Pro"}'
1190
+ ```
1191
+
1192
+ `start` always uses the human credential. The standing Shift uses the
1193
+ `agent:default` credential selected by `--as default`. With no project binding,
1194
+ `start --hub <url>` is accepted explicitly; with neither a binding nor `--hub`,
1195
+ it refuses instead of falling through to `OWENLOOP_HUB` or the production
1196
+ default. If both a binding and `--hub` exist they must agree.
1197
+
1198
+ ### `start` — start a published workflow
1199
+
1200
+ `owenloop start <defName>` sends `POST /api/start_run` and prints the new
1201
+ workflow id, its initial status, and the steps whose default crew was stamped or
1202
+ whose capability routes were validated. `--crew <name>` selects the crew for
1203
+ steps that declare no capability; capability-bearing steps continue to use
1204
+ their live hub bindings. `--title <text>` is display-only. Both `--crew` and
1205
+ `--title` require non-empty values; bare flags and `--crew=`/`--title=` are local
1206
+ usage errors before credential or network access. The command does not claim,
1207
+ dispatch, close, or otherwise drive work—the standing Shift discovers the run
1208
+ through its normal crew inbox.
1209
+
1210
+ **Publishing hub resolution.** `connect`, `push`, and `publish` resolve their
1211
+ target in this order:
1212
+
1213
+ 1. An explicit `--hub <origin>` always wins.
1214
+ 2. `.owenloop/hub.json`, when present, is the project override.
1215
+ 3. Global machine state supplies one unambiguous candidate:
1216
+ - with the file credential backend, exactly one origin containing a valid
1217
+ human-slot credential is selected automatically;
1218
+ - Keychain and external-command credential backends cannot enumerate their
1219
+ origins, so the validated `hubOrigin` in
1220
+ `$XDG_CONFIG_HOME/owenloop/settings.json` (or
1221
+ `~/.config/owenloop/settings.json`) is used, and the requested credential
1222
+ slot must exist there before the command proceeds.
1223
+ 4. If nothing safe resolves, the command exits 2 without network or publication
1224
+ output effects.
1225
+
1226
+ More than one file-backed origin is also an exit-2 ambiguity: the error lists
1227
+ the origins in deterministic order and asks for `--hub <origin>` or
1228
+ `owenloop connect --hub <origin>`. A non-enumerable backend with no settings
1229
+ `hubOrigin` names the exact settings path and asks for the same explicit
1230
+ choice. `owenloop setup` populates that non-secret settings field. `OWENLOOP_HUB`
1231
+ and `DEFAULT_HUB` are intentionally excluded from the publishing ladder because
1232
+ an ambient guess can target the wrong hub organization; ambiguous or missing
1233
+ resolution fails closed instead of choosing one.
1234
+
495
1235
  **Request timeouts.** Every hub call — OAuth discovery, client registration,
496
1236
  code exchange, token refresh, `whoami`, the workflow list, and each push — is
497
1237
  bounded by a 30s deadline; a stalled hub surfaces as a friendly `hub did not
@@ -567,28 +1307,66 @@ can read (only read) a stored credential through the same backend logic via the
567
1307
  package's exported `readStoredCredential` — see
568
1308
  [Embedding](embedding.md#whats-exported).
569
1309
 
1310
+ The macOS `security` adapter treats exit status 44 (`errSecItemNotFound`) as the
1311
+ only absence result: lookup returns no credential, and deletion succeeds
1312
+ idempotently (running the same deletion again changes nothing). Every other
1313
+ numeric status, signal termination, or command-start failure is a fatal backend
1314
+ error. Lookup and logout stop at that error; Owenloop neither reports success
1315
+ nor falls through to or deletes a file-store credential. Mapped errors name only
1316
+ the operation and backend failure class, never the service, account, credential,
1317
+ or stdin command.
1318
+
570
1319
  **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.
1320
+ token, or a `login`/`logout` that stores or deletes a slot — is serialized by the
1321
+ logical `credentials.lock` guard and the persistent SQLite lock database at
1322
+ `credentials.lock.sqlite-v2`, both siblings of `credentials.json` in the config
1323
+ dir (created for the keychain backend too, since the race the lock closes is
1324
+ backend-independent). The concern is a token-refresh
1325
+ race: two owenloop processes hitting an expiring OAuth token at once would each
1326
+ POST a refresh and each persist, and because refresh tokens rotate, the second
1327
+ write clobbers the first with a token whose refresh link is already spent —
1328
+ silently killing the credential. Under the lock a process re-reads the slot
1329
+ after acquiring it and, if another process already refreshed, **adopts** that
1330
+ fresh token instead of refreshing again — one network refresh, one write, no
1331
+ lost token. The lock matters only for OAuth refresh and store/delete; read paths
1332
+ and the external-command mode (which never writes the local store) do not take
1333
+ it.
1334
+
1335
+ SQLite owns exclusion through a `BEGIN IMMEDIATE` transaction tied to the live
1336
+ database connection. Release, normal process exit, and process crash close that
1337
+ connection and release the operating-system lock. Owenloop deliberately keeps
1338
+ the SQLite database path after release; Owenloop never deletes or replaces the
1339
+ path. A sibling `credentials.lock.owner.json` contains only diagnostic process
1340
+ metadata and does not determine ownership. If the lock cannot be acquired within
1341
+ the wait budget, the CLI fails loudly (`another owenloop process is using the
1342
+ credential store … — timed out waiting after Ns`) rather than refreshing
1343
+ unlocked. `OWENLOOP_CRED_LOCK_WAIT_MS` (default 45000) and
1344
+ `OWENLOOP_CRED_LOCK_POLL_MS` (default 100) override the wait behavior.
1345
+ `OWENLOOP_CRED_LOCK_STALE_MS` is accepted for compatibility but no longer causes
1346
+ pathname deletion. No token value appears in either lock file or the timeout
1347
+ message.
1348
+
1349
+ **Lock-file upgrade boundary.** The logical lock pathname, such as
1350
+ `credentials.lock`, remains a permanent, parseable JSON compatibility guard.
1351
+ The new SQLite lock database lives at `<logical-lock-path>.sqlite-v2`; for the
1352
+ credential store, that path is `credentials.lock.sqlite-v2`. A new client first
1353
+ holds SQLite's `BEGIN IMMEDIATE` transaction and then installs the guard at the
1354
+ old pathname with an exclusive create. The guard carries an impossible operating-
1355
+ system hostname, so a pre-SQLite client treats the guard as a live foreign-host
1356
+ owner and never age-reclaims it. An already-running old holder can release its
1357
+ ordinary JSON lock normally; the waiting new client then installs the guard and
1358
+ closes the one-way upgrade boundary. Old clients remain blocked after every new-
1359
+ client release or crash, while new clients continue to exclude one another
1360
+ through SQLite.
1361
+
1362
+ Release and crash cleanup close only the SQLite transaction. Owenloop never
1363
+ deletes, renames, or replaces either the permanent guard or the versioned SQLite
1364
+ database during normal lock lifecycle. A corrupt, partial, old-owner, or pre-
1365
+ boundary SQLite file already present at the logical legacy pathname fails closed:
1366
+ stop the relevant processes, verify that no old or pre-boundary process still
1367
+ owns that pathname, remove the legacy pathname manually, and let one upgraded
1368
+ client install the permanent guard. Routine stale-age or PID reclamation is no
1369
+ longer used, and `OWENLOOP_CRED_LOCK_STALE_MS` cannot weaken the boundary.
592
1370
 
593
1371
  **Supplying the credential from your own tooling.** If your secrets live in a
594
1372
  secret manager, or you run on a host with no keychain, set
@@ -630,14 +1408,35 @@ it — a `401` there means the credential is never written to disk. On success
630
1408
  `orgId`, `identity`, and `email` when the hub returns one), read straight from
631
1409
  `whoami`.
632
1410
 
1411
+ **Recording the hub for `owenloop mcp` (`~/.owenloop/config.json`).** After the
1412
+ credential above is verified and stored, `login` makes one more best-effort
1413
+ write: it records the hub origin it just authenticated against in
1414
+ `~/.owenloop/config.json` (`{"version": 1, "hub": "<origin>"}` — never a
1415
+ secret, just the origin). This file is separate from both the credential store
1416
+ above and from `owenloop setup`'s `~/.config/owenloop/settings.json`; its only
1417
+ reader is `owenloop mcp`'s [origin resolution](#choosing-the-hub-origin),
1418
+ which needs to know your hub without enumerating the credential store (the
1419
+ Keychain and external-command backends can't be listed at all — see below). A
1420
+ failure to write this file is a **warning** printed to stderr, never a fatal
1421
+ error and never blocking `login` itself, since the credential is already
1422
+ safely stored by the time this write is attempted. Logging into a second hub
1423
+ overwrites this file — "last login wins" — so if you routinely switch between
1424
+ hubs, pass `--hub` explicitly to `owenloop mcp` (or set `OWENLOOP_HUB`) rather
1425
+ than relying on whichever `login` ran most recently.
1426
+
633
1427
  ### `connect` — bind a project to a hub
634
1428
 
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.
1429
+ `owenloop connect` resolves a target through the publishing ladder, re-verifies
1430
+ the stored credential against `GET /api/whoami`, and writes
1431
+ `.owenloop/hub.json`. Run `login` first. With no `--hub`, an existing binding
1432
+ remains the target; an unbound project uses the unambiguous global fallback.
1433
+ An explicit `--hub` creates or replaces the project override, which is useful
1434
+ for multi-org or multi-hub repositories. `connect` is optional for the ordinary
1435
+ single-hub happy path, not a prerequisite for `push` or `publish`.
1436
+
1437
+ The JSON reports the same org/identity fields as `login`; re-connecting to the
1438
+ **same** origin reports no `switchedFrom`, switching to a **different** hub
1439
+ reports `switchedFrom: <old origin>` and rebinds the project to the new one.
641
1440
 
642
1441
  A symlinked project `.owenloop` directory is refused with a clear error rather
643
1442
  than followed: a hostile checkout cannot ship `.owenloop -> /elsewhere` to
@@ -647,16 +1446,40 @@ guarantee). The same refusal covers the default `state.db` FILE (and its SQLite
647
1446
  file would otherwise redirect the store's writes, since SQLite follows file
648
1447
  symlinks.
649
1448
 
650
- ### `push` — publish local defs to the bound hub
1449
+ ### `push` — publish local defs to the resolved hub
651
1450
 
652
1451
  `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
1452
+ them, or just the named ones) to the hub selected by the publishing ladder.
1453
+ `--hub` overrides a project binding for that invocation without rewriting it;
1454
+ otherwise the project override wins over global state. An unbound project with
1455
+ one file-backed human credential therefore needs no setup step. Ambiguous or
1456
+ missing candidates exit 2 as described above, and `OWENLOOP_HUB`/
1457
+ `DEFAULT_HUB` never participate. `push` never writes a project binding. It
654
1458
  reuses the **exact** all-or-nothing validation gate `add` uses — lint, validate,
655
1459
  and a bounded `check` — across every selected def before a single byte is sent;
656
1460
  any definite defect aborts the whole push. stdout is machine-parseable JSON;
657
1461
  the human-readable diff (`+ new`, `~ changed`, `= unchanged`, `! failed`) goes
658
1462
  to stderr.
659
1463
 
1464
+ `owenloop push --bundle <bundle.wnlp> [<defName>...]` is the executable,
1465
+ bundle-backed form. The exact archive is inspected and becomes the definition
1466
+ source; checkout files are ignored. Push requires exactly one adjacent
1467
+ publication sidecar produced by `owenloop publish` (`.dsse` or `.unsigned`),
1468
+ accepts an optional `.origin.dsse`, uploads those content-addressed objects,
1469
+ then calls `create_workflow` with the archive's canonical digest. This is what
1470
+ makes the hub stamp reference orders with a digest that execution hosts can
1471
+ resolve from their installed bundle store. Because a reference order identifies
1472
+ its executable instructions only by bundle digest plus step name, every workflow
1473
+ definition in the complete archive must use distinct step names. `push --bundle`
1474
+ refuses an archive when two definitions share a step name, even when positional
1475
+ arguments select only one of those definitions; the refusal happens before any
1476
+ bundle, evidence, or workflow-version write. Bundle mode conservatively sends
1477
+ each selected `create_workflow` request even when its YAML hash is unchanged,
1478
+ because the workflow listing does not expose the latest bundle identity; the
1479
+ hub's `(yaml, bundle digest)` idempotency decides whether to version-forward or
1480
+ return `noop`. `--dry-run` validates the archive and sidecars and performs only
1481
+ the read-only server diff—no bundle, sidecar, or definition is uploaded.
1482
+
660
1483
  **Idempotency is server-side truth, not a client ledger.** `push` fetches the
661
1484
  hub's own view of every def (`GET /api/workflows`, which reports each def's
662
1485
  `hash`) and diffs local content against it directly — there is no
@@ -678,6 +1501,15 @@ batch: the current def is recorded as `failed`, the not-yet-attempted remainder
678
1501
  is reported under a `skipped` output key, and any `Retry-After` the hub sent is
679
1502
  surfaced in the error.
680
1503
 
1504
+ Selected definitions are published in topological `calls:` order. If a selected
1505
+ dependency fails or is skipped, Owenloop sends no `create_workflow` request for
1506
+ its selected dependents; each dependent is added to `skipped`, names its failed
1507
+ or skipped dependencies in sorted order, and becomes unsuccessful so the skip
1508
+ propagates transitively. Independent selected definitions continue publishing.
1509
+ A locally `unchanged` dependency and a server `noop` dependency both count as
1510
+ successful, so either result permits the dependent to publish. Dependency
1511
+ matching covers bare names and same-package-qualified names in a bundle.
1512
+
681
1513
  The def hash is computed by re-parsing the raw YAML with no checkout-specific
682
1514
  `baseDir` — the same canonicalization the hub applies — so it's portable
683
1515
  across checkouts and machines by construction: a fresh clone at a different
@@ -698,6 +1530,59 @@ def isn't round-trippable. A def using `bodyFile:` is refused the same way
698
1530
  resolve the external file against once the YAML leaves this machine. Inline
699
1531
  both before pushing.
700
1532
 
1533
+ ### `publish` — pack and publish a workflow bundle
1534
+
1535
+ ```text
1536
+ owenloop publish <source-dir> [--output <bundle.wnlp>] [--source <json>] [--unsigned] [--hub <origin>]
1537
+ ```
1538
+
1539
+ `publish` is separate from both [`bundle pack`](#bundles) and [`push`](#push--publish-local-defs-to-the-resolved-hub). It packs one source directory with the same deterministic `packBundle` implementation as `bundle pack`, then publishes the bundle beside a local publication sidecar and, optionally, a signed origin sidecar. A project binding is optional; when present it supplies the project-specific author-key origin unless `--hub` overrides it.
1540
+
1541
+ The author-key origin comes from the same publishing ladder as `connect` and
1542
+ `push`: `--hub` wins, a project binding overrides global state, one file-backed
1543
+ human origin resolves automatically, and a non-enumerable backend uses the
1544
+ validated execution-settings `hubOrigin` only when the human credential exists.
1545
+ An ambiguous or absent candidate exits 2 before signing, packing, or output
1546
+ writes. `publish` never writes `.owenloop/hub.json`, consults `OWENLOOP_HUB`, or
1547
+ guesses `DEFAULT_HUB`.
1548
+
1549
+ Signed publication is the default. In signed mode, `publish` requires the human principal signing key for the resolved hub. Run `owenloop setup` before the first signed publication. `publish` never creates or repairs a signing key: an older key store that already contains the key but lacks the non-secret `<hash>.ref` pointer must be repaired by a setup run, whose `ensure` step backfills the pointer without regenerating or replacing the private key. If the author-key reference or key record is missing, `publish` fails and suggests `owenloop setup` or the explicit unsigned mode; the command does not silently downgrade to unsigned output.
1550
+
1551
+ In signed mode, `publish` confirms the existing key and probes the signer before `packBundle` runs, then signs the publication record before any bundle or sidecar is written. A signing failure therefore leaves no half-published artifact. The signature covers a DSSE publication record whose `digest` is the lowercase SHA-256 digest of the uncompressed canonical tar inside the `.wnlp` file. When `--source <json>` is supplied, the command signs a separate origin record with the same signer and digest, then writes `<output>.origin.dsse` beside the publication sidecar. The remote hub is not involved in this local signing operation and never produces or completes either signature.
1552
+
1553
+ `--source` is signer-supplied provenance, not a hub-derived label. The JSON value must be one of these closed forms:
1554
+
1555
+ - `{"kind":"git","repo":"<repo>","commit":"<40- or 64-hex commit SHA>"}`;
1556
+ - `{"kind":"console","user":"<authoring user>"}`, which requires a client-side signing ceremony; or
1557
+ - `{"kind":"agent","agent":"<agent identity>","session":"<session>"}`.
1558
+
1559
+ The origin record is part of the signed content. The hub or another relay stores and relays the signed record but cannot write, derive, default, or stamp an origin value. `attesterKeyId` in the record is only a candidate-selection hint; verification cross-checks the hint against the signer that produced the verified signature. `--source` cannot be combined with `--unsigned`. The CLI currently rejects the `console` form because that form requires a client-side signing ceremony rather than this command's local signing path.
1560
+
1561
+ `--unsigned` is an explicit opt-in. Unsigned mode still packs the canonical bundle, but writes an unauthenticated author-intent marker rather than a DSSE envelope. Anyone can write such a marker; consumers must treat missing and unverifiable signatures as unsigned regardless of whether the marker is present. Publication and unsigned sidecars are mutually exclusive:
1562
+
1563
+ - signed mode writes `<output>.wnlp.dsse` and removes a stale `<output>.wnlp.unsigned`;
1564
+ - `--unsigned` writes `<output>.wnlp.unsigned` and removes a stale `<output>.wnlp.dsse`.
1565
+
1566
+ A signed publish without `--source` removes a stale `<output>.origin.dsse`. Unsigned mode also removes a stale origin sidecar because an unsigned origin would only be an unsigned label.
1567
+
1568
+ The output defaults to `<package-name>-<version>.wnlp` next to the source directory. `--output` must name a path outside the source directory. Existing regular output and sidecar files may be replaced; directories and other non-regular paths are rejected.
1569
+
1570
+ Successful invocations print exactly one machine-readable JSON object to stdout. Signed output without an origin has this shape:
1571
+
1572
+ ```json
1573
+ {
1574
+ "ok": true,
1575
+ "bundle": "/absolute/path/report-1.2.0.wnlp",
1576
+ "digest": "<64 lowercase hex characters>",
1577
+ "name": "report",
1578
+ "version": "1.2.0",
1579
+ "signed": true,
1580
+ "envelope": "/absolute/path/report-1.2.0.wnlp.dsse"
1581
+ }
1582
+ ```
1583
+
1584
+ When `--source` is supplied, signed output also includes `"origin": "/absolute/path/report-1.2.0.wnlp.origin.dsse"`. Unsigned output has the same `ok`, `bundle`, `digest`, `name`, and `version` fields, with `"signed": false` and `"marker": "/absolute/path/report-1.2.0.wnlp.unsigned"` instead of `envelope`. Diagnostics and failures go to stderr and exit nonzero. `bundle pack` and `push` are unchanged by this command.
1585
+
701
1586
  Exact-match redirect URIs (no RFC 8252 variable-port allowance) and no
702
1587
  device-code grant remain recorded follow-ups on the service, not gaps in the
703
1588
  CLI.
@@ -733,10 +1618,22 @@ minting on the wrong org is not undone by a retry:
733
1618
 
734
1619
  Unlike other commands this does **not** fall back to `OWENLOOP_HUB` or the
735
1620
  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`.
1621
+ production hub while you're logged into a dev one. This is deliberately
1622
+ stricter than [`owenloop mcp`'s origin resolution](#choosing-the-hub-origin):
1623
+ `mcp` exposes both reads and writes, including `create_agent` (which mints and
1624
+ stores an agent token), `create_workflow`, `publish_event`, `submit`,
1625
+ `stage_enrollment`, and crew mutations. The default remains acceptable for
1626
+ `mcp` because each tool call authenticates against the resolved origin; when no
1627
+ human credential exists there, the existing `loginHint` surfaces the origin
1628
+ and asks for `owenloop login --hub <origin>` before the tool-specific action
1629
+ runs. If a credential does exist at an unintended origin and `create_agent`
1630
+ mints there, the stored agent token is revocable; `--hub` and `OWENLOOP_HUB`
1631
+ remain available when the operator wants to avoid inference. `agent new`
1632
+ **mints** a new credential directly, a side effect a retry cannot undo, so it
1633
+ stops at step 3 instead of ever guessing. Note that hub enumeration itself is
1634
+ **file-store only**: the keychain and the external-command backend cannot list
1635
+ their entries, so on such a machine step 2 cannot enumerate the store and you
1636
+ must pass `--hub`.
740
1637
 
741
1638
  **`--crews <a,b>`.** A comma-separated list of crew names the token is granted
742
1639
  on (trimmed, empties dropped). Omit the flag to let the hub default the token to
@@ -1062,16 +1959,19 @@ lines (the tolerant-false notices, the transfer summary) go to stderr only.
1062
1959
 
1063
1960
  ## `setup` — onboard a machine
1064
1961
 
1065
- `owenloop setup` is the one-shot onboarding command. It runs six ordered steps.
1962
+ `owenloop setup` is the one-shot onboarding command. It runs seven ordered steps.
1066
1963
  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:
1964
+ rekey and store a Scoped Identity credential, ensure the three principal
1965
+ signing keys, relay a signed machine enrollment grant, and write only
1966
+ `hubOrigin` in the execution settings file while preserving its other keys.
1967
+ The plugin step probes and, when needed, converges the bundled `owenloop` plugin
1968
+ for each available harness: Claude Code and Codex. Plugin convergence is
1969
+ non-fatal and setup continues when a harness is missing, the bundled marketplace
1970
+ root is unavailable, or a plugin command fails. A second run with the expected
1971
+ plugin version already installed performs no plugin writes. The steps:
1072
1972
 
1073
1973
  1. **inspect** — read-only report of what's already present (human credential,
1074
- execution settings, `claude` on PATH, agent slots). No writes.
1974
+ execution settings, `claude` and `codex` on PATH, agent slots). No writes.
1075
1975
  2. **human login** — verify the stored **human** credential, or run the same
1076
1976
  loopback-OAuth browser flow as `owenloop login` when none is present or it no
1077
1977
  longer verifies. This is the gate that makes step 3's mint/rekey legal.
@@ -1079,17 +1979,28 @@ installs the plugin. The steps:
1079
1979
  hub and reuse it; otherwise **mint** a new Scoped Identity or **rekey**
1080
1980
  (replace the credential of) an existing one. How the target is chosen is
1081
1981
  [below](#choosing-the-scoped-identity-flow-a-vs-flow-b).
1082
- 4. **execution settings** — write only `hubOrigin` into the execution settings
1982
+ 4. **signing keys** — ensure an Ed25519 signing key for each of the three local
1983
+ principals, in order: human, machine, agent. Details
1984
+ [below](#signing-keys-step-4). After key convergence, setup performs the
1985
+ enrollment relay sub-step described below.
1986
+ 5. **execution settings** — write only `hubOrigin` into the execution settings
1083
1987
  file so the local Step Agent talks to this hub, preserving every other key
1084
1988
  (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
1989
+ 6. **plugin** — probe and converge the bundled `owenloop` plugin separately
1990
+ for Claude Code and Codex. When the installed plugin is missing or its
1991
+ version differs from the CLI package, setup adds the bundled marketplace
1992
+ when needed and installs or updates the plugin. Claude Code uses
1993
+ `claude plugin install` for a fresh install and `claude plugin update` for
1994
+ an existing plugin. Codex uses `codex plugin add owenloop@owenloop` for both
1995
+ fresh installs and upgrades; setup does not call
1996
+ `codex plugin marketplace upgrade`, which applies only to Git marketplaces.
1997
+ **Non-fatal:** a missing harness or failed convergence is reported as
1998
+ `noted` and never fails setup. If the bundled marketplace root is
1999
+ unavailable, setup prints manual commands instead.
2000
+ 7. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
1090
2001
  the same surfaces, whose result becomes setup's exit code.
1091
2002
 
1092
- Progress lines (the `[n/6]` headers and `✓`/`✗` marks) go to **stderr**; the
2003
+ Progress lines (the `[n/7]` headers and `✓`/`✗` marks) go to **stderr**; the
1093
2004
  final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
1094
2005
  **stdout**.
1095
2006
 
@@ -1128,6 +2039,88 @@ is a usage error, because rekeying preserves the Scoped Identity's existing scop
1128
2039
  new Scoped Identity to change scopes). `setup` has no `--shift` shorthand — spell the
1129
2040
  scopes out with `--scopes work,run`.
1130
2041
 
2042
+ ### Signing keys (step 4)
2043
+
2044
+ Step 4 ensures one Ed25519 signing key per local principal — human, machine,
2045
+ agent — keyed by `{ hub origin, kind, principal id }`. It is **idempotent**:
2046
+ an existing key reports `existing` and is never regenerated or rewritten. A
2047
+ second full setup run performs zero key writes.
2048
+
2049
+ **Storage backends.** The key record goes to the macOS Keychain
2050
+ (`security`), to Linux libsecret (`secret-tool`) when that binary is on
2051
+ `PATH`, and otherwise to a `0600` file under `$HOME/.owenloop/keys/` (both
2052
+ parent directories forced `0700`, symlinks refused). One backend is selected
2053
+ once and a failure is a hard error — there is never a fallback to another
2054
+ backend, because a fallback could mint a second, different key for the same
2055
+ principal. `OWENLOOP_NO_KEYCHAIN=1` forces the file backend. Private bytes
2056
+ never appear on argv or in setup output.
2057
+
2058
+ **`--reuse-ssh-key <path>`** records your own existing Ed25519 SSH key for the
2059
+ **human** principal instead of generating one. The candidate is validated with
2060
+ a non-secret sign/verify challenge before anything is recorded, and only its
2061
+ canonical path + public key are stored — the private key is never copied. It
2062
+ applies to the human key only (machine and agent always get generated keys),
2063
+ and it is a **hard conflict** when a human key already exists: setup keeps the
2064
+ existing key and errors rather than rotating (rotation is not part of this
2065
+ work package). A nonexistent path fails up front, before any browser opens.
2066
+
2067
+ **Secret-output guarantee.** Step 4 prints only `kind state (backend)` — e.g.
2068
+ `✓ signing keys: human created (macos-security), machine created (file), agent
2069
+ existing (macos-security)` — never key bytes, fingerprints, or secret-store
2070
+ values. The full storage and signing model is in
2071
+ [Signing and key storage](crypto.md).
2072
+
2073
+ ### Machine enrollment relay
2074
+
2075
+ After the three keys are ensured, setup tries to register the machine public key
2076
+ with the hub. The relay is deliberately subordinate to local key convergence:
2077
+
2078
+ 1. Read-only inspect the human signing key. If no human signing key is present,
2079
+ setup records `skipped` and performs no enrollment request.
2080
+ 2. `GET /api/enrollments` with the human credential. If the hub is unavailable,
2081
+ returns an unsupported status such as `404`, returns `500`, or returns an
2082
+ unusable response, setup records `noted` and continues.
2083
+ 3. If the machine public-key fingerprint is already present, setup records
2084
+ `skipped` and does not sign or POST a duplicate.
2085
+ 4. Otherwise, the human signing key signs an `EnrollmentGrantRecord` locally.
2086
+ The grant names the machine principal `{ kind: "machine", id: "local" }`,
2087
+ uses the default least-privilege machine scope, and sets `grantedBy` to the
2088
+ human public-key fingerprint.
2089
+ 5. `POST /api/enrollments` receives only `{ envelope }`, where `envelope` is the
2090
+ signed DSSE enrollment grant. The machine private key, human private key
2091
+ bytes, key-store values, and private-key paths never enter the request body.
2092
+ HTTP `409` means already registered and becomes `skipped`; other transport or
2093
+ hub failures become `noted` and do not undo local key creation.
2094
+
2095
+ The relay is idempotent (repeating the operation after the first successful
2096
+ registration changes nothing) and the hub is only a storage/relay endpoint. The
2097
+ hub does not create, sign, or endorse the grant.
2098
+
2099
+ ## `enrollments` — inspect machine enrollment
2100
+
2101
+ `owenloop enrollments [--hub <url>]` fetches the hub's relayed DSSE envelopes and
2102
+ verifies each entry locally. The command is read-only: it does not call key
2103
+ creation, does not sign a grant, and does not POST to the hub. The command uses
2104
+ the local `allowed_signers` trust root when one is configured.
2105
+
2106
+ The command prints `{ ok, hub, enrollments }` on stdout. Each entry has one of
2107
+ four verdicts:
2108
+
2109
+ | verdict | meaning |
2110
+ |---|---|
2111
+ | `enrolled` | the grant payload and DSSE signature are valid, the signer is in the local `allowed_signers` root, and an enrollment-chain validator approved the grant |
2112
+ | `unenrolled` | no envelope was supplied for the roster entry |
2113
+ | `unverifiable` | verification cannot establish trust, including a missing `allowed_signers` root or the D1 fail-closed state where no chain validator is installed |
2114
+ | `invalid` | the envelope, payload, schema, signer authorization, signature, or chain-validator result is invalid |
2115
+
2116
+ WP-D1 intentionally does not install an enrollment-chain validator. Therefore a
2117
+ well-formed, correctly signed D1 grant is reported as `unverifiable` until WP-D4
2118
+ installs the validator. This prevents a signature from being mistaken for proof
2119
+ that the grantor is enrolled.
2120
+
2121
+ A missing human credential is exit `3`; hub, malformed-response, and other
2122
+ runtime failures are exit `1`; successful classification is exit `0`.
2123
+
1131
2124
  ### Hub resolution differs from `agent new`
1132
2125
 
1133
2126
  `setup` (and `doctor`) resolve the target hub like `agent new` with **one**
@@ -1187,22 +2180,30 @@ The checks, in order:
1187
2180
  | 3 | agent slot | an `agent:<name>` credential is stored | yes |
1188
2181
  | 4 | agent plane | that agent credential verifies live against the hub | yes |
1189
2182
  | 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) |
2183
+ | 6 | plugin (claude-code) | the Claude Code `owenloop` plugin is installed at the package version | **no** (rendered only) |
2184
+ | 7 | plugin (codex) | the Codex `owenloop` plugin is installed at the package version | **no** (rendered only) |
2185
+
2186
+ The plugin checks also report the detected harness CLI version. An installed
2187
+ plugin whose version cannot be parsed is reported as `version unknown` and is
2188
+ not treated as a failure. A parsed plugin version that differs from the
2189
+ package version is reported as version skew with the remedy `run owenloop
2190
+ setup`. A missing harness reports that the harness is not on `PATH`; a missing
2191
+ plugin reports the harness-specific marketplace and install command.
1191
2192
 
1192
2193
  Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
1193
2194
  <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.
2195
+ machine with no working human credential still renders the later checks,
2196
+ degrading honestly rather than dropping them.
1196
2197
 
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.
2198
+ **Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise. Both
2199
+ plugin checks (6–7) are *rendered* but do not affect the exit code.
1200
2200
 
1201
2201
  ## `mcp` — stdio control-plane server for MCP hosts
1202
2202
 
1203
2203
  `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
2204
+ plane** to a local MCP host (Claude Code, Codex, or any client that speaks MCP
2205
+ over stdio). The shipped Claude Code and Codex plugins launch this command from
2206
+ `PATH`. This is the `owenloop-cli-mcp` surface: an MCP host spawns it as a
1206
2207
  subprocess — **you do not run it yourself at a prompt**. It reads
1207
2208
  newline-delimited JSON-RPC 2.0 on stdin, translates each `tools/call` into one
1208
2209
  authenticated HTTPS request to the hub's `/api/*` REST mirror, and writes the
@@ -1215,29 +2216,77 @@ loopback listener. If no human credential is stored, a tool call returns an
1215
2216
  error telling you to run `owenloop login --hub <origin>` in a terminal and retry
1216
2217
  (see [Authentication and secrets](#authentication-and-secrets) below).
1217
2218
 
2219
+ ### Plugin/CLI version alignment
2220
+
2221
+ The shipped Claude Code and Codex plugins launch `owenloop mcp` from `PATH` and
2222
+ carry the plugin version in `.mcp.json` as `OWENLOOP_PLUGIN_VERSION`. The MCP
2223
+ server compares that expected version with its own package version on every
2224
+ recognized `tools/call`. The comparison is strict equality: a mismatch returns
2225
+ a tool error that names both versions and says `Run: owenloop setup`. The
2226
+ server does not reject the MCP startup handshake, so the diagnostic reaches the
2227
+ model and the human instead of appearing only as a transport-closed error.
2228
+
2229
+ Each plugin also declares a `SessionStart` hook. The hook reads the plugin
2230
+ manifest version, sends an MCP `initialize` request to `owenloop mcp` using a
2231
+ non-routable probe origin, and reads `serverInfo.version`; the root CLI has no
2232
+ supported `owenloop --version` flag. The hook reports a missing CLI, an
2233
+ unparseable version, or a mismatch to stderr and always exits successfully, so
2234
+ a diagnostic cannot block session startup. Claude Code runs the hook after
2235
+ installation. Codex runs plugin hooks only after the user approves them in
2236
+ `/hooks`; if the user does not approve Codex hooks, the always-on MCP check
2237
+ still catches a version mismatch when a tool call is made.
2238
+
2239
+ If the versions differ, run `owenloop setup` and follow the printed plugin
2240
+ installation instructions before retrying the MCP tool call.
2241
+
1218
2242
  ### Choosing the hub origin
1219
2243
 
1220
2244
  `owenloop mcp` binds to exactly one hub origin, resolved in this order:
1221
2245
 
1222
2246
  1. `--hub <url>` flag.
1223
2247
  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.
2248
+ 3. `~/.owenloop/config.json` — see below.
2249
+ 4. If the **file** credential backend holds exactly ONE hub with a valid
2250
+ `human` credential, that hub is used (kept for back-compat with installs
2251
+ from before step 3 existed).
2252
+ 5. The built-in **default hub**, `https://api.owenloop.com`.
2253
+
2254
+ Every inference rung after the first two **falls through silently** rather
2255
+ than stopping the server: a missing or corrupt config file, a `hub` value in
2256
+ it that doesn't parse as a valid origin, an unenumerable credential store
2257
+ (macOS Keychain or an external credential command — only the file backend can
2258
+ be listed at all), zero stored hubs, and more than one stored hub all just
2259
+ move on to the next rung. `owenloop mcp` never exits for an inferred-origin
2260
+ reason — this is deliberate: it is a long-running process spawned
2261
+ automatically by an MCP host on every session start, not a one-shot command a
2262
+ human is watching, so a hard stop here would silently break the plugin on any
2263
+ machine using the Keychain backend (the macOS default) unless the operator
2264
+ remembered to set `--hub` or `OWENLOOP_HUB` first.
2265
+
2266
+ The MCP surface is not read-only. It includes `create_agent`, which mints and
2267
+ stores a new agent token, plus state-changing tools such as `create_workflow`,
2268
+ `publish_event`, `submit`, `stage_enrollment`, and the crew mutations. The
2269
+ server still authenticates each tool call against the resolved origin. When no
2270
+ human credential exists at that origin, the first authenticated tool call
2271
+ returns `loginHint` with the origin and asks for `owenloop login --hub
2272
+ <origin>` before the tool-specific action runs. If a credential does exist at
2273
+ an unintended origin and `create_agent` mints there, the stored agent token is
2274
+ revocable; explicit `--hub` and `OWENLOOP_HUB` remain available to avoid
2275
+ inference. Contrast this with [`agent new`](#agent-new--mint-an-agent-token-into-a-slot),
2276
+ which **mints** a new credential directly and therefore stops rather than
2277
+ ever guessing — a wrong guess there is a side effect a retry cannot undo.
2278
+
2279
+ **`~/.owenloop/config.json`** is written by
2280
+ [`login`](#login--authenticate-the-cli-against-a-hub): a small, non-secret
2281
+ JSON file (`{"version": 1, "hub": "<origin>"}`) recording the hub `login` most
2282
+ recently authenticated against. It exists specifically so `mcp` can learn
2283
+ your hub without enumerating the credential store — see `login`'s own section
2284
+ for exactly when it's written and what happens if the write fails.
2285
+
2286
+ A malformed `--hub`/`OWENLOOP_HUB` value is still a normal exit-`1` error,
2287
+ like every other command — an explicit bad value is reported, never silently
2288
+ skipped, precisely because rungs 1–2 come from something the operator typed
2289
+ or set, not from inference.
1241
2290
 
1242
2291
  ### Tools
1243
2292
 
@@ -1341,7 +2390,7 @@ interactively.
1341
2390
 
1342
2391
  | variable | effect |
1343
2392
  |---|---|
1344
- | `OWENLOOP_HUB` | hub origin when `--hub` is absent (rung 2 of origin resolution) |
2393
+ | `OWENLOOP_HUB` | development override for the hub origin (rung 2, above `~/.owenloop/config.json`) |
1345
2394
  | `OWENLOOP_MCP_ENROLLMENT` | `1` forces `stage_enrollment` on, `0` off; unset = probe the hub |
1346
2395
  | `OWENLOOP_MCP_PROBE_TIMEOUT_MS` | deadline for the `stage_enrollment` capability probe (default `3000`) |
1347
2396
  | `OWENLOOP_HUB_TIMEOUT_MS` | per-request hub timeout (shared with the other hub commands) |
@@ -1453,8 +2502,13 @@ non-zero exit as a failure, not a success.
1453
2502
 
1454
2503
  ## What a job looks like
1455
2504
 
1456
- `tick` returns `{ workflow, orders, reaped }`. Each order is self-contained —
1457
- a Step Agent needs nothing else to do the work:
2505
+ `tick` returns `{ workflow, orders, reaped }`. Each order is a **reference
2506
+ packet**: it carries the routing fields and run-time context for the job — the
2507
+ run id, the captured input values, the owed outputs with their reason threads
2508
+ — plus a `defDigest` that names *which definition snapshot* holds the authored
2509
+ instructions. The instructions themselves (the step's `body:` prompt, any
2510
+ `command:` text) are **not** on the order, and `tick`/`order` never print
2511
+ them.
1458
2512
 
1459
2513
  ```jsonc
1460
2514
  {
@@ -1462,22 +2516,42 @@ a Step Agent needs nothing else to do the work:
1462
2516
  "workflow": "wf_…", // the instance this order belongs to — see deep tick below
1463
2517
  "step": "builder", // which step this job is for
1464
2518
  "key": "", // map jobs carry the element key + index
2519
+ "defDigest": "9f2c…", // identifies the definition snapshot to resolve instructions from
1465
2520
  "inputs": ["plan"],
1466
2521
  "outputs": ["pr"],
1467
- "prompt": "…body with ${WORKFLOW}/${RUN}/${INDEX} filled in…",
2522
+ "worker": "command", // the authored step's executor:, mapped verbatim (absent = 'agent')
1468
2523
  "consumes": { "plan": { /* the accepted input value */ } },
1469
2524
  "owes": [ // the feedback channel
1470
- { "path": "pr", "acceptance": "rejected", "judgmentRejects": 2, "schemaRejects": 0,
2525
+ { "path": "pr", "judgmentRejects": 2, "schemaRejects": 0,
1471
2526
  "reasons": [ { "action": "reject", "kind": "judgment", "by": "reviewer",
1472
2527
  "text": "tests are missing", "at": 0 } ] }
1473
2528
  ]
1474
2529
  }
1475
2530
  ```
1476
2531
 
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.
2532
+ A worker first **resolves the reference**: the `(defDigest, step, key)`
2533
+ boundary maps the order to the exact authored instructions from the worker's
2534
+ trusted local definition source — the same resolver the embedded engine and
2535
+ the CLI use. Resolution returns the authored `prompt` (with
2536
+ `${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}`
2537
+ materialized), the authored `command` if the step has one, and nothing
2538
+ fabricated. If the worker's source does not know the digest — the definition
2539
+ was never delivered, or the current on-disk definition no longer matches the
2540
+ pinned digest — resolution raises `UnknownDefDigestError`. If the digest is
2541
+ known but the referenced step is absent, resolution raises the distinct
2542
+ `UnknownInstructionError` and identifies the digest, step, and key. The worker
2543
+ must refuse either malformed reference rather than guess instructions by step
2544
+ name or fetch unverified text. Once resolved, the worker reads the resolved
2545
+ prompt + `consumes` + `owes`, does the work, reports with `green` (or
2546
+ `emit`/`seal` for collections), then `close`s the job. The reject counts in
2547
+ `owes[]` let a workflow escalate on its own — e.g. switch to a stronger model
2548
+ after two rejections — before the engine stalls the step.
2549
+
2550
+ Static authored text (prompts, commands) travels by digest reference; dynamic
2551
+ data — `consumes` values and the rejection `reasons` threads — stays on the
2552
+ order because it exists only for this run. A remote coordinator or transport
2553
+ that relays these packets never sees authored instruction text and never needs
2554
+ to: instructions resolve at the worker, from a source the worker trusts.
1481
2555
 
1482
2556
  **Deep tick and `order.workflow`.** `tick <wf>` is **deep by default**: it ticks
1483
2557
  `<wf>` and then descends into every live `calls:` child, folding their orders