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
@@ -0,0 +1,86 @@
1
+ # Agent runner and harness policy
2
+
3
+ `owenloop work agent-run` is the only supported dispatcher for workflow Step Agents. The Shift daemon starts `agent-run` children for agent orders. Plugins and skills supervise the Shift daemon; plugins do not package or dispatch a static workflow-worker agent.
4
+
5
+ The runtime worker resolves the verified workflow definition from the local workflow store, selects the final harness after CLI and environment overrides, and runs permission preflight before either a cold start or a resume. A policy refusal starts no model SDK, CLI, or app-server process. The worker prints every refusal reason, releases the held claim, and exits non-zero.
6
+
7
+ Runtime preflight is authoritative. `owenloop work lint` runs the same common and adapter checks for author feedback, but lint cannot account for a later `--harness` or `OWENLOOP_HARNESS` override.
8
+
9
+ Native judge entries do not carry a separately authored `x` map. The definition
10
+ compiler deep-clones the producer step's complete parsed `x` map onto every
11
+ synthesized judge step, and generated and persisted judge orders expose that
12
+ map as `Order.x`. The worker therefore reads the current judge's inherited
13
+ `x.harness` from the same verified definition snapshot used for the judge's
14
+ instructions. Final-adapter selection and mandatory preflight apply before
15
+ both judge cold starts and judge resumes. A judge entry's first-class `model`
16
+ continues to win over an inherited `x.harness.model` value.
17
+
18
+ ## `x.harness` permission fields
19
+
20
+ The reserved neutral fields are:
21
+
22
+ ```yaml
23
+ x:
24
+ harness:
25
+ id: claude-code
26
+ tools: [Read, Glob]
27
+ disallowedTools: [Bash]
28
+ filesystem: read-only
29
+ network: owenloop-only
30
+ permissionMode: default
31
+ maxTurns: 20
32
+ model: sonnet
33
+ effort: high
34
+ ```
35
+
36
+ - `tools` and `disallowedTools` accept a comma-separated string or a string array.
37
+ - An absent `tools` field means that the workflow did not declare a built-in-tool allow-list.
38
+ - `tools: []` is an explicit empty allow-list and disables all built-in tools on adapters that support tool lists.
39
+ - `filesystem` is one of `read-only`, `workspace-write`, or `unrestricted`.
40
+ - `network` is one of `owenloop-only` or `unrestricted`.
41
+ - `tools` and `disallowedTools` must not overlap.
42
+ - Invalid types, invalid closed-set values, generated `name`/`description` fields, and the legacy `x.claude-code` carrier are definition errors.
43
+ - Unknown `x.harness` keys remain opaque extension data. The selected adapter may interpret or warn about those keys.
44
+
45
+ A cache created by an older CLI may contain `filesystem` or `network` under `permissions.extensions`. The cache reader and final permission preflight refuse that shape because the old normalization would ignore the restriction. Run `owenloop work prepare <workflow>` again.
46
+
47
+ ## Capability matrix
48
+
49
+ | Restriction | Claude Code adapter | Codex adapter |
50
+ |---|---|---|
51
+ | absent `tools` | preserves the normal SDK built-in-tool default unless another restriction requires an audited set | supported only because no tool list was authored |
52
+ | `tools: []` | disables all built-in tools; only the born-bound Owenloop control tools remain | refused; Codex cannot enforce per-thread tool lists |
53
+ | non-empty `tools` | enforced through both `tools` and `allowedTools`; settings, skills, and external MCP are isolated so unlisted tools cannot widen the surface | refused |
54
+ | `disallowedTools` | enforced through `disallowedTools` | refused |
55
+ | `filesystem: read-only` | with `network: unrestricted`, uses `Read`, `Glob`, `Grep`, `WebFetch`, and `WebSearch`; with `network: owenloop-only`, uses only `Read`, `Glob`, and `Grep` | refused; Codex cannot prove a complete neutral read-only boundary because app-server configuration layers are outside the thread sandbox |
56
+ | `filesystem: workspace-write` | refused; the adapter cannot enforce an exact workspace boundary | refused; Codex cannot prove a complete neutral workspace-write boundary because app-server configuration layers are outside the thread sandbox |
57
+ | `filesystem: unrestricted` | supported | maps to sandbox `danger-full-access`; open-ended `codexConfig`, external MCP, and operator configuration remain backward compatible because no filesystem boundary is claimed |
58
+ | `network: owenloop-only` | supported through isolated settings, skills, MCP, and built-in tools | refused |
59
+ | `network: unrestricted` | supported | supported with `filesystem: unrestricted`, or with an omitted filesystem field and legacy sandbox `workspace-write` / `danger-full-access`; legacy sandbox `read-only` is refused because Codex has no independent read-only network control |
60
+ | `maxTurns` | enforced by the SDK | refused; Codex app-server has no thread or turn limit parameter |
61
+
62
+ Codex refusal of explicit `filesystem: read-only` and `filesystem: workspace-write` is intentional and runs before both cold start and resume. Codex app-server loads configuration from thread, project, global/managed, and persisted session layers. The pinned Codex version has no reliable switch that isolates every layer, and some layers can introduce host processes, providers, endpoints, MCP servers, or additional writable roots outside the thread sandbox. Partial filtering would claim a boundary the adapter cannot prove, so the adapter starts no app-server process and the worker releases the held claim.
63
+
64
+ Codex also refuses every defined `maxTurns` value before both cold start and resume. Codex app-server has no thread or turn limit parameter, so accepting `maxTurns` would silently discard an authored execution limit. The adapter starts no app-server process and the worker releases the held claim.
65
+
66
+ An omitted `filesystem` field preserves the existing Codex default sandbox behavior. `filesystem: unrestricted` preserves the existing explicit `danger-full-access` behavior. The legacy adapter extension `sandbox` remains available with `read-only`, `workspace-write`, or `danger-full-access` for backward compatibility, but `sandbox` is a vendor-specific pass-through rather than Owenloop's neutral filesystem guarantee. A workflow that requires an enforceable neutral read-only policy must select the Claude Code adapter.
67
+
68
+ The worker-created `owenloop` MCP mount still wins any `mcp_servers.owenloop` name clash. The default unrestricted mount registers `get_order`, `submit`, and `reject`. Codex approval policy still accepts only `untrusted`, `on-request`, or `never`.
69
+
70
+ The Claude Code adapter refuses a `read-only` allow-list containing anything outside `Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, and the born-bound control tools. With `network: owenloop-only`, the allowed read-only built-ins narrow to `Read`, `Glob`, and `Grep`; `WebFetch` and `WebSearch` remain available only with `network: unrestricted`. The Claude Code adapter refuses an `owenloop-only` allow-list containing Bash, web tools, skills, agent delegation, or any unaudited tool. The Claude Code adapter also refuses authored external MCP tool names because the current option surface cannot prove an exact per-tool allow-list for an external server.
71
+
72
+ ## Owenloop control-plane exception
73
+
74
+ `network: owenloop-only` means that the Step Agent may reach only the born-bound Owenloop MCP control plane for the held order. The exception exists so the Step Agent can call `get_order` and `submit`; without those calls the Step Agent cannot inspect or complete the order.
75
+
76
+ For Claude Code isolation, the adapter sets `settingSources: []`, `strictMcpConfig: true`, disables skills, excludes hooks and external MCP servers, and mounts only the worker-created `owenloop` MCP server. The restricted MCP child positively registers exactly `get_order` and `submit`; the restricted MCP child does not register `reject`. A future work-holder tool therefore does not enter restricted sessions unless the adapter explicitly adds the tool to the positive registration list. The adapter also restricts built-in tools to an audited no-network set. The same option construction runs for cold start and resume.
77
+
78
+ The born-bound Owenloop MCP server is created by the worker from the live workflow, run, origin, account, Shift, and held claim. Workflow extension data cannot replace that mount. During isolation, the adapter adds `mcp__owenloop__get_order` and `mcp__owenloop__submit` to `allowedTools` so both control calls execute without an unattended permission prompt. `allowedTools` controls permission automation; `allowedTools` does not filter the MCP server's `tools/list` response. The positive registration list on the MCP child is the visibility boundary. The adapter also adds `mcp__owenloop__reject` to `disallowedTools` as defense in depth. A direct deny or an MCP wildcard deny that blocks Owenloop `get_order` or `submit` is refused.
79
+
80
+ Outside Claude Code isolation, the default work-holder MCP child continues to register `get_order`, `submit`, and `reject`.
81
+
82
+ ## Security boundary
83
+
84
+ `x.harness` permission fields are enforced policy. Adapter preflight must prove that the selected adapter can implement each authored restriction exactly; unsupported policy fails closed.
85
+
86
+ `advisory.tools` is model guidance only. `advisory.tools` does not configure an adapter, does not remove a provider tool, and is not a security boundary.
package/docs/authoring.md CHANGED
@@ -78,6 +78,7 @@ steps:
78
78
  # to the engine, passed through on the order
79
79
  # (see below)
80
80
  workdir: … # opaque hint passed through on the order; omitted when unset
81
+ workdirFrom: workspace.payload.worktreePath # resolve workdir from a consumed value
81
82
  executor: agent # opaque executor value (default: agent); see below
82
83
  command: … # required when executor: command; opaque, never shelled out
83
84
  spec: # optional opaque config map, shape-checked like x: (a plain map)
@@ -112,6 +113,37 @@ a literal model id. Pin an exact model when you need reproducibility — just
112
113
  know the def is now host-specific, on purpose. Omit `model:` entirely and the
113
114
  dispatcher uses its default.
114
115
 
116
+ ## `workdirFrom:` — resolve a local workdir from a consumed value
117
+
118
+ `workdirFrom:` sets the existing `Order.workdir` from a nested field in a green,
119
+ plain consumed artifact. The grammar is `<consumedStem>.<dotted.value.path>`:
120
+
121
+ ```yaml
122
+ steps:
123
+ - name: provisioner
124
+ consumes: [proposal]
125
+ produces: [workspace]
126
+ - name: builder
127
+ consumes: [workspace]
128
+ produces: [pr]
129
+ workdirFrom: workspace.payload.worktreePath
130
+ ```
131
+
132
+ The stem named before the dotted value path must also appear in the step's
133
+ `consumes:` list, and the consume must be plain rather than map (`[$i]`) or
134
+ reduce (`[*]`). The engine resolves the longest consumed-stem prefix when an
135
+ artifact stem itself contains dots. `workdir:` and `workdirFrom:` are mutually
136
+ exclusive.
137
+
138
+ At order-build time the engine walks the consumed value using the dotted path.
139
+ A missing field, non-object intermediate, array, non-string final value, empty
140
+ string, or whitespace-only string defers the firing with reason
141
+ `workdir-unresolved`; the engine emits no order and inserts no run. The engine
142
+ passes a valid path through unchanged: the engine does not resolve or normalize
143
+ a relative path and does not change the worker's current-directory semantics.
144
+ The producer and worker must therefore run on the same machine. A permanently
145
+ unresolvable path remains deferred until the producer supplies a valid value.
146
+
115
147
  ## `executor:` — declaring the executor
116
148
 
117
149
  Every step in every def written before this feature dispatches to an LLM
@@ -229,6 +261,12 @@ indirection. Two consequences of the local filter are worth stating plainly:
229
261
  (each folded deferral in a `TickResult` carries its `reason`) so a
230
262
  permanently unclaimed step is caught rather than silently stuck.
231
263
 
264
+ A `workdirFrom` firing can also remain deferred forever with
265
+ `workdir-unresolved`. That reason means the producing step has not supplied a
266
+ usable nested path: the value is missing, has an invalid shape, or is not a
267
+ non-empty string. Fix the producing step or its artifact value; changing the
268
+ consumer's worker does not bypass the engine's workdir resolution check.
269
+
232
270
  `capabilities:` is distinct from [`executor:`](#executor--declaring-the-executor):
233
271
  `executor:` says what *kind* of executor should run an order once it's claimed;
234
272
  `capabilities:` says *which* caller may claim it in the first place — a tick filter
@@ -291,6 +329,15 @@ regardless of `executor:` — that requirement is orthogonal to this feature and
291
329
  applies even to a `executor: command` judge (the field just goes unread by a
292
330
  non-agent dispatcher).
293
331
 
332
+ Author `x:` on the producer step, not on individual judge entries. Every native
333
+ judge synthesized from that producer inherits the producer's complete parsed
334
+ `x:` map. Each judge receives an independent deep clone, so runner-side
335
+ mutation of the producer or one judge cannot alter a sibling judge. When the
336
+ producer omits `x:`, synthesized judges omit `x:` too. In particular, a
337
+ producer's `x.harness` policy governs both the producer order and every native
338
+ judge order. A judge entry's first-class `model:` remains authoritative over an
339
+ inherited `x.harness.model` value.
340
+
294
341
  Each judge is a real step under the hood — it fires its own Worker order
295
342
  through the normal pipeline, with its own throttles (`cadence:`,
296
343
  `maxRunsPerDay:`) and retry/timeout behavior. When `researcher` commits
@@ -420,7 +467,7 @@ steps:
420
467
  produces: [sandbox]
421
468
  body: Provision environment.
422
469
  - name: deliver
423
- calls: delivery # child workflow name (must exist in the same def dir)
470
+ calls: delivery # bare local name; use <package>/<workflow> for a CAS target
424
471
  inputs: # child input → parent artifact (gate: sandbox green)
425
472
  proposal: proposal
426
473
  produces: [delivered] # one parent artifact; greens when delivery's output greens
@@ -526,13 +573,17 @@ rather than inlining the payload itself.
526
573
 
527
574
  Don't put credentials or secrets in an artifact value. Values are persisted
528
575
  as plaintext in the SQLite store (no encryption at rest) and are copied
529
- verbatim into the prompt/context of every order that consumes them — anyone
530
- who can read the database or a downstream job's prompt can read it.
576
+ verbatim onto every order that consumes them — anyone who can read the
577
+ database, or a downstream worker's resolved context, can read them.
531
578
 
532
579
  Those values are also *retained*, not just transiently persisted: every
533
580
  artifact version is kept (the store never overwrites a prior version in place),
534
- and every run's issued order packet — prompt plus the input values it consumed
535
- — is written to the SQLite `run` table at claim time and stays there after the
536
- run closes and the workflow finishes. A secret that flowed through an input
581
+ and every run's issued order packet — the dynamic input values it consumed
582
+ and its accumulated rejection reasons — is written to the SQLite `run` table
583
+ at claim time and stays there after the run closes and the workflow finishes.
584
+ The step's authored prompt and command text are *not* in that packet: orders
585
+ are reference packets (design doc §29) and carry a `defDigest` pointing at
586
+ the definition snapshot instead, so instruction text is retained once, in the
587
+ definition, not duplicated per firing. A secret that flowed through an input
537
588
  therefore lives on in the database until the file itself is disposed of — see
538
589
  [Storage](../README.md#storage) for the operator's disposal responsibility.
@@ -0,0 +1,250 @@
1
+ # `.wnlp` bundle format
2
+
3
+ A `.wnlp` file packages one versioned package namespace, one or more named workflow definitions, and the regular files those definitions reference. The physical format is a gzip-compressed POSIX/PAX tar archive. Packing the same source bytes and canonical executable-bit choices produces identical archive bytes.
4
+
5
+ The bundle APIs are independent of the local workflow store and the network:
6
+
7
+ ```ts
8
+ import { digestBundle, inspectBundle, packBundle, unpackBundle } from 'owenloop';
9
+ ```
10
+
11
+ The command-line equivalents are documented in [`docs/cli.md`](cli.md#bundles).
12
+
13
+ ## Source layout
14
+
15
+ A source directory must contain `bundle.yaml` and every path listed by the manifest's `workflows` map. Workflow paths may be at the source root or below a subdirectory. For example:
16
+
17
+ ```text
18
+ report/
19
+ ├── bundle.yaml
20
+ ├── workflows/
21
+ │ ├── delivery.yaml
22
+ │ ├── init.yaml
23
+ │ └── instructions/
24
+ │ └── writer.md
25
+ └── schemas/
26
+ └── findings.json
27
+ ```
28
+
29
+ The packer recursively includes regular files below the source directory. The packer refuses symlinks, device files, FIFOs, sockets, and any other non-regular filesystem node. Directory entries are implied by file paths and are not stored in the archive.
30
+
31
+ Each workflow definition is authoritative for that workflow's execution. A `bodyFile` reference in a step or judge is relative to the directory containing that workflow YAML file. For example, `bodyFile: instructions/writer.md` in `workflows/delivery.yaml` resolves to `workflows/instructions/writer.md`. The authored `bodyFile` and the resolved archive path must both satisfy the canonical bundle path safety policy. The packer and strict archive reader apply the same rule before parsing the workflow.
32
+
33
+ ## `bundle.yaml`
34
+
35
+ The manifest is a package-only document. The manifest does not declare workers, commands, interpreters, scripts, or other execution behavior. Unknown keys, aliases, merge keys, tagged nodes, duplicate keys, non-string mapping keys, and invalid YAML are rejected.
36
+
37
+ The v2 shape is:
38
+
39
+ ```yaml
40
+ formatVersion: 2
41
+ package:
42
+ name: owenloop-delivery
43
+ version: 1.0.0
44
+ runtime:
45
+ minVersion: "0.5.1"
46
+ features:
47
+ - harness-policy-enforcement.v1
48
+ - native-judge-policy-inheritance.v1
49
+ workflows:
50
+ delivery: "workflows/delivery.yaml"
51
+ init: "workflows/init.yaml"
52
+ default: "delivery"
53
+ platforms:
54
+ - darwin-arm64
55
+ - linux-amd64
56
+ integrity:
57
+ algorithm: sha256
58
+ files:
59
+ workflows/delivery.yaml: "<64 lowercase hex characters>"
60
+ workflows/init.yaml: "<64 lowercase hex characters>"
61
+ workflows/instructions/writer.md: "<64 lowercase hex characters>"
62
+ schemas/findings.json: "<64 lowercase hex characters>"
63
+ capabilities:
64
+ commands:
65
+ - git
66
+ lock:
67
+ example/research@1.0.0: "<64 lowercase hex characters>"
68
+ ```
69
+
70
+ The following rules apply:
71
+
72
+ - `formatVersion` is exactly `2`. A v1 manifest is not accepted; there is no compatibility parser.
73
+ - `package.name` is a portable package namespace. The default store coordinate for the package is `package.name/package.name@package.version`; an explicit store namespace override may replace the first component. A workflow definition name is not the package name.
74
+ - `package.version` is a non-empty printable ASCII version string without path separators.
75
+ - `runtime` is optional. When present, `runtime` is a closed mapping that contains `minVersion`, `features`, or both; `runtime: {}` is invalid. Runtime requirements are described in [Runtime compatibility](#runtime-compatibility).
76
+ - `workflows` is a non-empty map from workflow names to archive-relative YAML paths. Each workflow name matches `/^[a-z][a-z0-9-]*$/`. Each path must pass the canonical bundle path safety policy, and two workflow names may not point to the same path.
77
+ - A workflow file's `name:` must equal the workflow map key. For example, `workflows.delivery` must point to a file containing `name: delivery`.
78
+ - An installed workflow is addressable from `calls:` by the qualified name `<package>/<workflow>`. A bare `calls: <workflow>` inside a CAS-installed bundle is resolved to a sibling from that same bundle; it does not search unrelated bundles for a same-named workflow. An exact versioned `calls: namespace/name@version` resolves through the verified store-index coordinate to the bundle's selected default workflow, then the engine checks the matching `lock` digest before creating the child.
79
+ - `default` is optional. When present, `default` must be one of the workflow map keys. When absent, a single-workflow package has that one workflow as its implicit default. A package with two or more workflows has no implicit default: the versioned coordinate is not registered as a callable target, while explicit `<package>/<workflow>` targets remain available.
80
+ - `platforms` is a duplicate-free list of portable selector strings. The list is advisory; platform policy is outside the package parser.
81
+ - `integrity.algorithm` is exactly `sha256`.
82
+ - `integrity.files` contains one lowercase 64-hex SHA-256 digest for every regular archive file except `bundle.yaml`. The packer regenerates this map from the source bytes and does not edit the source manifest. Excluding `bundle.yaml` avoids a recursive self-hash; the def digest still covers the complete canonical tar, including `bundle.yaml`.
83
+ - `capabilities` contains requested capability classes and values. The manifest does not grant capabilities.
84
+ - `lock` maps exact versioned `namespace/name@version` call references to lowercase 64-hex **bundle digests**. Every explicit versioned `calls:` target in every workflow must have a matching lock key. A bare same-bundle call has no lock entry: its pin is the containing bundle's own digest. The runtime compares bundle digests at child spawn; it does not compare this lock value with a per-workflow instruction digest.
85
+
86
+ Canonical manifest serialization uses the fixed top-level order `formatVersion`, `package`, optional `runtime`, `workflows`, optional `default`, `platforms`, `integrity`, `capabilities`, `lock`. Runtime fields use the order `minVersion`, then `features`; feature identifiers are sorted by ascending UTF-8 bytes. Other mapping keys and list values use their defined canonical order. Strings use JSON-style double quotes, indentation is two spaces, and the document has exactly one final newline. Inspection rejects a manifest that parses correctly but is not in that canonical byte form.
87
+
88
+ ## Runtime compatibility
89
+
90
+ The optional `runtime` mapping declares requirements that the Owenloop process must satisfy before Owenloop returns usable workflow definitions or instructions:
91
+
92
+ ```yaml
93
+ runtime:
94
+ minVersion: "0.5.1"
95
+ features:
96
+ - harness-policy-enforcement.v1
97
+ - native-judge-policy-inheritance.v1
98
+ ```
99
+
100
+ The mapping is strict and closed. Unknown keys are rejected. At least one of `minVersion` and `features` is required.
101
+
102
+ - `minVersion` is exactly one canonical strict SemVer value. Ranges, a leading `v`, surrounding whitespace, and non-canonical forms are invalid. Owenloop compares the running package version with standard SemVer prerelease precedence; build metadata does not affect precedence.
103
+ - `features` is a non-empty, duplicate-free sequence. Each identifier is at most 128 UTF-8 bytes and matches `/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*\.v[1-9][0-9]*$/`: lowercase portable segments ending in a positive, non-zero-padded `.vN` version.
104
+ - When both fields are present, both requirements must pass. The fields use AND semantics, not alternatives.
105
+
106
+ This Owenloop release advertises exactly these feature identifiers:
107
+
108
+ - `harness-policy-enforcement.v1`
109
+ - `native-judge-policy-inheritance.v1`
110
+
111
+ The running version comes from Owenloop's production `packageVersion()` source. A production build that cannot read a valid package version uses the `0.0.0` sentinel. The sentinel fails every declared `minVersion`, including `minVersion: "0.0.0"`, and the refusal tells the operator to install or upgrade Owenloop. The sentinel may still satisfy a feature-only declaration because feature support is evaluated independently.
112
+
113
+ Malformed runtime declarations fail with `BundleError.code === "MANIFEST_ERROR"`. A well-formed declaration that requires a newer Owenloop version or an unsupported feature fails with `BundleError.code === "RUNTIME_INCOMPATIBLE"`. Runtime-incompatible source bundles cannot be packed; runtime-incompatible packed bundles cannot be inspected, unpacked, installed, loaded as instructions, or executed. Definition listing and status discovery retain their existing fail-open behavior: they warn, skip the incompatible installed object, and continue loading unrelated definitions. Instruction and execution resolution fail closed before a command process, agent harness, or provider starts.
114
+
115
+ An absent `runtime` field preserves the previous canonical manifest bytes and bundle digest exactly. Adding, changing, or removing a present runtime declaration changes `bundle.yaml`, the canonical tar bytes, and therefore the content-addressed bundle digest. Readers that predate the runtime contract reject a present `runtime` key as an unknown top-level manifest key; authors must set requirements only when every required consumer supports this contract.
116
+
117
+ ## Canonical archive
118
+
119
+ The def digest is the lowercase SHA-256 hash of the exact **uncompressed canonical tar bytes**. The gzip bytes are a transport encoding and are not the bundle identity.
120
+
121
+ For every regular file:
122
+
123
+ - Archive paths use `/` separators and are sorted by ascending UTF-8 bytes. A backslash is rejected as a character in a canonical bundle path; the reader never treats a backslash as an alternate separator.
124
+ - Empty paths, NUL bytes, absolute paths, Windows drive paths, UNC paths, and `.` or `..` path segments are rejected.
125
+ - A regular-file path may not be a complete-segment prefix of another regular-file path. For example, one archive cannot contain both `a` and `a/b` because `a` cannot be both a regular file and a parent directory.
126
+ - The canonical `.wnlp` path policy is deliberately stricter than the GitHub archive compatibility policy used by `owenloop add`. GitHub archive handling keeps its separate compatibility rules; ordinary backslashes that policy accepts are still invalid in canonical bundle paths.
127
+ - `uid` and `gid` are `0`.
128
+ - `uname` and `gname` are empty.
129
+ - `mtime` is `0`.
130
+ - Mode is `0644`, or `0755` when any source execute bit is set. Other mode bits do not affect the output.
131
+ - Short UTF-8 paths use canonical USTAR headers.
132
+ - Paths that do not fit the USTAR name field use one deterministic POSIX PAX `path` record in a `PaxHeader` entry.
133
+ - Header fields use canonical zero-padded octal values, USTAR magic `ustar\0`, version `00`, and zeroed link, device, and prefix fields.
134
+ - Each regular archive file uses typeflag `0`.
135
+ - Every entry's data padding, including the padding after a `PaxHeader` data record, is zero-filled.
136
+ - The archive ends with exactly two zero blocks and no bytes after the terminator.
137
+
138
+ The gzip wrapper uses compression level 9 and has no optional filename, comment, or extra fields. Gzip mtime bytes are zero, and gzip header byte 9 (the OS byte) is explicitly forced to zero so Darwin and Linux produce the same bytes.
139
+
140
+ The canonical tar contains regular-file entries only. Parent directories are implied by `/`-separated file paths and are never emitted as tar entries. The strict reader rejects archive symlink, hardlink, device, FIFO, socket, directory, and unknown entry types. The packer rejects source symlinks and non-regular filesystem nodes. Absolute paths, `.` segments, and `..` traversal are refused rather than normalized.
141
+
142
+ The strict reader is as constrained as the writer. Every byte range parsed by the reader is limited to the exact form emitted by the canonical writer, including regular-file data padding and PAX-header data padding, which must be zero. This closes padding malleability: attacker-chosen bytes cannot sit inside the digest-covered tar while remaining absent from every per-file hash.
143
+
144
+ ## Reading and extraction safety
145
+
146
+ `inspectBundle` and `unpackBundle` apply bounded compressed size, expanded size, tar-header count, per-file size, and path length limits before returning or writing file data. Strict readers reject malformed checksums and octal fields, truncated headers or data, malformed or dangling PAX metadata, duplicate paths, complete-segment file-prefix collisions, backslashes, unsupported entry types, non-canonical headers, unsorted effective paths, trailing bytes, missing manifests, invalid manifests, runtime-incompatible manifests, missing or invalid workflows, unsafe workflow paths, workflow validation failures, and integrity mismatches.
147
+
148
+ `parseManifestBytes` is the common runtime-admission boundary. Source packing, packed inspection, unpacking, workflow-store installation, installed-object verification, definition discovery, instruction lookup, and worker execution all pass through that boundary before returning usable definitions or instructions.
149
+
150
+ `unpackBundle` validates the complete archive before filesystem writes. The destination must not already exist. The unpacker checks every existing destination ancestor and rejects operator-created symlinks, then writes into a fresh sibling staging directory. The staging directory is renamed into place only after all files are written; failed unpack operations remove staging and leave the destination absent.
151
+
152
+ ## Installed-object verification on read
153
+
154
+ The store's bundle ingestor verifies an installed object again every time a resolver needs its contents. The verifier safely enumerates every installed regular file, reads each file once, and preserves the existing detailed refusals for missing integrity-listed files, changed file digests, unlisted extra files, unsafe paths, symlinks, devices, FIFOs, and other wrong filesystem types.
155
+
156
+ After the per-file checks pass, the verifier reconstructs the complete canonical uncompressed tar from the installed files, including `bundle.yaml`. Installed non-executable files reconstruct as canonical mode `0644`; files with any execute bit reconstruct as `0755`. The SHA-256 digest of those canonical tar bytes must equal the object's `objects/sha256/<digest>` content address. This complete-object check covers runtime-only changes and removal of the runtime declaration even though `integrity.files` excludes `bundle.yaml` to avoid a recursive self-hash.
157
+
158
+ A store index entry records the sorted workflow names alongside the package coordinate and bundle digest. Executable definition discovery preserves each verified coordinate and fails closed on corrupt index or object state; read-only status inspection can skip damage only while reporting that its result is incomplete. Runtime instruction resolution reads the verified installed manifest and loads every listed workflow; a requested instruction digest may match any workflow in the installed object. A verification failure prevents the object from populating usable definition and instruction caches. Cache hits are re-verified, and a later failure evicts the cached object.
159
+
160
+ This check is separate from the read-only file modes applied during install. Installation maps canonical `0644` files to read-only `0444` and canonical `0755` files to read/execute-only `0555`, preserving the executable distinction needed to reconstruct identity. Changing an installed object on disk therefore produces an integrity refusal at resolution time, not a best-effort read and not an `unknown-digest` fallback.
161
+
162
+ An executable file installed by an older Owenloop release may already have lost its execute bit because older hardening mapped every regular file to `0444`. Reinstalling the exact original `.wnlp` is a supported atomic repair for that same-digest object. Owenloop first applies strict archive parsing, manifest and runtime admission, configured signature and policy verification, per-file integrity verification, and canonical digest verification to the supplied archive. Owenloop then reconstructs and completely verifies a clean staged object before replacing the broken destination through the normal journaled directory swap. The broken object's bytes are never reused. The prior object remains as the swap backup until the unchanged same-digest index state is durably committed; a failed repair restores the recoverable prior object and index state. A successful repair preserves the existing coordinate-to-digest mapping, and a later reinstall follows normal idempotent deduplication.
163
+
164
+ ## Bundle assets during execution
165
+
166
+ When a command or agent step resolves its definition from an installed bundle,
167
+ owenloop sets `OWENLOOP_BUNDLE_DIR` to the verified installed object directory.
168
+ The directory is the bundle root, so a command can reference a shipped script with
169
+ an explicit quoted path:
170
+
171
+ ```sh
172
+ node "$OWENLOOP_BUNDLE_DIR/scripts/provision.mjs"
173
+ ```
174
+
175
+ owenloop sets `OWENLOOP_BUNDLE_DIR` only for definitions with installed-bundle
176
+ provenance. A definition without bundle provenance receives no value. Bundle
177
+ scripts must treat an unset or empty variable as a hard error and report a
178
+ message such as `this workflow must run from an installed bundle`; owenloop does
179
+ not synthesize a fallback directory.
180
+
181
+ Command and agent children receive two engine-derived identity variables:
182
+ `OWENLOOP_WORKFLOW` contains the workflow-instance id, and `OWENLOOP_RUN`
183
+ contains the run id. Both variables are always set, including for definitions
184
+ without bundle provenance. A command can read them directly:
185
+
186
+ ```sh
187
+ printf '%s %s\n' "$OWENLOOP_WORKFLOW" "$OWENLOOP_RUN"
188
+ ```
189
+
190
+ For agent children, admitting a name to `ADMITTED_OWENLOOP_KEYS` is only a
191
+ filter permission: `filterOwenloopEnv` permits an existing value through, but
192
+ does not make that value authoritative. `agent-run` sets both variables from
193
+ the worker's own engine-derived target before starting the child and overwrites
194
+ ambient values, so a nested agent receives its own identity rather than a
195
+ stale parent value.
196
+
197
+ Run identity is safe to expose because the engine derives it from the worker's
198
+ own `--order` argument. Consumed artifact values are attacker-influenceable and
199
+ are not exposed, and command text is not interpolated; no consume-side gate
200
+ exists for either capability.
201
+
202
+ `OWENLOOP_BUNDLE_DIR` is read-only. Workers must never write into the directory.
203
+ The workflow store is content-addressed and verifies the installed object again
204
+ when a resolver reads it. A write changes the object bytes, so the next read
205
+ fails the digest or file-integrity check instead of executing the modified
206
+ bundle. Mount or copy enforcement is not part of the current contract;
207
+ documentation is the enforcement boundary for now.
208
+
209
+ ## API results
210
+
211
+ `packBundle(sourceDir)` returns:
212
+
213
+ - `bytes`: the complete gzip-compressed `.wnlp` file;
214
+ - `digest`: the canonical uncompressed-tar digest;
215
+ - `manifest`: the canonical manifest archived in `bytes`; and
216
+ - `entries`: sorted path, size, executable-bit, and per-file digest metadata.
217
+
218
+ `inspectBundle(bytes)` returns the digest, runtime-admitted validated manifest, and entry metadata without writing files. `unpackBundle(bytes, destination)` returns the same inspection result plus the absolute materialized destination path.
219
+
220
+ `digestBundle(bytes)` is the deliberate identity-only exception to runtime admission. The function enforces the compressed and expanded size limits, inflates the gzip payload, and hashes the exact decompressed bytes. The function does not parse or validate a canonical tar and does not parse `bundle.yaml`; therefore `digestBundle` can return a digest for bounded gzip content that is not an admissible bundle, including an archive whose runtime declaration the current Owenloop process cannot satisfy. A successful digest does not mean the content is a canonical tar or that the bundle is admissible for packing, inspection, unpacking, installation, definition loading, instruction lookup, or execution.
221
+
222
+ `owenloop publish` signs exactly `packBundle(sourceDir).digest`: the lowercase 64-hex SHA-256 digest of the uncompressed canonical tar. It does not sign the gzip wrapper bytes or the separate compiled-definition hash used by `push`.
223
+
224
+ All bundle failures are `BundleError` instances with a stable `code` suitable for scripts. The CLI keeps that code in the stderr diagnostic.
225
+
226
+ ## Limits
227
+
228
+ The default shared archive limits are:
229
+
230
+ | limit | default |
231
+ |---|---:|
232
+ | compressed input | 256 MiB |
233
+ | expanded tar | 1 GiB |
234
+ | tar headers | 50,000 |
235
+ | one regular file | 100 MiB |
236
+ | one path | 1,024 characters |
237
+
238
+ The in-process APIs accept `limits` overrides through `PackOptions` or `InspectOptions`. Limits apply before archive data is copied or extracted.
239
+
240
+ ## Verification example
241
+
242
+ A package can be inspected with both owenloop and a stock tar implementation:
243
+
244
+ ```sh
245
+ owenloop bundle inspect ./report-1.2.0.wnlp
246
+ owenloop bundle digest ./report-1.2.0.wnlp
247
+ tar -tzf ./report-1.2.0.wnlp
248
+ ```
249
+
250
+ The digest printed by `owenloop bundle digest` is stable across gzip metadata, operating-system, and filesystem timestamp differences when the canonical file bytes and executable-bit choices are unchanged. CI recomputes a checked-in golden vector on both Ubuntu and macOS to guard this cross-platform stability.