owenloop 0.5.7 → 0.5.9

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 (111) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/README.md +7 -8
  3. package/dist/packages/work/src/agent/capability-model.d.ts +64 -82
  4. package/dist/packages/work/src/agent/capability-model.js +94 -91
  5. package/dist/packages/work/src/agent/loop.d.ts +55 -26
  6. package/dist/packages/work/src/agent/loop.js +144 -50
  7. package/dist/packages/work/src/bundle/types.d.ts +3 -3
  8. package/dist/packages/work/src/consumed-verifier.js +6 -17
  9. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  10. package/dist/packages/work/src/exec/loop.js +206 -35
  11. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  12. package/dist/packages/work/src/exec/receipt.js +6 -6
  13. package/dist/packages/work/src/harness/child-env.js +4 -5
  14. package/dist/packages/work/src/harness/claude.js +100 -0
  15. package/dist/packages/work/src/harness/codex.js +3 -4
  16. package/dist/packages/work/src/harness/session-store.d.ts +63 -3
  17. package/dist/packages/work/src/harness/session-store.js +104 -9
  18. package/dist/packages/work/src/hub/client.d.ts +19 -4
  19. package/dist/packages/work/src/hub/client.js +7 -3
  20. package/dist/packages/work/src/hub/types.d.ts +87 -3
  21. package/dist/packages/work/src/main.js +1 -0
  22. package/dist/packages/work/src/roles/agent-run.js +46 -43
  23. package/dist/packages/work/src/roles/exec.js +2 -0
  24. package/dist/packages/work/src/roles/sessions.d.ts +3 -2
  25. package/dist/packages/work/src/roles/sessions.js +9 -2
  26. package/dist/packages/work/src/roles/settings.js +3 -1
  27. package/dist/packages/work/src/roles/shift.js +14 -2
  28. package/dist/packages/work/src/roles/util.d.ts +1 -0
  29. package/dist/packages/work/src/roles/util.js +10 -0
  30. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  31. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  32. package/dist/packages/work/src/settings/roster.d.ts +105 -0
  33. package/dist/packages/work/src/settings/roster.js +439 -0
  34. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  35. package/dist/packages/work/src/settings/serving.js +79 -0
  36. package/dist/packages/work/src/settings/settings.d.ts +25 -24
  37. package/dist/packages/work/src/settings/settings.js +29 -33
  38. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  39. package/dist/packages/work/src/shift/loop.js +299 -51
  40. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  41. package/dist/packages/work/src/shift/runtime.d.ts +15 -0
  42. package/dist/packages/work/src/shift/runtime.js +95 -13
  43. package/dist/packages/work/src/shift/server.js +2 -0
  44. package/dist/packages/work/src/shift/spawn.d.ts +18 -50
  45. package/dist/packages/work/src/shift/spawn.js +30 -65
  46. package/dist/packages/work/src/shift/state.d.ts +29 -2
  47. package/dist/packages/work/src/shift/state.js +45 -15
  48. package/dist/packages/work/src/usage.d.ts +1 -1
  49. package/dist/packages/work/src/usage.js +10 -5
  50. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  51. package/dist/packages/work/src/util/modifier-init.js +73 -0
  52. package/dist/src/bundle/tar.d.ts +9 -4
  53. package/dist/src/bundle/tar.js +9 -4
  54. package/dist/src/capabilities.d.ts +50 -0
  55. package/dist/src/capabilities.js +38 -0
  56. package/dist/src/cli.d.ts +15 -1
  57. package/dist/src/cli.js +1099 -32
  58. package/dist/src/config-dir.d.ts +14 -19
  59. package/dist/src/config-dir.js +16 -24
  60. package/dist/src/credentials.d.ts +1 -1
  61. package/dist/src/credentials.js +1 -1
  62. package/dist/src/crypto/index.d.ts +1 -1
  63. package/dist/src/crypto/index.js +1 -1
  64. package/dist/src/crypto/org-root.d.ts +30 -12
  65. package/dist/src/crypto/org-root.js +162 -14
  66. package/dist/src/crypto/records.d.ts +3 -0
  67. package/dist/src/crypto/records.js +8 -0
  68. package/dist/src/crypto/trust-roots.d.ts +2 -2
  69. package/dist/src/crypto/trust-roots.js +2 -2
  70. package/dist/src/defs.d.ts +6 -1
  71. package/dist/src/defs.js +203 -8
  72. package/dist/src/engine.d.ts +55 -6
  73. package/dist/src/engine.js +172 -22
  74. package/dist/src/global-config.d.ts +4 -7
  75. package/dist/src/global-config.js +4 -7
  76. package/dist/src/hub.d.ts +207 -5
  77. package/dist/src/hub.js +263 -3
  78. package/dist/src/index.d.ts +5 -5
  79. package/dist/src/index.js +3 -3
  80. package/dist/src/mcp/serve.d.ts +22 -0
  81. package/dist/src/mcp/serve.js +88 -8
  82. package/dist/src/model.d.ts +2 -0
  83. package/dist/src/model.js +32 -25
  84. package/dist/src/order-resolver.d.ts +1 -0
  85. package/dist/src/order-resolver.js +8 -1
  86. package/dist/src/schemas/index.d.ts +19 -0
  87. package/dist/src/schemas/order.v1.schema.json +13 -2
  88. package/dist/src/store/pre-commit-verifier.js +1 -1
  89. package/dist/src/store.d.ts +5 -0
  90. package/dist/src/store.js +43 -8
  91. package/dist/src/types.d.ts +64 -7
  92. package/dist/src/work-settings.d.ts +2 -4
  93. package/dist/src/work-settings.js +2 -4
  94. package/docs/agent-runner.md +2 -2
  95. package/docs/authoring.md +90 -2
  96. package/docs/bundles.md +29 -3
  97. package/docs/cli.md +456 -120
  98. package/docs/crypto.md +32 -16
  99. package/docs/design.md +70 -1
  100. package/docs/routing.md +762 -0
  101. package/docs/shift-logs.md +37 -10
  102. package/docs/wire-contracts.md +50 -7
  103. package/examples/workflows/delivery.yaml +31 -14
  104. package/examples/workflows/ship.yaml +10 -2
  105. package/package.json +1 -1
  106. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  107. package/plugins/claude-code/plugin/.mcp.json +1 -1
  108. package/plugins/claude-code/plugin/skills/author/SKILL.md +1 -2
  109. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  110. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  111. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +1 -2
@@ -51,6 +51,8 @@ export interface ReasonEntry {
51
51
  text: string;
52
52
  /** version the artifact was at when this entry was written (provenance) */
53
53
  fromVersion?: number;
54
+ /** Machine-readable correction supplied when rejecting a bound artifact. */
55
+ requested?: string;
54
56
  }
55
57
  /**
56
58
  * The fingerprint: the version of every consumed input at claim time
@@ -172,8 +174,31 @@ export interface Order {
172
174
  * value the shift's settings map is keyed by. It is a snapshot of the offer:
173
175
  * an already-claimed order is never recomposed, so re-reading it later
174
176
  * always shows what the claim was actually judged on.
177
+ *
178
+ * When `reroutedFrom` is present this field holds the REROUTE TARGET, not
179
+ * what the def composed. That is deliberate: this is the capability being
180
+ * served, so it is the one a shift must resolve its model against.
175
181
  */
176
182
  capabilities?: string[];
183
+ /**
184
+ * Ordered crews the offering side matched for this order's capabilities.
185
+ * Absent when the caller supplied no stamps. Hub → worker, NOT the separate
186
+ * worker → hub `serve_crews` narrowing advertisement.
187
+ */
188
+ crews?: string[];
189
+ /**
190
+ * The composed capabilities this order WOULD have been offered under, present
191
+ * only when a caller-supplied reroute rule substituted something else into
192
+ * `capabilities` above.
193
+ *
194
+ * Absent on every ordinary offer, so its presence is itself the signal that
195
+ * the order is not running on the capability its def asked for. Kept separate
196
+ * from `capabilities` rather than replacing it because both facts are true at
197
+ * once and an operator needs each for a different question: `capabilities`
198
+ * answers "what is serving this", `reroutedFrom` answers "what did we ask
199
+ * for". A single field could only ever answer one.
200
+ */
201
+ reroutedFrom?: string[];
177
202
  /**
178
203
  * The modifier this order was composed with. Normally the run's modifier;
179
204
  * on an escalated re-offer, the step's escalation target instead (the run's
@@ -189,10 +214,13 @@ export interface Order {
189
214
  *
190
215
  * The engine decides the transition; this flag is how the decision reaches
191
216
  * the layer that acts on it, instead of that layer re-deriving it by
192
- * diffing `modifier` against the run record. The hub reads it to apply the
193
- * escalation wait policy (wait-then-fallback, even where the deployment
194
- * default is `forever`); a brief reads it to tell the worker it is on the
195
- * recovery path.
217
+ * diffing `modifier` against the run record. A brief reads it to tell the
218
+ * worker it is on the recovery path.
219
+ *
220
+ * An escalated offer gets NO special wait or fallback treatment. It routes by
221
+ * exactly the same rules as any other offer, because "this run is recovering"
222
+ * is not evidence that its operator wants a lower grade of service — see
223
+ * `wait-policy.ts` in the hub.
196
224
  */
197
225
  escalated?: true;
198
226
  /** Opaque config object for a non-agent/non-command worker type (or
@@ -291,14 +319,18 @@ export interface WorkflowData {
291
319
  params?: Record<string, string>;
292
320
  /**
293
321
  * The ONE modifier this run carries, validated against the def's declared
294
- * `modifiers` set when the run is created and immutable thereafter — no
295
- * step, worker or judge can write it (only `start_run` sets it; escalation
296
- * overrides it per-offer without changing it here).
322
+ * `modifiers` set when the run is created. The starter supplies the initial
323
+ * value; after that, only the engine may replace it while accepting an
324
+ * artifact whose def-declared bind targets `modifier`. No step, worker, or
325
+ * judge writes it directly; escalation still overrides it per-offer without
326
+ * changing the stored value.
297
327
  *
298
328
  * Absent = an unmodified run: every step is offered on bare capabilities.
299
329
  * Deletes with the run, like the rest of the row.
300
330
  */
301
331
  modifier?: string;
332
+ /** Engine-written, non-routing metadata populated by artifact binds. */
333
+ meta?: Record<string, unknown>;
302
334
  /** Instance-to-definition pinning (§28): the compiled def this instance was
303
335
  * created against, snapshotted verbatim as JSON. Absent on rows created
304
336
  * before this feature shipped — those instances fall back to today's
@@ -339,6 +371,11 @@ export interface GroupDef {
339
371
  mode: GroupMode;
340
372
  of: string[];
341
373
  }
374
+ /** A normalized artifact-to-instance routing write declared on a produce. */
375
+ export interface ArtifactBind {
376
+ to: string;
377
+ from: string;
378
+ }
342
379
  /** A parsed produce declaration. */
343
380
  export interface ProducePattern {
344
381
  raw: string;
@@ -348,6 +385,8 @@ export interface ProducePattern {
348
385
  suffix: string;
349
386
  /** optional JSON Schema the produced value must satisfy at commit time (§19) */
350
387
  schema?: JsonSchema;
388
+ /** Optional normalized artifact-to-instance write applied on acceptance. */
389
+ bind?: ArtifactBind;
351
390
  /** §6/§18 per-produce override of the step's maxAttempts (judgment-reject
352
391
  * stall cap). Falls back to the owning step's maxAttempts when absent —
353
392
  * see model.ts effectiveMaxAttempts(). Only meaningful on {name,...}
@@ -412,6 +451,22 @@ export interface EffectDef {
412
451
  * Defaults to 'escalate' when idempotent:false and omitted. */
413
452
  onInvalidate?: 'pin' | 'escalate' | string;
414
453
  }
454
+ /**
455
+ * Declares that a step is cleanup: it must still be dispatched when the run is
456
+ * cancelled, not only on the normal green path.
457
+ *
458
+ * This is not a firing trigger. `on:`/`FiringTrigger` is the in-run scheduler's
459
+ * vocabulary, evaluated from artifact state and time facts. Run cancellation is
460
+ * neither of those, so `onCancel:` is inert in this engine: it is a declaration
461
+ * the control plane reads when it cancels a run.
462
+ */
463
+ export interface OnCancelDef {
464
+ /** The subset of the step's own plain consume stems the cancel-path firing
465
+ * requires. Required, may be empty. This is explicit because a cleanup
466
+ * step's normal consume set may include a terminal artifact that never
467
+ * greens after cancellation, and the control plane must not guess inputs. */
468
+ consumes: string[];
469
+ }
415
470
  /** A step (step) definition. */
416
471
  /**
417
472
  * A step's escalation rule (def-authored, engine-applied).
@@ -494,6 +549,8 @@ export interface StepDef {
494
549
  idleAfter?: string;
495
550
  /** Parsed idleAfter in milliseconds. */
496
551
  idleAfterMs?: number;
552
+ /** Cleanup-on-cancel declaration. Absent = no cancel-path dispatch. See OnCancelDef. */
553
+ onCancel?: OnCancelDef;
497
554
  /** Per-step reap TTL override in milliseconds. Falls back to the engine's DEFAULT_REAP_TTL_MS. */
498
555
  reapTtlMs?: number;
499
556
  /** A2: opaque routing capabilities for peer-orchestrator claim filtering. A tick
@@ -3,8 +3,7 @@
3
3
  * into the execution-side settings file.
4
4
  *
5
5
  * `owenloop work` reads its settings from `$OWENLOOP_CONFIG_DIR/settings.json`
6
- * (else `$XDG_CONFIG_HOME/owenloop/settings.json`, else
7
- * `$HOME/.config/owenloop/settings.json`) and, by design,
6
+ * (else `$HOME/.owenloop/settings.json`) and, by design,
8
7
  * NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
9
8
  * `owenloop setup` can point `owenloop work` at the hub it just authenticated
10
9
  * against.
@@ -26,8 +25,7 @@
26
25
  /**
27
26
  * The execution settings file path for this environment, through the one shared
28
27
  * ladder in `config-dir.ts`: `OWENLOOP_CONFIG_DIR` (absolute, used verbatim)
29
- * wins over `$XDG_CONFIG_HOME/owenloop`, which wins over
30
- * `$HOME/.config/owenloop`. Throws as a `CliError` when no rung yields a value,
28
+ * wins over `$HOME/.owenloop`. Throws as a `CliError` when no rung yields a value,
31
29
  * so the CLI reports it as an operator error rather than a crash.
32
30
  */
33
31
  export declare function owenloopSettingsPath(env: Record<string, string | undefined>): string;
@@ -3,8 +3,7 @@
3
3
  * into the execution-side settings file.
4
4
  *
5
5
  * `owenloop work` reads its settings from `$OWENLOOP_CONFIG_DIR/settings.json`
6
- * (else `$XDG_CONFIG_HOME/owenloop/settings.json`, else
7
- * `$HOME/.config/owenloop/settings.json`) and, by design,
6
+ * (else `$HOME/.owenloop/settings.json`) and, by design,
8
7
  * NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
9
8
  * `owenloop setup` can point `owenloop work` at the hub it just authenticated
10
9
  * against.
@@ -31,8 +30,7 @@ import { CliError } from "./util.js";
31
30
  /**
32
31
  * The execution settings file path for this environment, through the one shared
33
32
  * ladder in `config-dir.ts`: `OWENLOOP_CONFIG_DIR` (absolute, used verbatim)
34
- * wins over `$XDG_CONFIG_HOME/owenloop`, which wins over
35
- * `$HOME/.config/owenloop`. Throws as a `CliError` when no rung yields a value,
33
+ * wins over `$HOME/.owenloop`. Throws as a `CliError` when no rung yields a value,
36
34
  * so the CLI reports it as an operator error rather than a crash.
37
35
  */
38
36
  export function owenloopSettingsPath(env) {
@@ -2,9 +2,9 @@
2
2
 
3
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
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.
5
+ The runtime worker resolves the verified workflow definition from the local workflow store, selects the final harness after crew-roster selection and any CLI debug override, 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
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.
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` override or a selected crew-roster candidate.
8
8
 
9
9
  Native judge entries do not carry a separately authored `x` map. The definition
10
10
  compiler deep-clones the producer step's complete parsed `x` map onto every
package/docs/authoring.md CHANGED
@@ -41,7 +41,8 @@ steps:
41
41
  properties: { plan: { type: string } }
42
42
  # maxAttempts: 2 # optional; overrides the step's maxAttempts (below)
43
43
  # maxSchemaFailures: 1 # just for this produce — see design.md §6
44
- body: | # the prompt; ${WORKFLOW} ${RUN} ${INDEX} are filled in
44
+ # bind: modifier # accepted value's `modifier` key writes through to run routing
45
+ body: | # the prompt; runtime placeholders are filled in when available
45
46
  Read the proposal and produce a `plan`.
46
47
  bodyFile: path/to.md # load body from a file, relative to this workflow's dir (must resolve inside it); mutually exclusive with body
47
48
 
@@ -62,6 +63,8 @@ steps:
62
63
  onInvalidate: escalate # consulted only when idempotent: false (see below)
63
64
  on: [inputsGreen] # optional; firing trigger (see below)
64
65
  idleAfter: 30m # required when 'idle' is in on:
66
+ onCancel: # optional cleanup declaration (see below)
67
+ consumes: [workspace] # plain consume subset needed after cancellation
65
68
  invalidates: [plan] # which input stems this step may invalidate
66
69
  cadence: "0s" # min spacing between runs (e.g. "30m")
67
70
  maxRunsPerDay: 1000
@@ -225,7 +228,9 @@ full contract.
225
228
  A command step's `consumes:` reach the command through its environment, not its
226
229
  working directory: `owenloop work exec` sets `OWENLOOP_CONSUMES` with the JSON
227
230
  inline, or `OWENLOOP_CONSUMES_FILE` with a path to it once that JSON exceeds
228
- 64 KiB. See [`docs/bundles.md` § Consumed inputs for command
231
+ 64 KiB. The worker also supplies rejection feedback and the order's current
232
+ modifier through `OWENLOOP_FEEDBACK`/`OWENLOOP_FEEDBACK_FILE` and
233
+ `OWENLOOP_MODIFIER`. See [`docs/bundles.md` § Consumed inputs for command
229
234
  steps](bundles.md#consumed-inputs-for-command-steps) for the reader snippet and
230
235
  the omitted-key rule.
231
236
 
@@ -314,6 +319,57 @@ if nothing consumes it. A stem under `generates:` is deliberately consumed by no
314
319
  are otherwise identical: schema-validated, fingerprinted, greenable, and visible in
315
320
  `status`/`show`.
316
321
 
322
+ ## `bind:` — write an accepted artifact into run state
323
+
324
+ A produce mapping may declare a `bind:` target. When that artifact is accepted,
325
+ the engine writes the selected value into the run instance in the same
326
+ acceptance transaction. The artifact's own version and event history remains the
327
+ record of the value and any later rejection; the bind adds the engine's sync
328
+ event.
329
+
330
+ The short form reads the accepted object's key named after the final segment of
331
+ the target. Here, the producer submits an object such as
332
+ `{ modifier: 'deep' }`; `bind: modifier` reads its `modifier` key.
333
+
334
+ ```yaml
335
+ modifiers: [express, standard, deep]
336
+ steps:
337
+ - name: choose_modifier
338
+ produces:
339
+ - name: modifier
340
+ bind: modifier
341
+ ```
342
+
343
+ The mapping form selects a dotted object path. It is equivalent to the short
344
+ form when `from` is omitted: `bind: { to: meta.customer }` reads the
345
+ accepted object's `customer` key.
346
+
347
+ ```yaml
348
+ - { name: customer, bind: { to: meta.customer } }
349
+ - name: decision
350
+ bind: { to: modifier, from: payload.value }
351
+ ```
352
+
353
+ The two supported target families are:
354
+
355
+ - `modifier` — the extracted value must be one member of the workflow's
356
+ declared `modifiers:` list. A name with whitespace cannot be in that list
357
+ because `modifiers:` refuses it at definition-parse time. A workflow may bind
358
+ `modifier` only once. A value outside the list is refused at submit time.
359
+ - `meta.<key>` — writes any JSON value into non-routing instance metadata.
360
+ Metadata never changes capability composition or routing.
361
+
362
+ `from` is always a dot-separated path through object keys; there is no
363
+ whole-value form. Arrays, escaping, and array indexes are not part of this
364
+ grammar. A missing path is a submit-time refusal.
365
+ Bindings are supported on singleton and map produces, not collection produces.
366
+ Only a green acceptance applies the bind: a producer submission that is waiting
367
+ for judges has not synchronized the run yet.
368
+
369
+ When a capability-bearing step can run before the modifier-bound artifact is
370
+ accepted, lint warns that the step is not downstream of the bound artifact.
371
+ Wire the dependency explicitly if that step must use the synchronized modifier.
372
+
317
373
  ## `judges:` — quality gates before green
318
374
 
319
375
  A `produces` entry can declare one or more **judges**: deterministic quality
@@ -572,6 +628,38 @@ carry an empty input fingerprint, so a commit can never satisfy it, and
572
628
  relative `idleAfter` window and survives a process restart.
573
629
  `engine.nextAlarm(workflow)` tells an external scheduler when to wake the instance.
574
630
 
631
+ ## `onCancel:` — cleanup that survives cancellation
632
+
633
+ `onCancel:` declares that a step is cleanup a control plane should dispatch when
634
+ it cancels a run. It is **not** an `on:` firing trigger: the standalone engine
635
+ has no run-cancellation state and never schedules it. A host that supports
636
+ cancellation reads this declaration separately.
637
+
638
+ The declaration names the inputs needed on the cancel path:
639
+
640
+ ```yaml
641
+ - name: deprovisioner
642
+ consumes: [merge, workspace] # normal path
643
+ onCancel:
644
+ consumes: [workspace] # cancel path
645
+ ```
646
+
647
+ The subset is explicit because cancellation can leave a normal input permanently
648
+ non-green. In this example, `merge` is terminal and will not green after a
649
+ cancel, so the control plane must not guess whether to wait for it or omit it.
650
+
651
+ `onCancel:` must be a mapping with a required `consumes:` list; an empty list
652
+ is allowed. Each listed name must be one of the step's own plain consumes, and a
653
+ name may appear only once. Map (`[$i]`) and reduce (`[*]`) consumes are not
654
+ allowed because a cancellation firing is keyless and runs once. The key is not
655
+ valid on a `calls:` step. An `allGreen` or `idle` evaluator may carry
656
+ `onCancel:`, but because evaluators cannot consume inputs, its list must be
657
+ empty.
658
+
659
+ `terminal: true` and `onCancel:` are deliberately compatible. Whether running
660
+ a destructive step during cleanup is sensible is the workflow author's decision,
661
+ not an engine policy.
662
+
575
663
  ## Consume / produce grammar
576
664
 
577
665
  | pattern | role | fires |
package/docs/bundles.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # `.wnlp` bundle format
2
2
 
3
- A `.wnlp` file packages one versioned package namespace, one or more named workflow definitions, and the regular files those definitions reference. The physical format is a gzip-compressed POSIX/PAX tar archive. Packing the same source bytes and canonical executable-bit choices produces identical archive bytes.
3
+ A `.wnlp` file packages one versioned package namespace, one or more named workflow definitions, and the regular files those definitions reference. The physical format is a gzip-compressed POSIX/PAX tar archive. Packing the same source bytes and canonical executable-bit choices produces an identical uncompressed canonical tar and therefore an identical bundle digest. The gzip wrapper's compressed payload depends on the zlib implementation linked by the running Node process and is not part of the bundle identity.
4
4
 
5
5
  The bundle APIs are independent of the local workflow store and the network:
6
6
 
@@ -135,7 +135,7 @@ For every regular file:
135
135
  - Every entry's data padding, including the padding after a `PaxHeader` data record, is zero-filled.
136
136
  - The archive ends with exactly two zero blocks and no bytes after the terminator.
137
137
 
138
- The gzip wrapper uses compression level 9 and has no optional filename, comment, or extra fields. Gzip mtime bytes are zero, and gzip header byte 9 (the OS byte) is explicitly forced to zero so Darwin and Linux produce the same bytes.
138
+ The gzip wrapper uses compression level 9 and has no optional filename, comment, or extra fields. Its magic, CM, FLG, MTIME, and OS ranges (bytes 0-1, 2, 3, 4-7, and 9) are fixed; mtime is zero and header byte 9 (the OS byte) is explicitly forced to zero. XFL (byte 8) comes from the linked zlib implementation and is intentionally not normalized. The compressed payload itself varies with the linked zlib implementation and is not the bundle identity; see the def digest above.
139
139
 
140
140
  The canonical tar contains regular-file entries only. Parent directories are implied by `/`-separated file paths and are never emitted as tar entries. The strict reader rejects archive symlink, hardlink, device, FIFO, socket, directory, and unknown entry types. The packer rejects source symlinks and non-regular filesystem nodes. Absolute paths, `.` segments, and `..` traversal are refused rather than normalized.
141
141
 
@@ -255,6 +255,30 @@ consume-side verification under its hard rule and refuses the whole order when
255
255
  the consumed evidence is absent, unverifiable, or invalid, so the environment
256
256
  block is built only for an order whose inputs already verified.
257
257
 
258
+ ### Rejection feedback and modifier context
259
+
260
+ When an order has owed paths with non-empty reason threads, `owenloop work exec`
261
+ also supplies the feedback as a JSON array through one of these variables:
262
+
263
+ | Variable | Set when | Value |
264
+ | --- | --- | --- |
265
+ | `OWENLOOP_FEEDBACK` | serialized feedback is at or under 65536 bytes | inline array of `{path, reasons}` objects |
266
+ | `OWENLOOP_FEEDBACK_FILE` | serialized feedback is strictly larger | absolute path to a private `0600` UTF-8 file containing that array |
267
+
268
+ Exactly one feedback variable is present when feedback exists; both are removed
269
+ when there is no feedback, so a nested command cannot inherit a stale thread.
270
+ The overflow file is removed after the command exits. Each `reasons` entry is
271
+ the normal artifact reason shape and may include `requested`, the machine-readable
272
+ replacement requested for a bound modifier artifact.
273
+
274
+ `OWENLOOP_MODIFIER` is set to the modifier stamped on this order, including an
275
+ escalation target when the order is an escalated re-offer. It is absent when the
276
+ run has no modifier. This is order metadata, not an instruction to mutate the
277
+ run; only an accepted artifact with a declared bind can do that.
278
+
279
+ An agent prompt can read the same value as `${MODIFIER}`. Unknown placeholders
280
+ remain unchanged; when an order has no modifier, `${MODIFIER}` remains literal.
281
+
258
282
  ## Working directory for command steps
259
283
 
260
284
  An order carries a `workdir` when its step declared `workdir:` or
@@ -292,7 +316,9 @@ shift. See [`docs/shift-logs.md`](shift-logs.md) for the directory layout,
292
316
 
293
317
  The receipt still does not carry the warning, and that is by design rather than
294
318
  a gap: the receipt captures the **command's** streams, and this warning is the
295
- **exec worker's** own. One destination each, no duplication.
319
+ **exec worker's** own. The reverse is not symmetric: the worker also relays the
320
+ command's captured tail into its own output, so a command's last 4 KiB appears
321
+ in both the receipt and `<run>.log`. See [docs/shift-logs.md](shift-logs.md).
296
322
 
297
323
  Two consequences worth stating separately:
298
324