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
@@ -123,42 +123,107 @@ export interface TaskData {
123
123
  alarmAt?: number;
124
124
  }
125
125
  /** A run node — audit/budget trail, and the holder of a claim's fingerprint. */
126
- /** A self-contained unit of work emitted by a tick. */
126
+ /**
127
+ * A reference-mode unit of work emitted by a tick (WP-B1). The order is a
128
+ * REFERENCE packet: `defDigest` identifies the pinned definition snapshot
129
+ * that emitted it, and the authored static instruction bytes (prompt,
130
+ * command, acceptance) ride the resolver boundary instead — see
131
+ * `OrderResolver` in order-resolver.ts. An order NEVER carries authored
132
+ * prompt or command text, nor `owes[].acceptance` (the artifact lifecycle
133
+ * state is dynamic engine state, not channel-1 instructions). It does carry
134
+ * the routing/reference fields, the dynamic consumed input values, and the
135
+ * dynamic rejection feedback. One shape serves both local (`owenloop tick`)
136
+ * and embedded/library callers — there is no verify-mode or legacy branch.
137
+ */
127
138
  export interface Order {
128
139
  run: string;
129
140
  workflow: string;
130
141
  step: string;
131
142
  key: string;
132
143
  index?: number;
144
+ /** The digest of the definition snapshot this order was emitted against.
145
+ * Resolves static instructions through the `(defDigest, step, key)`
146
+ * boundary; an unknown digest is a named refusal (UnknownDefDigestError). */
147
+ defDigest: string;
133
148
  inputs: string[];
134
149
  outputs: string[];
135
150
  workdir?: string;
136
151
  model?: string;
137
- /** Declares which kind of executor this order is for. Absent = 'agent'
152
+ /** Declares which kind of worker this order is for. Absent = 'agent'
138
153
  * (today's behavior). Opaque to the engine; carried through verbatim from
139
- * the step definition, same pass-through contract as `model`/`x`. */
140
- executor?: string;
141
- /** The command string for a `executor: command` order. Opaque to the engine
142
- * — never parsed, never shelled out. */
143
- command?: string;
144
- /** Opaque config object for a non-agent/non-command executor type (or
145
- * alongside `command`). Carried through untouched, contents never read. */
154
+ * the authored step's `executor:` field (the YAML grammar is unchanged),
155
+ * same pass-through contract as `model`/`x`. */
156
+ worker?: string;
157
+ /** The artifact stem this order's judge step is verdicting, when present. */
158
+ judge?: string;
159
+ /**
160
+ * The COMPOSED routing capabilities this order was offered under — the
161
+ * step's authored capabilities each suffixed with the run's modifier
162
+ * (`wise` → `wise:deep`), or the authored names verbatim when the run
163
+ * carries no modifier. Absent when the step authored none.
164
+ *
165
+ * This is the value a claiming crew's bindings are matched against and the
166
+ * value the shift's settings map is keyed by. It is a snapshot of the offer:
167
+ * an already-claimed order is never recomposed, so re-reading it later
168
+ * always shows what the claim was actually judged on.
169
+ */
170
+ capabilities?: string[];
171
+ /**
172
+ * The modifier this order was composed with. Normally the run's modifier;
173
+ * on an escalated re-offer, the step's escalation target instead (the run's
174
+ * own modifier is left alone). Carried separately from `capabilities` so a
175
+ * brief can surface the requested depth without re-parsing a compound.
176
+ */
177
+ modifier?: string;
178
+ /**
179
+ * `true` when `modifier` above is the step's ESCALATION TARGET rather than
180
+ * the run's own modifier — i.e. this offer is a recovery re-offer made
181
+ * after the step's produce accumulated `escalation.after` judgment
182
+ * rejections. Absent on every ordinary offer.
183
+ *
184
+ * The engine decides the transition; this flag is how the decision reaches
185
+ * the layer that acts on it, instead of that layer re-deriving it by
186
+ * diffing `modifier` against the run record. The hub reads it to apply the
187
+ * escalation wait policy (wait-then-fallback, even where the deployment
188
+ * default is `forever`); a brief reads it to tell the worker it is on the
189
+ * recovery path.
190
+ */
191
+ escalated?: true;
192
+ /** Opaque config object for a non-agent/non-command worker type (or
193
+ * alongside a command). Carried through untouched, contents never read. */
146
194
  spec?: Record<string, unknown>;
147
195
  /** §27.3: the step's opaque `x:` extension map, carried through untouched
148
196
  * (same pass-through contract as `model`). The engine never reads it —
149
197
  * it exists for the external runner/tooling consuming this order. */
150
198
  x?: Record<string, unknown>;
151
- prompt: string;
152
199
  /** captured handles of the green inputs this run builds on */
153
200
  consumes: Record<string, unknown>;
201
+ /**
202
+ * The versions of the consumed inputs captured at claim time. Drivers cover
203
+ * this map in a submission signature instead of recomputing it from values.
204
+ */
205
+ consumedFingerprint?: Fingerprint;
154
206
  /** the owed outputs and their accumulated reason threads (the feedback channel) */
155
207
  owes: Array<{
156
208
  path: string;
157
- acceptance: string;
209
+ /** The target version this claim's next successful producer commit lands
210
+ * (committed version + 1), issued by the engine inside the claim
211
+ * transaction. This is the version a producer signs in a submission
212
+ * proof and a downstream consumer checks it against. Absent when the hub
213
+ * is not version-aware, which leaves the producer submit unsigned. */
214
+ version?: number;
158
215
  judgmentRejects: number;
159
216
  schemaRejects: number;
160
217
  reasons: ReasonEntry[];
218
+ /** Opaque proof/signature placeholder for future WP-A4-signed reason
219
+ * threads. Data-only today: no cryptographic code attaches or verifies
220
+ * it — the slot exists so signed dynamic data can land without changing
221
+ * the reference-mode wire shape. */
222
+ proof?: string;
161
223
  }>;
224
+ /** Opaque proof/signature placeholder for future WP-A4-signed dynamic
225
+ * consume values. Data-only today — same contract as `owes[].proof`. */
226
+ consumesProof?: string;
162
227
  /** The trigger that woke this firing (§21). Absent = 'inputsGreen'. */
163
228
  cause?: FiringTrigger;
164
229
  }
@@ -184,6 +249,16 @@ export interface WorkflowData {
184
249
  def: string;
185
250
  title?: string;
186
251
  params?: Record<string, string>;
252
+ /**
253
+ * The ONE modifier this run carries, validated against the def's declared
254
+ * `modifiers` set when the run is created and immutable thereafter — no
255
+ * step, worker or judge can write it (only `start_run` sets it; escalation
256
+ * overrides it per-offer without changing it here).
257
+ *
258
+ * Absent = an unmodified run: every step is offered on bare capabilities.
259
+ * Deletes with the run, like the rest of the row.
260
+ */
261
+ modifier?: string;
187
262
  /** Instance-to-definition pinning (§28): the compiled def this instance was
188
263
  * created against, snapshotted verbatim as JSON. Absent on rows created
189
264
  * before this feature shipped — those instances fall back to today's
@@ -266,6 +341,13 @@ export interface ProducePattern {
266
341
  * (or additionally alongside `command`). Shape-checked as a plain map
267
342
  * only (mirrors `x:`'s asExtension contract) — contents never read. */
268
343
  spec?: Record<string, unknown>;
344
+ /** Routing capabilities for this judge's synthesized step. Omitted =
345
+ * INHERIT the producing step's `capabilities`, so a judge routes to the
346
+ * same grade of crew as the work it judges instead of being claimable by
347
+ * anyone. Set explicitly to route a judge somewhere else; an explicit
348
+ * empty list is not accepted (it would reopen the def-silent hole
349
+ * deliberately, which no author means to do). */
350
+ capabilities?: string[];
269
351
  }>;
270
352
  }
271
353
  /**
@@ -291,6 +373,27 @@ export interface EffectDef {
291
373
  onInvalidate?: 'pin' | 'escalate' | string;
292
374
  }
293
375
  /** A step (step) definition. */
376
+ /**
377
+ * A step's escalation rule (def-authored, engine-applied).
378
+ *
379
+ * There is NO rung order anywhere in this system — `modifier` is an explicit
380
+ * target drawn from the def's declared `modifiers` set, never "the next one
381
+ * up". Escalation therefore cannot be expressed as arithmetic on a ladder, and
382
+ * nothing here is comparable to anything else.
383
+ *
384
+ * `after` must be strictly less than the effective `maxAttempts` of every
385
+ * produce on the owning step. At `judgmentRejects >= maxAttempts` the engine
386
+ * freezes the artifact (`model.ts` `isStalled`), so an escalation authored at
387
+ * or past that threshold would re-offer a step that can never run again —
388
+ * deterministically dead. `validateDef` rejects it rather than accepting a
389
+ * rule that silently does nothing.
390
+ */
391
+ export interface EscalationDef {
392
+ /** Judgment-reject count that triggers the escalated re-offer. */
393
+ after: number;
394
+ /** Target modifier, a member of the def's declared `modifiers` set. */
395
+ modifier: string;
396
+ }
294
397
  export interface StepDef {
295
398
  name: string;
296
399
  /** Inputs this step reads — and, by the same declaration, the artifacts it has
@@ -335,6 +438,12 @@ export interface StepDef {
335
438
  spec?: Record<string, unknown>;
336
439
  /** opaque location hint passed through on the order; no default — absent unless the def sets it */
337
440
  workdir?: string;
441
+ /**
442
+ * Resolve the order's workdir from `<consumedStem>.<dotted.path>` in a consumed
443
+ * artifact value. Mutually exclusive with workdir; the stem must be a plain
444
+ * consume so the value passes the engine's consume-side verification gate.
445
+ */
446
+ workdirFrom?: string;
338
447
  /** the step's output is a destructive completion (e.g. a merge): green is terminal (§15.2) */
339
448
  terminal?: boolean;
340
449
  /** Step-level effect contract (§6.5). Only consulted for non-terminal greens whose inputs move. */
@@ -350,8 +459,19 @@ export interface StepDef {
350
459
  /** A2: opaque routing capabilities for peer-orchestrator claim filtering. A tick
351
460
  * caller passing a capability filter only claims steps whose capabilities intersect it;
352
461
  * absent (or empty, normalized to absent at parse) = claimable by any caller.
353
- * Distinct from `executor`/`executors` (executor-kind), which this never touches. */
462
+ * Distinct from `executor`/`executors` (executor-kind), which this never touches.
463
+ *
464
+ * AUTHORED NAMES ONLY — never a compound. A `:` is rejected at parse
465
+ * (`buildStep`) because the suffix position is engine-owned: the engine
466
+ * composes `<capability>:<modifier>` at offer time (see
467
+ * `WorkflowDef.modifiers` and `Order.capabilities`). */
354
468
  capabilities?: string[];
469
+ /** Per-step escalation rule: after `after` judgment rejections of this
470
+ * step's produced artifact, the engine re-offers THIS step composed with
471
+ * `modifier` instead of the run's modifier. Step-scoped — the run's own
472
+ * modifier is never changed. Absent = the step never escalates and
473
+ * rejections run the normal retry path until the stall brake. */
474
+ escalation?: EscalationDef;
355
475
  /** A3 (REL-8): per-step OPT-IN max total lease lifetime override in
356
476
  * milliseconds — the cap on `claimedAt + maxLease` past which renewals can no
357
477
  * longer keep a lease fresh. Overrides the engine `maxLeaseMs`; when both are
@@ -389,6 +509,20 @@ export interface WorkflowDef {
389
509
  * that are expanded at load time by `expandIncludes`; the engine always sees a flat list.
390
510
  */
391
511
  steps: StepDef[];
512
+ /**
513
+ * The def's declared modifier vocabulary — an UNORDERED SET of plain names
514
+ * (e.g. `[express, standard, deep]`). The engine attaches no meaning, no
515
+ * order and no arithmetic to these values; it only checks membership.
516
+ *
517
+ * A run may carry ONE of them (`WorkflowData.modifier`, set at start and
518
+ * never changed afterwards). At offer time the engine composes each of a
519
+ * step's capabilities with it — `wise` + `deep` → `wise:deep` — and that
520
+ * compound is what a crew binding is matched against.
521
+ *
522
+ * Absent = this def cannot receive a modifier at all, and every step is
523
+ * offered on its bare capabilities exactly as before this feature existed.
524
+ */
525
+ modifiers?: string[];
392
526
  /** Workflow-level public outputs / embedding interface (design doc §5.2).
393
527
  * Declared stems are intentional leaves: lint-exempt from dead-end warnings.
394
528
  * A stem listed here that no step produces is a hard validateDef error. */
@@ -9,30 +9,15 @@
9
9
  * it would be silently skipped (unrepresentable, not corrupt).
10
10
  *
11
11
  * This is intentionally narrow: just enough tar to unpack a GitHub tarball,
12
- * not a general-purpose tar library.
12
+ * not a general-purpose tar library. The parsing, resource limits, and path
13
+ * policy live in `src/archive.ts` (the ONE shared archive boundary, also
14
+ * used by `src/bundle/` and `src/add.ts`); this module keeps the historical
15
+ * `extractTarGz` API and compatible reading behavior.
13
16
  */
14
- /**
15
- * Resource bounds enforced while unpacking a tarball. Defaults are sized for
16
- * GitHub codeload output and are deliberately generous; tests inject tiny
17
- * values to exercise the limits without building giant fixtures.
18
- *
19
- * - `maxCompressedBytes` (256 MiB): the buffered tarball download itself.
20
- * - `maxExpandedBytes` (1 GiB): total inflated size — kills gzip bombs at
21
- * inflate time. GitHub's own recommended repo size sits comfortably below.
22
- * - `maxFileCount` (50k): number of regular files kept.
23
- * - `maxFileBytes` (100 MiB): GitHub blocks pushing files larger than this,
24
- * and LFS content is never in the tarball, so no legit entry exceeds it.
25
- * - `maxPathLength` (1024): guards against absurdly long entry paths (pax or
26
- * USTAR prefix-composed) before they are ever used as a filesystem path.
27
- */
28
- export interface TarLimits {
29
- maxCompressedBytes: number;
30
- maxExpandedBytes: number;
31
- maxFileCount: number;
32
- maxFileBytes: number;
33
- maxPathLength: number;
34
- }
35
- export declare const DEFAULT_TAR_LIMITS: TarLimits;
17
+ import { DEFAULT_TAR_LIMITS } from './archive.ts';
18
+ import type { TarLimits } from './archive.ts';
19
+ export type { TarLimits };
20
+ export { DEFAULT_TAR_LIMITS };
36
21
  /**
37
22
  * Extract a gzipped tar archive into a flat map of in-archive path → file
38
23
  * bytes. Directory entries are dropped; only regular files are kept. Pax
package/dist/src/untar.js CHANGED
@@ -9,59 +9,13 @@
9
9
  * it would be silently skipped (unrepresentable, not corrupt).
10
10
  *
11
11
  * This is intentionally narrow: just enough tar to unpack a GitHub tarball,
12
- * not a general-purpose tar library.
12
+ * not a general-purpose tar library. The parsing, resource limits, and path
13
+ * policy live in `src/archive.ts` (the ONE shared archive boundary, also
14
+ * used by `src/bundle/` and `src/add.ts`); this module keeps the historical
15
+ * `extractTarGz` API and compatible reading behavior.
13
16
  */
14
- import { gunzipSync } from 'node:zlib';
15
- const BLOCK = 512;
16
- export const DEFAULT_TAR_LIMITS = {
17
- maxCompressedBytes: 256 * 1024 * 1024,
18
- maxExpandedBytes: 1024 * 1024 * 1024,
19
- maxFileCount: 50_000,
20
- maxFileBytes: 100 * 1024 * 1024,
21
- maxPathLength: 1024,
22
- };
23
- /** Parse a NUL/space-padded octal field (tar's numeric encoding) into a number. */
24
- function parseOctal(bytes) {
25
- let s = '';
26
- for (const b of bytes) {
27
- if (b === 0 || b === 32 /* space */)
28
- continue;
29
- s += String.fromCharCode(b);
30
- }
31
- return s.length ? parseInt(s, 8) : 0;
32
- }
33
- function readCString(bytes) {
34
- const nul = bytes.indexOf(0);
35
- const slice = nul >= 0 ? bytes.subarray(0, nul) : bytes;
36
- return Buffer.from(slice).toString('utf8');
37
- }
38
- /** Parse a pax extended-header data block's `key=value` records, e.g. `path=...`. */
39
- function parsePaxRecords(data) {
40
- const text = Buffer.from(data).toString('utf8');
41
- const out = new Map();
42
- let i = 0;
43
- while (i < text.length) {
44
- // Each record is "<len> <key>=<value>\n", <len> counts the whole record
45
- // (including the length prefix itself and the trailing newline).
46
- const spaceIdx = text.indexOf(' ', i);
47
- if (spaceIdx < 0)
48
- break;
49
- const len = parseInt(text.slice(i, spaceIdx), 10);
50
- if (!Number.isFinite(len) || len <= 0)
51
- break;
52
- const record = text.slice(i, i + len);
53
- const eq = record.indexOf('=', spaceIdx - i + 1);
54
- if (eq >= 0) {
55
- const key = record.slice(spaceIdx - i + 1, eq);
56
- // record.slice(eq + 1) still has the trailing '\n' the pax format
57
- // mandates — strip it to get the bare value.
58
- const value = record.slice(eq + 1).replace(/\n$/, '');
59
- out.set(key, value);
60
- }
61
- i += len;
62
- }
63
- return out;
64
- }
17
+ import { DEFAULT_TAR_LIMITS, inflateArchive, parseTar } from "./archive.js";
18
+ export { DEFAULT_TAR_LIMITS };
65
19
  /**
66
20
  * Extract a gzipped tar archive into a flat map of in-archive path → file
67
21
  * bytes. Directory entries are dropped; only regular files are kept. Pax
@@ -75,90 +29,10 @@ function parsePaxRecords(data) {
75
29
  */
76
30
  export function extractTarGz(bytes, limits = {}) {
77
31
  const lim = { ...DEFAULT_TAR_LIMITS, ...limits };
78
- if (bytes.length > lim.maxCompressedBytes) {
79
- throw new Error(`compressed archive size ${bytes.length} exceeds limit of ${lim.maxCompressedBytes} bytes`);
80
- }
81
- let tar;
82
- try {
83
- // maxOutputLength caps the inflated size — a gzip bomb aborts here with
84
- // ERR_BUFFER_TOO_LARGE rather than exhausting memory.
85
- tar = gunzipSync(bytes, { maxOutputLength: lim.maxExpandedBytes });
86
- }
87
- catch (e) {
88
- if (e.code === 'ERR_BUFFER_TOO_LARGE') {
89
- throw new Error(`expanded archive size exceeds limit of ${lim.maxExpandedBytes} bytes`);
90
- }
91
- throw e;
92
- }
32
+ const tar = inflateArchive(bytes, lim);
33
+ const entries = parseTar(tar, lim, { policy: 'compatible' });
93
34
  const out = new Map();
94
- let offset = 0;
95
- let fileCount = 0;
96
- let pendingLongPath;
97
- while (offset + BLOCK <= tar.length) {
98
- const header = tar.subarray(offset, offset + BLOCK);
99
- // Two consecutive all-zero blocks mark the end of the archive.
100
- if (header.every((b) => b === 0))
101
- break;
102
- const nameField = readCString(header.subarray(0, 100));
103
- const sizeField = parseOctal(header.subarray(124, 136));
104
- const typeflag = String.fromCharCode(header[156] ?? 0);
105
- const prefixField = readCString(header.subarray(345, 500));
106
- // parseOctal on a corrupt size field can yield NaN; a valid entry is a
107
- // non-negative integer.
108
- if (!Number.isInteger(sizeField) || sizeField < 0) {
109
- throw new Error(`corrupt tar header: invalid size field (got ${sizeField})`);
110
- }
111
- offset += BLOCK;
112
- const dataStart = offset;
113
- const dataEnd = dataStart + sizeField;
114
- // subarray silently clamps a past-the-end range, so a truncated archive
115
- // would otherwise yield a short read instead of an error — guard it.
116
- if (dataEnd > tar.length) {
117
- throw new Error(`corrupt tar archive: entry data (${sizeField} bytes) extends past end of archive`);
118
- }
119
- const data = tar.subarray(dataStart, dataEnd);
120
- // Data is padded up to the next 512-byte boundary.
121
- offset += Math.ceil(sizeField / BLOCK) * BLOCK;
122
- if (typeflag === '5') {
123
- // directory — nothing to keep
124
- continue;
125
- }
126
- if (typeflag === 'g') {
127
- // pax global extended header — applies to the whole archive; we don't
128
- // need any of its records (uid/gid/etc), just skip its data.
129
- continue;
130
- }
131
- if (typeflag === 'x') {
132
- // pax extended header for the NEXT entry — currently only 'path' matters.
133
- const records = parsePaxRecords(data);
134
- const p = records.get('path');
135
- if (p !== undefined)
136
- pendingLongPath = p;
137
- continue;
138
- }
139
- if (typeflag !== '0' && typeflag !== '\0') {
140
- // unsupported typeflag (symlink, hardlink, GNU longname, ...) — skip.
141
- pendingLongPath = undefined;
142
- continue;
143
- }
144
- // Regular file.
145
- if (sizeField > lim.maxFileBytes) {
146
- throw new Error(`archive entry exceeds per-file size limit of ${lim.maxFileBytes} bytes (${sizeField} bytes)`);
147
- }
148
- // Validate the FINAL, fully-resolved name (pax 'path' override or USTAR
149
- // prefix+name), not the raw 100-byte field — that is what a caller joins.
150
- const name = pendingLongPath ?? (prefixField ? `${prefixField}/${nameField}` : nameField);
151
- pendingLongPath = undefined;
152
- if (name) {
153
- if (name.length > lim.maxPathLength) {
154
- throw new Error(`archive entry path length ${name.length} exceeds limit of ${lim.maxPathLength} chars`);
155
- }
156
- fileCount += 1;
157
- if (fileCount > lim.maxFileCount) {
158
- throw new Error(`archive file count exceeds limit of ${lim.maxFileCount}`);
159
- }
160
- out.set(name, new Uint8Array(data));
161
- }
162
- }
35
+ for (const e of entries)
36
+ out.set(e.path, e.data);
163
37
  return out;
164
38
  }
@@ -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
@@ -165,6 +197,13 @@ interpreted by the engine beyond that. All three (`executor`, `command`,
165
197
  like `model` and `workdir`. See [`docs/design.md` §27.4](design.md) for the
166
198
  full contract.
167
199
 
200
+ A command step's `consumes:` reach the command through its environment, not its
201
+ working directory: `owenloop work exec` sets `OWENLOOP_CONSUMES` with the JSON
202
+ inline, or `OWENLOOP_CONSUMES_FILE` with a path to it once that JSON exceeds
203
+ 64 KiB. See [`docs/bundles.md` § Consumed inputs for command
204
+ steps](bundles.md#consumed-inputs-for-command-steps) for the reader snippet and
205
+ the omitted-key rule.
206
+
168
207
  ## `capabilities:` — logical capability tags
169
208
 
170
209
  `capabilities:` is an optional list of strings on a step naming what that step
@@ -229,6 +268,12 @@ indirection. Two consequences of the local filter are worth stating plainly:
229
268
  (each folded deferral in a `TickResult` carries its `reason`) so a
230
269
  permanently unclaimed step is caught rather than silently stuck.
231
270
 
271
+ A `workdirFrom` firing can also remain deferred forever with
272
+ `workdir-unresolved`. That reason means the producing step has not supplied a
273
+ usable nested path: the value is missing, has an invalid shape, or is not a
274
+ non-empty string. Fix the producing step or its artifact value; changing the
275
+ consumer's worker does not bypass the engine's workdir resolution check.
276
+
232
277
  `capabilities:` is distinct from [`executor:`](#executor--declaring-the-executor):
233
278
  `executor:` says what *kind* of executor should run an order once it's claimed;
234
279
  `capabilities:` says *which* caller may claim it in the first place — a tick filter
@@ -291,6 +336,15 @@ regardless of `executor:` — that requirement is orthogonal to this feature and
291
336
  applies even to a `executor: command` judge (the field just goes unread by a
292
337
  non-agent dispatcher).
293
338
 
339
+ Author `x:` on the producer step, not on individual judge entries. Every native
340
+ judge synthesized from that producer inherits the producer's complete parsed
341
+ `x:` map. Each judge receives an independent deep clone, so runner-side
342
+ mutation of the producer or one judge cannot alter a sibling judge. When the
343
+ producer omits `x:`, synthesized judges omit `x:` too. In particular, a
344
+ producer's `x.harness` policy governs both the producer order and every native
345
+ judge order. A judge entry's first-class `model:` remains authoritative over an
346
+ inherited `x.harness.model` value.
347
+
294
348
  Each judge is a real step under the hood — it fires its own Worker order
295
349
  through the normal pipeline, with its own throttles (`cadence:`,
296
350
  `maxRunsPerDay:`) and retry/timeout behavior. When `researcher` commits
@@ -420,7 +474,7 @@ steps:
420
474
  produces: [sandbox]
421
475
  body: Provision environment.
422
476
  - name: deliver
423
- calls: delivery # child workflow name (must exist in the same def dir)
477
+ calls: delivery # bare local name; use <package>/<workflow> for a CAS target
424
478
  inputs: # child input → parent artifact (gate: sandbox green)
425
479
  proposal: proposal
426
480
  produces: [delivered] # one parent artifact; greens when delivery's output greens
@@ -526,13 +580,17 @@ rather than inlining the payload itself.
526
580
 
527
581
  Don't put credentials or secrets in an artifact value. Values are persisted
528
582
  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.
583
+ verbatim onto every order that consumes them — anyone who can read the
584
+ database, or a downstream worker's resolved context, can read them.
531
585
 
532
586
  Those values are also *retained*, not just transiently persisted: every
533
587
  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
588
+ and every run's issued order packet — the dynamic input values it consumed
589
+ and its accumulated rejection reasons — is written to the SQLite `run` table
590
+ at claim time and stays there after the run closes and the workflow finishes.
591
+ The step's authored prompt and command text are *not* in that packet: orders
592
+ are reference packets (design doc §29) and carry a `defDigest` pointing at
593
+ the definition snapshot instead, so instruction text is retained once, in the
594
+ definition, not duplicated per firing. A secret that flowed through an input
537
595
  therefore lives on in the database until the file itself is disposed of — see
538
596
  [Storage](../README.md#storage) for the operator's disposal responsibility.