owenloop 0.5.8 → 0.5.10

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 (131) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.md +81 -39
  3. package/bin/owenloop.mjs +16 -1
  4. package/dist/packages/work/src/agent/loop.d.ts +23 -8
  5. package/dist/packages/work/src/agent/loop.js +55 -6
  6. package/dist/packages/work/src/bundle/pull.d.ts +21 -0
  7. package/dist/packages/work/src/bundle/pull.js +118 -0
  8. package/dist/packages/work/src/consumed-verifier.js +6 -17
  9. package/dist/packages/work/src/exec/instructions.d.ts +4 -1
  10. package/dist/packages/work/src/exec/instructions.js +3 -0
  11. package/dist/packages/work/src/exec/loop.d.ts +2 -2
  12. package/dist/packages/work/src/exec/loop.js +273 -46
  13. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  14. package/dist/packages/work/src/exec/receipt.js +6 -6
  15. package/dist/packages/work/src/harness/claude.js +116 -0
  16. package/dist/packages/work/src/harness/codex.d.ts +8 -0
  17. package/dist/packages/work/src/harness/codex.js +27 -1
  18. package/dist/packages/work/src/harness/contract.d.ts +9 -0
  19. package/dist/packages/work/src/hub/client.d.ts +19 -4
  20. package/dist/packages/work/src/hub/client.js +7 -3
  21. package/dist/packages/work/src/hub/types.d.ts +84 -0
  22. package/dist/packages/work/src/main.js +1 -0
  23. package/dist/packages/work/src/roles/agent-run.js +57 -32
  24. package/dist/packages/work/src/roles/exec.js +27 -8
  25. package/dist/packages/work/src/roles/settings.js +2 -0
  26. package/dist/packages/work/src/roles/shift.js +14 -2
  27. package/dist/packages/work/src/roles/util.d.ts +1 -0
  28. package/dist/packages/work/src/roles/util.js +10 -0
  29. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  30. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  31. package/dist/packages/work/src/settings/roster.d.ts +84 -0
  32. package/dist/packages/work/src/settings/roster.js +364 -5
  33. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  34. package/dist/packages/work/src/settings/serving.js +79 -0
  35. package/dist/packages/work/src/settings/settings.d.ts +14 -1
  36. package/dist/packages/work/src/settings/settings.js +14 -0
  37. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  38. package/dist/packages/work/src/shift/loop.js +416 -54
  39. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  40. package/dist/packages/work/src/shift/runtime.d.ts +18 -0
  41. package/dist/packages/work/src/shift/runtime.js +104 -5
  42. package/dist/packages/work/src/shift/server.js +2 -0
  43. package/dist/packages/work/src/shift/spawn.d.ts +17 -2
  44. package/dist/packages/work/src/shift/spawn.js +16 -13
  45. package/dist/packages/work/src/shift/state.d.ts +29 -2
  46. package/dist/packages/work/src/shift/state.js +45 -15
  47. package/dist/packages/work/src/submit-proof.d.ts +11 -8
  48. package/dist/packages/work/src/submit-proof.js +11 -8
  49. package/dist/packages/work/src/usage.d.ts +1 -1
  50. package/dist/packages/work/src/usage.js +7 -1
  51. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  52. package/dist/packages/work/src/util/modifier-init.js +73 -0
  53. package/dist/src/bundle/tar.d.ts +9 -4
  54. package/dist/src/bundle/tar.js +9 -4
  55. package/dist/src/capabilities.d.ts +76 -6
  56. package/dist/src/capabilities.js +49 -6
  57. package/dist/src/capability-mapping-client.d.ts +29 -0
  58. package/dist/src/capability-mapping-client.js +160 -0
  59. package/dist/src/cli.d.ts +16 -3
  60. package/dist/src/cli.js +1925 -281
  61. package/dist/src/config-dir.d.ts +1 -1
  62. package/dist/src/config-dir.js +1 -1
  63. package/dist/src/crypto/index.d.ts +1 -1
  64. package/dist/src/crypto/index.js +1 -1
  65. package/dist/src/crypto/org-root.d.ts +30 -12
  66. package/dist/src/crypto/org-root.js +162 -14
  67. package/dist/src/crypto/records.d.ts +2 -0
  68. package/dist/src/crypto/records.js +2 -0
  69. package/dist/src/defs.d.ts +38 -2
  70. package/dist/src/defs.js +593 -86
  71. package/dist/src/engine.d.ts +103 -25
  72. package/dist/src/engine.js +331 -79
  73. package/dist/src/hub.d.ts +77 -0
  74. package/dist/src/hub.js +162 -0
  75. package/dist/src/implements.d.ts +56 -0
  76. package/dist/src/implements.js +790 -0
  77. package/dist/src/index.d.ts +11 -9
  78. package/dist/src/index.js +6 -5
  79. package/dist/src/mcp/serve.d.ts +22 -0
  80. package/dist/src/mcp/serve.js +330 -41
  81. package/dist/src/mcp/server.d.ts +10 -7
  82. package/dist/src/mcp/server.js +53 -8
  83. package/dist/src/model.d.ts +48 -10
  84. package/dist/src/model.js +252 -99
  85. package/dist/src/order-resolver.d.ts +1 -0
  86. package/dist/src/order-resolver.js +8 -1
  87. package/dist/src/schemas/index.d.ts +11 -0
  88. package/dist/src/schemas/order.v1.schema.json +7 -1
  89. package/dist/src/store/def-source.d.ts +19 -0
  90. package/dist/src/store/def-source.js +87 -17
  91. package/dist/src/store/gc-recovery.d.ts +46 -0
  92. package/dist/src/store/gc-recovery.js +258 -0
  93. package/dist/src/store/gc.d.ts +94 -0
  94. package/dist/src/store/gc.js +562 -0
  95. package/dist/src/store/index.d.ts +3 -1
  96. package/dist/src/store/index.js +2 -0
  97. package/dist/src/store/install.d.ts +34 -5
  98. package/dist/src/store/install.js +73 -11
  99. package/dist/src/store/pre-commit-verifier.js +42 -2
  100. package/dist/src/store/snapshot-guard.d.ts +18 -0
  101. package/dist/src/store/snapshot-guard.js +94 -0
  102. package/dist/src/store.d.ts +69 -4
  103. package/dist/src/store.js +254 -16
  104. package/dist/src/types.d.ts +101 -20
  105. package/dist/src/util.js +4 -1
  106. package/docs/authoring.md +235 -10
  107. package/docs/bundles.md +45 -2
  108. package/docs/cli.md +437 -55
  109. package/docs/crypto.md +32 -10
  110. package/docs/design.md +177 -47
  111. package/docs/evals/mcp-charter-baseline.json +428 -0
  112. package/docs/mcp-charter-eval.md +124 -0
  113. package/docs/routing.md +189 -34
  114. package/docs/shift-logs.md +38 -9
  115. package/docs/wire-contracts.md +78 -14
  116. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  117. package/examples/workflows/delivery.yaml +31 -14
  118. package/examples/workflows/ship.yaml +38 -4
  119. package/package.json +2 -1
  120. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  121. package/plugins/claude-code/plugin/.mcp.json +1 -1
  122. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  123. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  124. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  125. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  126. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  127. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  128. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  129. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  130. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  131. package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
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,38 @@ 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
+
51
+ After a successful command, the worker submits its receipt once for each owed
52
+ path, in order. HTTP `429` is retried for that path at most twice more (up to
53
+ 30 seconds total), honoring `Retry-After` or using 5-second then 10-second
54
+ fallback waits. The worker keeps the same receipt and request for every retry;
55
+ it does not retry other HTTP errors or response-level rejections. A lease that
56
+ becomes terminal during a wait suppresses the next submit. Retry notices are
57
+ written to the worker's stderr, and rate-limit notices are rendered as
58
+ `HTTP 429 (rate limited)` without relaying the response body. Other HubError
59
+ details are collapsed to one line and bounded, so an edge-generated HTML page
60
+ cannot flood `<run>.log`.
61
+
43
62
  Under shift dispatch fd 1 and fd 2 both point at the same file, so the header —
44
63
  not the channel — is what tells these outcomes apart in `<run>.log`. The two
45
64
  channels still matter: stderr is what a reader treats as trouble, and routine
@@ -179,9 +198,9 @@ Two properties an uploader can rely on:
179
198
  | `reaped` | `workflow`, `run`, `kind`, `pid` | a worker exited and was collected |
180
199
  | `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
200
  | `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 |
201
+ | `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
202
  | `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 |
203
+ | `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
204
  | `event-queue-overflow` | `dropped` | the socket FIFO evicted events; see below |
186
205
  | `ended` | — | an operator ran `owenloop shift end` |
187
206
  | `gate` | optional `workflow`, `run`, `name`, `question` | reserved; not emitted today |
@@ -250,8 +269,18 @@ one.
250
269
 
251
270
  `order-dropped.reason` is the stable machine discriminator and is one of
252
271
  `malformed-digest`, `malformed-worker`, `unsupported-worker`,
253
- `verification-failed`, `metadata-unavailable`. `message` is human text — match
254
- on `reason`, display `message`.
272
+ `verification-failed`, `metadata-unavailable`, `agent-lane-closed`,
273
+ `dispatch-cap-full`, `agent-cap-full`, or `claim-expired`. The capacity,
274
+ expiry, and `agent-lane-closed` reasons return the claim to the hub; malformed
275
+ and unsupported reasons leave it for the pickup window. `message` is human
276
+ text — match on `reason`, display `message`.
277
+
278
+ Malformed, unsupported, verification, and metadata drops leave a modern order
279
+ for the hub's pickup window. `dispatch-cap-full`, `agent-cap-full`,
280
+ `agent-lane-closed`, and `claim-expired` return the claim immediately. When a
281
+ claim instead reaches its pickup lapse, the public released-lease close records
282
+ lease churn by incrementing the task `attempts` shown in status; it does not
283
+ turn the released row into a daily/cadence run or a judgment rework attempt.
255
284
 
256
285
  ### The first record is self-describing
257
286
 
@@ -91,13 +91,21 @@ version the next successful commit lands (claim-time committed version + 1), and
91
91
  therefore the version the consumer supplies to `verifyConsumed` as
92
92
  `expectedVersion`.
93
93
 
94
- The target is retry-safe because the engine computes it inside the claim
95
- transaction and persists it with the immutable order. Every read of that claim
96
- returns the same number, so a refinement, a committed submit whose response was
97
- lost, an unsigned commit, or a client process restart cannot move it. Refusal
98
- paths that leave the run open do not bump the artifact, and a refinement is a
99
- new claim with a newly issued target. A stale target fails the consumer's
100
- version check — a refusal, never an admitted unverified value.
94
+ The target is retry-safe because the engine issues it inside the claim
95
+ transaction and persists it with the order rather than leaving a client to guess
96
+ one: a refinement is a new claim with a newly issued target, and an unsigned
97
+ commit or a client process restart does not move it.
98
+
99
+ One thing does move it, deliberately. A judgment or human reject leaves the same
100
+ claim live to retry and follows a commit that already bumped the artifact, so
101
+ the engine re-stamps that claim's `owes[].version` from the current committed
102
+ version at the reject site. Refusal paths that leave the run open without
103
+ bumping the artifact (a schema reject) leave it untouched. A client must
104
+ therefore re-read the target off the order on every submit and never cache it.
105
+ A committed submit whose response was lost and is then replayed is a separate,
106
+ still-open residual: it bumps the artifact with no reject in between, so nothing
107
+ re-stamps the target and it strands one behind. A stale target fails the
108
+ consumer's version check — a refusal, never an admitted unverified value.
101
109
 
102
110
  A target counts as authoritative only when it is a positive integer, since the
103
111
  smallest commit a producer can land is v1. Given an absent target, a `0`, or a
@@ -295,17 +303,20 @@ Required fields are `run`, `workflow`, `step`, `key`, `defDigest`, `inputs`,
295
303
  `outputs`, `consumes`, and `owes`.
296
304
 
297
305
  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.
306
+ `consumedFingerprint`, `consumesProof`, `cause`, `capabilities`, `crews`,
307
+ `reroutedFrom`, `modifier`, and `escalated`. `workdir` may be authored as a
308
+ literal `workdir:` or resolved by the engine from a step's `workdirFrom:`, whose
309
+ stem names either a consumed artifact or a declared input; the Order wire shape
310
+ remains unchanged. No proof field covers `workdir` in any case.
302
311
 
303
312
  `defDigest` is a non-empty opaque reference. `inputs` and `outputs` are string
304
313
  arrays. `consumes` is an open artifact-path map; `spec` and `x` are opaque
305
314
  objects carried through without engine interpretation. `owes` contains the owed
306
315
  path, an optional target `version` (the version the next successful commit for
307
316
  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
317
+ counters, reason entries, and an optional opaque `proof` string. A reason entry
318
+ may also carry optional `requested`, the validated replacement value requested
319
+ when rejecting an artifact bound to the run's modifier. `cause`, when present, is
309
320
  `inputsGreen`, `allGreen`, or `idle`.
310
321
 
311
322
  **Decision A — version cross-check without fingerprint recomputation.** The
@@ -381,8 +392,61 @@ out of the `CommandReceipt`; malformed or over-cap JSON produces
381
392
  `payloadError` and no `payload`, while leaving the command exit code unchanged.
382
393
  When the hub supplies authoritative output-version metadata and the driver can
383
394
  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.
395
+ submission proof. Current successful producer command receipts are unsigned
396
+ because the deployed hub does not supply a retry-safe target version.
397
+
398
+ An ordinary command submits its complete `CommandReceipt` only when it exits
399
+ successfully without a machinery error. A non-zero exit or machinery error is
400
+ not submitted as an artifact; the worker escalates it through `ask` on the
401
+ first owed path instead:
402
+
403
+ ```json
404
+ {
405
+ "workflow": "<workflow>",
406
+ "run": "<run>",
407
+ "path": "<owed artifact path>",
408
+ "question": "<operator-facing failure diagnosis>",
409
+ "context": "<JSON-encoded CommandReceipt>"
410
+ }
411
+ ```
412
+
413
+ The question identifies the command, exit code or signal, machinery error when
414
+ present, output byte counts, output hash, and captured output tail. The receipt
415
+ in `context` is diagnostic data, not a submitted value. A successful `ask`
416
+ freezes the owed artifact and closes the run; a human answers with the
417
+ artifact's retry path. Only the first owed path is escalated because `ask`
418
+ closes the run, so additional owed paths remain debts.
419
+
420
+ Receipt submission is retried only for `HubError` responses with HTTP `429`.
421
+ The worker makes at most three total attempts for each owed path, with a
422
+ 30-second wall-clock retry window. It honors a supplied `Retry-After` delay
423
+ exactly when that delay fits the remaining window; without one, it waits 5
424
+ seconds before the second attempt and 10 seconds before the third. A delay that
425
+ would exceed the window fails the submit rather than being shortened. The
426
+ receipt, proof, and request bytes are built once per path and replayed
427
+ unchanged. Non-429 transport errors, response-level submit rejections, and
428
+ `409 run_closed` remain fail-fast and are not treated as successful replays.
429
+ If the lease becomes terminal during a retry wait, the worker sends no further
430
+ receipt. The worker releases the claim on submit failure; a successful submit
431
+ of every owed path closes normally without a release.
432
+
433
+ When a valid payload contains a plain-step `reject`, the command worker sends
434
+ the directive's `text` as the reject reason and, when command output is
435
+ available, appends the captured tail in this form:
436
+
437
+ ```text
438
+ <text>
439
+
440
+ --- command output (last <N> bytes) ---
441
+ <tail>
442
+ ```
443
+
444
+ The tail is the last 4 KiB of combined stdout-then-stderr output, decoded as
445
+ lossy UTF-8, with trailing newline characters removed before the byte count is
446
+ computed. `N` is the UTF-8 byte count of that trimmed tail. An empty tail leaves
447
+ the directive's text unchanged. The payload marker line is not removed from
448
+ the tail. This augmentation applies to payload rejects; judge rejects retain
449
+ their existing text-selection behavior.
386
450
 
387
451
  A worker rejects an artifact through the `reject` verb. The request is exactly:
388
452
 
@@ -31,7 +31,7 @@
31
31
  # wf=$(owenloop create compile-dev-playbook \
32
32
  # --provide brief='{"task":"add Stripe subscription billing to a Node/TypeScript app","category":"billing"}' \
33
33
  # | jq -r .workflow)
34
- # owenloop tick $wf # ... conduct to done (e.g. with the owenloop-conduct skill)
34
+ # owenloop tick $wf # ... conduct to done (e.g. with the conduct plugin skill)
35
35
  # # `approval` is a human gate before publish. Flying solo? Pre-approve at create:
36
36
  # # --provide approval='{"approved_by":"alex"}'
37
37
  # # Otherwise the instance parks blocked on it — durably, in SQLite — until:
@@ -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: