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
package/docs/cli.md CHANGED
@@ -60,6 +60,11 @@ for the full breakdown.
60
60
  | `capability bind <capability> <crew> [--hub <url>]` | add a crew to a workflow capability on the hub org — a capability may route to many crews (admin; human credential) — see [Capability routes](#capability-routes) |
61
61
  | `capability unbind <capability> <crew> [--hub <url>]` | remove one `(capability, crew)` route — see [Capability routes](#capability-routes) |
62
62
  | `capability list [--hub <url>]` | list the hub org's capability routes — see [Capability routes](#capability-routes) |
63
+ | `routing alerts [--workflow <wf>] [--limit <n>] [--hub <url>]` | list the hub org's routing alerts — every hold, reroute, wait and fallback the hub recorded — see [Routing](#routing) |
64
+ | `routing show <workflow> [--hub <url>]` | print one **hub run's** routing: modifier, wait policy, alerts, resolution reports and escalations — see [Routing](#routing) |
65
+ | `routing rule list [--hub <url>]` | list the org's capability **reroute rules**, in the order the hub tries them — see [Routing](#routing) |
66
+ | `routing rule add <capability> <target> [--position <n>] [--hub <url>]` | add one reroute rule — offer `<capability>` as `<target>` when it has no live crew binding (admin; human credential) — see [Routing](#routing) |
67
+ | `routing rule rm <capability> <target> [--hub <url>]` | remove one reroute rule — see [Routing](#routing) |
63
68
  | `crew list [--hub <url>]` | list the hub org's crews with their members (includes the orphan crew once one exists) — see [Crews](#crews) |
64
69
  | `crew new <name> --kind personal\|shared [--owner <memberId>] [--hub <url>]` | create a crew on the hub org (admin, or own personal crew; human credential) — see [Crews](#crews) |
65
70
  | `crew rm <crewId> [--hub <url>]` | delete a crew; work stamped to it moves to the org's orphan crew — see [Crews](#crews) |
@@ -68,6 +73,7 @@ for the full breakdown.
68
73
  | `setup [--hub <url>] [--new-agent <name> \| --replace-agent <name>] [--crews <a,b>] [--scopes <a,b>] [--reuse-ssh-key <path>]` | onboard this machine: may store human and Scoped Identity credentials, ensure the three principal signing keys, relay the machine enrollment grant, write only execution-settings `hubOrigin`, and converge the bundled plugins for Claude Code and Codex — see [`setup`](#setup--onboard-a-machine) |
69
74
  | `enrollments [--hub <url>]` | read and locally classify the hub's relayed machine enrollment grants; never creates keys or writes the roster — see [`enrollments`](#enrollments--inspect-machine-enrollment) |
70
75
  | `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
76
+ | `roster show [crew]` | print the merged **crew roster** and the provenance of every selected candidate layer |
71
77
  | `mcp [--hub <url>]` | serve the hub control plane to a local MCP host over stdio — spawned by MCP hosts, not run by humans — see [`mcp`](#mcp--stdio-control-plane-server-for-mcp-hosts) |
72
78
  | `shift start <crew...>`, `shift next`, `shift status`, `shift end` | run the foreground shift daemon and its local clients — see [`shift`](#shift--foreground-daemon-and-client) |
73
79
  | `work <subcommand> [options]` | run the execution-side CLI companion — see [`work`](#work--execution-side-cli-companion) |
@@ -171,17 +177,12 @@ but attendance is advisory and observability-only. Attendance never changes
171
177
  routing, dispatch, or lease behavior.
172
178
 
173
179
  <a id="config-dir"></a>
174
- The execution settings file is `<config>/settings.json`. Throughout this
175
- document `<config>` is owenloop's own config directory, resolved from the
176
- environment by this ladder, highest first:
177
-
178
- 1. `$OWENLOOP_CONFIG_DIR` when set to a non-blank ABSOLUTE path — used verbatim,
179
- with no `owenloop` segment appended;
180
- 2. `$XDG_CONFIG_HOME/owenloop` when `XDG_CONFIG_HOME` is non-blank;
181
- 3. `$HOME/.config/owenloop`.
182
-
183
- The same directory holds `credentials.json`, `allowed_signers`, `org-root.pub`,
184
- `roster/`, and `revocations/`.
180
+ By default, the execution settings file is `$HOME/.owenloop/settings.json`.
181
+ For test or throwaway isolation, `OWENLOOP_CONFIG_DIR` may name an absolute
182
+ directory used verbatim; `XDG_CONFIG_HOME` is not consulted. In the paths below,
183
+ `<config>` means the resolved owenloop config directory. The same directory
184
+ holds `credentials.json`, `allowed_signers`, `org-root.pub`, `roster/`, and
185
+ `revocations/`.
185
186
 
186
187
  ### `shift start <crew...>`
187
188
 
@@ -253,102 +254,56 @@ directories an order is **allowed to name**. Neither derives from the other.
253
254
  owenloop shift start build --work-root ~/code --work-root /srv/work
254
255
  ```
255
256
 
256
- **One harness per shift.** A shift has no per-order harness switch and no
257
- `--harness` flag. It never puts `--harness` on a worker's command line; each
258
- `agent-run` child resolves its own adapter, in this order:
257
+ **Crew roster selection.** “Roster” in this section means the **crew
258
+ roster** for capability routing, not the unrelated trust roster of signed
259
+ enrollment grants in `~/.owenloop/roster/`. A selected roster candidate decides
260
+ the harness, model, and effort for an agent order. Its precedence is:
259
261
 
260
- 1. its own `--harness` flag — which a shift never supplies;
261
- 2. `OWENLOOP_HARNESS` in the environment the child inherits, which is the
262
- shift's environment;
263
- 3. the `harness:` field on the verified step definition;
262
+ 1. the first available candidate in the first matching crew roster;
263
+ 2. `owenloop work agent-run --harness` (a local debug override);
264
+ 3. the verified step's `x.harness.id`;
264
265
  4. the first registered adapter.
265
266
 
266
- Rank 2 is the operator's control. Export `OWENLOOP_HARNESS` in the shell that
267
- starts the shift and every agent order that shift dispatches runs on that
268
- adapter. To run two adapters at once, start two shifts:
269
-
270
- ```bash
271
- OWENLOOP_HARNESS=claude-code OWENLOOP_CONFIG_DIR=~/.config/owenloop-shifts/claude/owenloop owenloop shift start build --state-dir ~/.local/state/owenloop/claude
272
- ```
273
-
274
- ```bash
275
- OWENLOOP_HARNESS=codex OWENLOOP_CONFIG_DIR=~/.config/owenloop-shifts/codex/owenloop owenloop shift start build --state-dir ~/.local/state/owenloop/codex
276
- ```
277
-
278
- Both shifts may serve the SAME crew. The hub does not route by harness — it
279
- offers an order to any shift whose crew is bound to the order's capability, and
280
- whichever shift claims it first runs it on its own adapter.
281
-
282
- **A per-shift config directory is not optional when the adapters differ.** The
283
- settings file resolves from the config directory (see above), and it carries
284
- `capabilityModels` — a map of composed capability to `{model, effort}` whose
285
- model ids are strings the SHIFT'S OWN adapter accepts. Two shifts on different
286
- adapters need different model ids for the same capability, so they need
287
- different settings files, so they need different config directories. A shared
288
- config directory would give both shifts one adapter's model ids, and the shift
289
- holding the wrong adapter fails at the vendor API on its first order.
290
-
291
- **Use `OWENLOOP_CONFIG_DIR` for this, not `XDG_CONFIG_HOME`.** Both resolve the
292
- settings file, and `OWENLOOP_CONFIG_DIR` wins — but `XDG_CONFIG_HOME` is a
293
- machine-wide contract that `gh`, `git`, `gcloud`, `npm`, and most of the rest of
294
- a developer's toolchain also read, and a shift spreads its ENTIRE environment
295
- into every worker it dispatches, which passes it on to every command step's
296
- child process. Scoping a shift with `XDG_CONFIG_HOME` therefore relocates the
297
- configuration of every tool the workflow's own scripts shell out to. Measured,
298
- not theorized: on one delivery run this stranded `gh`'s stored credential, and
299
- the workflow's merge gate spent its full 40-minute wall clock deferring on a CI
300
- probe that could not authenticate, followed by four consecutive merge failures
301
- reading `could not resolve a pull request handle for the branch`. Nothing was
302
- wrong with either script. `OWENLOOP_CONFIG_DIR` scopes owenloop and only
303
- owenloop.
304
-
305
- `OWENLOOP_CONFIG_DIR` names the owenloop config directory ITSELF — the directory
306
- that directly holds `settings.json`, `credentials.json`, and `allowed_signers`.
307
- No `owenloop` path segment is appended to it, unlike the `XDG_CONFIG_HOME` rung.
308
- It must be an ABSOLUTE path: a relative one would resolve against whatever
309
- working directory a step happens to have, and `workdirFrom` gives every step its
310
- own.
311
-
312
- Give each shift its own `--state-dir` as well. The state directory holds the
313
- control socket (`shift.sock`), and a second shift starting against a socket
314
- another shift already owns is refused.
315
-
316
- **`capabilityModels` — which model serves which capability.** The hub decides
317
- WHAT grade of work an order is; it composes the step's capability with the run's
318
- depth modifier and stamps the result on the order (`builder` at the `deep`
319
- modifier becomes `builder:deep`). It never decides which model serves that
320
- grade. That decision is local, and this map is where the operator makes it:
267
+ The shift passes its start crews to each agent worker internally. A named crew
268
+ uses `~/.owenloop/crews/<crew>.json` above the machine-global
269
+ `~/.owenloop/settings.json` `roster` key. Each capability row is atomic:
270
+ the stronger layer replaces the weaker candidate array, and candidates are
271
+ tried in listed order. A step's `x.harness.id` is a policy constraint: a row
272
+ whose candidates do not include it is released as
273
+ `incompatible-harness-policy`; no available candidate is
274
+ `unresolvable-capability`.
321
275
 
322
276
  ```json
323
277
  {
324
- "capabilityModels": {
325
- "builder:deep": { "model": "claude-opus-5", "effort": "xhigh" },
326
- "builder": { "model": "claude-sonnet-5", "effort": "high" },
327
- "wise": { "model": "claude-fable-5", "effort": "xhigh" }
278
+ "roster": {
279
+ "builder:deep": [
280
+ { "harness": "claude-code", "model": "claude-opus-5", "effort": "xhigh" },
281
+ { "harness": "codex", "model": "gpt-5.6-sol", "effort": "xhigh" }
282
+ ],
283
+ "builder": [
284
+ { "harness": "codex", "model": "gpt-5.6-terra", "effort": "high" }
285
+ ]
328
286
  }
329
287
  }
330
288
  ```
331
289
 
332
- Lookup runs two passes over the order's capabilities: every EXACT composed key
333
- first, then every BARE name part. `builder:deep` takes the first row above;
334
- `builder:express` has no exact row and falls back to the `builder` row.
335
- `effort` must be one of `low`, `medium`, `high`, `xhigh`, `max`. The model id is
336
- never checked against a list — owenloop keeps no registry of which models exist,
337
- so a model released after your owenloop build still works.
338
-
339
- A capability with no exact row and no bare row is REFUSED, not run on a default:
340
- the worker releases the claim, reports the refusal to the hub, and exits `1`. An
341
- order carrying no capabilities at all is not refused — it runs on the adapter's
342
- own default model, which is how capability-silent steps have always run.
343
-
344
- **Migrating from `tierMap` / `tierProfiles`.** Both keys are removed. A settings
345
- file that still contains either one fails to load with an error naming
346
- `capabilityModels`; the shift does not start. This is deliberate — a shift that
347
- ignored the old keys would have no capability map at all and would refuse every
348
- order it claimed, hours later and far from the cause. Rewrite the tier rungs as
349
- capability rows: whatever `tierProfiles.strongest` pointed at becomes the
350
- `{model, effort}` of your `:deep` rows, and whatever `standard` pointed at
351
- becomes the bare rows.
290
+ The array form is required even with one candidate. There is no migration path:
291
+ the retired key is rejected at settings load. Exact composed capability lookup
292
+ runs across the order's whole capability list before bare-name lookup, so an
293
+ exact row is never shadowed by an earlier bare row.
294
+
295
+ `~/.owenloop/config.json` and `~/.owenloop/settings.json` intentionally
296
+ remain separate. The control-plane `config.json` carries `hub`, is written by
297
+ `owenloop login`, and is read by `owenloop mcp`. The execution-plane
298
+ `settings.json` carries `hubOrigin` and the machine-global crew roster, is
299
+ written by `owenloop setup`, and is read by `owenloop work`. They answer
300
+ different callers and neither reads the other.
301
+
302
+ `owenloop roster show [crew]` prints the merged roster, every candidate's
303
+ winning-layer provenance, and every layer inspected (including an absent crew
304
+ file). `owenloop doctor` adds one line for each present crew roster file,
305
+ showing its found/absent layers and registered versus missing candidate
306
+ harnesses.
352
307
 
353
308
  A clean start or `--once` completion exits `0`. `owenloop shift --help` also
354
309
  exits `0`. Runtime failures such as credential reads or socket/runtime setup
@@ -549,8 +504,7 @@ An absent `x.harness.tools` field preserves the adapter's default tool surface;
549
504
  `tools: []` is an explicit empty allow-list. The two forms are not equivalent.
550
505
  Invalid reserved fields and overlapping `tools` / `disallowedTools` are refused.
551
506
  `owenloop work lint` runs the same common and adapter checks, but runtime
552
- preflight remains authoritative because `--harness` or `OWENLOOP_HARNESS` can
553
- select a different adapter after lint. See [Agent runner and harness policy](agent-runner.md)
507
+ preflight remains authoritative because roster availability and `--harness` can select a different adapter after lint. See [Agent runner and harness policy](agent-runner.md)
554
508
  for the capability matrix and the born-bound Owenloop control-plane exception.
555
509
 
556
510
  **Harness-session durability.** `agent-run` records the provider session in the
@@ -1354,7 +1308,7 @@ owenloop login --hub https://hub.example
1354
1308
  owenloop connect --hub https://hub.example
1355
1309
  owenloop push newhire-onboarding
1356
1310
  OWENLOOP_ACCOUNT=default owenloop work prepare newhire-onboarding --origin https://hub.example
1357
- OWENLOOP_HARNESS=codex owenloop shift start openai --origin https://hub.example --as default
1311
+ owenloop shift start openai --origin https://hub.example --as default
1358
1312
  ```
1359
1313
 
1360
1314
  Starting another run does not repeat installation, publication, preparation,
@@ -1420,6 +1374,8 @@ Three properties come from the hub verb, not from this command:
1420
1374
  `owenloop instance show <workflow>` sends `GET /api/status/:wf` and prints the
1421
1375
  instance's state: `done`, the `debts` it still owes, the steps that are
1422
1376
  `eligible` or `blocked`, the runs `inFlight`, and `defDrift`.
1377
+ It also prints the hub's liveness verdict as `instanceStatus` and `terminal`
1378
+ when the hub provides those fields.
1423
1379
 
1424
1380
  It answers the question no other local command can: **why is this run not
1425
1381
  moving?** Two of its fields are the entire diagnosis, and both are invisible
@@ -1433,6 +1389,13 @@ from the outside because each one looks exactly like an idle shift:
1433
1389
  never offered to anyone. Present only when something is actually parked;
1434
1390
  `getStatus` omits the field otherwise, and `instance show` omits it too rather
1435
1391
  than printing `[]`, which would read as "asked, and the answer is none."
1392
+ - **`instanceStatus` and `terminal`** — the hub's liveness verdict. `terminal: true`
1393
+ means the instance will receive no further dispatch; failed and
1394
+ cancelled instances can therefore be terminal even when `done` is false.
1395
+ A terminal instance also writes an advisory to stderr, while the JSON state
1396
+ remains on stdout. These fields are omitted when an older hub does not send
1397
+ them; an explicit `terminal: false` is preserved as the hub's affirmative
1398
+ live answer.
1436
1399
 
1437
1400
  Naming, because two obvious names were already taken by different commands:
1438
1401
 
@@ -1662,7 +1625,7 @@ credential above is verified and stored, `login` makes one more best-effort
1662
1625
  write: it records the hub origin it just authenticated against in
1663
1626
  `~/.owenloop/config.json` (`{"version": 1, "hub": "<origin>"}` — never a
1664
1627
  secret, just the origin). This file is separate from both the credential store
1665
- above and from `owenloop setup`'s `~/.config/owenloop/settings.json`; its only
1628
+ above and from `owenloop setup`'s `~/.owenloop/settings.json`; its only
1666
1629
  reader is `owenloop mcp`'s [origin resolution](#choosing-the-hub-origin),
1667
1630
  which needs to know your hub without enumerating the credential store (the
1668
1631
  Keychain and external-command backends can't be listed at all — see below). A
@@ -2065,6 +2028,237 @@ needs a translation step.
2065
2028
  | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
2066
2029
  | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
2067
2030
 
2031
+ ## Routing
2032
+
2033
+ `owenloop routing` reads and edits the hub's **live routing** state — what the
2034
+ hub did when it tried to reach a crew, and the operator's standing instructions
2035
+ for what to do when it cannot. [Routing](routing.md) is the conceptual guide;
2036
+ this section is the command surface.
2037
+
2038
+ **Three different objects share the word "routing". They are not
2039
+ interchangeable:**
2040
+
2041
+ | object | what it is | where it lives | which command |
2042
+ |---|---|---|---|
2043
+ | **capability route** | a `(capability, crew)` **binding** — the row that grants a crew the right to be offered that capability's work | `capability_routes` on the hub org | [`capability bind`/`unbind`/`list`](#capability-routes) |
2044
+ | **capability reroute rule** | an ordered operator statement — "when `<capability>` has no live crew binding, offer it as `<target>` instead" | `capability_reroutes` on the hub org | `routing rule list`/`add`/`rm` |
2045
+ | **routing alert** | an immutable **event row** the hub wrote when it held, rerouted, waited or fell back | `routing_alerts` on the hub org | `routing alerts`, and `routing show` for one run |
2046
+
2047
+ **A reroute rule is not a binding.** It names no crew, grants nobody access, and
2048
+ has no live/dangling distinction. It only says which *other capability name* the
2049
+ hub may substitute — and the substitution only reaches a crew if that target
2050
+ capability has a live binding of its own. Adding a reroute rule can therefore
2051
+ never widen who may claim work by itself; the widening, if any, already exists in
2052
+ `capability_routes`.
2053
+
2054
+ **A `binding-gap` alert means the hub HELD an offer** because its compound
2055
+ capability (`<capability>:<modifier>`, e.g. `build:express`) had no live crew
2056
+ binding, and it found no usable reroute target either. Holding is the deliberate
2057
+ default — the hub no longer silently falls back to the bare capability name — so
2058
+ these alerts are the record of work that is waiting rather than work that ran on
2059
+ the wrong grade. See [Routing §9b](routing.md#9b-the-new-rule-what-is-being-built).
2060
+
2061
+ ### `routing alerts`
2062
+
2063
+ `GET /api/routing_alerts`, authenticated as your **human** credential. Lists the
2064
+ org's routing alerts. An org that has never held, rerouted, waited or fallen
2065
+ back is a normal success (exit 0) with an empty `alerts` array.
2066
+
2067
+ **The array order is the hub's answer and is never re-sorted here, and the two
2068
+ orderings are different:**
2069
+
2070
+ - **No `--workflow`** — an org-wide inbox, **newest first**. This is the "what is
2071
+ wrong right now" view.
2072
+ - **`--workflow <wf>`** — one run's alerts, **oldest first**. This is a
2073
+ chronological timeline: hold, then wait, then reroute, in the order the hub
2074
+ decided them.
2075
+
2076
+ Passing `--workflow` is what flips the ordering, so a script that pages through
2077
+ both must not assume one direction. The value is echoed back on stdout as
2078
+ `workflow` precisely so a reader can tell the two views apart without
2079
+ re-inspecting argv.
2080
+
2081
+ `--limit <n>` caps how many rows the hub returns. Omit it and the hub applies
2082
+ its own default page size. The hub **silently ignores** a limit it cannot use (a
2083
+ non-integer, zero, or a negative) and answers with its default instead — so the
2084
+ CLI rejects a `--limit` that is not a number **before** any request, rather than
2085
+ reporting a page size you never asked for.
2086
+
2087
+ A row's `modifier`, `step` and `detail` are legitimately `null` — an org-level
2088
+ event carrying no step or no modifier is a real state, not a defect — and they
2089
+ are printed as `null` rather than dropped. `detail` is an opaque per-kind
2090
+ metadata string the CLI forwards verbatim and never parses.
2091
+
2092
+ ### `routing show <workflow>`
2093
+
2094
+ `GET /api/run_routing/<workflow>`, authenticated as your **human** credential.
2095
+ Prints the complete routing picture for ONE hub run: its modifier, its wait
2096
+ policy, its own alerts, its resolution reports (which rule matched for each step)
2097
+ and its escalations.
2098
+
2099
+ **This is not the local `show` command.** `owenloop show <wf>` dumps the raw
2100
+ artifacts of a **local** instance out of the local sqlite database and never
2101
+ touches a hub. `owenloop routing show <workflow>` takes a **hub** workflow id and
2102
+ reads hub state. They share four letters and nothing else.
2103
+
2104
+ `modifier` is **omitted entirely** for a run started without one. The key's
2105
+ absence is how stdout says "no modifier" — an empty string is never printed,
2106
+ because a modifier named nothing is not a state the hub can hold.
2107
+
2108
+ **An unknown or foreign workflow id gets a generic error today.** The hub's verb
2109
+ raises an untyped error for a run this org does not own or that does not exist,
2110
+ and its edge maps that to `HTTP 500` with the message `internal server error`.
2111
+ The CLI prints whatever message the hub sends, so a future typed `404` will
2112
+ surface as a useful sentence with no change here — but do not read today's
2113
+ `internal server error` as a hub defect; it is what "no such run for you" looks
2114
+ like on this endpoint right now.
2115
+
2116
+ `resolutionReports` and `escalations` belong to adjacent subsystems. Their rows
2117
+ are checked to be objects and then forwarded **verbatim**, so a field added on
2118
+ the hub widens what this command prints instead of breaking it.
2119
+
2120
+ ### `routing rule list`
2121
+
2122
+ `GET /api/capability_reroutes`, authenticated as your **human** credential. Lists
2123
+ the org's reroute rules. An org with no rules is a normal success (exit 0) with
2124
+ an empty `reroutes` array.
2125
+
2126
+ **The array order is semantic: it is the order the hub TRIES the substitutions
2127
+ in**, and it is never re-sorted here. Rows are grouped by source `capability` and
2128
+ ascending `position` within each group, so the first row for a capability is the
2129
+ first target the hub attempts. Re-sorting this list client-side — even
2130
+ alphabetically, even "for readability" — would misreport which substitution
2131
+ actually happens.
2132
+
2133
+ ### `routing rule add <capability> <target>`
2134
+
2135
+ `POST /api/add_capability_reroute`, authenticated as your **human** credential;
2136
+ requires the **admin** role on the hub. Adds one ordered rule: when
2137
+ `<capability>` has no live crew binding, the hub may offer the work as
2138
+ `<target>` instead.
2139
+
2140
+ The CLI performs no client-side validation of either argument — the hub is the
2141
+ enforcement of record. It rejects a rule whose `capability` and `target` are
2142
+ equal (`400 capability_reroute_invalid`), and the CLI surfaces that message
2143
+ verbatim.
2144
+
2145
+ **`--position <n>` sets the rule's rank among the rules for that same
2146
+ `<capability>`,** counting from `0` — lower is tried first. **Omitting
2147
+ `--position` APPENDS** the rule after the source capability's existing rules. The
2148
+ flag is omitted from the request body entirely when you do not pass it; sending
2149
+ `0` would mean "try this first", which is a different instruction.
2150
+
2151
+ **Adding is idempotent per `(capability, target)` pair.** Re-adding a pair that
2152
+ already exists is a normal success — the hub answers `200` with `alreadyPresent:
2153
+ true` and changes nothing (the original row keeps its position and timestamp).
2154
+ `ruleCount` reports how many rules the source capability has after the write.
2155
+
2156
+ Chains are resolved **by the hub**, not by this CLI and not by the engine: if
2157
+ `a → b` and `b → c` both exist, the hub walks the chain and hands the engine one
2158
+ final substitution.
2159
+
2160
+ ### `routing rule rm <capability> <target>`
2161
+
2162
+ `POST /api/remove_capability_reroute`, authenticated as your **human**
2163
+ credential; requires the **admin** role on the hub. Removes the ONE
2164
+ `(capability, target)` rule you name. `<target>` is **required**: a capability
2165
+ may have several reroute rules, so a capability-only removal would delete more
2166
+ than you asked for.
2167
+
2168
+ **`rm` is idempotent, and unlike `add` it cannot fail on a bad pair.** Removing a
2169
+ rule that is not there is a normal success — the hub answers `200` with
2170
+ `removed: false` rather than a `404` — and the CLI prints a full document plus a
2171
+ stderr line saying nothing was removed. A script can call `routing rule rm`
2172
+ unconditionally without first checking whether the rule exists.
2173
+
2174
+ **Removing the last rule for a capability makes it HOLD again.** `remainingTargets:
2175
+ []` on stdout is that signal, and stderr says so in words: with no rule left, an
2176
+ offer for that capability with no live crew binding waits instead of
2177
+ substituting. Nothing is lost — the held work resumes as soon as a crew binds
2178
+ the capability or a rule is added back.
2179
+
2180
+ ### Flags, hub resolution, output and exits
2181
+
2182
+ **Flags.** `--hub <url>` on every subcommand; `--workflow <wf>` and `--limit <n>`
2183
+ on `routing alerts`; `--position <n>` on `routing rule add` (plus the global
2184
+ `--db`/`--defs`). The allowlist is per top-level command, so `--position` on
2185
+ `routing alerts` is accepted and ignored rather than rejected — the same
2186
+ looseness `crew list` has with `--kind`.
2187
+
2188
+ **Which hub gets acted on (`--hub`).** Resolution is the same narrow ladder
2189
+ `capability bind` uses, and for the same reason — a reroute rule written against
2190
+ the wrong org moves in-flight work and is not undone by a retry:
2191
+
2192
+ 1. `--hub <origin>` if given (normalized the same way as everywhere else).
2193
+ 2. Otherwise the **one** hub your credential *file* stores — if exactly one is
2194
+ present, it's used.
2195
+ 3. Otherwise the command **exits 2** naming both remedies (pass `--hub`, or log
2196
+ in to exactly one hub); when more than one hub is stored their origins are
2197
+ listed back so you can pick.
2198
+
2199
+ This does **not** fall back to `OWENLOOP_HUB` or the built-in default hub, and
2200
+ hub enumeration is **file-store only**: the keychain and the external-command
2201
+ backend cannot list their entries, so on such a machine step 2 cannot enumerate
2202
+ the store and you must pass `--hub`.
2203
+
2204
+ **Printed JSON.** stdout is exactly one whitelisted JSON document per
2205
+ invocation, built from named fields — never a raw hub body — so `| jq` always
2206
+ works. Human progress lines (the two `routing rule rm` warnings) go to stderr
2207
+ only.
2208
+
2209
+ | subcommand | stdout |
2210
+ |---|---|
2211
+ | `routing alerts` | `{ "ok": true, "hub": "<origin>", "workflow": "wf_1", "alerts": [ { "id": "ral_1", "at": 1738000000000, "workflow": "wf_1", "kind": "binding-gap", "capability": "build:express", "modifier": "express", "step": "builder", "detail": null } ] }` |
2212
+ | `routing show` | `{ "ok": true, "hub": "<origin>", "workflow": "wf_1", "defName": "delivery", "modifier": "express", "waitPolicy": { "wait": "forever" }, "alerts": [ … ], "resolutionReports": [ … ], "escalations": [ … ] }` |
2213
+ | `routing rule list` | `{ "ok": true, "hub": "<origin>", "reroutes": [ { "capability": "build:express", "target": "build:standard", "position": 0, "createdAt": 1738000000000 } ] }` |
2214
+ | `routing rule add` | `{ "ok": true, "hub": "<origin>", "capability": "build:express", "target": "build:standard", "position": 0, "alreadyPresent": false, "ruleCount": 2 }` |
2215
+ | `routing rule rm` | `{ "ok": true, "hub": "<origin>", "capability": "build:express", "target": "build:standard", "removed": true, "remainingTargets": ["build"] }` |
2216
+
2217
+ Every field carries the **hub's own name**, verbatim — the same words its audit
2218
+ log and the web console use — so correlating stdout against them never needs a
2219
+ translation step.
2220
+
2221
+ - `workflow` (`routing alerts`) — present **only** when you passed `--workflow`,
2222
+ so its presence alone means the list is scoped and oldest-first. An empty
2223
+ `--workflow ''` is rejected as a usage error rather than sent, because the hub
2224
+ treats an empty value as absent and would answer org-wide under a stdout
2225
+ claiming a filter.
2226
+ - `kind` (`routing alerts`, `routing show`) — the hub's own event name
2227
+ (`binding-gap`, `reroute`, and others). It is forwarded verbatim and
2228
+ deliberately **not** narrowed to a fixed set, so a kind the hub adds later
2229
+ prints rather than breaks the command.
2230
+ - `modifier` (`routing show`) — **absent**, not `null`, for a run started without
2231
+ a modifier. On an alert row the same field IS `null`-able, because an alert
2232
+ that concerns no modified capability is a real event.
2233
+ - `waitPolicy` (`routing show`) — `{ "wait": "forever" }`, or
2234
+ `{ "wait": "<duration>", "then": "fallback" }` for a timed policy. `then` is
2235
+ absent on the forever form.
2236
+ - `position` (`routing rule list`, `routing rule add`) — the rule's rank among
2237
+ the rules for the same source capability, from `0`; lower is tried first. On
2238
+ `routing rule add` it is the rank the **hub** stored, which is routinely one
2239
+ you never typed, because omitting `--position` appends.
2240
+ - `alreadyPresent` (`routing rule add`) — was this exact `(capability, target)`
2241
+ pair already a rule before the call? `false` means the call created it.
2242
+ - `ruleCount` (`routing rule add`) — how many reroute rules the source capability
2243
+ has after the write.
2244
+ - `removed` (`routing rule rm`) — did this call actually remove a rule? `false`
2245
+ is the tolerant "it was never there" case, not an error.
2246
+ - `remainingTargets` (`routing rule rm`) — the targets the capability can still
2247
+ be substituted with. `[]` means the capability now **HOLDS** whenever it has no
2248
+ live crew binding: `jq '.remainingTargets | length == 0'`.
2249
+ - `capability` and `target` are the values the **hub** echoed back, not your
2250
+ argv: if the hub normalized either, stdout tells the truth about what was
2251
+ stored.
2252
+
2253
+ **Exit codes.**
2254
+
2255
+ | code | meaning |
2256
+ |---|---|
2257
+ | `0` | the alerts, run routing or rules were listed; the rule was added (or was already present); the rule was removed (or was already absent) |
2258
+ | `1` | usage error (an unknown subcommand, a missing `<workflow>`/`<capability>`/`<target>`, a non-numeric `--limit`, an empty `--workflow`) or a runtime or hub error — a self-referential rule, a `403` for a non-admin, an unknown workflow (see `routing show` above), a malformed response, or a network timeout |
2259
+ | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
2260
+ | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
2261
+
2068
2262
  ## Crews
2069
2263
 
2070
2264
  A **crew** is an org-scoped queue that agent work is stamped to. Every hub org
package/docs/crypto.md CHANGED
@@ -523,16 +523,16 @@ sidecar is checked against the bundle digest and the local `allowed_signers`
523
523
  trust root. Origin verification is separate: `verifyOrigin` returns `absent`
524
524
  when the origin sidecar is missing, `verified` only after DSSE signature, schema,
525
525
  signer-key, and bundle-digest checks pass, and `unverifiable` or `invalid` for
526
- the corresponding failures. The trust-root path is `<config>/allowed_signers`, where `<config>` is
527
- `$OWENLOOP_CONFIG_DIR` when set to a non-blank absolute path, else
528
- `$XDG_CONFIG_HOME/owenloop` when `XDG_CONFIG_HOME` is non-blank, else
529
- `$HOME/.config/owenloop`. A missing or malformed trust root produces the distinct
526
+ the corresponding failures. The trust-root path is `<config>/allowed_signers`,
527
+ where `<config>` is `$HOME/.owenloop` by default or the absolute
528
+ `OWENLOOP_CONFIG_DIR` override. `XDG_CONFIG_HOME` is not consulted. A missing
529
+ or malformed trust root produces the distinct
530
530
  `unverifiable` verdict; a present signature that fails verification produces
531
531
  `invalid`.
532
532
 
533
533
  The execution and install policy is `defPolicy`, with built-in default `warn`.
534
- Set `defPolicy` in the JSON settings file at `<config>/settings.json` (same
535
- ladder as the trust root above), for example:
534
+ Set `defPolicy` in the JSON settings file at `$HOME/.owenloop/settings.json`,
535
+ for example:
536
536
 
537
537
  ```json
538
538
  {
@@ -711,16 +711,16 @@ whole organization.
711
711
 
712
712
  ### Local anchor and envelope files
713
713
 
714
- The optional filesystem loader derives paths from injected environment state:
715
- `OWENLOOP_CONFIG_DIR` wins over `XDG_CONFIG_HOME`, which wins over `HOME`;
716
- there is no ambient home-directory lookup.
717
- The local layout is:
714
+ The optional filesystem loader derives paths from the shared owenloop config
715
+ directory (`$HOME/.owenloop` by default, or the absolute
716
+ `OWENLOOP_CONFIG_DIR` override). `XDG_CONFIG_HOME` is not consulted. The local
717
+ layout is:
718
718
 
719
719
  ```text
720
- <config>/owenloop/org-root.pub # public anchor, 0644
721
- <config>/owenloop/org-root # private anchor, 0600
722
- <config>/owenloop/roster/<sha256hex(keyid)>.grant.dsse
723
- <config>/owenloop/revocations/<sha256hex(keyid)>.revocation.dsse
720
+ <config>/org-root.pub # public anchor, 0644
721
+ <config>/org-root # private anchor, 0600
722
+ <config>/roster/<sha256hex(keyid)>.grant.dsse
723
+ <config>/revocations/<sha256hex(keyid)>.revocation.dsse
724
724
  ```
725
725
 
726
726
  The root key is stored outside `PrincipalKeyManager` because the root is not a