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
@@ -0,0 +1,762 @@
1
+ # Routing: how a step in a workflow reaches a model
2
+
3
+ This document explains the whole path from "a workflow definition says this
4
+ step needs a builder" to "a specific model, at a specific reasoning effort, on
5
+ a specific CLI, does the work."
6
+
7
+ It is written to be read once, start to finish, by someone who has never seen
8
+ the system. Every term is defined before it is used. Nothing is left implicit.
9
+
10
+ ---
11
+
12
+ ## 0. Status of this document
13
+
14
+ Sections 1 through 8 describe behavior that is live today, with one
15
+ explicitly marked exception inside section 8a.
16
+
17
+ Section 9 (**When nobody is certified**) describes a rule that is CHANGING.
18
+ Both the old rule and the new rule are stated, and it is marked which is which,
19
+ because a deployment running an older hub still does the old thing.
20
+
21
+ Section 10 (**Reroute rules**) describes a feature whose engine, hub and CLI
22
+ halves are now in place; the MCP surface is not. It is marked as such.
23
+
24
+ ---
25
+
26
+ ## 1. The four words
27
+
28
+ The single biggest source of confusion is the word **capability**. It sounds
29
+ like a property of a machine — "this box can run Opus." It is not that at all.
30
+
31
+ Use this mapping instead. It is exact, not a loose analogy.
32
+
33
+ | Term | Think of it as | Who writes it | Where it lives |
34
+ |---|---|---|---|
35
+ | **capability** | a **job posting** | the workflow author | the workflow definition file (`delivery.yaml`) |
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 |
37
+ | **crew** | a **team certified for that posting** | the hub operator | the hub's `capability_routes` table |
38
+ | **shift** | a **team member clocking in** | whoever runs the machine | a local `settings.json` on that machine |
39
+
40
+ Read as one sentence:
41
+
42
+ > A **workflow definition** posts a job (`build`). The person starting the run
43
+ > stamps a grade on it (`deep`), making the posting `build:deep`. The **hub**
44
+ > looks up which **crews** are certified for `build:deep`. A **shift** — one
45
+ > member of a certified crew, currently clocked in — takes the job and decides,
46
+ > from its own local settings, which model and effort to run it on.
47
+
48
+ Four things follow from that sentence, and all four are places people get it
49
+ wrong:
50
+
51
+ 1. **A capability never names a model.** `build` does not mean "Opus." It means
52
+ "somebody who does building." The model is chosen at the very last step, by
53
+ the shift, from its own settings file.
54
+ 2. **A capability never names a machine.** Nothing in the definition or the hub
55
+ knows what hardware or CLI exists.
56
+ 3. **Certifying a crew is a promise about every member.** Binding `build:deep`
57
+ to the crew `openai` says: *every shift that serves the openai crew can do
58
+ deep build work.* If one member cannot, the binding is wrong.
59
+ 4. **The mapping is many-to-many, both directions.** One capability can be
60
+ bound to several crews. One crew can be bound to several capabilities. One
61
+ shift can serve several crews (`owenloop shift start anthropic openai`
62
+ takes a list). On the staging hub every shift serves exactly one crew, so
63
+ this shows the shape of the argument rather than a shift that exists today.
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
+
73
+ ---
74
+
75
+ ## 2. The three vocabularies, precisely
76
+
77
+ There are exactly three kinds of capability string, and they are different
78
+ things. Mixing them up is the second biggest source of confusion.
79
+
80
+ **Authored capability** — what a workflow step declares. Never contains a
81
+ colon.
82
+
83
+ ```yaml
84
+ - name: builder
85
+ capabilities: [build] # <- authored capability
86
+ ```
87
+
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*
91
+ to it. `deep` is not "more" than `express` as far as any code is concerned;
92
+ they are just two different strings. A definition declares which ones it
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:
96
+
97
+ ```yaml
98
+ modifiers: [express, standard, deep]
99
+ ```
100
+
101
+ **Compound capability** — an authored capability with a modifier glued on by a
102
+ colon: `build:deep`. **Nobody writes this by hand in a workflow definition.**
103
+ It is composed by the engine at the moment an order is offered, by
104
+ `composeCapabilities(step.capabilities, modifier)` in `src/capabilities.ts`.
105
+
106
+ A run with no modifier composes to the bare authored capability. `build` stays
107
+ `build`. There is no default modifier — omitting `--modifier` does not mean
108
+ `standard`, it means *no modifier at all*.
109
+
110
+ ---
111
+
112
+ ## 3. Where each fact physically lives
113
+
114
+ Three files, three different owners, three different machines potentially.
115
+
116
+ ### 3a. The workflow definition — "what job is this?"
117
+
118
+ A `.yaml` in a bundle, e.g. `owenloop-delivery/workflows/delivery.yaml`.
119
+
120
+ ```yaml
121
+ modifiers: [express, standard, deep]
122
+
123
+ steps:
124
+ - name: planner
125
+ capabilities: [wise]
126
+ - name: builder
127
+ capabilities: [build]
128
+ - name: reviewer
129
+ capabilities: [review]
130
+ - name: provisioner
131
+ capabilities: [utility]
132
+ ```
133
+
134
+ This file names jobs. It names no models, no crews, no machines.
135
+
136
+ ### 3b. The hub's `capability_routes` table — "who is certified?"
137
+
138
+ A table inside the hub, one row per `(capability string, crew)` pair. Written
139
+ with `owenloop capability bind <capability> <crew>`.
140
+
141
+ The staging hub's current rows are exactly these sixteen:
142
+
143
+ | capability | crew |
144
+ |---|---|
145
+ | `wise` | `anthropic` |
146
+ | `wise:express` | `anthropic` |
147
+ | `wise:standard` | `anthropic` |
148
+ | `wise:deep` | `anthropic` |
149
+ | `build` | `openai` |
150
+ | `build:express` | `openai` |
151
+ | `build:standard` | `openai` |
152
+ | `build:deep` | `openai` |
153
+ | `review` | `openai` |
154
+ | `review:express` | `openai` |
155
+ | `review:standard` | `openai` |
156
+ | `review:deep` | `openai` |
157
+ | `utility` | `openai` |
158
+ | `utility:express` | `openai` |
159
+ | `utility:standard` | `openai` |
160
+ | `utility:deep` | `openai` |
161
+
162
+ The live table gives the `anthropic` crew one job family and its modifiers:
163
+ the four `wise` strings. It gives the `openai` crew three job families and
164
+ their modifiers: `build`, `review`, and `utility`. A crew name says which
165
+ team; a capability says which job. Nothing in `anthropic` or `openai` tells
166
+ you what job it does, and that is correct — the crew name is not supposed to.
167
+
168
+ A capability can still be certified to a crew whose name has nothing to do with
169
+ the job. If an operator wanted deep build work on Anthropic models, the
170
+ operator would run:
171
+
172
+ ```bash
173
+ owenloop capability bind build:deep anthropic
174
+ owenloop capability unbind build:deep openai
175
+ ```
176
+
177
+ The *job* is still a build job. Only the *team* changes.
178
+
179
+ These are two commands, not one. `capability bind` on an already-bound
180
+ capability **adds** a crew; it never replaces one. With only the bind,
181
+ `build:deep` would be certified to both `openai` and `anthropic`, and
182
+ which crew's shift claims a given order would be a race. The unbind is what
183
+ makes it a move. This is verified by `src/cli.ts:5079` and independently by
184
+ `docs/authoring.md:254`.
185
+
186
+ That hypothetical move also needs a rate-card change. The shift first looks
187
+ for an exact `build:deep` row and then may fall back to a bare `build` row.
188
+ The `anthropic` card shown here has neither row, so after the rebind it would
189
+ refuse the order with `unresolvable-capability`, and the hub would re-offer it.
190
+ If the card had a bare `build` row, the shift would run that row's potentially
191
+ different model and effort instead. The operator must add an intentional
192
+ `build:deep` row to the `anthropic` card as part of the same move.
193
+
194
+ ### 3c. The crew roster — “what can this machine run?”
195
+ A machine's global fallback lives under the `roster` key in
196
+ `~/.owenloop/settings.json`; a named crew's stronger layer is
197
+ `~/.owenloop/crews/<crew>.json`. Both files use the same top-level shape:
198
+
199
+ ```json
200
+ {
201
+ "roster": {
202
+ "wise:deep": [
203
+ { "harness": "claude-code", "model": "claude-fable-5", "effort": "xhigh" },
204
+ { "harness": "codex", "model": "gpt-5.6-sol", "effort": "xhigh" }
205
+ ],
206
+ "wise": [
207
+ { "harness": "claude-code", "model": "claude-opus-5", "effort": "high" }
208
+ ]
209
+ }
210
+ }
211
+ ```
212
+
213
+ Every value is a non-empty ordered candidate array. The stronger crew layer
214
+ replaces a capability's full array from the machine-global layer; arrays are
215
+ never combined. Exact composed capability lookup runs before bare-name lookup
216
+ across all offered capabilities. The first candidate whose harness is
217
+ registered wins, unless a step's `x.harness.id` requires a different harness.
218
+ That mismatch is an `incompatible-harness-policy` release; no registered
219
+ candidate is `unresolvable-capability`.
220
+
221
+ ### 4. The four things a shift is configured with
222
+
223
+ A shift start command names its crews, credentials, display identity, and
224
+ state directory. It no longer carries an operator-selected harness or a
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.
234
+
235
+ | Name | What it selects |
236
+ |---|---|
237
+ | **crew** (positional) | worker → hub `serve_crews` offer scope; the hub-stamped `order.crews` resolves the agent worker's roster sequence |
238
+ | **`--as`** | which stored credential to authenticate with |
239
+ | **`--name`** | a display label for this shift |
240
+ | **`--state-dir`** | local socket and child-state storage |
241
+
242
+ Use `owenloop roster show [crew]` to see each selected candidate and the
243
+ layer that supplied it. `owenloop doctor` reports the same layers and whether
244
+ their candidate harnesses are registered.
245
+
246
+ ## 5. What actually happens when an order is offered
247
+
248
+ Here is one order, end to end, in order.
249
+
250
+ **Step 1 — a human starts a run.**
251
+
252
+ ```bash
253
+ owenloop start delivery --modifier deep \
254
+ --provide proposal='{"text":"..."}' \
255
+ --provide target='{"path":"/Users/alex/code/owenloop"}'
256
+ ```
257
+
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.
263
+
264
+ **Step 2 — a shift asks for work.**
265
+
266
+ The `openai-1` shift calls the hub verb `whats_next`, authenticating as
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.
270
+
271
+ **Step 3 — the hub works out what this caller is authorized to do today.**
272
+
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:
276
+
277
+ - it looks up which crews the account `shift-openai-1` belongs to;
278
+ - it reads every `capability_routes` row for those crews;
279
+ - the resulting list of capability strings is the caller's capability set.
280
+
281
+ The function is `listCapabilitiesForCrews(storage, memberCrewIds)`. For the
282
+ `openai-1` shift on staging that yields this set:
283
+
284
+ ```
285
+ ['build', 'build:deep', 'build:express', 'build:standard',
286
+ 'review', 'review:deep', 'review:express', 'review:standard',
287
+ 'utility', 'utility:deep', 'utility:express', 'utility:standard']
288
+ ```
289
+
290
+ The strings are shown alphabetically for readability; their order is not
291
+ significant.
292
+
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.
296
+
297
+ **Step 4 — the engine composes the posting.**
298
+
299
+ For the `builder` step, whose authored capability is `build`, and a run whose
300
+ modifier is `deep`:
301
+
302
+ ```
303
+ composeCapabilities(['build'], 'deep') -> ['build:deep']
304
+ ```
305
+
306
+ The order will be offered as `build:deep`.
307
+
308
+ **Step 5 — the hub decides how strictly to match.**
309
+
310
+ For each composed capability, the hub asks: *is any live crew certified for
311
+ this exact string?* "Live" means the `capability_routes` row exists **and** the
312
+ crew it names still exists — a row pointing at a deleted crew is dangling and
313
+ counts as nothing.
314
+
315
+ - `build:deep` has a live row (crew `openai`) → match mode **`exact`**. Only
316
+ crews certified for the exact string `build:deep` may claim.
317
+ - If it had no live row → see section 9.
318
+
319
+ **Step 6 — the match.**
320
+
321
+ `claimMatches(offered, caller, modes)`. Offered is `['build:deep']`. The
322
+ `openai-1` shift's caller set contains `build:deep`. Under `exact` mode
323
+ that is a match. The order is handed to `openai-1`, with
324
+ `order.capabilities = ['build:deep']`.
325
+
326
+ The `anthropic` shift, whose caller set is
327
+ `['wise', 'wise:deep', 'wise:express', 'wise:standard']`, does **not** match
328
+ — it is not certified for `build:deep`. That is the correct outcome, and it
329
+ is what stops a deep build job landing on the Anthropic shift. The two caller
330
+ sets do not overlap at all, which is exactly what it looks like when
331
+ eligibility comes entirely from crew membership and the crews are named after
332
+ teams.
333
+
334
+ **Step 7 — the worker picks the model.**
335
+
336
+ The agent reads `order.capabilities` — `['build:deep']` — plus the hub →
337
+ worker `order.crews` stamp, and resolves those merged crew rosters in order:
338
+
339
+ 1. Try the **exact compound**: `build:deep` → an ordered candidate array. Found.
340
+ 2. If not found, try the **bare name part**: `build`.
341
+ 3. If neither is found, the worker **refuses the order** with
342
+ `unresolvable-capability` and the hub re-offers it.
343
+
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.
348
+
349
+ **Step 8 — the harness runs it.**
350
+
351
+ the selected roster candidate for the openai shifts, so the Codex CLI is spawned
352
+ with model `gpt-5.6-terra` and effort `xhigh`.
353
+
354
+ Valid efforts, in order: `low`, `medium`, `high`, `xhigh`, `max`.
355
+
356
+ ---
357
+
358
+ ## 6. Why the model is chosen last, not first
359
+
360
+ A reasonable person asks: why not just write the model in the workflow
361
+ definition?
362
+
363
+ Because the definition is shared and the hardware is not. The same
364
+ `delivery.yaml` runs on a laptop with one API key, a CI box with another, and
365
+ someone else's fork entirely. A model name in the definition would be a promise
366
+ the author cannot keep.
367
+
368
+ So the definition says what *kind* of worker it needs. The hub says which
369
+ *teams* are certified. The machine owner says what those teams *run on*. Each
370
+ layer states only what it actually knows.
371
+
372
+ ---
373
+
374
+ ## 7. Two shifts, one crew — and when that is wrong
375
+
376
+ The `openai` crew has exactly two staging shifts: `openai-1` and `openai-2`.
377
+ Both run codex and carry the same rate card. Because a crew is a team, both
378
+ become eligible for that crew's jobs.
379
+
380
+ **This works, with one consequence you must accept: which member gets the order
381
+ is a race.** First claim wins. The hub does not choose between eligible
382
+ members.
383
+
384
+ That is fine for a job where you genuinely do not care which member claims it
385
+ — a generic `coder` posting where either shift is acceptable.
386
+
387
+ For this staging pair, the two `openai` shifts must carry byte-identical rate
388
+ cards. Crew membership is what makes a shift eligible, and both members are
389
+ eligible for every capability the crew is certified for. If `openai-2` were
390
+ missing a row that `openai-1` has, the hub would eventually hand `openai-2` an
391
+ order it cannot price; `openai-2` would refuse with
392
+ `unresolvable-capability`; the hub would re-offer the order. That is the
393
+ claim-refuse-reoffer loop, and nothing about it is visible from the hub side —
394
+ the routing table is identical in both cases. This is why section 3c says both
395
+ openai cards are byte-identical.
396
+
397
+ This is a property of these two shifts sharing the `codex` adapter, not a
398
+ universal rule for every pair of shifts serving one crew. Shifts on different
399
+ adapters may use different model ids and separate settings directories; the
400
+ invariant is that every eligible shift must be able to resolve every capability
401
+ the crew is certified for.
402
+
403
+ It is exactly wrong for `wise:deep`, where the entire point is "this specific
404
+ one must be claude-fable-5." `wise:deep` is certified to `anthropic`, and
405
+ the anthropic card serves it with `claude-fable-5`, a different model from
406
+ every other `wise` row. If you want a guarantee about *which model*, you need
407
+ a crew whose members all run that model, and you certify that crew for the
408
+ compound.
409
+
410
+ One more failure mode: a step can declare a permission policy an adapter cannot
411
+ enforce (see `x.harness` in a step definition). A member on the wrong harness
412
+ releases the order with `incompatible-harness-policy`, and the hub re-offers it.
413
+ So a mixed crew can also produce a claim-then-release loop if the step's policy
414
+ is adapter-specific.
415
+
416
+ ---
417
+
418
+ ## 8. Escalation — the per-step, temporary grade change
419
+
420
+ A step can declare an escalation:
421
+
422
+ ```yaml
423
+ - name: builder
424
+ capabilities: [build]
425
+ escalation:
426
+ after: 3
427
+ modifier: deep
428
+ ```
429
+
430
+ Read: *after this step's owed artifact has been judgment-rejected 3 times,
431
+ re-offer this step composed with `deep` instead of the run's own modifier.*
432
+
433
+ Four properties, all easy to get wrong:
434
+
435
+ 1. **It is the engine's transition, not the worker's.** No agent reads this
436
+ block. A worker cannot opt in or out.
437
+ 2. **It is per step and per run.** The `builder` escalating does not change
438
+ what `planner` or `reviewer` are offered as.
439
+ 3. **It never rewrites the run's stored modifier.** The instance still says
440
+ `modifier = "standard"`. Only that one step's offer moved.
441
+ 4. **It is a no-op on a run that is already at the target grade.** A `deep` run
442
+ whose builder escalates to `deep` just keeps re-offering `build:deep`.
443
+
444
+ The order carries a marker, `order.escalated = true`, so a reader can tell an
445
+ escalated re-offer from an ordinary one.
446
+
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.
575
+
576
+ ---
577
+
578
+ ## 9. When nobody is certified — the rule that is changing
579
+
580
+ This is the single line that has caused more confusion than everything else in
581
+ this document combined. It is worth reading twice.
582
+
583
+ **The situation:** a run is started with `--modifier express`. The `builder`
584
+ step composes to `build:express`. The hub looks in `capability_routes` and
585
+ finds **no live crew certified for `build:express`.**
586
+
587
+ ### 9a. The OLD rule (what a current hub does)
588
+
589
+ The hub falls back to **name matching**: it offers the job to any crew
590
+ certified for anything whose name part is `build` — so the crew certified for
591
+ plain `build` claims it.
592
+
593
+ Why that is bad: the claiming shift receives `order.capabilities =
594
+ ['build:express']`, finds no `build:express` row in its `roster`,
595
+ falls back to its bare `build` row, and runs on that model. The run believes it
596
+ got express service. It actually got whatever the generic build row happens to
597
+ be. Nothing failed, nothing was logged loudly, and the operator has no signal.
598
+
599
+ It converts the fact *"no shift is serving express right now"* into the
600
+ different fact *"the operator accepted a different grade of service."* Those
601
+ are not the same thing and the system had no business equating them.
602
+
603
+ ### 9b. The NEW rule (what is being built)
604
+
605
+ **An unbound compound holds.** The hub keeps the mode at `exact`, so the order
606
+ simply waits until a crew certified for `build:express` clocks in. It does not
607
+ degrade to a generic worker.
608
+
609
+ **And the operator is told.** The hub writes a routing alert (kind
610
+ `binding-gap`) naming the capability that has no certified crew.
611
+
612
+ **Holding is not failure.** A held order is not dead. It is waiting. The
613
+ existing stall-notification system covers the case where a run sits too long,
614
+ and a crew that was restarted picks the work up when it comes back. There is no
615
+ built-in timer that silently downgrades the job.
616
+
617
+ The old behavior had a 15-minute escalation-fallback window baked in. That is
618
+ being removed. If an operator wants a timed fallback, they configure it; the
619
+ system does not assume it.
620
+
621
+ ---
622
+
623
+ ## 10. Reroute rules — saying "yes, substitute" on purpose
624
+
625
+ *(The engine half is in `owenloop`, the hub half is in `owenloop-service`, and
626
+ the CLI surface is `owenloop routing rule` — see
627
+ [Routing](cli.md#routing) in the CLI reference. The MCP surface follows.)*
628
+
629
+ Holding is the right default, but sometimes the operator genuinely does want a
630
+ substitution — "if nobody is serving `build:express` right now, `build:standard`
631
+ is fine." Section 9's rule makes that a decision the operator states, instead of
632
+ something the hub assumes.
633
+
634
+ A **reroute rule** is exactly that statement:
635
+
636
+ ```
637
+ build:express -> build:standard
638
+ ```
639
+
640
+ How it works, mechanically:
641
+
642
+ 1. The hub composes the offer as usual and finds `build:express` has no live
643
+ binding.
644
+ 2. The hub consults the operator's reroute rules and finds a target,
645
+ `build:standard`, that *does* have a live binding.
646
+ 3. The hub hands the engine a **rewrite**: `{ 'build:express': 'build:standard' }`.
647
+ 4. The engine **substitutes the string**. The order goes out as
648
+ `build:standard`, and carries `reroutedFrom: ['build:express']`.
649
+ 5. The hub writes a routing alert (kind `reroute`) recording that it happened.
650
+
651
+ **Why substitute the string rather than just loosen the match?** Because the
652
+ claiming shift resolves its model from `order.capabilities`. If the hub merely
653
+ widened the match, the shift would receive `build:express`, find no row for it,
654
+ and fall back to its bare `build` row — the wrong model, which is the exact bug
655
+ section 9a describes. Substituting means the shift receives `build:standard` and
656
+ resolves *standard's* model, which is what the operator asked for.
657
+
658
+ **Why two fields on the order?** A rerouted order has two simultaneously true
659
+ answers to "which capability is this?"
660
+
661
+ - `capabilities` — the capability **being served**. This is what the shift
662
+ resolves its model against.
663
+ - `reroutedFrom` — the capability the definition **asked for**.
664
+
665
+ `reroutedFrom` is absent on every ordinary offer, so its presence alone tells a
666
+ reader the order is not running on what its definition requested. A single field
667
+ could only ever carry one of the two facts, and an operator asking "why did this
668
+ run on Opus?" would have no way back to "because we asked for express."
669
+
670
+ **The run's stored modifier is never touched by a reroute.** Re-reading the run
671
+ record still shows the grade of service that was requested. Only the offer
672
+ moved.
673
+
674
+ **Chains are resolved by the hub, not the engine.** If `a -> b` and `b -> c`,
675
+ the hub walks the chain and hands the engine the final answer. The engine
676
+ performs exactly one substitution and never looks a target up again, so a cycle
677
+ is impossible there rather than merely bounded.
678
+
679
+ ### How an operator states and inspects all of this
680
+
681
+ The rules and the alerts are two separate command surfaces on one hub org — see
682
+ [Routing](cli.md#routing) in the CLI reference for flags, output shape and exit
683
+ codes.
684
+
685
+ | what you want | command |
686
+ |---|---|
687
+ | write the rule `build:express -> build:standard` | `owenloop routing rule add build:express build:standard` |
688
+ | put a rule ahead of the ones already there | `owenloop routing rule add build:express build --position 0` |
689
+ | see the rules in the order the hub tries them | `owenloop routing rule list` |
690
+ | take one rule back | `owenloop routing rule rm build:express build:standard` |
691
+ | see every hold, reroute, wait and fallback org-wide | `owenloop routing alerts` |
692
+ | see one run's routing timeline | `owenloop routing show <workflow>` |
693
+
694
+ **Three cautions the command names do not carry on their own.**
695
+
696
+ 1. **A reroute rule is not a binding.** `routing rule add` writes a
697
+ `capability_reroutes` row, which names no crew and grants nobody access.
698
+ `capability bind` writes a `capability_routes` row, which does. A reroute
699
+ only reaches a crew if its **target** capability has a live binding of its
700
+ own, so adding a rule cannot by itself widen who may claim work.
701
+ 2. **`routing rule list` order is meaning, not presentation.** Rows are grouped
702
+ by source capability and ordered by ascending `position` — the first row for
703
+ a capability is the first target the hub attempts.
704
+ 3. **Removing the last rule for a capability restores holding.** With no rule
705
+ left, an unbound compound waits again, exactly as section 9b describes. The
706
+ CLI prints `remainingTargets: []` and says so on stderr.
707
+
708
+ ---
709
+
710
+ ## 11. The mistakes we keep making
711
+
712
+ Each of these has actually happened. Each has a one-line correction.
713
+
714
+ | Mistake | Correction |
715
+ |---|---|
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`. |
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. |
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. |
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. |
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. |
722
+ | "`--modifier` defaults to standard." | Omitting it means **no modifier**. Steps are offered on bare authored capabilities. |
723
+ | "A modifier means 'more effort'." | To the engine it is an opaque string. All meaning lives in the shift's `roster` map. |
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`. |
726
+ | "Escalation upgrades the run." | It re-offers **one step**, temporarily. The run's stored modifier is untouched. |
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). |
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. |
729
+
730
+ ---
731
+
732
+ ## 12. One-screen summary
733
+
734
+ ```
735
+ delivery.yaml steps: [{ name: builder, capabilities: [build] }]
736
+ |
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)
740
+ |
741
+ engine composes build + deep -> "build:deep"
742
+ |
743
+ hub reads capability_routes: build:deep -> crew "openai"
744
+ |
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)
748
+ |
749
+ match: exact -> only crews certified for "build:deep" may claim
750
+ |
751
+ the openai-1 shift claims; order.capabilities = ["build:deep"]
752
+ order.crews = ["openai"]
753
+ |
754
+ agent resolves the stamped crew roster:
755
+ "build:deep": [{ harness: codex, model: gpt-5.6-terra, effort: xhigh }]
756
+ |
757
+ the selected candidate spawns that model at that effort
758
+ ```
759
+
760
+ If the lookup at step 3 finds nobody: the order **holds** and an alert is
761
+ written. If the operator has configured a reroute rule, the hub substitutes the
762
+ target capability and records `reroutedFrom` on the order.