owenloop 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (229) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +144 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +29 -4
  5. package/dist/packages/work/src/agent/brief.js +49 -4
  6. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  7. package/dist/packages/work/src/agent/capability-model.js +148 -0
  8. package/dist/packages/work/src/agent/loop.d.ts +56 -7
  9. package/dist/packages/work/src/agent/loop.js +166 -9
  10. package/dist/packages/work/src/bundle/cache.d.ts +7 -5
  11. package/dist/packages/work/src/bundle/cache.js +20 -6
  12. package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
  13. package/dist/packages/work/src/bundle/fetch.js +27 -7
  14. package/dist/packages/work/src/bundle/types.d.ts +8 -4
  15. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  16. package/dist/packages/work/src/consumed-verifier.js +205 -0
  17. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  18. package/dist/packages/work/src/exec/instructions.js +323 -0
  19. package/dist/packages/work/src/exec/loop.d.ts +29 -1
  20. package/dist/packages/work/src/exec/loop.js +313 -35
  21. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  22. package/dist/packages/work/src/exec/payload.js +54 -0
  23. package/dist/packages/work/src/exec/receipt.d.ts +9 -6
  24. package/dist/packages/work/src/exec/receipt.js +12 -1
  25. package/dist/packages/work/src/exec/runner.d.ts +7 -1
  26. package/dist/packages/work/src/exec/runner.js +84 -3
  27. package/dist/packages/work/src/harness/child-env.js +7 -0
  28. package/dist/packages/work/src/harness/claude.d.ts +20 -8
  29. package/dist/packages/work/src/harness/claude.js +260 -58
  30. package/dist/packages/work/src/harness/codex.d.ts +5 -4
  31. package/dist/packages/work/src/harness/codex.js +169 -41
  32. package/dist/packages/work/src/harness/contract.d.ts +36 -11
  33. package/dist/packages/work/src/harness/fake.js +1 -0
  34. package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
  35. package/dist/packages/work/src/harness/permissions.d.ts +16 -3
  36. package/dist/packages/work/src/harness/permissions.js +102 -13
  37. package/dist/packages/work/src/harness/session-store.d.ts +30 -10
  38. package/dist/packages/work/src/harness/session-store.js +317 -89
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +134 -12
  41. package/dist/packages/work/src/hub/client.d.ts +8 -1
  42. package/dist/packages/work/src/hub/client.js +15 -1
  43. package/dist/packages/work/src/hub/types.d.ts +137 -33
  44. package/dist/packages/work/src/hub/types.js +8 -10
  45. package/dist/packages/work/src/mcp/server.js +1 -1
  46. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  47. package/dist/packages/work/src/owenloop-bin.js +18 -0
  48. package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
  49. package/dist/packages/work/src/roles/agent-run.js +115 -34
  50. package/dist/packages/work/src/roles/exec.d.ts +8 -0
  51. package/dist/packages/work/src/roles/exec.js +27 -2
  52. package/dist/packages/work/src/roles/hold.d.ts +6 -0
  53. package/dist/packages/work/src/roles/hold.js +83 -13
  54. package/dist/packages/work/src/roles/lint.d.ts +3 -4
  55. package/dist/packages/work/src/roles/lint.js +41 -7
  56. package/dist/packages/work/src/roles/settings.js +19 -2
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +36 -2
  59. package/dist/packages/work/src/settings/settings.d.ts +70 -1
  60. package/dist/packages/work/src/settings/settings.js +90 -4
  61. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  62. package/dist/packages/work/src/shift/logretention.js +407 -0
  63. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  64. package/dist/packages/work/src/shift/logsink.js +98 -0
  65. package/dist/packages/work/src/shift/loop.d.ts +32 -4
  66. package/dist/packages/work/src/shift/loop.js +687 -166
  67. package/dist/packages/work/src/shift/protocol.d.ts +128 -1
  68. package/dist/packages/work/src/shift/protocol.js +14 -0
  69. package/dist/packages/work/src/shift/runtime.d.ts +16 -0
  70. package/dist/packages/work/src/shift/runtime.js +291 -5
  71. package/dist/packages/work/src/shift/server.d.ts +13 -0
  72. package/dist/packages/work/src/shift/server.js +61 -36
  73. package/dist/packages/work/src/shift/spawn.d.ts +115 -19
  74. package/dist/packages/work/src/shift/spawn.js +234 -30
  75. package/dist/packages/work/src/shift/state.d.ts +76 -49
  76. package/dist/packages/work/src/shift/state.js +350 -103
  77. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  78. package/dist/packages/work/src/shift/truncate.js +73 -0
  79. package/dist/packages/work/src/submit-proof.d.ts +61 -0
  80. package/dist/packages/work/src/submit-proof.js +119 -0
  81. package/dist/packages/work/src/submit-value.d.ts +48 -0
  82. package/dist/packages/work/src/submit-value.js +118 -0
  83. package/dist/packages/work/src/usage.d.ts +1 -1
  84. package/dist/packages/work/src/usage.js +11 -0
  85. package/dist/src/add.d.ts +64 -259
  86. package/dist/src/add.js +81 -615
  87. package/dist/src/archive.d.ts +97 -0
  88. package/dist/src/archive.js +591 -0
  89. package/dist/src/bundle/index.d.ts +64 -0
  90. package/dist/src/bundle/index.js +508 -0
  91. package/dist/src/bundle/manifest.d.ts +50 -0
  92. package/dist/src/bundle/manifest.js +435 -0
  93. package/dist/src/bundle/runtime.d.ts +26 -0
  94. package/dist/src/bundle/runtime.js +64 -0
  95. package/dist/src/bundle/tar.d.ts +62 -0
  96. package/dist/src/bundle/tar.js +238 -0
  97. package/dist/src/bundle/types.d.ts +105 -0
  98. package/dist/src/bundle/types.js +21 -0
  99. package/dist/src/capabilities.d.ts +93 -0
  100. package/dist/src/capabilities.js +101 -0
  101. package/dist/src/cli.d.ts +90 -20
  102. package/dist/src/cli.js +2421 -374
  103. package/dist/src/credentials.d.ts +4 -3
  104. package/dist/src/credentials.js +21 -19
  105. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  106. package/dist/src/crypto/allowed-signers.js +307 -0
  107. package/dist/src/crypto/canonical.d.ts +8 -0
  108. package/dist/src/crypto/canonical.js +92 -0
  109. package/dist/src/crypto/chain.d.ts +65 -0
  110. package/dist/src/crypto/chain.js +377 -0
  111. package/dist/src/crypto/dsse.d.ts +209 -0
  112. package/dist/src/crypto/dsse.js +282 -0
  113. package/dist/src/crypto/enrollment.d.ts +78 -0
  114. package/dist/src/crypto/enrollment.js +186 -0
  115. package/dist/src/crypto/index.d.ts +48 -0
  116. package/dist/src/crypto/index.js +44 -0
  117. package/dist/src/crypto/keys.d.ts +258 -0
  118. package/dist/src/crypto/keys.js +908 -0
  119. package/dist/src/crypto/org-root.d.ts +33 -0
  120. package/dist/src/crypto/org-root.js +78 -0
  121. package/dist/src/crypto/origin-rules.d.ts +56 -0
  122. package/dist/src/crypto/origin-rules.js +143 -0
  123. package/dist/src/crypto/policy-floor.d.ts +98 -0
  124. package/dist/src/crypto/policy-floor.js +353 -0
  125. package/dist/src/crypto/records.d.ts +319 -0
  126. package/dist/src/crypto/records.js +168 -0
  127. package/dist/src/crypto/scope.d.ts +49 -0
  128. package/dist/src/crypto/scope.js +83 -0
  129. package/dist/src/crypto/ssh.d.ts +171 -0
  130. package/dist/src/crypto/ssh.js +396 -0
  131. package/dist/src/crypto/submission.d.ts +33 -0
  132. package/dist/src/crypto/submission.js +47 -0
  133. package/dist/src/crypto/trust-roots.d.ts +29 -0
  134. package/dist/src/crypto/trust-roots.js +39 -0
  135. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  136. package/dist/src/crypto/verify-consumed.js +259 -0
  137. package/dist/src/crypto/verify-origin.d.ts +50 -0
  138. package/dist/src/crypto/verify-origin.js +151 -0
  139. package/dist/src/crypto/verify-publication.d.ts +60 -0
  140. package/dist/src/crypto/verify-publication.js +150 -0
  141. package/dist/src/defs.d.ts +24 -1
  142. package/dist/src/defs.js +335 -27
  143. package/dist/src/engine.d.ts +211 -6
  144. package/dist/src/engine.js +459 -59
  145. package/dist/src/factory.d.ts +16 -0
  146. package/dist/src/factory.js +16 -4
  147. package/dist/src/global-config.d.ts +59 -0
  148. package/dist/src/global-config.js +84 -0
  149. package/dist/src/hub.d.ts +102 -32
  150. package/dist/src/hub.js +147 -58
  151. package/dist/src/index.d.ts +19 -2
  152. package/dist/src/index.js +23 -2
  153. package/dist/src/install.d.ts +538 -0
  154. package/dist/src/install.js +1981 -0
  155. package/dist/src/lock.d.ts +15 -57
  156. package/dist/src/lock.js +251 -143
  157. package/dist/src/mcp/serve.d.ts +46 -22
  158. package/dist/src/mcp/serve.js +174 -44
  159. package/dist/src/mcp/server.js +12 -1
  160. package/dist/src/model.d.ts +51 -0
  161. package/dist/src/model.js +157 -1
  162. package/dist/src/order-resolver.d.ts +184 -0
  163. package/dist/src/order-resolver.js +252 -0
  164. package/dist/src/package-version.d.ts +10 -0
  165. package/dist/src/package-version.js +42 -0
  166. package/dist/src/paths.d.ts +14 -1
  167. package/dist/src/paths.js +18 -0
  168. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  169. package/dist/src/schemas/index.d.ts +1433 -0
  170. package/dist/src/schemas/index.js +31 -0
  171. package/dist/src/schemas/order.v1.schema.json +120 -0
  172. package/dist/src/schemas/origin.v1.schema.json +68 -0
  173. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  174. package/dist/src/schemas/publication.v1.schema.json +31 -0
  175. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  176. package/dist/src/schemas/submission.v1.schema.json +61 -0
  177. package/dist/src/store/def-source.d.ts +52 -0
  178. package/dist/src/store/def-source.js +335 -0
  179. package/dist/src/store/index-file.d.ts +69 -0
  180. package/dist/src/store/index-file.js +151 -0
  181. package/dist/src/store/index.d.ts +27 -0
  182. package/dist/src/store/index.js +22 -0
  183. package/dist/src/store/ingestor.d.ts +43 -0
  184. package/dist/src/store/ingestor.js +211 -0
  185. package/dist/src/store/install.d.ts +228 -0
  186. package/dist/src/store/install.js +555 -0
  187. package/dist/src/store/instruction-source.d.ts +49 -0
  188. package/dist/src/store/instruction-source.js +298 -0
  189. package/dist/src/store/origin-evidence.d.ts +21 -0
  190. package/dist/src/store/origin-evidence.js +66 -0
  191. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  192. package/dist/src/store/pre-commit-verifier.js +418 -0
  193. package/dist/src/store/resolve.d.ts +138 -0
  194. package/dist/src/store/resolve.js +363 -0
  195. package/dist/src/store/types.d.ts +288 -0
  196. package/dist/src/store/types.js +356 -0
  197. package/dist/src/store.d.ts +33 -1
  198. package/dist/src/store.js +57 -4
  199. package/dist/src/types.d.ts +146 -12
  200. package/dist/src/untar.d.ts +8 -23
  201. package/dist/src/untar.js +10 -136
  202. package/docs/agent-runner.md +86 -0
  203. package/docs/authoring.md +64 -6
  204. package/docs/bundles.md +350 -0
  205. package/docs/cli.md +1298 -106
  206. package/docs/crypto.md +832 -0
  207. package/docs/design.md +342 -20
  208. package/docs/embedding.md +132 -25
  209. package/docs/shift-logs.md +642 -0
  210. package/docs/wire-contracts.md +395 -0
  211. package/package.json +6 -1
  212. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  213. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  214. package/plugins/claude-code/plugin/.mcp.json +14 -0
  215. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  216. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  217. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  218. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  219. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  220. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  221. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  222. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  223. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  224. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  225. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  226. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  227. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  228. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  229. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
@@ -11,16 +11,21 @@
11
11
  * claims survive a session drain). The loop's first `get_order` beats the
12
12
  * lease and delivers the order packet via `onOrder`; the loop then keeps the
13
13
  * lease warm underneath everything below.
14
- * 2. VALIDATE — a `null` packet, a missing/blank `command`, a non-`command`
15
- * executor, or a missing/empty `owes` is a MISROUTE (plan decision 3): not exec's to
16
- * fail (a Step Agent could legitimately run it), so a targeted release, no
17
- * submit, exit 1.
14
+ * 2. VALIDATE — a `null` packet, a non-`command` worker, or a missing/empty
15
+ * `owes` list is a MISROUTE (plan decision 3): not exec's to fail (a Step
16
+ * Agent could legitimately run it), so a targeted release, no submit, exit 1.
17
+ * A command worker's `defDigest` is then resolved through the verified local
18
+ * workflow store. Missing or corrupt instructions are a named refusal, not a
19
+ * misroute, and no child process is started.
18
20
  * 3. RUN + RACE — the runner shells the command out while the lease loop runs.
19
21
  * Whichever settles first wins (plan decision 9):
20
- * - command settles (any exit code, or a machinery error) ⇒ build a
21
- * receipt and `submit` it to every owed path, then stop the lease
22
- * WITHOUT release (the run just closed). Exit 0 — delivering the receipt
23
- * IS the job, even for a failing command (the exit code carries truth).
22
+ * - an ordinary command settles (any exit code, or a machinery error) ⇒
23
+ * build a receipt and `submit` it to every owed path. A payload reject
24
+ * follows those submits. Exit 0 means the receipt/reject delivery won;
25
+ * the receipt's exit code still carries the command result.
26
+ * - a judge command exits 0 ⇒ submit its receipt; a non-zero exit ⇒ send
27
+ * `reject` for `order.judge` without a receipt; signal or machinery
28
+ * failure ⇒ no verdict, leave the claim for the reap path.
24
29
  * - lease goes terminal first (lease-lost / ownership-error / unreachable /
25
30
  * the engine closed the run) ⇒ kill the command's process group, NO
26
31
  * submit (a submit would race the re-offer), exit 1.
@@ -34,13 +39,117 @@
34
39
  * The role (`src/roles/exec.ts`) maps each `ExecOutcome` to an exit code.
35
40
  */
36
41
  import { createHash } from 'node:crypto';
42
+ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
43
+ import { tmpdir } from 'node:os';
44
+ import { join, resolve } from 'node:path';
37
45
  import { createLeaseLoop } from "../lease/loop.js";
46
+ import { parsePayloadLine } from "./payload.js";
38
47
  import { buildReceipt } from "./receipt.js";
48
+ import { buildSubmitProof } from "../submit-proof.js";
39
49
  /** sha256 of the empty byte string — the hash for a run with no captured output. */
40
50
  const EMPTY_HASH = createHash('sha256').digest('hex');
51
+ /**
52
+ * The largest serialized `consumes` payload delivered inline in
53
+ * `OWENLOOP_CONSUMES`; anything strictly larger goes to a file named by
54
+ * `OWENLOOP_CONSUMES_FILE`. Measured with `Buffer.byteLength(json, 'utf8')` —
55
+ * never `json.length`, which counts UTF-16 code units and under-reports every
56
+ * multi-byte character.
57
+ *
58
+ * 64 KiB, chosen against the binding OS limit rather than a round number:
59
+ * Linux `execve` enforces `MAX_ARG_STRLEN`, a hard PER-ENTRY cap of 131072
60
+ * bytes (32 × 4 KiB pages) independent of the total `ARG_MAX`; macOS has no
61
+ * per-entry cap but shares ~1 MB of `ARG_MAX` across argv AND the whole
62
+ * environment block, and the child environment here starts from a full
63
+ * inherited `process.env`. 64 KiB clears the Linux per-entry cap with room for
64
+ * the `OWENLOOP_CONSUMES=` prefix and leaves the rest of the macOS budget to
65
+ * the inherited block.
66
+ */
67
+ export const CONSUMES_INLINE_MAX_BYTES = 65_536;
41
68
  function errMsg(e) {
42
69
  return e instanceof Error ? e.message : String(e);
43
70
  }
71
+ /**
72
+ * Put the order's consumed inputs on `childEnv`, and return the temp DIRECTORY
73
+ * holding the overflow file — or `undefined` when the payload went inline.
74
+ *
75
+ * The contract a command script sees, and the reason it is two variables:
76
+ *
77
+ * - `OWENLOOP_CONSUMES` carries `JSON.stringify(order.consumes ?? {})`
78
+ * verbatim whenever that fits within `CONSUMES_INLINE_MAX_BYTES`. It is set
79
+ * even when there are no consumed inputs — the value is then `{}`, not an
80
+ * absent variable.
81
+ * - `OWENLOOP_CONSUMES_FILE` names a `0600` UTF-8 file holding that same JSON
82
+ * when it does not fit.
83
+ *
84
+ * Exactly ONE of the two is present on any spawn, because this function always
85
+ * assigns one and `delete`s the other. That mutual exclusion is what lets the
86
+ * presence of `OWENLOOP_CONSUMES_FILE` act as the discriminator with no third
87
+ * "mode" variable, and it is required anyway by the collision rule below.
88
+ *
89
+ * COLLISION RULE (the same reasoning as `OWENLOOP_WORKFLOW`/`OWENLOOP_RUN` at
90
+ * the spawn site): `childEnv` starts from `process.env`, and a shift can itself
91
+ * have been launched from inside another command step, so both names may
92
+ * already carry the PARENT order's values — a stale inputs object in the inline
93
+ * case, and in the file case a path whose directory has already been removed.
94
+ * Neither name is ever conditionally assigned.
95
+ *
96
+ * The JSON is the raw `order.consumes` object with no envelope, so a command
97
+ * script and an agent step see the identical shape. Key omission is preserved:
98
+ * an input that was declared but never produced is ABSENT from the object, not
99
+ * present as `null`, and a script tests for it with `'key' in consumes`.
100
+ */
101
+ function deliverConsumes(childEnv, consumes) {
102
+ // `order.consumes` arrives JSON-decoded off the wire, so there is no
103
+ // realistic cycle or BigInt to throw on. The throw is still surfaced rather
104
+ // than swallowed: leaving the variable unset would push a script back onto
105
+ // deriving its context from its cwd — the exact failure this delivery exists
106
+ // to remove — so the caller turns it into a machinery failure and no child is
107
+ // spawned.
108
+ let json;
109
+ try {
110
+ json = JSON.stringify(consumes ?? {});
111
+ }
112
+ catch (e) {
113
+ throw new Error(`cannot serialize the order's consumed inputs for OWENLOOP_CONSUMES: ${errMsg(e)}`);
114
+ }
115
+ if (Buffer.byteLength(json, 'utf8') <= CONSUMES_INLINE_MAX_BYTES) {
116
+ childEnv['OWENLOOP_CONSUMES'] = json;
117
+ delete childEnv['OWENLOOP_CONSUMES_FILE'];
118
+ return undefined;
119
+ }
120
+ // `mkdtempSync` rather than a composed run/step/random filename: several
121
+ // shifts run concurrently on one machine, and this gives a collision-free
122
+ // `0700` directory without owning a naming scheme. The file is `0600`
123
+ // because its content is agent-produced artifact data.
124
+ const dir = mkdtempSync(join(tmpdir(), 'owenloop-consumes-'));
125
+ try {
126
+ const file = join(dir, 'consumes.json');
127
+ writeFileSync(file, json, { encoding: 'utf8', mode: 0o600 });
128
+ childEnv['OWENLOOP_CONSUMES_FILE'] = file;
129
+ delete childEnv['OWENLOOP_CONSUMES'];
130
+ return dir;
131
+ }
132
+ catch (e) {
133
+ // The directory exists but the caller will never learn its path, so remove
134
+ // it here rather than leaking it; the caller's `finally` only covers a
135
+ // directory this function returned.
136
+ removeConsumesDir(dir);
137
+ throw e;
138
+ }
139
+ }
140
+ /** Best-effort removal of an overflow directory; a cleanup failure never fails a step. */
141
+ function removeConsumesDir(dir) {
142
+ if (dir === undefined)
143
+ return;
144
+ try {
145
+ rmSync(dir, { recursive: true, force: true });
146
+ }
147
+ catch {
148
+ // Swallowed on purpose: the child has already exited and its receipt is
149
+ // authoritative. A temp-directory that outlives the run is a tidiness
150
+ // problem, not a result.
151
+ }
152
+ }
44
153
  export function createExecLoop(opts) {
45
154
  const { hub, runner, workflow } = opts;
46
155
  const runId = opts.run;
@@ -109,8 +218,33 @@ export function createExecLoop(opts) {
109
218
  return 'hub-unreachable';
110
219
  return 'lease-lost';
111
220
  }
221
+ /** Deliver one reject verb and settle the lease after the response arrives. */
222
+ async function issueReject(path, text, successOutcome) {
223
+ try {
224
+ const res = await hub.reject({ workflow, run: runId, path, text });
225
+ if (res.ok !== true) {
226
+ opts.err(`owenloop work exec: reject of ${path} was refused: ${res.text}`);
227
+ lease.stop('reject-failed', res.closed === true ? { release: false } : undefined);
228
+ await leasePromise;
229
+ return 'reject-failed';
230
+ }
231
+ // A closed response means the hub already ended the claiming run. For a
232
+ // non-closed reject, release the still-open claim before this worker exits.
233
+ lease.stop(successOutcome, res.closed === true ? { release: false } : undefined);
234
+ await leasePromise;
235
+ return successOutcome;
236
+ }
237
+ catch (e) {
238
+ opts.err(`owenloop work exec: reject of ${path} failed: ${errMsg(e)}`);
239
+ // Receipts, when any, are already committed. Do not retry blindly or
240
+ // pretend the reject landed.
241
+ lease.stop('reject-failed');
242
+ await leasePromise;
243
+ return 'reject-failed';
244
+ }
245
+ }
112
246
  /** Build the receipt and submit it to every owed path. */
113
- async function submitReceipt(result, order) {
247
+ async function submitReceipt(result, order, resolvedCommand) {
114
248
  if (signalled) {
115
249
  // The operator killed the work and the command settled before the lease
116
250
  // (the release HTTP round-trip is slower than a TERM'd child dying), so
@@ -121,17 +255,65 @@ export function createExecLoop(opts) {
121
255
  await leasePromise;
122
256
  return 'killed';
123
257
  }
258
+ const parsedPayload = parsePayloadLine(result.payloadLine, result.payloadOverCap);
259
+ if (order.judge !== undefined) {
260
+ if (result.exitCode === null) {
261
+ // A signal or machinery failure is not a verdict. Leave the claim for
262
+ // the engine's reap path rather than releasing a silent judgement.
263
+ opts.err(`owenloop work exec: judge ${order.judge} ended without a verdict`);
264
+ lease.stop('judge-no-verdict', { release: false });
265
+ await leasePromise;
266
+ return 'judge-no-verdict';
267
+ }
268
+ if (result.exitCode !== 0) {
269
+ // Judge payload directives are deliberately ignored: one judge order
270
+ // has one verdict, and the command exit code supplies that verdict.
271
+ let text = result.outputTail;
272
+ if (parsedPayload.payload !== undefined && typeof parsedPayload.payload === 'object' && parsedPayload.payload !== null && !Array.isArray(parsedPayload.payload)) {
273
+ const reason = parsedPayload.payload['reason'];
274
+ if (typeof reason === 'string' && reason.trim() !== '')
275
+ text = reason;
276
+ }
277
+ if (text === '')
278
+ text = `judge command exited with code ${result.exitCode}`;
279
+ return issueReject(order.judge, text, 'judge-rejected');
280
+ }
281
+ }
124
282
  const receipt = buildReceipt(result, {
125
- command: order.command ?? '',
283
+ command: resolvedCommand,
126
284
  orchestrator: opts.holder.id,
127
285
  workflow,
128
286
  run: runId,
129
287
  step: order.step,
130
- });
288
+ }, parsedPayload);
131
289
  for (const owe of order.owes) {
132
290
  let res;
133
291
  try {
134
- res = await hub.submit({ workflow, run: runId, path: owe.path, value: receipt, holder: opts.holder });
292
+ let proof;
293
+ if (opts.origin !== undefined) {
294
+ // The immutable order can authorize a judge proof only when the owed
295
+ // path is the fingerprinted judged artifact. Producer command receipts
296
+ // remain unsigned until the hub issues a retry-safe target version.
297
+ proof = await buildSubmitProof({
298
+ origin: opts.origin,
299
+ order,
300
+ path: owe.path,
301
+ value: receipt,
302
+ now: opts.now,
303
+ warn: opts.err,
304
+ ...(opts.principalKeys !== undefined ? { principalKeys: opts.principalKeys } : {}),
305
+ ...(opts.env !== undefined ? { env: opts.env } : {}),
306
+ ...(opts.sshProcess !== undefined ? { sshProcess: opts.sshProcess } : {}),
307
+ });
308
+ }
309
+ res = await hub.submit({
310
+ workflow,
311
+ run: runId,
312
+ path: owe.path,
313
+ value: receipt,
314
+ ...(proof !== undefined ? { proof } : {}),
315
+ holder: opts.holder,
316
+ });
135
317
  }
136
318
  catch (e) {
137
319
  opts.err(`owenloop work exec: submit to ${owe.path} failed: ${errMsg(e)}`);
@@ -150,6 +332,12 @@ export function createExecLoop(opts) {
150
332
  }
151
333
  opts.out(`owenloop work exec: submitted receipt to ${owe.path} (${outcome})`);
152
334
  }
335
+ if (order.judge === undefined && parsedPayload.reject !== undefined) {
336
+ // All owed submissions must land before invalidating a consumed input;
337
+ // rejection moves the consume fingerprint and would born-reject later
338
+ // submits from this run.
339
+ return issueReject(parsedPayload.reject.path, parsedPayload.reject.text, 'rejected');
340
+ }
153
341
  // Every owed path landed — the run has closed, so stop WITHOUT releasing.
154
342
  lease.stop('submitted', { release: false });
155
343
  await leasePromise;
@@ -166,42 +354,132 @@ export function createExecLoop(opts) {
166
354
  if (first.t === 'lease')
167
355
  return mapNoHold(first.o);
168
356
  const order = first.res.order;
169
- const command = order?.command;
170
357
  if (order === null ||
171
- typeof command !== 'string' ||
172
- command === '' ||
173
- (order.executor !== undefined && order.executor !== 'command') ||
358
+ order.worker !== 'command' ||
174
359
  !Array.isArray(order.owes) ||
175
360
  order.owes.length === 0) {
176
- opts.err(`owenloop work exec: ${workflow}/${runId} is not a runnable command order (misroute) — releasing`);
361
+ opts.err(`owenloop work exec: ${workflow}/${runId} is not a command order (misroute) — releasing`);
177
362
  lease.stop('misroute'); // targeted release — not exec's to fail
178
363
  await leasePromise;
179
364
  return 'misroute';
180
365
  }
181
- // Run the command and race it against the lease going terminal.
182
- let cmd;
366
+ let resolvedCommand;
367
+ let resolvedBundleDir;
183
368
  try {
184
- cmd = runner.start(command, { cwd: order.workdir ?? opts.cwd });
369
+ const resolved = await opts.instructions.resolveCommand(order);
370
+ if (!resolved.ok) {
371
+ opts.err(`owenloop work exec: ${resolved.reason}`);
372
+ lease.stop('unresolved-instructions');
373
+ await leasePromise;
374
+ return 'unresolved-instructions';
375
+ }
376
+ resolvedCommand = resolved.command;
377
+ resolvedBundleDir = resolved.bundleDir;
185
378
  }
186
379
  catch (e) {
187
- return submitReceipt(machineryFailure(e), order);
380
+ opts.err(`owenloop work exec: instruction refusal (integrity) for ${workflow}/${runId} ` +
381
+ `defDigest '${order.defDigest}': ${errMsg(e)}`);
382
+ lease.stop('unresolved-instructions');
383
+ await leasePromise;
384
+ return 'unresolved-instructions';
188
385
  }
189
- running = cmd;
190
- opts.out(`owenloop work exec: running ${workflow}/${runId} (step '${order.step}')`);
191
- const outcome = await Promise.race([
192
- cmd.done.then((r) => ({ t: 'done', r })).catch((e) => ({ t: 'done', r: machineryFailure(e) })),
193
- leasePromise.then((o) => ({ t: 'lease', o })),
194
- ]);
195
- if (outcome.t === 'lease') {
196
- await cmd.kill(); // no receipt — a submit now would race the re-offer
197
- if (signalled) {
198
- opts.err(`owenloop work exec: signalled mid-run — killed the command group, released ${workflow}/${runId}`);
199
- return 'killed';
386
+ // Run the command and race it against the lease going terminal.
387
+ // `consumesDir` holds the OWENLOOP_CONSUMES_FILE overflow directory when
388
+ // the serialized inputs did not fit inline. The `finally` below removes it
389
+ // on every path out of this block, including a spawn that threw.
390
+ //
391
+ // On the RECEIPT path the removal follows the child's exit, because a
392
+ // script may read the file late in its run. On the LEASE-TERMINAL path it
393
+ // does not: `cmd.kill()` (see `exec/runner.ts`) posts SIGTERM, races `done`
394
+ // against the grace timer, then posts SIGKILL and returns WITHOUT awaiting
395
+ // `done`, so this unlink can precede full reaping of the killed process
396
+ // group. That is deliberate and harmless — the run is abandoned and submits
397
+ // no receipt — but it is not a guarantee to build on. Do not add work here
398
+ // that assumes the child is gone.
399
+ let consumesDir;
400
+ try {
401
+ let cmd;
402
+ try {
403
+ // spawn's env replaces the child environment. Start from the actual exec
404
+ // process environment so config-only opts.env cannot strip PATH/HOME, then
405
+ // explicitly remove bundle provenance for loose definitions.
406
+ const childEnv = { ...process.env };
407
+ if (resolvedBundleDir === undefined)
408
+ delete childEnv['OWENLOOP_BUNDLE_DIR'];
409
+ else
410
+ childEnv['OWENLOOP_BUNDLE_DIR'] = resolvedBundleDir;
411
+ // Run identity is engine-derived from ExecLoopOptions, never a consumed
412
+ // artifact value, and always present. The consumed inputs that follow ARE
413
+ // artifact values, and they are admitted here only because
414
+ // `resolveCommand` above already ran the consume-side verification gate
415
+ // (`hardRule: true`) and refused the order outright on absent,
416
+ // unverifiable, or invalid evidence. They travel in the environment
417
+ // block and nowhere else — never in argv and never in the command text,
418
+ // which is returned verbatim from the verified store and is not
419
+ // interpolated. All four names below overwrite inherited values so a
420
+ // nested exec sees its own order rather than its parent's.
421
+ childEnv['OWENLOOP_WORKFLOW'] = workflow;
422
+ childEnv['OWENLOOP_RUN'] = runId;
423
+ consumesDir = deliverConsumes(childEnv, order.consumes);
424
+ // The order carries no workdir when the step declared neither `workdir:`
425
+ // nor `workdirFrom:` (the hub resolves `workdirFrom` and ships the
426
+ // result, so an absent field IS that signal). Substituting the shift's
427
+ // launch directory silently is how a run ends up operating on an
428
+ // unintended tree with nothing in the output saying so, hence the
429
+ // record. It stays a WARNING: `provisioner` creates the worktree its
430
+ // successors use and `deprovisioner` deletes its own, so both
431
+ // legitimately have no workdir to resolve, and a throw here would break
432
+ // every delivery run the moment it shipped.
433
+ //
434
+ // WHERE THIS LINE ACTUALLY GOES. `opts.err` is this process's stderr.
435
+ // Run by hand, that is the operator's terminal. Dispatched by
436
+ // `owenloop shift start`, `createDefaultSpawner` (`src/shift/spawn.ts`)
437
+ // now attaches fd 1 and fd 2 to `<log-dir>/<run>.log`, so this warning
438
+ // is on disk under the run id it belongs to and outlives both the
439
+ // worker and the shift. See `docs/shift-logs.md`.
440
+ //
441
+ // It was previously discarded: every worker launched with
442
+ // `stdio: ['ignore','ignore','ignore']`, so a shift-dispatched exec
443
+ // wrote this line to `/dev/null`. That was the blocker on turning this
444
+ // warning into a throw — an unseen warning is not a migration notice.
445
+ // The delivery half is now done; the enforcement release is still a
446
+ // separate decision. `docs/bundles.md` ("Working directory for command
447
+ // steps") tracks the same state for bundle authors.
448
+ //
449
+ // The RECEIPT still does not carry it: the receipt captures the
450
+ // *command's* streams, and this line is the exec worker's own.
451
+ const cwd = order.workdir ?? opts.cwd;
452
+ if (order.workdir === undefined) {
453
+ opts.err(`owenloop work exec: step '${order.step}' (${workflow}/${runId}) declared neither workdir nor ` +
454
+ `workdirFrom — inheriting the shift launch directory '${resolve(cwd)}' as the command's cwd. ` +
455
+ 'A future release will require a step to declare this inheritance explicitly.');
456
+ }
457
+ const startOptions = { cwd, env: childEnv };
458
+ cmd = runner.start(resolvedCommand, startOptions);
459
+ }
460
+ catch (e) {
461
+ return submitReceipt(machineryFailure(e), order, resolvedCommand);
200
462
  }
201
- opts.err(`owenloop work exec: lease ${outcome.o} while the command ran — killed the command, no receipt submitted`);
202
- return mapLeaseDuringRun(outcome.o);
463
+ running = cmd;
464
+ opts.out(`owenloop work exec: running ${workflow}/${runId} (step '${order.step}')`);
465
+ const outcome = await Promise.race([
466
+ cmd.done.then((r) => ({ t: 'done', r })).catch((e) => ({ t: 'done', r: machineryFailure(e) })),
467
+ leasePromise.then((o) => ({ t: 'lease', o })),
468
+ ]);
469
+ if (outcome.t === 'lease') {
470
+ await cmd.kill(); // no receipt — a submit now would race the re-offer
471
+ if (signalled) {
472
+ opts.err(`owenloop work exec: signalled mid-run — killed the command group, released ${workflow}/${runId}`);
473
+ return 'killed';
474
+ }
475
+ opts.err(`owenloop work exec: lease ${outcome.o} while the command ran — killed the command, no receipt submitted`);
476
+ return mapLeaseDuringRun(outcome.o);
477
+ }
478
+ return submitReceipt(outcome.r, order, resolvedCommand);
479
+ }
480
+ finally {
481
+ removeConsumesDir(consumesDir);
203
482
  }
204
- return submitReceipt(outcome.r, order);
205
483
  }
206
484
  function stop(reason) {
207
485
  if (signalled)
@@ -0,0 +1,29 @@
1
+ /**
2
+ * The command payload channel. The runner only captures the bounded raw text
3
+ * after the marker; this module parses that text and validates the one
4
+ * worker-to-hub directive supported by exec.
5
+ */
6
+ /** The exact line prefix a command must print on stdout to emit a payload. */
7
+ export declare const PAYLOAD_MARKER = "##owenloop:payload##";
8
+ /** Maximum UTF-8 byte length of the JSON text after the marker. */
9
+ export declare const PAYLOAD_MAX_BYTES: number;
10
+ export interface RejectDirective {
11
+ path: string;
12
+ text: string;
13
+ }
14
+ export interface ParsedPayload {
15
+ /** Present when the marker contained valid JSON, including `null`/primitives. */
16
+ payload?: unknown;
17
+ /** Present when the marker or its reject directive could not be used. */
18
+ payloadError?: string;
19
+ /** Present only for a strictly valid reject directive. */
20
+ reject?: RejectDirective;
21
+ }
22
+ /**
23
+ * Parse the raw text after `PAYLOAD_MARKER`.
24
+ *
25
+ * `overCap` comes from the runner's bounded scanner. It is separate from the
26
+ * string because the scanner must not retain more than the cap just to report
27
+ * that a later byte made the line too large.
28
+ */
29
+ export declare function parsePayloadLine(payloadLine?: string, overCap?: boolean): ParsedPayload;
@@ -0,0 +1,54 @@
1
+ /**
2
+ * The command payload channel. The runner only captures the bounded raw text
3
+ * after the marker; this module parses that text and validates the one
4
+ * worker-to-hub directive supported by exec.
5
+ */
6
+ /** The exact line prefix a command must print on stdout to emit a payload. */
7
+ export const PAYLOAD_MARKER = '##owenloop:payload##';
8
+ /** Maximum UTF-8 byte length of the JSON text after the marker. */
9
+ export const PAYLOAD_MAX_BYTES = 64 * 1024;
10
+ function isRecord(value) {
11
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
12
+ }
13
+ function hasNonEmptyString(value) {
14
+ return typeof value === 'string' && value.trim().length > 0;
15
+ }
16
+ /**
17
+ * Parse the raw text after `PAYLOAD_MARKER`.
18
+ *
19
+ * `overCap` comes from the runner's bounded scanner. It is separate from the
20
+ * string because the scanner must not retain more than the cap just to report
21
+ * that a later byte made the line too large.
22
+ */
23
+ export function parsePayloadLine(payloadLine, overCap = false) {
24
+ if (overCap)
25
+ return { payloadError: `payload JSON exceeds the ${PAYLOAD_MAX_BYTES / 1024} KiB cap` };
26
+ if (payloadLine === undefined)
27
+ return {};
28
+ const jsonText = payloadLine.trim();
29
+ if (jsonText === '')
30
+ return { payloadError: 'payload marker has no JSON text' };
31
+ if (Buffer.byteLength(jsonText, 'utf8') > PAYLOAD_MAX_BYTES) {
32
+ return { payloadError: `payload JSON exceeds the ${PAYLOAD_MAX_BYTES / 1024} KiB cap` };
33
+ }
34
+ let payload;
35
+ try {
36
+ payload = JSON.parse(jsonText);
37
+ }
38
+ catch (error) {
39
+ const message = error instanceof Error ? error.message : String(error);
40
+ return { payloadError: `payload JSON is malformed: ${message}` };
41
+ }
42
+ if (!isRecord(payload) || !('reject' in payload))
43
+ return { payload };
44
+ const rawReject = payload['reject'];
45
+ if (!isRecord(rawReject)) {
46
+ return { payload, payloadError: 'payload reject directive must be an object' };
47
+ }
48
+ const path = rawReject['path'];
49
+ const text = rawReject['text'];
50
+ if (!hasNonEmptyString(path) || !hasNonEmptyString(text)) {
51
+ return { payload, payloadError: 'payload reject directive requires non-empty string path and text' };
52
+ }
53
+ return { payload, reject: { path, text } };
54
+ }
@@ -1,11 +1,12 @@
1
1
  /**
2
2
  * The command receipt (C5, plan decision 8) — the audit record exec submits for
3
- * a command order. It IS the result contract: the hub `submit` verb has no
4
- * failure channel, so a receipt is submitted for EVERY finished command — a
5
- * non-zero `exitCode` (or `exitCode: null` + `error` for machinery failure)
6
- * carries the truth, and exec still exits 0 because its job (deliver the
7
- * receipt) succeeded. Pure construction so it is trivially asserted in tests.
3
+ * an ordinary command order, and for a judge order that exits 0. The hub `submit`
4
+ * verb has no failure channel, so a non-zero `exitCode` (or `exitCode: null` +
5
+ * `error` for machinery failure) carries the command result. A non-zero judge
6
+ * exit uses `reject` instead of a receipt, and signal-killed work submits neither.
7
+ * Pure construction so it is trivially asserted in tests.
8
8
  */
9
+ import { type ParsedPayload } from './payload.ts';
9
10
  import type { CommandResult } from './runner.ts';
10
11
  /** The submitted artifact value for a command order. */
11
12
  export interface CommandReceipt {
@@ -18,6 +19,8 @@ export interface CommandReceipt {
18
19
  stdoutBytes: number;
19
20
  stderrBytes: number;
20
21
  outputTail: string;
22
+ payload?: unknown;
23
+ payloadError?: string;
21
24
  startedAt: number;
22
25
  finishedAt: number;
23
26
  durationMs: number;
@@ -35,4 +38,4 @@ export interface ReceiptContext {
35
38
  step: string;
36
39
  }
37
40
  /** Fold a raw `CommandResult` and its order context into the submitted receipt. */
38
- export declare function buildReceipt(result: CommandResult, ctx: ReceiptContext): CommandReceipt;
41
+ export declare function buildReceipt(result: CommandResult, ctx: ReceiptContext, parsedPayload?: ParsedPayload): CommandReceipt;
@@ -1,5 +1,14 @@
1
+ /**
2
+ * The command receipt (C5, plan decision 8) — the audit record exec submits for
3
+ * an ordinary command order, and for a judge order that exits 0. The hub `submit`
4
+ * verb has no failure channel, so a non-zero `exitCode` (or `exitCode: null` +
5
+ * `error` for machinery failure) carries the command result. A non-zero judge
6
+ * exit uses `reject` instead of a receipt, and signal-killed work submits neither.
7
+ * Pure construction so it is trivially asserted in tests.
8
+ */
9
+ import { parsePayloadLine } from "./payload.js";
1
10
  /** Fold a raw `CommandResult` and its order context into the submitted receipt. */
2
- export function buildReceipt(result, ctx) {
11
+ export function buildReceipt(result, ctx, parsedPayload = parsePayloadLine(result.payloadLine, result.payloadOverCap)) {
3
12
  return {
4
13
  kind: 'command-receipt',
5
14
  command: ctx.command,
@@ -10,6 +19,8 @@ export function buildReceipt(result, ctx) {
10
19
  stdoutBytes: result.stdoutBytes,
11
20
  stderrBytes: result.stderrBytes,
12
21
  outputTail: result.outputTail,
22
+ ...('payload' in parsedPayload ? { payload: parsedPayload.payload } : {}),
23
+ ...(parsedPayload.payloadError !== undefined ? { payloadError: parsedPayload.payloadError } : {}),
13
24
  startedAt: result.startedAt,
14
25
  finishedAt: result.finishedAt,
15
26
  durationMs: result.durationMs,
@@ -16,6 +16,10 @@ export interface CommandResult {
16
16
  stderrBytes: number;
17
17
  /** Last ≤4 KiB of combined stdout+stderr, decoded lossily as UTF-8. */
18
18
  outputTail: string;
19
+ /** Raw text after the last matching stdout payload marker, before JSON parsing. */
20
+ payloadLine?: string;
21
+ /** True when the last matching marker line exceeded the payload cap. */
22
+ payloadOverCap?: boolean;
19
23
  startedAt: number;
20
24
  finishedAt: number;
21
25
  durationMs: number;
@@ -31,6 +35,7 @@ export interface RunningCommand {
31
35
  export interface CommandRunner {
32
36
  start(command: string, opts: {
33
37
  cwd: string;
38
+ env?: Record<string, string | undefined>;
34
39
  }): RunningCommand;
35
40
  }
36
41
  /** The fully-resolved spawn arguments — pure data, asserted directly in tests. */
@@ -41,6 +46,7 @@ export interface CommandPlan {
41
46
  cwd: string;
42
47
  detached: true;
43
48
  stdio: ['ignore', 'pipe', 'pipe'];
49
+ env?: Record<string, string | undefined>;
44
50
  };
45
51
  }
46
52
  /**
@@ -48,7 +54,7 @@ export interface CommandPlan {
48
54
  * spawn, no I/O — so tests assert the shape without launching anything. POSIX
49
55
  * `/bin/sh` keeps the default runner portable (ubuntu-latest CI, macOS dev).
50
56
  */
51
- export declare function buildCommandPlan(command: string, cwd: string): CommandPlan;
57
+ export declare function buildCommandPlan(command: string, cwd: string, env?: Record<string, string | undefined>): CommandPlan;
52
58
  export interface DefaultRunnerOptions {
53
59
  /** SIGTERM→SIGKILL grace on a group kill (default 5_000). */
54
60
  graceMs?: number;