owenloop 0.5.8 → 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 (87) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +4 -2
  3. package/dist/packages/work/src/agent/loop.d.ts +23 -8
  4. package/dist/packages/work/src/agent/loop.js +48 -6
  5. package/dist/packages/work/src/consumed-verifier.js +6 -17
  6. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  7. package/dist/packages/work/src/exec/loop.js +181 -32
  8. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  9. package/dist/packages/work/src/exec/receipt.js +6 -6
  10. package/dist/packages/work/src/harness/claude.js +100 -0
  11. package/dist/packages/work/src/hub/client.d.ts +19 -4
  12. package/dist/packages/work/src/hub/client.js +7 -3
  13. package/dist/packages/work/src/hub/types.d.ts +84 -0
  14. package/dist/packages/work/src/main.js +1 -0
  15. package/dist/packages/work/src/roles/agent-run.js +19 -22
  16. package/dist/packages/work/src/roles/exec.js +2 -0
  17. package/dist/packages/work/src/roles/settings.js +2 -0
  18. package/dist/packages/work/src/roles/shift.js +14 -2
  19. package/dist/packages/work/src/roles/util.d.ts +1 -0
  20. package/dist/packages/work/src/roles/util.js +10 -0
  21. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  22. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  23. package/dist/packages/work/src/settings/roster.d.ts +84 -0
  24. package/dist/packages/work/src/settings/roster.js +364 -5
  25. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  26. package/dist/packages/work/src/settings/serving.js +79 -0
  27. package/dist/packages/work/src/settings/settings.d.ts +14 -1
  28. package/dist/packages/work/src/settings/settings.js +14 -0
  29. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  30. package/dist/packages/work/src/shift/loop.js +299 -51
  31. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  32. package/dist/packages/work/src/shift/runtime.d.ts +15 -0
  33. package/dist/packages/work/src/shift/runtime.js +94 -4
  34. package/dist/packages/work/src/shift/server.js +2 -0
  35. package/dist/packages/work/src/shift/spawn.d.ts +17 -2
  36. package/dist/packages/work/src/shift/spawn.js +16 -13
  37. package/dist/packages/work/src/shift/state.d.ts +29 -2
  38. package/dist/packages/work/src/shift/state.js +45 -15
  39. package/dist/packages/work/src/usage.d.ts +1 -1
  40. package/dist/packages/work/src/usage.js +7 -1
  41. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  42. package/dist/packages/work/src/util/modifier-init.js +73 -0
  43. package/dist/src/bundle/tar.d.ts +9 -4
  44. package/dist/src/bundle/tar.js +9 -4
  45. package/dist/src/capabilities.d.ts +6 -0
  46. package/dist/src/cli.d.ts +14 -1
  47. package/dist/src/cli.js +687 -75
  48. package/dist/src/config-dir.d.ts +1 -1
  49. package/dist/src/config-dir.js +1 -1
  50. package/dist/src/crypto/index.d.ts +1 -1
  51. package/dist/src/crypto/index.js +1 -1
  52. package/dist/src/crypto/org-root.d.ts +30 -12
  53. package/dist/src/crypto/org-root.js +162 -14
  54. package/dist/src/crypto/records.d.ts +2 -0
  55. package/dist/src/crypto/records.js +2 -0
  56. package/dist/src/defs.d.ts +6 -1
  57. package/dist/src/defs.js +203 -8
  58. package/dist/src/engine.d.ts +42 -7
  59. package/dist/src/engine.js +158 -16
  60. package/dist/src/index.d.ts +4 -4
  61. package/dist/src/index.js +2 -2
  62. package/dist/src/mcp/serve.d.ts +22 -0
  63. package/dist/src/mcp/serve.js +88 -8
  64. package/dist/src/model.d.ts +2 -0
  65. package/dist/src/model.js +32 -25
  66. package/dist/src/order-resolver.d.ts +1 -0
  67. package/dist/src/order-resolver.js +8 -1
  68. package/dist/src/schemas/index.d.ts +11 -0
  69. package/dist/src/schemas/order.v1.schema.json +7 -1
  70. package/dist/src/store.d.ts +5 -0
  71. package/dist/src/store.js +43 -8
  72. package/dist/src/types.d.ts +40 -3
  73. package/docs/authoring.md +90 -2
  74. package/docs/bundles.md +26 -2
  75. package/docs/cli.md +170 -28
  76. package/docs/crypto.md +19 -3
  77. package/docs/design.md +70 -1
  78. package/docs/routing.md +189 -34
  79. package/docs/shift-logs.md +20 -9
  80. package/docs/wire-contracts.md +50 -7
  81. package/examples/workflows/delivery.yaml +31 -14
  82. package/examples/workflows/ship.yaml +10 -2
  83. package/package.json +1 -1
  84. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  85. package/plugins/claude-code/plugin/.mcp.json +1 -1
  86. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  87. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
package/docs/routing.md CHANGED
@@ -11,7 +11,8 @@ the system. Every term is defined before it is used. Nothing is left implicit.
11
11
 
12
12
  ## 0. Status of this document
13
13
 
14
- Sections 1 through 8 describe behavior that is live today.
14
+ Sections 1 through 8 describe behavior that is live today, with one
15
+ explicitly marked exception inside section 8a.
15
16
 
16
17
  Section 9 (**When nobody is certified**) describes a rule that is CHANGING.
17
18
  Both the old rule and the new rule are stated, and it is marked which is which,
@@ -32,7 +33,7 @@ Use this mapping instead. It is exact, not a loose analogy.
32
33
  | Term | Think of it as | Who writes it | Where it lives |
33
34
  |---|---|---|---|
34
35
  | **capability** | a **job posting** | the workflow author | the workflow definition file (`delivery.yaml`) |
35
- | **modifier** | the **grade on the posting** | the person starting the run | chosen once at `start_run`, stored on the instance |
36
+ | **modifier** | the **grade on the posting** | the starter at `start_run`, then the engine through a declared artifact bind | the run instance; an optional bound artifact is the writer |
36
37
  | **crew** | a **team certified for that posting** | the hub operator | the hub's `capability_routes` table |
37
38
  | **shift** | a **team member clocking in** | whoever runs the machine | a local `settings.json` on that machine |
38
39
 
@@ -61,6 +62,14 @@ wrong:
61
62
  takes a list). On the staging hub every shift serves exactly one crew, so
62
63
  this shows the shape of the argument rather than a shift that exists today.
63
64
 
65
+ The final model choice is a separate **roster** cascade. A shift refreshes the
66
+ hub organization rosters into its local disk cache, then the spawned
67
+ `agent-run` child reads that cache offline. For a named crew the strongest-first
68
+ layers are machine `crews/<crew>.json`, machine `settings.json`, cached hub
69
+ crew roster, and cached hub org-global roster. The cached hub layers are
70
+ deliberately weakest; an unavailable cache is visible in `owenloop roster show`
71
+ but never makes a shift or order fail when a machine row can route it.
72
+
64
73
  ---
65
74
 
66
75
  ## 2. The three vocabularies, precisely
@@ -76,10 +85,14 @@ colon.
76
85
  capabilities: [build] # <- authored capability
77
86
  ```
78
87
 
79
- **Modifier** — one word, chosen once per run. The engine attaches *no meaning*
88
+ **Modifier** — one word, carried by the run instance. The starter supplies the
89
+ initial value; after that, a def-declared artifact bind is the only thing that
90
+ can change it (section 8a). The engine attaches *no meaning*
80
91
  to it. `deep` is not "more" than `express` as far as any code is concerned;
81
92
  they are just two different strings. A definition declares which ones it
82
- accepts:
93
+ accepts. One word is a rule, not a convention: `modifiers:` refuses a name
94
+ containing whitespace at definition-parse time (`parseModifiers` in
95
+ `src/defs.ts`), so a spaced name fails at publish rather than at bind:
83
96
 
84
97
  ```yaml
85
98
  modifiers: [express, standard, deep]
@@ -179,9 +192,6 @@ different model and effort instead. The operator must add an intentional
179
192
  `build:deep` row to the `anthropic` card as part of the same move.
180
193
 
181
194
  ### 3c. The crew roster — “what can this machine run?”
182
-
183
- “Roster” in this document means the **crew roster** used for capability
184
- routing, never the trust roster of signed grants in `~/.owenloop/roster/`.
185
195
  A machine's global fallback lives under the `roster` key in
186
196
  `~/.owenloop/settings.json`; a named crew's stronger layer is
187
197
  `~/.owenloop/crews/<crew>.json`. Both files use the same top-level shape:
@@ -212,14 +222,19 @@ candidate is `unresolvable-capability`.
212
222
 
213
223
  A shift start command names its crews, credentials, display identity, and
214
224
  state directory. It no longer carries an operator-selected harness or a
215
- per-shift config directory. The shift passes its positional crews to agent
216
- children internally; they try matching merged crew rosters in command-line
217
- order. This is an interim Phase-1 rule until the hub stamps matched crews on
218
- the order.
225
+ per-shift config directory. Its crews are the worker → hub
226
+ `serve_crews` narrowing advertisement. It also sends a derived
227
+ `serve_capabilities` advertisement: the sorted raw keys from its effective
228
+ merged rosters, with bare names and exact compounds mixed. `[]` means
229
+ "clocked in, serving nothing." This can only narrow offers; it never grants
230
+ authority, and the shift passes NO crews to agent children. **Today's hub
231
+ ignores `serve_capabilities`; the hub-side intersect ships separately.** For a
232
+ capability-bearing order, the hub stamps its matched crews on the order and the
233
+ agent resolves those rosters in the stamped order.
219
234
 
220
235
  | Name | What it selects |
221
236
  |---|---|
222
- | **crew** (positional) | which crew rosters the shift serves |
237
+ | **crew** (positional) | worker → hub `serve_crews` offer scope; the hub-stamped `order.crews` resolves the agent worker's roster sequence |
223
238
  | **`--as`** | which stored credential to authenticate with |
224
239
  | **`--name`** | a display label for this shift |
225
240
  | **`--state-dir`** | local socket and child-state storage |
@@ -240,18 +255,24 @@ owenloop start delivery --modifier deep \
240
255
  --provide target='{"path":"/Users/alex/code/owenloop"}'
241
256
  ```
242
257
 
243
- The hub creates an instance and stores `modifier = "deep"` on it. **This value
244
- is set once and never changes for the life of the run.** There is no verb that
245
- updates it.
258
+ The hub creates an instance and stores `modifier = "deep"` on it as the run's
259
+ initial hint. A def may later declare one artifact with `bind: modifier`; when
260
+ that artifact is accepted, the engine synchronizes the instance's modifier in
261
+ the same acceptance transaction. There is still no general-purpose verb that
262
+ lets a worker write the column.
246
263
 
247
264
  **Step 2 — a shift asks for work.**
248
265
 
249
266
  The `openai-1` shift calls the hub verb `whats_next`, authenticating as
250
- account `shift-openai-1`.
267
+ account `shift-openai-1`. Alongside its `serve_crews` scope it sends
268
+ `serve_capabilities`: raw keys from the merged roster cascade. A bare key is
269
+ not expanded locally, because the shift does not know the modifier vocabulary.
251
270
 
252
- **Step 3 — the hub works out what this caller can do.**
271
+ **Step 3 — the hub works out what this caller is authorized to do today.**
253
272
 
254
- The hub does *not* read anything the shift sent about its abilities. Instead:
273
+ Today's hub still ignores the shift's `serve_capabilities` field. The
274
+ hub-side intersect-before-match is a separately shipped follow-up. Instead,
275
+ the current hub:
255
276
 
256
277
  - it looks up which crews the account `shift-openai-1` belongs to;
257
278
  - it reads every `capability_routes` row for those crews;
@@ -269,8 +290,9 @@ The function is `listCapabilitiesForCrews(storage, memberCrewIds)`. For the
269
290
  The strings are shown alphabetically for readability; their order is not
270
291
  significant.
271
292
 
272
- This is why point 3 in section 1 matters: **eligibility comes entirely from
273
- crew membership.** A shift cannot claim, declare, or negotiate a capability.
293
+ This is why point 3 in section 1 matters: **authority comes entirely from crew
294
+ membership.** A shift can advertise a local offer filter, but cannot claim,
295
+ declare, or negotiate authority for a capability.
274
296
 
275
297
  **Step 4 — the engine composes the posting.**
276
298
 
@@ -309,18 +331,20 @@ sets do not overlap at all, which is exactly what it looks like when
309
331
  eligibility comes entirely from crew membership and the crews are named after
310
332
  teams.
311
333
 
312
- **Step 7 — the shift picks the model.**
334
+ **Step 7 — the worker picks the model.**
313
335
 
314
- The `openai-1` shift reads `order.capabilities` — `['build:deep']` — and
315
- looks it up in its merged crew roster:
336
+ The agent reads `order.capabilities` — `['build:deep']` — plus the hub →
337
+ worker `order.crews` stamp, and resolves those merged crew rosters in order:
316
338
 
317
339
  1. Try the **exact compound**: `build:deep` → an ordered candidate array. Found.
318
340
  2. If not found, try the **bare name part**: `build`.
319
- 3. If neither is found, the shift **refuses the order** with
341
+ 3. If neither is found, the worker **refuses the order** with
320
342
  `unresolvable-capability` and the hub re-offers it.
321
343
 
322
- That third case is a real, deliberate refusal, not a crash. A shift that has no
323
- rate for a job does not guess a model.
344
+ An absent, empty, malformed, or unreadable crew stamp is also refused and
345
+ released; there is no fallback to the crews the shift was started with. These
346
+ are real, deliberate refusals, not crashes. A worker that has no rate for a job
347
+ does not guess a model.
324
348
 
325
349
  **Step 8 — the harness runs it.**
326
350
 
@@ -420,10 +444,134 @@ Four properties, all easy to get wrong:
420
444
  The order carries a marker, `order.escalated = true`, so a reader can tell an
421
445
  escalated re-offer from an ordinary one.
422
446
 
423
- **A planner cannot upgrade the run's grade.** That feature does not exist. The
424
- modifier is set at `start_run` and there is no code path that updates it. A
425
- planner that thinks the human picked the wrong depth says so in its plan
426
- document; it does not reroute itself.
447
+ Escalation moves one offer. It never rewrites the run's stored modifier. There
448
+ is a separate mechanism that does, and it is the only one.
449
+
450
+ ### 8a. The modifier bind — the engine's only post-start writer
451
+
452
+ A workflow definition can declare that one artifact **carries** the run's
453
+ modifier. When that artifact is accepted, the engine writes its value onto the
454
+ run instance. The declaration lives on the produce:
455
+
456
+ ```yaml
457
+ modifiers: [express, standard, deep]
458
+
459
+ steps:
460
+ - name: init
461
+ executor: command
462
+ capabilities: [init]
463
+ command: >-
464
+ value="$(owenloop util modifier-init --default standard)" &&
465
+ node -e 'console.log("##owenloop:payload##" +
466
+ JSON.stringify({value: process.argv[1]}))' "$value"
467
+ produces:
468
+ - name: modifier
469
+ bind: { to: modifier, from: payload.value }
470
+ ```
471
+
472
+ Read: *when `modifier` is accepted, set the run's modifier to the `payload.value`
473
+ field of the accepted value.* The full authoring grammar — the short form, the
474
+ `meta.<key>` target family, the dot-path rules — is in
475
+ [`docs/authoring.md`](authoring.md#bind--write-an-accepted-artifact-into-run-state).
476
+ What follows is what the mechanism *means* for routing.
477
+
478
+ Five properties, in the order they matter:
479
+
480
+ 1. **A `modifier` bind requires the def to declare `modifiers:`.** Without it,
481
+ loading the definition fails: `step '<step>' produce '<stem>' binds modifier
482
+ but workflow '<def>' declares no modifiers:` (`src/defs.ts`). A definition may
483
+ bind `modifier` at most once — a second one is
484
+ `workflow '<def>' binds modifier more than once`. The only other legal target
485
+ family is `bind: meta.<key>`, which writes non-routing instance metadata and
486
+ never touches capability composition. Binding is available on singleton and
487
+ per-element (map) produces; it is refused on collection produces and on
488
+ `calls:` outcomes.
489
+
490
+ 2. **The engine is the only writer.** No agent, step, worker, judge, or human
491
+ writes the run's modifier directly. The write goes through one private engine
492
+ method, `applyArtifactBind` (`src/engine.ts`), into one store method,
493
+ `setWorkflowRouting` (`src/store.ts`) — and those are the only two production
494
+ call sites of that store method under `src/`. There is no verb, flag, or MCP
495
+ call that sets it. `--modifier` at `start_run` supplies the initial value and
496
+ nothing after that.
497
+
498
+ 3. **The write happens inside the artifact-acceptance transaction.** The
499
+ modifier changes **if and only if** the bound artifact reaches green — by a
500
+ producer commit on a produce with no judges, by the last judge's approval, or
501
+ by a human `green`. All three branches run inside the same `store.tx()` that
502
+ writes the artifact, so acceptance and the routing write commit together or
503
+ neither happens. A submission still waiting on judges has synchronized
504
+ nothing. A value outside the declared set is refused before its accepted value
505
+ or green transition is written: a producer commit records the artifact as
506
+ `rejected`, comes back `schema-rejected`, and burns a schema attempt; a human
507
+ `green` throws `ModifierRefusalError` — the same refusal `start_run` uses.
508
+
509
+ 4. **The lever for changing it is rejecting the bound artifact with
510
+ `requested:`.**
511
+
512
+ ```bash
513
+ owenloop reject <wf> modifier --by planner --text "this needs deep review" \
514
+ --requested deep
515
+ ```
516
+
517
+ The engine validates `deep` against the definition's declared `modifiers:` at
518
+ **reject** time, not later: an undeclared value throws
519
+ `ModifierRefusalError` and nothing is written at all. A `--requested` on an
520
+ artifact that is not bound to `modifier` is refused outright. The validated
521
+ value is then carried on the rejection's reason entry, and reaches the
522
+ producer's next order as `owes[].reasons[].requested` — and, for a command
523
+ step, through `OWENLOOP_FEEDBACK` (see
524
+ [`docs/bundles.md`](bundles.md#rejection-feedback-and-modifier-context)).
525
+ `requested` is a **request to the producer**, not a write. The producer
526
+ re-emits; only the acceptance of that new value moves the run.
527
+
528
+ **Who may pull the lever is the ordinary authority rule, unchanged.** `human`
529
+ and `engine` may always reject. A judge step may reject only the stem named in
530
+ its own `judges:` marker. Any other step may reject only an artifact it
531
+ declares in `consumes:`. So a planner that is meant to ask for a different
532
+ grade must declare `consumes: [modifier]` in the definition; a planner with no
533
+ such edge cannot reject it and can only say so in its plan document.
534
+
535
+ 5. **The record of what changed is the artifact history.** Each accepted sync
536
+ writes exactly one artifact event: `action: bound`, `actor: engine`,
537
+ `version: 0`, `metadata: { from, to }`, where `from` is `null` when the target
538
+ had no prior value. `Store.getArtifactHistory(workflow, path)` surfaces those
539
+ in its artifact-level `events` bucket. The event is idempotent by
540
+ construction, keyed on the accepted artifact version, so one acceptance can
541
+ only ever produce one row. The second half of the record is per-offer:
542
+ `order.modifier` is stamped on every order, so an order always says which
543
+ grade that firing actually ran under.
544
+
545
+ **What the binding does not do.** It is ordinary dataflow, not a hidden reroute.
546
+ The engine reads the run's current modifier at tick time and composes each offer
547
+ from it, so claims already in flight finish under the modifier stamped on their
548
+ own orders, and only offers composed *after* the sync see the new value. A
549
+ capability-bearing step that is not downstream of the bound artifact can
550
+ therefore be offered on the old grade. `lintDef` warns about exactly that:
551
+ `step '<name>' declares capabilities (…) but is not downstream of artifact
552
+ '<path>' bound to modifier`. If a step must run at the synchronized grade, wire
553
+ the dependency explicitly — make it consume the bound artifact.
554
+
555
+ **Escalation and the bind are separate mechanisms over related state.**
556
+ Escalation is derived per offer from a reject count and leaves the stored
557
+ modifier alone. The bind rewrites the stored modifier; that value can determine
558
+ whether an otherwise eligible escalation target differs and therefore whether
559
+ escalation applies. A run can do both. An escalated offer stamps the escalation
560
+ target on `order.modifier` for that one firing; the next ordinary offer composes
561
+ from the run's stored value again — whatever the last accepted bind left there.
562
+
563
+ **Command producers: bind the payload, not the receipt.** A command step's
564
+ accepted artifact value is the whole `CommandReceipt`. The short form
565
+ `bind: modifier` is shorthand for `{to: modifier, from: modifier}`. A
566
+ `CommandReceipt` has no top-level `modifier` key, so that derived path does
567
+ not resolve and the submit is refused. Have the command emit a payload marker —
568
+ `##owenloop:payload##{"value":"deep"}` — and bind `from: payload.value`.
569
+
570
+ > **Not shipped.** The routing plan also calls for a hub-side routing alert of
571
+ > kind `modifier-changed`, raised on each sync so an operator sees it. It exists
572
+ > in neither `owenloop` nor `owenloop-service` today. When it lands it is a
573
+ > notification for operator attention — the artifact history above stays the
574
+ > system of record, and an alert must never be read as one.
427
575
 
428
576
  ---
429
577
 
@@ -568,11 +716,13 @@ Each of these has actually happened. Each has a one-line correction.
568
716
  | "Name the crew after the job it performs — call the crew that builds `build`." | A crew is named after the **team**, never after the job. When `build` is both a capability and a crew name the two lookups become invisible, and the reader cannot tell the hub-side routing table (`capability_routes`) from the shift-side rate card (`roster`). Name crews `anthropic` and `openai`. |
569
717
  | "The capability says which model to use." | It says which *job*. The model comes from the shift's local `settings.json`, at the very last step. |
570
718
  | "`build:deep` belongs to the openai crew." | No — `build:deep` is *certified to* the `openai` crew. Certify a second crew for it and both are eligible. Nothing owns it. |
571
- | "A shift declares its capabilities." | It declares its **crew**. The hub derives capabilities from crew membership via `listCapabilitiesForCrews`. |
719
+ | "A shift declares its capabilities." | A shift now advertises raw merged-roster keys as an offer filter, but that never grants authority. Authority remains crew-derived, and the worker's refusal backstop is unchanged. Today's hub ignores the field; the intersect ships separately. |
720
+ | "The shift's positional crews decide an agent worker's roster." | No. They only advertise worker → hub `serve_crews`; the hub-stamped `order.crews` list resolves each capability-bearing order's roster sequence. |
572
721
  | "The shift that is clocked in has no rate for `build:deep`, so serve it something else." | Do not serve it at all. Certify the crew that *can* do it. That is what the binding is for. |
573
722
  | "`--modifier` defaults to standard." | Omitting it means **no modifier**. Steps are offered on bare authored capabilities. |
574
723
  | "A modifier means 'more effort'." | To the engine it is an opaque string. All meaning lives in the shift's `roster` map. |
575
- | "A planner can decide the run needs to go deeper." | It can *say so*. It cannot change the run's modifier — no code path does. |
724
+ | "A planner can decide the run needs to go deeper." | Only where the definition declares `modifiers:`, binds an artifact to `modifier`, and the planner **consumes** that artifact. Then it rejects it with `--requested deep`, the producer re-emits, and the **engine** — never the planner — writes the run's modifier when that artifact is accepted. With no such wiring the planner can still only say so in its plan document (section 8a). |
725
+ | "The bind means my step writes the run's modifier." | No step writes it. The engine does, inside the acceptance transaction of the bound artifact. `--requested` on a reject is a validated *request* to that artifact's producer, not a write — and it is refused outright on any artifact that is not bound to `modifier`. |
576
726
  | "Escalation upgrades the run." | It re-offers **one step**, temporarily. The run's stored modifier is untouched. |
577
727
  | "If nobody serves the compound, close enough is fine." | Not any more. It holds and alerts. Substitution is something the operator configures on purpose (section 10). |
578
728
  | "Two harnesses in one crew gives me control over which model runs." | It gives you *either* model. First claim wins. Use separate crews when you need a guarantee. |
@@ -584,19 +734,24 @@ Each of these has actually happened. Each has a one-line correction.
584
734
  ```
585
735
  delivery.yaml steps: [{ name: builder, capabilities: [build] }]
586
736
  |
587
- owenloop start --modifier deep (stored once, never changes)
737
+ owenloop start --modifier standard (initial hint; a bind may later change it)
738
+ |
739
+ bound artifact accepted -> engine syncs the run modifier (audited in its history)
588
740
  |
589
741
  engine composes build + deep -> "build:deep"
590
742
  |
591
743
  hub reads capability_routes: build:deep -> crew "openai"
592
744
  |
593
745
  hub derives caller set from the asking shift's crew memberships
746
+ shift sends serve_crews plus raw merged-roster serve_capabilities
747
+ (today's hub ignores serve_capabilities; the intersect ships separately)
594
748
  |
595
749
  match: exact -> only crews certified for "build:deep" may claim
596
750
  |
597
751
  the openai-1 shift claims; order.capabilities = ["build:deep"]
752
+ order.crews = ["openai"]
598
753
  |
599
- shift merges its crew roster:
754
+ agent resolves the stamped crew roster:
600
755
  "build:deep": [{ harness: codex, model: gpt-5.6-terra, effort: xhigh }]
601
756
  |
602
757
  the selected candidate spawns that model at that effort
@@ -27,19 +27,27 @@ Do not collapse these — the rest of this page depends on telling them apart.
27
27
  stderr are what `<run>.log` holds.
28
28
  3. **The command a worker runs** — the `command:` text of a command step,
29
29
  executed by the worker under `/bin/sh -c`. **Its** streams are captured into
30
- the receipt the worker submits to the hub, and the worker relays the captured
31
- tail (≤4 KiB) into its own output so a copy reaches `<run>.log`.
30
+ the `CommandReceipt`. On success, the worker submits that receipt to the hub;
31
+ on failure, it sends the receipt as diagnostic context on an `ask` and
32
+ submits no artifact. In both cases the worker relays the captured tail (≤4
33
+ KiB) into its own output so a copy reaches `<run>.log`.
32
34
 
33
35
  The worker never **inherits** the command's streams. Every relayed line carries
34
- the literal ` | ` prefix. Both the receipt and `<run>.log` contain the
35
- captured tail; full streams are represented only by the receipt's output hash
36
- and stdout/stderr byte counts.
36
+ the literal ` | ` prefix. The receipt and `<run>.log` contain the captured
37
+ tail; for a failed command, the receipt is ask context rather than an artifact.
38
+ Full streams are represented only by the receipt's output hash and stdout/stderr
39
+ byte counts.
37
40
 
38
41
  | Command outcome | Worker channel | Header |
39
42
  | --- | --- | --- |
40
43
  | exit 0 and no machinery error | stdout | `… the command for step 'X' succeeded; its output follows` |
41
44
  | anything else | stderr | `… the command for step 'X' exited N` / `was killed by …` / `could not be run (…)`; `its last output follows` |
42
45
 
46
+ An ordinary command that fails raises an `ask` on its first owed path with the
47
+ receipt and captured output as diagnostics. Nothing is greened, and the owed
48
+ artifact waits for a human retry; additional owed paths remain debts because
49
+ `ask` closes the run.
50
+
43
51
  Under shift dispatch fd 1 and fd 2 both point at the same file, so the header —
44
52
  not the channel — is what tells these outcomes apart in `<run>.log`. The two
45
53
  channels still matter: stderr is what a reader treats as trouble, and routine
@@ -179,9 +187,9 @@ Two properties an uploader can rely on:
179
187
  | `reaped` | `workflow`, `run`, `kind`, `pid` | a worker exited and was collected |
180
188
  | `failed` | `workflow`, `run`, `step`, `kind`, `message`, and — from the exit path only — `executable`, `exitStatus`, `signal`, optional `harness` | a worker died or could not be spawned; **two producers, two shapes** — see below |
181
189
  | `capacity` | `inFlight`, `cap` | no free slot, so the `whats_next` sweep was deferred — explains a shift running nothing new while work is outstanding. **Edge-triggered**, and emitted only on a *changed* wake — see below |
182
- | `hub-error` | `op` (`wake`\|`whats_next`), `message`, optional `workflow` | a hub call failed. `workflow` present = the targeted `whats_next` for that one workflow; `workflow` absent with `op: 'whats_next'` = the untargeted inbox call, which aborts the whole sweep. **File-only** — see below |
190
+ | `hub-error` | `op` (`wake`\|`whats_next`\|`roster_sync`\|`release`), `message`, optional `workflow` | a hub call failed. `workflow` present = the targeted `whats_next` or release for that one workflow; `workflow` absent with `op: 'whats_next'` = the untargeted inbox call, which aborts the whole sweep. `op: 'roster_sync'` records the non-fatal startup or periodic hub-roster refresh failure. `op: 'release'` means returning an undispatchable claim failed, so it will instead wait for pickup expiry. **File-only** — see below |
183
191
  | `bundle-miss` | `workflow`, `def` | a legacy order named a def with no cached bundle |
184
- | `order-dropped` | `workflow`, `run`, `step`, `reason`, `message` | the shift refused one order and left it for hub pickup |
192
+ | `order-dropped` | `workflow`, `run`, `step`, `reason`, `message` | the shift refused one order; capacity and expiry reasons return the claim to the hub while malformed and unsupported reasons leave it for pickup |
185
193
  | `event-queue-overflow` | `dropped` | the socket FIFO evicted events; see below |
186
194
  | `ended` | — | an operator ran `owenloop shift end` |
187
195
  | `gate` | optional `workflow`, `run`, `name`, `question` | reserved; not emitted today |
@@ -250,8 +258,11 @@ one.
250
258
 
251
259
  `order-dropped.reason` is the stable machine discriminator and is one of
252
260
  `malformed-digest`, `malformed-worker`, `unsupported-worker`,
253
- `verification-failed`, `metadata-unavailable`. `message` is human text — match
254
- on `reason`, display `message`.
261
+ `verification-failed`, `metadata-unavailable`, `agent-lane-closed`,
262
+ `dispatch-cap-full`, `agent-cap-full`, or `claim-expired`. The capacity,
263
+ expiry, and `agent-lane-closed` reasons return the claim to the hub; malformed
264
+ and unsupported reasons leave it for the pickup window. `message` is human
265
+ text — match on `reason`, display `message`.
255
266
 
256
267
  ### The first record is self-describing
257
268
 
@@ -295,17 +295,20 @@ Required fields are `run`, `workflow`, `step`, `key`, `defDigest`, `inputs`,
295
295
  `outputs`, `consumes`, and `owes`.
296
296
 
297
297
  Optional fields are `index`, `workdir`, `model`, `worker`, `judge`, `spec`, `x`,
298
- `consumedFingerprint`, `consumesProof`, and `cause`. `workdir` may be authored
299
- as a literal `workdir:` or resolved by the engine from a step's `workdirFrom:`,
300
- whose stem names either a consumed artifact or a declared input; the Order wire
301
- shape remains unchanged. No proof field covers `workdir` in any case.
298
+ `consumedFingerprint`, `consumesProof`, `cause`, `capabilities`, `crews`,
299
+ `reroutedFrom`, `modifier`, and `escalated`. `workdir` may be authored as a
300
+ literal `workdir:` or resolved by the engine from a step's `workdirFrom:`, whose
301
+ stem names either a consumed artifact or a declared input; the Order wire shape
302
+ remains unchanged. No proof field covers `workdir` in any case.
302
303
 
303
304
  `defDigest` is a non-empty opaque reference. `inputs` and `outputs` are string
304
305
  arrays. `consumes` is an open artifact-path map; `spec` and `x` are opaque
305
306
  objects carried through without engine interpretation. `owes` contains the owed
306
307
  path, an optional target `version` (the version the next successful commit for
307
308
  that path lands, issued inside the claim transaction), judgment/schema rejection
308
- counters, reason entries, and an optional opaque `proof` string. `cause`, when present, is
309
+ counters, reason entries, and an optional opaque `proof` string. A reason entry
310
+ may also carry optional `requested`, the validated replacement value requested
311
+ when rejecting an artifact bound to the run's modifier. `cause`, when present, is
309
312
  `inputsGreen`, `allGreen`, or `idle`.
310
313
 
311
314
  **Decision A — version cross-check without fingerprint recomputation.** The
@@ -381,8 +384,48 @@ out of the `CommandReceipt`; malformed or over-cap JSON produces
381
384
  `payloadError` and no `payload`, while leaving the command exit code unchanged.
382
385
  When the hub supplies authoritative output-version metadata and the driver can
383
386
  sign, the parsed payload is part of the receipt value covered by the DSSE
384
- submission proof. Current producer command receipts are unsigned because the
385
- deployed hub does not supply a retry-safe target version.
387
+ submission proof. Current successful producer command receipts are unsigned
388
+ because the deployed hub does not supply a retry-safe target version.
389
+
390
+ An ordinary command submits its complete `CommandReceipt` only when it exits
391
+ successfully without a machinery error. A non-zero exit or machinery error is
392
+ not submitted as an artifact; the worker escalates it through `ask` on the
393
+ first owed path instead:
394
+
395
+ ```json
396
+ {
397
+ "workflow": "<workflow>",
398
+ "run": "<run>",
399
+ "path": "<owed artifact path>",
400
+ "question": "<operator-facing failure diagnosis>",
401
+ "context": "<JSON-encoded CommandReceipt>"
402
+ }
403
+ ```
404
+
405
+ The question identifies the command, exit code or signal, machinery error when
406
+ present, output byte counts, output hash, and captured output tail. The receipt
407
+ in `context` is diagnostic data, not a submitted value. A successful `ask`
408
+ freezes the owed artifact and closes the run; a human answers with the
409
+ artifact's retry path. Only the first owed path is escalated because `ask`
410
+ closes the run, so additional owed paths remain debts.
411
+
412
+ When a valid payload contains a plain-step `reject`, the command worker sends
413
+ the directive's `text` as the reject reason and, when command output is
414
+ available, appends the captured tail in this form:
415
+
416
+ ```text
417
+ <text>
418
+
419
+ --- command output (last <N> bytes) ---
420
+ <tail>
421
+ ```
422
+
423
+ The tail is the last 4 KiB of combined stdout-then-stderr output, decoded as
424
+ lossy UTF-8, with trailing newline characters removed before the byte count is
425
+ computed. `N` is the UTF-8 byte count of that trimmed tail. An empty tail leaves
426
+ the directive's text unchanged. The payload marker line is not removed from
427
+ the tail. This augmentation applies to payload rejects; judge rejects retain
428
+ their existing text-selection behavior.
386
429
 
387
430
  A worker rejects an artifact through the `reject` verb. The request is exactly:
388
431
 
@@ -1,23 +1,40 @@
1
- # Software-delivery wiring.
1
+ # Software-delivery wiring — a TEACHING EXAMPLE, not a production workflow.
2
2
  #
3
- # A linear pipeline where each step consumes the previous one's output and owes
4
- # the next. The interesting dynamics are the *knock-backs*: the reviewer can
5
- # reject the PR (re-arming the builder), and any upstream change cascades
6
- # forward — a re-planned `plan` invalidates the `pr`, its `verdict`, and the
7
- # `merge` automatically (the forward cascade, §7). The `merge` is terminal: once
8
- # green it is a destructive completion and can never be re-armed (§15.2).
3
+ # This file exists to show the engine's core dynamics in the fewest possible
4
+ # steps. It is NOT the delivery line this project's authors actually run, and
5
+ # it is not a copy of any deployed definition. The real one is a separately
6
+ # published workflow bundle named `owenloop-delivery`: an order of magnitude
7
+ # larger, with provisioner/deprovisioner lifecycle steps, a merge gate, mentor
8
+ # consults, capability routing and run modifiers. For an in-repo definition
9
+ # shaped like a real production line, read `ship.yaml` next door.
10
+ #
11
+ # What this one teaches: a linear pipeline where each step consumes the
12
+ # previous one's output and owes the next. The interesting dynamics are the
13
+ # *knock-backs* — the reviewer can reject the PR (re-arming the builder), and
14
+ # any upstream change cascades forward: a re-planned `plan` invalidates the
15
+ # `pr`, its `verdict`, and the `merge` automatically (the forward cascade, §7).
16
+ # The `merge` is terminal: once green it is a destructive completion and can
17
+ # never be re-armed (§15.2).
18
+ #
19
+ # Drive it (play every Step Agent yourself):
20
+ # export OWENLOOP_DEFS=examples/workflows
21
+ # export OWENLOOP_DB=/tmp/owenloop-delivery-demo.db
9
22
  #
10
- # Drive it (the "wiring" / worker step):
11
23
  # wf=$(owenloop create delivery --provide proposal='{"text":"add dark mode"}' | jq -r .workflow)
12
- # owenloop tick $wf # -> an order for `planner`
13
- # owenloop green $wf <run> plan --value '{"plan":"..."}'
14
- # ... # tick/green down the chain
24
+ # run=$(owenloop tick $wf | jq -r '.orders[0].run') # -> the `planner` order
25
+ # owenloop green $wf $run plan --value '{"plan":"..."}'
26
+ # owenloop close $wf $run
27
+ # ... # tick/green/close down the chain
15
28
  # owenloop reject $wf pr --by reviewer --text "tests missing" # knock-back
16
- # owenloop status $wf # debts / eligible / blocked
29
+ # owenloop status $wf # done / debts / eligible / blocked / pending / inFlight
17
30
 
18
31
  name: delivery
19
- title: Software delivery
20
- description: Plan → build → review → merge, with reviewer knock-backs.
32
+ title: Software delivery (teaching example)
33
+ description: >-
34
+ Plan → build → review → merge, with reviewer knock-backs. A minimal wiring
35
+ written to teach the engine's dynamics — not the production delivery line
36
+ (that is the separately published `owenloop-delivery` bundle); see ship.yaml
37
+ for a production-shaped definition.
21
38
  outputs: [merge]
22
39
 
23
40
  inputs:
@@ -6,8 +6,9 @@
6
6
  # plan + provision → build → review → document → check → merge → clean up
7
7
  #
8
8
  # This is the grown-up sibling of delivery.yaml (which teaches the wiring in
9
- # four steps). It's the line the authors actually run their own changes down,
10
- # genericized: full artifact schemas, tiered models, honest escalation, and —
9
+ # four steps). It's modeled on the line the authors actually run their own
10
+ # changes down, genericized and trimmed: full artifact schemas, tiered models,
11
+ # honest escalation, and —
11
12
  # the part most pipelines get wrong — the machine lifecycle as first-class
12
13
  # steps. `provisioner` stands up the branch/worktree BEFORE the builder starts
13
14
  # and owns it as the `workspace` artifact; `deprovisioner` reclaims it AFTER
@@ -342,6 +343,9 @@ steps:
342
343
  branch: { type: string, minLength: 1 }
343
344
  worktreePath: { type: string }
344
345
  on: [inputsGreen] # fires exactly once when merge (terminal) AND workspace are green
346
+ onCancel:
347
+ consumes: [workspace] # cancelling must still reclaim the machine. merge is deliberately
348
+ # absent: it is terminal and never greens on a cancelled run.
345
349
  model: fast # mechanical git teardown
346
350
  reapTtl: 15m
347
351
  body: |
@@ -369,3 +373,7 @@ steps:
369
373
  time, so the artifact would be born-rejected on every firing. With
370
374
  inputsGreen the fingerprint matches and, once green, re-firing is
371
375
  suppressed because `merge` is terminal — so this runs exactly once.)
376
+
377
+ (Cancellation note: `onCancel:` is inert in the standalone engine. A
378
+ control plane that supports cancellation reads it to dispatch this
379
+ cleanup step with only the declared cancel-path inputs.)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.8",
3
+ "version": "0.5.9",
4
4
  "description": "Deterministic rails for agentic workflows. Declare steps and dependencies; the engine guarantees order, redoes what changes invalidate, and stops what keeps failing — instead of hoping the agent follows through.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "typicalday",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.8",
3
+ "version": "0.5.9",
4
4
  "description": "Claude Code driver for owenloop — cross-harness shift and conduct skills driven by the owenloop CLI, plus one hub control-plane MCP server backing an author skill and a fallback worker, for conducting and authoring workflows against your hosted owenloop server.",
5
5
  "author": {
6
6
  "name": "Typical Day"
@@ -7,7 +7,7 @@
7
7
  "mcp"
8
8
  ],
9
9
  "env": {
10
- "OWENLOOP_PLUGIN_VERSION": "0.5.8"
10
+ "OWENLOOP_PLUGIN_VERSION": "0.5.9"
11
11
  }
12
12
  }
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.8",
3
+ "version": "0.5.9",
4
4
  "description": "Codex plugin for the owenloop workflow engine.",
5
5
  "skills": "./skills/",
6
6
  "mcpServers": "./.mcp.json"
@@ -6,7 +6,7 @@
6
6
  "mcp"
7
7
  ],
8
8
  "env": {
9
- "OWENLOOP_PLUGIN_VERSION": "0.5.8"
9
+ "OWENLOOP_PLUGIN_VERSION": "0.5.9"
10
10
  },
11
11
  "env_vars": [
12
12
  "HOME",