owenloop 0.5.7 → 0.5.8

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 (65) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +3 -6
  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 +39 -25
  6. package/dist/packages/work/src/agent/loop.js +102 -50
  7. package/dist/packages/work/src/bundle/types.d.ts +3 -3
  8. package/dist/packages/work/src/exec/loop.js +37 -15
  9. package/dist/packages/work/src/harness/child-env.js +4 -5
  10. package/dist/packages/work/src/harness/codex.js +3 -4
  11. package/dist/packages/work/src/harness/session-store.d.ts +63 -3
  12. package/dist/packages/work/src/harness/session-store.js +104 -9
  13. package/dist/packages/work/src/hub/types.d.ts +3 -3
  14. package/dist/packages/work/src/roles/agent-run.js +48 -42
  15. package/dist/packages/work/src/roles/sessions.d.ts +3 -2
  16. package/dist/packages/work/src/roles/sessions.js +9 -2
  17. package/dist/packages/work/src/roles/settings.js +1 -1
  18. package/dist/packages/work/src/settings/roster.d.ts +21 -0
  19. package/dist/packages/work/src/settings/roster.js +80 -0
  20. package/dist/packages/work/src/settings/settings.d.ts +12 -24
  21. package/dist/packages/work/src/settings/settings.js +17 -35
  22. package/dist/packages/work/src/shift/runtime.js +2 -10
  23. package/dist/packages/work/src/shift/spawn.d.ts +6 -53
  24. package/dist/packages/work/src/shift/spawn.js +28 -66
  25. package/dist/packages/work/src/usage.d.ts +1 -1
  26. package/dist/packages/work/src/usage.js +3 -4
  27. package/dist/src/capabilities.d.ts +44 -0
  28. package/dist/src/capabilities.js +38 -0
  29. package/dist/src/cli.d.ts +1 -0
  30. package/dist/src/cli.js +460 -5
  31. package/dist/src/config-dir.d.ts +13 -18
  32. package/dist/src/config-dir.js +15 -23
  33. package/dist/src/credentials.d.ts +1 -1
  34. package/dist/src/credentials.js +1 -1
  35. package/dist/src/crypto/records.d.ts +1 -0
  36. package/dist/src/crypto/records.js +6 -0
  37. package/dist/src/crypto/trust-roots.d.ts +2 -2
  38. package/dist/src/crypto/trust-roots.js +2 -2
  39. package/dist/src/engine.d.ts +14 -0
  40. package/dist/src/engine.js +21 -13
  41. package/dist/src/global-config.d.ts +4 -7
  42. package/dist/src/global-config.js +4 -7
  43. package/dist/src/hub.d.ts +207 -5
  44. package/dist/src/hub.js +263 -3
  45. package/dist/src/index.d.ts +2 -2
  46. package/dist/src/index.js +1 -1
  47. package/dist/src/schemas/index.d.ts +8 -0
  48. package/dist/src/schemas/order.v1.schema.json +6 -1
  49. package/dist/src/store/pre-commit-verifier.js +1 -1
  50. package/dist/src/types.d.ts +24 -4
  51. package/dist/src/work-settings.d.ts +2 -4
  52. package/dist/src/work-settings.js +2 -4
  53. package/docs/agent-runner.md +2 -2
  54. package/docs/bundles.md +3 -1
  55. package/docs/cli.md +295 -101
  56. package/docs/crypto.md +14 -14
  57. package/docs/routing.md +607 -0
  58. package/docs/shift-logs.md +22 -6
  59. package/package.json +1 -1
  60. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  61. package/plugins/claude-code/plugin/.mcp.json +1 -1
  62. package/plugins/claude-code/plugin/skills/author/SKILL.md +1 -2
  63. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  64. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  65. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +1 -2
@@ -0,0 +1,607 @@
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.
15
+
16
+ Section 9 (**When nobody is certified**) describes a rule that is CHANGING.
17
+ Both the old rule and the new rule are stated, and it is marked which is which,
18
+ because a deployment running an older hub still does the old thing.
19
+
20
+ Section 10 (**Reroute rules**) describes a feature whose engine, hub and CLI
21
+ halves are now in place; the MCP surface is not. It is marked as such.
22
+
23
+ ---
24
+
25
+ ## 1. The four words
26
+
27
+ The single biggest source of confusion is the word **capability**. It sounds
28
+ like a property of a machine — "this box can run Opus." It is not that at all.
29
+
30
+ Use this mapping instead. It is exact, not a loose analogy.
31
+
32
+ | Term | Think of it as | Who writes it | Where it lives |
33
+ |---|---|---|---|
34
+ | **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
+ | **crew** | a **team certified for that posting** | the hub operator | the hub's `capability_routes` table |
37
+ | **shift** | a **team member clocking in** | whoever runs the machine | a local `settings.json` on that machine |
38
+
39
+ Read as one sentence:
40
+
41
+ > A **workflow definition** posts a job (`build`). The person starting the run
42
+ > stamps a grade on it (`deep`), making the posting `build:deep`. The **hub**
43
+ > looks up which **crews** are certified for `build:deep`. A **shift** — one
44
+ > member of a certified crew, currently clocked in — takes the job and decides,
45
+ > from its own local settings, which model and effort to run it on.
46
+
47
+ Four things follow from that sentence, and all four are places people get it
48
+ wrong:
49
+
50
+ 1. **A capability never names a model.** `build` does not mean "Opus." It means
51
+ "somebody who does building." The model is chosen at the very last step, by
52
+ the shift, from its own settings file.
53
+ 2. **A capability never names a machine.** Nothing in the definition or the hub
54
+ knows what hardware or CLI exists.
55
+ 3. **Certifying a crew is a promise about every member.** Binding `build:deep`
56
+ to the crew `openai` says: *every shift that serves the openai crew can do
57
+ deep build work.* If one member cannot, the binding is wrong.
58
+ 4. **The mapping is many-to-many, both directions.** One capability can be
59
+ bound to several crews. One crew can be bound to several capabilities. One
60
+ shift can serve several crews (`owenloop shift start anthropic openai`
61
+ takes a list). On the staging hub every shift serves exactly one crew, so
62
+ this shows the shape of the argument rather than a shift that exists today.
63
+
64
+ ---
65
+
66
+ ## 2. The three vocabularies, precisely
67
+
68
+ There are exactly three kinds of capability string, and they are different
69
+ things. Mixing them up is the second biggest source of confusion.
70
+
71
+ **Authored capability** — what a workflow step declares. Never contains a
72
+ colon.
73
+
74
+ ```yaml
75
+ - name: builder
76
+ capabilities: [build] # <- authored capability
77
+ ```
78
+
79
+ **Modifier** — one word, chosen once per run. The engine attaches *no meaning*
80
+ to it. `deep` is not "more" than `express` as far as any code is concerned;
81
+ they are just two different strings. A definition declares which ones it
82
+ accepts:
83
+
84
+ ```yaml
85
+ modifiers: [express, standard, deep]
86
+ ```
87
+
88
+ **Compound capability** — an authored capability with a modifier glued on by a
89
+ colon: `build:deep`. **Nobody writes this by hand in a workflow definition.**
90
+ It is composed by the engine at the moment an order is offered, by
91
+ `composeCapabilities(step.capabilities, modifier)` in `src/capabilities.ts`.
92
+
93
+ A run with no modifier composes to the bare authored capability. `build` stays
94
+ `build`. There is no default modifier — omitting `--modifier` does not mean
95
+ `standard`, it means *no modifier at all*.
96
+
97
+ ---
98
+
99
+ ## 3. Where each fact physically lives
100
+
101
+ Three files, three different owners, three different machines potentially.
102
+
103
+ ### 3a. The workflow definition — "what job is this?"
104
+
105
+ A `.yaml` in a bundle, e.g. `owenloop-delivery/workflows/delivery.yaml`.
106
+
107
+ ```yaml
108
+ modifiers: [express, standard, deep]
109
+
110
+ steps:
111
+ - name: planner
112
+ capabilities: [wise]
113
+ - name: builder
114
+ capabilities: [build]
115
+ - name: reviewer
116
+ capabilities: [review]
117
+ - name: provisioner
118
+ capabilities: [utility]
119
+ ```
120
+
121
+ This file names jobs. It names no models, no crews, no machines.
122
+
123
+ ### 3b. The hub's `capability_routes` table — "who is certified?"
124
+
125
+ A table inside the hub, one row per `(capability string, crew)` pair. Written
126
+ with `owenloop capability bind <capability> <crew>`.
127
+
128
+ The staging hub's current rows are exactly these sixteen:
129
+
130
+ | capability | crew |
131
+ |---|---|
132
+ | `wise` | `anthropic` |
133
+ | `wise:express` | `anthropic` |
134
+ | `wise:standard` | `anthropic` |
135
+ | `wise:deep` | `anthropic` |
136
+ | `build` | `openai` |
137
+ | `build:express` | `openai` |
138
+ | `build:standard` | `openai` |
139
+ | `build:deep` | `openai` |
140
+ | `review` | `openai` |
141
+ | `review:express` | `openai` |
142
+ | `review:standard` | `openai` |
143
+ | `review:deep` | `openai` |
144
+ | `utility` | `openai` |
145
+ | `utility:express` | `openai` |
146
+ | `utility:standard` | `openai` |
147
+ | `utility:deep` | `openai` |
148
+
149
+ The live table gives the `anthropic` crew one job family and its modifiers:
150
+ the four `wise` strings. It gives the `openai` crew three job families and
151
+ their modifiers: `build`, `review`, and `utility`. A crew name says which
152
+ team; a capability says which job. Nothing in `anthropic` or `openai` tells
153
+ you what job it does, and that is correct — the crew name is not supposed to.
154
+
155
+ A capability can still be certified to a crew whose name has nothing to do with
156
+ the job. If an operator wanted deep build work on Anthropic models, the
157
+ operator would run:
158
+
159
+ ```bash
160
+ owenloop capability bind build:deep anthropic
161
+ owenloop capability unbind build:deep openai
162
+ ```
163
+
164
+ The *job* is still a build job. Only the *team* changes.
165
+
166
+ These are two commands, not one. `capability bind` on an already-bound
167
+ capability **adds** a crew; it never replaces one. With only the bind,
168
+ `build:deep` would be certified to both `openai` and `anthropic`, and
169
+ which crew's shift claims a given order would be a race. The unbind is what
170
+ makes it a move. This is verified by `src/cli.ts:5079` and independently by
171
+ `docs/authoring.md:254`.
172
+
173
+ That hypothetical move also needs a rate-card change. The shift first looks
174
+ for an exact `build:deep` row and then may fall back to a bare `build` row.
175
+ The `anthropic` card shown here has neither row, so after the rebind it would
176
+ refuse the order with `unresolvable-capability`, and the hub would re-offer it.
177
+ If the card had a bare `build` row, the shift would run that row's potentially
178
+ different model and effort instead. The operator must add an intentional
179
+ `build:deep` row to the `anthropic` card as part of the same move.
180
+
181
+ ### 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
+ A machine's global fallback lives under the `roster` key in
186
+ `~/.owenloop/settings.json`; a named crew's stronger layer is
187
+ `~/.owenloop/crews/<crew>.json`. Both files use the same top-level shape:
188
+
189
+ ```json
190
+ {
191
+ "roster": {
192
+ "wise:deep": [
193
+ { "harness": "claude-code", "model": "claude-fable-5", "effort": "xhigh" },
194
+ { "harness": "codex", "model": "gpt-5.6-sol", "effort": "xhigh" }
195
+ ],
196
+ "wise": [
197
+ { "harness": "claude-code", "model": "claude-opus-5", "effort": "high" }
198
+ ]
199
+ }
200
+ }
201
+ ```
202
+
203
+ Every value is a non-empty ordered candidate array. The stronger crew layer
204
+ replaces a capability's full array from the machine-global layer; arrays are
205
+ never combined. Exact composed capability lookup runs before bare-name lookup
206
+ across all offered capabilities. The first candidate whose harness is
207
+ registered wins, unless a step's `x.harness.id` requires a different harness.
208
+ That mismatch is an `incompatible-harness-policy` release; no registered
209
+ candidate is `unresolvable-capability`.
210
+
211
+ ### 4. The four things a shift is configured with
212
+
213
+ A shift start command names its crews, credentials, display identity, and
214
+ 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.
219
+
220
+ | Name | What it selects |
221
+ |---|---|
222
+ | **crew** (positional) | which crew rosters the shift serves |
223
+ | **`--as`** | which stored credential to authenticate with |
224
+ | **`--name`** | a display label for this shift |
225
+ | **`--state-dir`** | local socket and child-state storage |
226
+
227
+ Use `owenloop roster show [crew]` to see each selected candidate and the
228
+ layer that supplied it. `owenloop doctor` reports the same layers and whether
229
+ their candidate harnesses are registered.
230
+
231
+ ## 5. What actually happens when an order is offered
232
+
233
+ Here is one order, end to end, in order.
234
+
235
+ **Step 1 — a human starts a run.**
236
+
237
+ ```bash
238
+ owenloop start delivery --modifier deep \
239
+ --provide proposal='{"text":"..."}' \
240
+ --provide target='{"path":"/Users/alex/code/owenloop"}'
241
+ ```
242
+
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.
246
+
247
+ **Step 2 — a shift asks for work.**
248
+
249
+ The `openai-1` shift calls the hub verb `whats_next`, authenticating as
250
+ account `shift-openai-1`.
251
+
252
+ **Step 3 — the hub works out what this caller can do.**
253
+
254
+ The hub does *not* read anything the shift sent about its abilities. Instead:
255
+
256
+ - it looks up which crews the account `shift-openai-1` belongs to;
257
+ - it reads every `capability_routes` row for those crews;
258
+ - the resulting list of capability strings is the caller's capability set.
259
+
260
+ The function is `listCapabilitiesForCrews(storage, memberCrewIds)`. For the
261
+ `openai-1` shift on staging that yields this set:
262
+
263
+ ```
264
+ ['build', 'build:deep', 'build:express', 'build:standard',
265
+ 'review', 'review:deep', 'review:express', 'review:standard',
266
+ 'utility', 'utility:deep', 'utility:express', 'utility:standard']
267
+ ```
268
+
269
+ The strings are shown alphabetically for readability; their order is not
270
+ significant.
271
+
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.
274
+
275
+ **Step 4 — the engine composes the posting.**
276
+
277
+ For the `builder` step, whose authored capability is `build`, and a run whose
278
+ modifier is `deep`:
279
+
280
+ ```
281
+ composeCapabilities(['build'], 'deep') -> ['build:deep']
282
+ ```
283
+
284
+ The order will be offered as `build:deep`.
285
+
286
+ **Step 5 — the hub decides how strictly to match.**
287
+
288
+ For each composed capability, the hub asks: *is any live crew certified for
289
+ this exact string?* "Live" means the `capability_routes` row exists **and** the
290
+ crew it names still exists — a row pointing at a deleted crew is dangling and
291
+ counts as nothing.
292
+
293
+ - `build:deep` has a live row (crew `openai`) → match mode **`exact`**. Only
294
+ crews certified for the exact string `build:deep` may claim.
295
+ - If it had no live row → see section 9.
296
+
297
+ **Step 6 — the match.**
298
+
299
+ `claimMatches(offered, caller, modes)`. Offered is `['build:deep']`. The
300
+ `openai-1` shift's caller set contains `build:deep`. Under `exact` mode
301
+ that is a match. The order is handed to `openai-1`, with
302
+ `order.capabilities = ['build:deep']`.
303
+
304
+ The `anthropic` shift, whose caller set is
305
+ `['wise', 'wise:deep', 'wise:express', 'wise:standard']`, does **not** match
306
+ — it is not certified for `build:deep`. That is the correct outcome, and it
307
+ is what stops a deep build job landing on the Anthropic shift. The two caller
308
+ sets do not overlap at all, which is exactly what it looks like when
309
+ eligibility comes entirely from crew membership and the crews are named after
310
+ teams.
311
+
312
+ **Step 7 — the shift picks the model.**
313
+
314
+ The `openai-1` shift reads `order.capabilities` — `['build:deep']` — and
315
+ looks it up in its merged crew roster:
316
+
317
+ 1. Try the **exact compound**: `build:deep` → an ordered candidate array. Found.
318
+ 2. If not found, try the **bare name part**: `build`.
319
+ 3. If neither is found, the shift **refuses the order** with
320
+ `unresolvable-capability` and the hub re-offers it.
321
+
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.
324
+
325
+ **Step 8 — the harness runs it.**
326
+
327
+ the selected roster candidate for the openai shifts, so the Codex CLI is spawned
328
+ with model `gpt-5.6-terra` and effort `xhigh`.
329
+
330
+ Valid efforts, in order: `low`, `medium`, `high`, `xhigh`, `max`.
331
+
332
+ ---
333
+
334
+ ## 6. Why the model is chosen last, not first
335
+
336
+ A reasonable person asks: why not just write the model in the workflow
337
+ definition?
338
+
339
+ Because the definition is shared and the hardware is not. The same
340
+ `delivery.yaml` runs on a laptop with one API key, a CI box with another, and
341
+ someone else's fork entirely. A model name in the definition would be a promise
342
+ the author cannot keep.
343
+
344
+ So the definition says what *kind* of worker it needs. The hub says which
345
+ *teams* are certified. The machine owner says what those teams *run on*. Each
346
+ layer states only what it actually knows.
347
+
348
+ ---
349
+
350
+ ## 7. Two shifts, one crew — and when that is wrong
351
+
352
+ The `openai` crew has exactly two staging shifts: `openai-1` and `openai-2`.
353
+ Both run codex and carry the same rate card. Because a crew is a team, both
354
+ become eligible for that crew's jobs.
355
+
356
+ **This works, with one consequence you must accept: which member gets the order
357
+ is a race.** First claim wins. The hub does not choose between eligible
358
+ members.
359
+
360
+ That is fine for a job where you genuinely do not care which member claims it
361
+ — a generic `coder` posting where either shift is acceptable.
362
+
363
+ For this staging pair, the two `openai` shifts must carry byte-identical rate
364
+ cards. Crew membership is what makes a shift eligible, and both members are
365
+ eligible for every capability the crew is certified for. If `openai-2` were
366
+ missing a row that `openai-1` has, the hub would eventually hand `openai-2` an
367
+ order it cannot price; `openai-2` would refuse with
368
+ `unresolvable-capability`; the hub would re-offer the order. That is the
369
+ claim-refuse-reoffer loop, and nothing about it is visible from the hub side —
370
+ the routing table is identical in both cases. This is why section 3c says both
371
+ openai cards are byte-identical.
372
+
373
+ This is a property of these two shifts sharing the `codex` adapter, not a
374
+ universal rule for every pair of shifts serving one crew. Shifts on different
375
+ adapters may use different model ids and separate settings directories; the
376
+ invariant is that every eligible shift must be able to resolve every capability
377
+ the crew is certified for.
378
+
379
+ It is exactly wrong for `wise:deep`, where the entire point is "this specific
380
+ one must be claude-fable-5." `wise:deep` is certified to `anthropic`, and
381
+ the anthropic card serves it with `claude-fable-5`, a different model from
382
+ every other `wise` row. If you want a guarantee about *which model*, you need
383
+ a crew whose members all run that model, and you certify that crew for the
384
+ compound.
385
+
386
+ One more failure mode: a step can declare a permission policy an adapter cannot
387
+ enforce (see `x.harness` in a step definition). A member on the wrong harness
388
+ releases the order with `incompatible-harness-policy`, and the hub re-offers it.
389
+ So a mixed crew can also produce a claim-then-release loop if the step's policy
390
+ is adapter-specific.
391
+
392
+ ---
393
+
394
+ ## 8. Escalation — the per-step, temporary grade change
395
+
396
+ A step can declare an escalation:
397
+
398
+ ```yaml
399
+ - name: builder
400
+ capabilities: [build]
401
+ escalation:
402
+ after: 3
403
+ modifier: deep
404
+ ```
405
+
406
+ Read: *after this step's owed artifact has been judgment-rejected 3 times,
407
+ re-offer this step composed with `deep` instead of the run's own modifier.*
408
+
409
+ Four properties, all easy to get wrong:
410
+
411
+ 1. **It is the engine's transition, not the worker's.** No agent reads this
412
+ block. A worker cannot opt in or out.
413
+ 2. **It is per step and per run.** The `builder` escalating does not change
414
+ what `planner` or `reviewer` are offered as.
415
+ 3. **It never rewrites the run's stored modifier.** The instance still says
416
+ `modifier = "standard"`. Only that one step's offer moved.
417
+ 4. **It is a no-op on a run that is already at the target grade.** A `deep` run
418
+ whose builder escalates to `deep` just keeps re-offering `build:deep`.
419
+
420
+ The order carries a marker, `order.escalated = true`, so a reader can tell an
421
+ escalated re-offer from an ordinary one.
422
+
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.
427
+
428
+ ---
429
+
430
+ ## 9. When nobody is certified — the rule that is changing
431
+
432
+ This is the single line that has caused more confusion than everything else in
433
+ this document combined. It is worth reading twice.
434
+
435
+ **The situation:** a run is started with `--modifier express`. The `builder`
436
+ step composes to `build:express`. The hub looks in `capability_routes` and
437
+ finds **no live crew certified for `build:express`.**
438
+
439
+ ### 9a. The OLD rule (what a current hub does)
440
+
441
+ The hub falls back to **name matching**: it offers the job to any crew
442
+ certified for anything whose name part is `build` — so the crew certified for
443
+ plain `build` claims it.
444
+
445
+ Why that is bad: the claiming shift receives `order.capabilities =
446
+ ['build:express']`, finds no `build:express` row in its `roster`,
447
+ falls back to its bare `build` row, and runs on that model. The run believes it
448
+ got express service. It actually got whatever the generic build row happens to
449
+ be. Nothing failed, nothing was logged loudly, and the operator has no signal.
450
+
451
+ It converts the fact *"no shift is serving express right now"* into the
452
+ different fact *"the operator accepted a different grade of service."* Those
453
+ are not the same thing and the system had no business equating them.
454
+
455
+ ### 9b. The NEW rule (what is being built)
456
+
457
+ **An unbound compound holds.** The hub keeps the mode at `exact`, so the order
458
+ simply waits until a crew certified for `build:express` clocks in. It does not
459
+ degrade to a generic worker.
460
+
461
+ **And the operator is told.** The hub writes a routing alert (kind
462
+ `binding-gap`) naming the capability that has no certified crew.
463
+
464
+ **Holding is not failure.** A held order is not dead. It is waiting. The
465
+ existing stall-notification system covers the case where a run sits too long,
466
+ and a crew that was restarted picks the work up when it comes back. There is no
467
+ built-in timer that silently downgrades the job.
468
+
469
+ The old behavior had a 15-minute escalation-fallback window baked in. That is
470
+ being removed. If an operator wants a timed fallback, they configure it; the
471
+ system does not assume it.
472
+
473
+ ---
474
+
475
+ ## 10. Reroute rules — saying "yes, substitute" on purpose
476
+
477
+ *(The engine half is in `owenloop`, the hub half is in `owenloop-service`, and
478
+ the CLI surface is `owenloop routing rule` — see
479
+ [Routing](cli.md#routing) in the CLI reference. The MCP surface follows.)*
480
+
481
+ Holding is the right default, but sometimes the operator genuinely does want a
482
+ substitution — "if nobody is serving `build:express` right now, `build:standard`
483
+ is fine." Section 9's rule makes that a decision the operator states, instead of
484
+ something the hub assumes.
485
+
486
+ A **reroute rule** is exactly that statement:
487
+
488
+ ```
489
+ build:express -> build:standard
490
+ ```
491
+
492
+ How it works, mechanically:
493
+
494
+ 1. The hub composes the offer as usual and finds `build:express` has no live
495
+ binding.
496
+ 2. The hub consults the operator's reroute rules and finds a target,
497
+ `build:standard`, that *does* have a live binding.
498
+ 3. The hub hands the engine a **rewrite**: `{ 'build:express': 'build:standard' }`.
499
+ 4. The engine **substitutes the string**. The order goes out as
500
+ `build:standard`, and carries `reroutedFrom: ['build:express']`.
501
+ 5. The hub writes a routing alert (kind `reroute`) recording that it happened.
502
+
503
+ **Why substitute the string rather than just loosen the match?** Because the
504
+ claiming shift resolves its model from `order.capabilities`. If the hub merely
505
+ widened the match, the shift would receive `build:express`, find no row for it,
506
+ and fall back to its bare `build` row — the wrong model, which is the exact bug
507
+ section 9a describes. Substituting means the shift receives `build:standard` and
508
+ resolves *standard's* model, which is what the operator asked for.
509
+
510
+ **Why two fields on the order?** A rerouted order has two simultaneously true
511
+ answers to "which capability is this?"
512
+
513
+ - `capabilities` — the capability **being served**. This is what the shift
514
+ resolves its model against.
515
+ - `reroutedFrom` — the capability the definition **asked for**.
516
+
517
+ `reroutedFrom` is absent on every ordinary offer, so its presence alone tells a
518
+ reader the order is not running on what its definition requested. A single field
519
+ could only ever carry one of the two facts, and an operator asking "why did this
520
+ run on Opus?" would have no way back to "because we asked for express."
521
+
522
+ **The run's stored modifier is never touched by a reroute.** Re-reading the run
523
+ record still shows the grade of service that was requested. Only the offer
524
+ moved.
525
+
526
+ **Chains are resolved by the hub, not the engine.** If `a -> b` and `b -> c`,
527
+ the hub walks the chain and hands the engine the final answer. The engine
528
+ performs exactly one substitution and never looks a target up again, so a cycle
529
+ is impossible there rather than merely bounded.
530
+
531
+ ### How an operator states and inspects all of this
532
+
533
+ The rules and the alerts are two separate command surfaces on one hub org — see
534
+ [Routing](cli.md#routing) in the CLI reference for flags, output shape and exit
535
+ codes.
536
+
537
+ | what you want | command |
538
+ |---|---|
539
+ | write the rule `build:express -> build:standard` | `owenloop routing rule add build:express build:standard` |
540
+ | put a rule ahead of the ones already there | `owenloop routing rule add build:express build --position 0` |
541
+ | see the rules in the order the hub tries them | `owenloop routing rule list` |
542
+ | take one rule back | `owenloop routing rule rm build:express build:standard` |
543
+ | see every hold, reroute, wait and fallback org-wide | `owenloop routing alerts` |
544
+ | see one run's routing timeline | `owenloop routing show <workflow>` |
545
+
546
+ **Three cautions the command names do not carry on their own.**
547
+
548
+ 1. **A reroute rule is not a binding.** `routing rule add` writes a
549
+ `capability_reroutes` row, which names no crew and grants nobody access.
550
+ `capability bind` writes a `capability_routes` row, which does. A reroute
551
+ only reaches a crew if its **target** capability has a live binding of its
552
+ own, so adding a rule cannot by itself widen who may claim work.
553
+ 2. **`routing rule list` order is meaning, not presentation.** Rows are grouped
554
+ by source capability and ordered by ascending `position` — the first row for
555
+ a capability is the first target the hub attempts.
556
+ 3. **Removing the last rule for a capability restores holding.** With no rule
557
+ left, an unbound compound waits again, exactly as section 9b describes. The
558
+ CLI prints `remainingTargets: []` and says so on stderr.
559
+
560
+ ---
561
+
562
+ ## 11. The mistakes we keep making
563
+
564
+ Each of these has actually happened. Each has a one-line correction.
565
+
566
+ | Mistake | Correction |
567
+ |---|---|
568
+ | "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
+ | "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
+ | "`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`. |
572
+ | "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
+ | "`--modifier` defaults to standard." | Omitting it means **no modifier**. Steps are offered on bare authored capabilities. |
574
+ | "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. |
576
+ | "Escalation upgrades the run." | It re-offers **one step**, temporarily. The run's stored modifier is untouched. |
577
+ | "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
+ | "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. |
579
+
580
+ ---
581
+
582
+ ## 12. One-screen summary
583
+
584
+ ```
585
+ delivery.yaml steps: [{ name: builder, capabilities: [build] }]
586
+ |
587
+ owenloop start --modifier deep (stored once, never changes)
588
+ |
589
+ engine composes build + deep -> "build:deep"
590
+ |
591
+ hub reads capability_routes: build:deep -> crew "openai"
592
+ |
593
+ hub derives caller set from the asking shift's crew memberships
594
+ |
595
+ match: exact -> only crews certified for "build:deep" may claim
596
+ |
597
+ the openai-1 shift claims; order.capabilities = ["build:deep"]
598
+ |
599
+ shift merges its crew roster:
600
+ "build:deep": [{ harness: codex, model: gpt-5.6-terra, effort: xhigh }]
601
+ |
602
+ the selected candidate spawns that model at that effort
603
+ ```
604
+
605
+ If the lookup at step 3 finds nobody: the order **holds** and an alert is
606
+ written. If the operator has configured a reroute rule, the hub substitutes the
607
+ target capability and records `reroutedFrom` on the order.
@@ -27,13 +27,29 @@ 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. They are **not** in `<run>.log`.
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`.
31
32
 
32
- So a `<run>.log` holds the worker's own diagnostics — "holding this order",
33
- "running this step", the `workdir` fallback warning, a crash stack — and not the
34
- command's output. One destination each, no duplication. `packages/work/test/
35
- shift-logs-acceptance.test.ts` asserts both halves, the presence and the
36
- absence.
33
+ 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.
37
+
38
+ | Command outcome | Worker channel | Header |
39
+ | --- | --- | --- |
40
+ | exit 0 and no machinery error | stdout | `… the command for step 'X' succeeded; its output follows` |
41
+ | anything else | stderr | `… the command for step 'X' exited N` / `was killed by …` / `could not be run (…)`; `its last output follows` |
42
+
43
+ Under shift dispatch fd 1 and fd 2 both point at the same file, so the header —
44
+ not the channel — is what tells these outcomes apart in `<run>.log`. The two
45
+ channels still matter: stderr is what a reader treats as trouble, and routine
46
+ success output there would make every green step look like a problem.
47
+
48
+ A command that printed nothing gets ` (the command produced no output)` on both
49
+ paths, because a gate that prints nothing is itself a diagnosis. The relay is
50
+ unconditional and has no off switch.
51
+ `packages/work/test/shift-logs-acceptance.test.ts` asserts that the marker
52
+ appears in `<run>.log` exactly once, as ` | <marker>`.
37
53
 
38
54
  ## Where the directory is
39
55
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.7",
3
+ "version": "0.5.8",
4
4
  "description": "Deterministic rails for agentic workflows. Declare steps and dependencies; the engine guarantees order, redoes what changes invalidate, and stops what keeps failing — instead of hoping the agent follows through.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "typicalday",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.7",
3
+ "version": "0.5.8",
4
4
  "description": "Claude Code driver for owenloop — cross-harness shift and conduct skills driven by the owenloop CLI, plus one hub control-plane MCP server backing an author skill and a fallback worker, for conducting and authoring workflows against your hosted owenloop server.",
5
5
  "author": {
6
6
  "name": "Typical Day"
@@ -7,7 +7,7 @@
7
7
  "mcp"
8
8
  ],
9
9
  "env": {
10
- "OWENLOOP_PLUGIN_VERSION": "0.5.7"
10
+ "OWENLOOP_PLUGIN_VERSION": "0.5.8"
11
11
  }
12
12
  }
13
13
  }
@@ -66,8 +66,7 @@ x:
66
66
  ```
67
67
 
68
68
  `id` is optional. When `id` is absent, the runtime may select the registered
69
- default adapter; `--harness` and `OWENLOOP_HARNESS` overrides take precedence
70
- over the definition. Keep policy in `x.harness` even when `id` is absent.
69
+ default adapter; a selected crew-roster candidate takes precedence; `--harness` is a local debug override. Keep policy in `x.harness` even when `id` is absent.
71
70
 
72
71
  When a producer declares native `judges:`, put `x.harness` on the producer
73
72
  step, not on each judge entry. Every synthesized judge automatically inherits