owenloop 0.5.6 → 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 (82) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/README.md +3 -6
  3. package/dist/packages/work/src/agent/approvals.d.ts +53 -0
  4. package/dist/packages/work/src/agent/approvals.js +132 -0
  5. package/dist/packages/work/src/agent/brief.d.ts +12 -0
  6. package/dist/packages/work/src/agent/brief.js +51 -0
  7. package/dist/packages/work/src/agent/capability-model.d.ts +64 -82
  8. package/dist/packages/work/src/agent/capability-model.js +94 -91
  9. package/dist/packages/work/src/agent/loop.d.ts +43 -25
  10. package/dist/packages/work/src/agent/loop.js +135 -50
  11. package/dist/packages/work/src/bundle/types.d.ts +3 -3
  12. package/dist/packages/work/src/exec/loop.js +37 -15
  13. package/dist/packages/work/src/harness/child-env.js +4 -5
  14. package/dist/packages/work/src/harness/claude.d.ts +4 -0
  15. package/dist/packages/work/src/harness/claude.js +72 -3
  16. package/dist/packages/work/src/harness/codex.d.ts +37 -1
  17. package/dist/packages/work/src/harness/codex.js +136 -18
  18. package/dist/packages/work/src/harness/contract.d.ts +54 -1
  19. package/dist/packages/work/src/harness/session-store.d.ts +127 -17
  20. package/dist/packages/work/src/harness/session-store.js +157 -60
  21. package/dist/packages/work/src/hub/client.d.ts +13 -1
  22. package/dist/packages/work/src/hub/client.js +3 -0
  23. package/dist/packages/work/src/hub/types.d.ts +104 -3
  24. package/dist/packages/work/src/main.js +1 -0
  25. package/dist/packages/work/src/roles/agent-run.js +52 -42
  26. package/dist/packages/work/src/roles/approvals.d.ts +76 -0
  27. package/dist/packages/work/src/roles/approvals.js +231 -0
  28. package/dist/packages/work/src/roles/sessions.d.ts +3 -2
  29. package/dist/packages/work/src/roles/sessions.js +9 -2
  30. package/dist/packages/work/src/roles/settings.js +1 -1
  31. package/dist/packages/work/src/settings/roster.d.ts +21 -0
  32. package/dist/packages/work/src/settings/roster.js +80 -0
  33. package/dist/packages/work/src/settings/settings.d.ts +12 -24
  34. package/dist/packages/work/src/settings/settings.js +17 -35
  35. package/dist/packages/work/src/shift/loop.d.ts +2 -0
  36. package/dist/packages/work/src/shift/loop.js +2 -0
  37. package/dist/packages/work/src/shift/runtime.js +17 -9
  38. package/dist/packages/work/src/shift/spawn.d.ts +10 -53
  39. package/dist/packages/work/src/shift/spawn.js +28 -60
  40. package/dist/packages/work/src/usage.d.ts +1 -1
  41. package/dist/packages/work/src/usage.js +8 -4
  42. package/dist/src/capabilities.d.ts +44 -0
  43. package/dist/src/capabilities.js +38 -0
  44. package/dist/src/cli.d.ts +1 -0
  45. package/dist/src/cli.js +460 -5
  46. package/dist/src/config-dir.d.ts +13 -18
  47. package/dist/src/config-dir.js +15 -23
  48. package/dist/src/credentials.d.ts +1 -1
  49. package/dist/src/credentials.js +1 -1
  50. package/dist/src/crypto/records.d.ts +3 -0
  51. package/dist/src/crypto/records.js +19 -0
  52. package/dist/src/crypto/trust-roots.d.ts +2 -2
  53. package/dist/src/crypto/trust-roots.js +2 -2
  54. package/dist/src/engine.d.ts +14 -0
  55. package/dist/src/engine.js +26 -14
  56. package/dist/src/global-config.d.ts +4 -7
  57. package/dist/src/global-config.js +4 -7
  58. package/dist/src/hub.d.ts +207 -5
  59. package/dist/src/hub.js +263 -3
  60. package/dist/src/index.d.ts +2 -2
  61. package/dist/src/index.js +1 -1
  62. package/dist/src/model.d.ts +37 -1
  63. package/dist/src/model.js +47 -1
  64. package/dist/src/schemas/index.d.ts +19 -0
  65. package/dist/src/schemas/order.v1.schema.json +15 -1
  66. package/dist/src/store/pre-commit-verifier.js +1 -1
  67. package/dist/src/types.d.ts +58 -4
  68. package/dist/src/work-settings.d.ts +2 -4
  69. package/dist/src/work-settings.js +2 -4
  70. package/docs/agent-runner.md +2 -2
  71. package/docs/bundles.md +3 -1
  72. package/docs/cli.md +295 -101
  73. package/docs/crypto.md +14 -14
  74. package/docs/routing.md +607 -0
  75. package/docs/shift-logs.md +22 -6
  76. package/package.json +1 -1
  77. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  78. package/plugins/claude-code/plugin/.mcp.json +1 -1
  79. package/plugins/claude-code/plugin/skills/author/SKILL.md +1 -2
  80. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  81. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  82. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +1 -2
@@ -4,17 +4,11 @@
4
4
  * `allowed_signers`, `org-root.pub`, `roster/`, and `revocations/`.
5
5
  *
6
6
  * WHY THIS MODULE EXISTS. Until now four call sites each re-derived the same
7
- * ladder — `$XDG_CONFIG_HOME/owenloop` else `$HOME/.config/owenloop` — and
8
- * `XDG_CONFIG_HOME` was therefore the ONLY lever an operator had for pointing
9
- * one owenloop process at a different settings file than another. That lever is
10
- * not owenloop's to take. `XDG_CONFIG_HOME` is a machine-wide contract that
11
- * `gh`, `git`, `gcloud`, `npm`, and most of the rest of a developer's toolchain
12
- * also read, and `owenloop shift start` spreads its whole environment into
13
- * every worker it dispatches (`shift/spawn.ts`), which in turn passes it to
14
- * every command step's child process (`exec/` sets exactly three variables of
15
- * its own on top). So an operator running two shifts with different
16
- * `capabilityModels` had to set `XDG_CONFIG_HOME` per shift, and that silently
17
- * relocated the config of every other tool the workflow's scripts shell out to.
7
+ * ladder, which made it too easy for each subsystem to resolve a different
8
+ * directory. Owenloop now owns exactly one default: `$HOME/.owenloop`.
9
+ * Operators who need isolation can set the explicit, owenloop-specific
10
+ * `OWENLOOP_CONFIG_DIR`, without changing the configuration roots of unrelated
11
+ * tools that a workflow may invoke.
18
12
  *
19
13
  * MEASURED, not theorized. On run `wf_8b2abe6b` the delivery line's `merge-gate`
20
14
  * and `merger` steps both failed inside their `gh` probes, because `gh` looked
@@ -27,18 +21,19 @@
27
21
  *
28
22
  * THE FIX IS AN OWENLOOP-SPECIFIC VARIABLE. `OWENLOOP_CONFIG_DIR` names the
29
23
  * owenloop config directory ITSELF — no `owenloop` path segment is appended to
30
- * it — so an operator can scope owenloop's config per process while leaving
24
+ * it — so tests and throwaway experiments can scope owenloop's config while leaving
31
25
  * `XDG_CONFIG_HOME` alone for everything else:
32
26
  *
33
- * OWENLOOP_CONFIG_DIR=~/.config/owenloop-shifts/utility/owenloop \
34
- * owenloop shift start utility …
27
+ * OWENLOOP_CONFIG_DIR=/tmp/owenloop-test owenloop work settings
35
28
  *
36
29
  * PRECEDENCE, highest first:
37
30
  * 1. `OWENLOOP_CONFIG_DIR` → used verbatim
38
- * 2. `XDG_CONFIG_HOME` → `<xdg>/owenloop`
39
- * 3. `HOME` → `<home>/.config/owenloop`
40
- * Blank or whitespace-only values are treated as unset at every rung, matching
41
- * the behaviour the four previous copies already had for `XDG_CONFIG_HOME`.
31
+ * 2. `HOME` → `<home>/.owenloop`
32
+ * Blank or whitespace-only values are treated as unset at every rung.
33
+ *
34
+ * `OWENLOOP_CONFIG_DIR` is no longer an operator-facing knob. It survives
35
+ * only for test and throwaway isolation; normal operation uses the HOME-rooted
36
+ * directory above.
42
37
  *
43
38
  * ABSOLUTE PATHS ONLY. A relative `OWENLOOP_CONFIG_DIR` would resolve against
44
39
  * whatever the current working directory happens to be, and a worker's cwd
@@ -73,13 +68,10 @@ export function owenloopConfigDir(env) {
73
68
  }
74
69
  return explicit;
75
70
  }
76
- const xdg = present(env.XDG_CONFIG_HOME);
77
- if (xdg !== undefined)
78
- return join(xdg, 'owenloop');
79
71
  const home = present(env.HOME);
80
72
  if (home !== undefined)
81
- return join(home, '.config', 'owenloop');
82
- throw new Error('cannot locate a config directory: set OWENLOOP_CONFIG_DIR, XDG_CONFIG_HOME, or HOME');
73
+ return join(home, '.owenloop');
74
+ throw new Error('cannot locate a config directory: set OWENLOOP_CONFIG_DIR or HOME');
83
75
  }
84
76
  /** A file inside owenloop's config directory. */
85
77
  export function owenloopConfigFile(env, ...segments) {
@@ -10,7 +10,7 @@
10
10
  *
11
11
  * **Concurrency safety (the reason this module exists):** the refresh-and-persist
12
12
  * critical section is serialized by a lockfile next to the store
13
- * (`~/.config/owenloop/credentials.lock`, via `src/lock.ts`). Multiple long-lived
13
+ * (`~/.owenloop/credentials.lock`, via `src/lock.ts`). Multiple long-lived
14
14
  * processes sharing one slot (the `mcp` server case) would otherwise race a
15
15
  * refresh — both read the old refresh token, both rotate it server-side, and the
16
16
  * loser persists a now-dead token, causing a silent logout an hour later. The
@@ -10,7 +10,7 @@
10
10
  *
11
11
  * **Concurrency safety (the reason this module exists):** the refresh-and-persist
12
12
  * critical section is serialized by a lockfile next to the store
13
- * (`~/.config/owenloop/credentials.lock`, via `src/lock.ts`). Multiple long-lived
13
+ * (`~/.owenloop/credentials.lock`, via `src/lock.ts`). Multiple long-lived
14
14
  * processes sharing one slot (the `mcp` server case) would otherwise race a
15
15
  * refresh — both read the old refresh token, both rotate it server-side, and the
16
16
  * loser persists a now-dead token, causing a silent logout an hour later. The
@@ -289,6 +289,7 @@ export declare const ORDER_FIELDS: {
289
289
  readonly cause: "optional";
290
290
  readonly capabilities: "optional";
291
291
  readonly modifier: "optional";
292
+ readonly reroutedFrom: "optional";
292
293
  readonly escalated: "optional";
293
294
  };
294
295
  /** Indexed access pins the already-emitted nested Order shape without cloning it. */
@@ -298,6 +299,8 @@ export declare const ORDER_OWED_FIELDS: {
298
299
  readonly judgmentRejects: "required";
299
300
  readonly schemaRejects: "required";
300
301
  readonly reasons: "required";
302
+ readonly schema: "optional";
303
+ readonly schemaAppliesTo: "optional";
301
304
  readonly proof: "optional";
302
305
  };
303
306
  export declare const ORDER_REASON_FIELDS: {
@@ -135,6 +135,12 @@ export const ORDER_FIELDS = {
135
135
  // emitted before this field existed still validates unchanged.
136
136
  capabilities: 'optional',
137
137
  modifier: 'optional',
138
+ // Set only when a caller-supplied reroute rule replaced the composed offer,
139
+ // holding what the def actually asked for. Signed like the rest of the
140
+ // routing snapshot for the same reason `escalated` is: an order served on a
141
+ // substituted capability must not be replayable as one that was served on
142
+ // the capability it requested.
143
+ reroutedFrom: 'optional',
138
144
  // Set only when `modifier` is the step's escalation target rather than the
139
145
  // run's. Covered by the signature like every other routing field: a claim
140
146
  // made on a recovery re-offer must not be replayable as an ordinary one.
@@ -147,6 +153,19 @@ export const ORDER_OWED_FIELDS = {
147
153
  judgmentRejects: 'required',
148
154
  schemaRejects: 'required',
149
155
  reasons: 'required',
156
+ // The declared JSON Schema for this owed path and what it governs, projected
157
+ // off the owning produce entry. Optional because most produces declare no
158
+ // schema, so every order emitted before this field existed still validates
159
+ // unchanged — and an order for an unconstrained output carries neither key
160
+ // rather than a null.
161
+ //
162
+ // These are DERIVED, not dynamic: both come from the definition, whose
163
+ // identity the order already pins in `defDigest`. Listing them here is about
164
+ // the wire shape being complete, not about adding anything the signature did
165
+ // not already cover — a tampered schema is a tampered def, and the digest is
166
+ // what catches that.
167
+ schema: 'optional',
168
+ schemaAppliesTo: 'optional',
150
169
  proof: 'optional',
151
170
  };
152
171
  export const ORDER_REASON_FIELDS = {
@@ -2,8 +2,8 @@
2
2
  * Resolution of the local SSHSIG trust root used for workflow publications.
3
3
  *
4
4
  * The path is derived only from injected environment state, through the shared
5
- * `owenloopConfigDir` ladder (`OWENLOOP_CONFIG_DIR` > `XDG_CONFIG_HOME` >
6
- * `HOME`); no ambient home directory lookup is allowed here. An absent file is
5
+ * `owenloopConfigDir` ladder (`OWENLOOP_CONFIG_DIR` > `HOME`); no ambient
6
+ * home directory lookup is allowed here. An absent file is
7
7
  * a normal result so the
8
8
  * publication verifier can classify it as `unverifiable` instead of confusing
9
9
  * a missing trust root with an unsigned bundle.
@@ -2,8 +2,8 @@
2
2
  * Resolution of the local SSHSIG trust root used for workflow publications.
3
3
  *
4
4
  * The path is derived only from injected environment state, through the shared
5
- * `owenloopConfigDir` ladder (`OWENLOOP_CONFIG_DIR` > `XDG_CONFIG_HOME` >
6
- * `HOME`); no ambient home directory lookup is allowed here. An absent file is
5
+ * `owenloopConfigDir` ladder (`OWENLOOP_CONFIG_DIR` > `HOME`); no ambient
6
+ * home directory lookup is allowed here. An absent file is
7
7
  * a normal result so the
8
8
  * publication verifier can classify it as `unverifiable` instead of confusing
9
9
  * a missing trust root with an unsigned bundle.
@@ -11,6 +11,7 @@
11
11
  */
12
12
  import type { WorkflowStatus } from './model.ts';
13
13
  import type { SchemaIssue } from './schema.ts';
14
+ import type { CapabilityRewrites } from './capabilities.ts';
14
15
  import type { MatchMode } from './capabilities.ts';
15
16
  import type { Store } from './store.ts';
16
17
  import type { Author, Fingerprint, Order, WorkflowDef } from './types.ts';
@@ -545,6 +546,19 @@ export declare class Engine {
545
546
  * decides a mode, it only enforces the one it is handed.
546
547
  */
547
548
  matchModes?: Record<string, MatchMode>;
549
+ /**
550
+ * Per-offered-capability reroute, keyed by the COMPOSED capability the
551
+ * offer would otherwise carry. Supplied by the same caller that supplies
552
+ * `matchModes` and for the same reason — choosing a reroute target means
553
+ * reading crew bindings, which the pure engine cannot see. Substitution
554
+ * is a single hop; the caller resolves any chain before calling. See
555
+ * `applyCapabilityRewrites`.
556
+ *
557
+ * A rewrite changes what the offer IS, not what the run asked for: the
558
+ * instance's stored modifier is never touched, so re-reading the run
559
+ * record still shows the grade of service that was requested.
560
+ */
561
+ capabilityRewrites?: CapabilityRewrites;
548
562
  }): TickResult;
549
563
  /**
550
564
  * The recursive tick worker. Runs this instance's own maintain → reap →
@@ -10,10 +10,10 @@
10
10
  * born-rejects the output instead of greening it.
11
11
  */
12
12
  import { elementPath, parseElement, parseWorkdirFrom, sealPath, } from "./paths.js";
13
- import { collectionStem, computeFingerprint, eligibleFirings, fingerprintMatches, groupBlockingWinner, isEscalated, isGreen, judgeNameOf, maintainDecisions, pendingOwed, plainConsumes, rejectionEpisode, requiredInputs, workflowStatus, } from "./model.js";
13
+ import { collectionStem, computeFingerprint, eligibleFirings, fingerprintMatches, groupBlockingWinner, isEscalated, isGreen, judgeNameOf, maintainDecisions, owedSchema, pendingOwed, plainConsumes, rejectionEpisode, requiredInputs, workflowStatus, } from "./model.js";
14
14
  import { summarizeIssues, validateValue } from "./schema.js";
15
15
  import { hashDef } from "./defs.js";
16
- import { claimMatches, composeCapabilities } from "./capabilities.js";
16
+ import { applyCapabilityRewrites, claimMatches, composeCapabilities } from "./capabilities.js";
17
17
  import { localMidnightMs, nowMs, randId } from "./util.js";
18
18
  import { createDefInstructionSource, OrderResolver } from "./order-resolver.js";
19
19
  const DEFAULT_REAP_TTL_MS = 2 * 60 * 60 * 1000; // 2h
@@ -986,7 +986,7 @@ export class Engine {
986
986
  tick(workflow, opts = {}) {
987
987
  // `capabilities` is passed through AS GIVEN — an omitted filter (undefined)
988
988
  // and an empty list are different claims. See `claimMatches`.
989
- return this.tickInternal(workflow, opts.now ?? nowMs(), opts.deep ?? true, opts.capabilities, new Set(), 0, undefined, opts.matchModes ?? {});
989
+ return this.tickInternal(workflow, opts.now ?? nowMs(), opts.deep ?? true, opts.capabilities, new Set(), 0, undefined, opts.matchModes ?? {}, opts.capabilityRewrites ?? {});
990
990
  }
991
991
  /**
992
992
  * The recursive tick worker. Runs this instance's own maintain → reap →
@@ -1027,7 +1027,7 @@ export class Engine {
1027
1027
  * edge it hangs from. The guard is silent (no debt/reasons/events), mirroring
1028
1028
  * the abort discipline of `publishCallsGreen`/`provisionCallsChild`.
1029
1029
  */
1030
- tickInternal(workflow, now, deep, capabilities, visited, depth, parentEdge, matchModes = {}) {
1030
+ tickInternal(workflow, now, deep, capabilities, visited, depth, parentEdge, matchModes = {}, capabilityRewrites = {}) {
1031
1031
  if (depth > this.maxCallDepth) {
1032
1032
  throw new Error(`calls depth limit exceeded (maxCallDepth=${this.maxCallDepth}) ticking '${workflow}': `
1033
1033
  + `a calls: composition is deeper than the bound, which usually means a calls: cycle `
@@ -1076,11 +1076,11 @@ export class Engine {
1076
1076
  // Compute time facts for idle eligibility (clock-read boundary).
1077
1077
  const timeFacts = this.computeTimeFacts(def, workflow, arts, now);
1078
1078
  const firings = eligibleFirings(def, arts, timeFacts);
1079
- const { selected, deferred } = this.applySchedule(workflow, def, firings, now, arts, capabilities, modifier, matchModes);
1079
+ const { selected, deferred } = this.applySchedule(workflow, def, firings, now, arts, capabilities, modifier, matchModes, capabilityRewrites);
1080
1080
  const orders = [];
1081
1081
  const allDeferred = [...deferred];
1082
1082
  for (const f of selected) {
1083
- const claimed = this.claim(workflow, def, f, arts, now, modifier);
1083
+ const claimed = this.claim(workflow, def, f, arts, now, modifier, capabilityRewrites);
1084
1084
  if (claimed === 'in-flight') {
1085
1085
  const d = { step: f.step, key: f.key, inputs: f.inputs, outputs: f.outputs, reason: 'in-flight' };
1086
1086
  if (f.index !== undefined)
@@ -1115,7 +1115,7 @@ export class Engine {
1115
1115
  parentWf: workflow,
1116
1116
  step,
1117
1117
  callsStem: step.produces[0].stem,
1118
- }, matchModes);
1118
+ }, matchModes, capabilityRewrites);
1119
1119
  // orders: flatten; each Order already carries its own `workflow`.
1120
1120
  result.orders.push(...cr.orders);
1121
1121
  // deferred: stamp child-originated entries with the child id, preserving
@@ -1203,7 +1203,7 @@ export class Engine {
1203
1203
  * escalation authored every firing of a step composes identically, so this
1204
1204
  * behaves exactly as a per-step filter would.
1205
1205
  */
1206
- applySchedule(workflow, def, firings, now, arts, capabilities, modifier, matchModes) {
1206
+ applySchedule(workflow, def, firings, now, arts, capabilities, modifier, matchModes, capabilityRewrites) {
1207
1207
  const midnight = localMidnightMs(now);
1208
1208
  const selected = [];
1209
1209
  const deferred = [];
@@ -1220,10 +1220,13 @@ export class Engine {
1220
1220
  // A2: caller capability filter vs. this firing's COMPOSED offer. Composed
1221
1221
  // here, not authored, so a caller bound to `wise:deep` is judged against
1222
1222
  // what the order will actually carry — including when `deep` came from the
1223
- // escalation rule rather than the run.
1223
+ // escalation rule rather than the run, and including a reroute the caller
1224
+ // decided on. The filter and `buildOrder` apply the same two functions in
1225
+ // the same order, so what is matched is always what gets stamped.
1224
1226
  const stepFirings = [];
1225
1227
  for (const f of all) {
1226
- const offered = composeCapabilities(step.capabilities, this.routingFor(step, f, arts, modifier).modifier);
1228
+ const composed = composeCapabilities(step.capabilities, this.routingFor(step, f, arts, modifier).modifier);
1229
+ const { offered } = applyCapabilityRewrites(composed, capabilityRewrites);
1227
1230
  if (claimMatches(offered, capabilities, matchModes))
1228
1231
  stepFirings.push(f);
1229
1232
  else
@@ -1304,7 +1307,7 @@ export class Engine {
1304
1307
  return this.staleness(task, now, ttl, maxLease) === 'fresh';
1305
1308
  }
1306
1309
  /** Claim a firing's lease via CAS, snapshot the fingerprint, open a run. */
1307
- claim(workflow, def, f, arts, now, modifier) {
1310
+ claim(workflow, def, f, arts, now, modifier, capabilityRewrites = {}) {
1308
1311
  const existing = this.store.getTask(workflow, f.step, f.key);
1309
1312
  if (existing && existing.status === 'claimed') {
1310
1313
  const run = existing.run ? this.store.getRun(existing.run) : undefined;
@@ -1332,7 +1335,7 @@ export class Engine {
1332
1335
  // `applySchedule` so the offer and the filter read the same function on the
1333
1336
  // same in-tx `arts` snapshot; nothing between them can move.
1334
1337
  const routing = this.routingFor(this.step(def, f.step), f, arts, modifier);
1335
- const order = this.buildOrder(def, workflow, runId, f, arts, fp, routing);
1338
+ const order = this.buildOrder(def, workflow, runId, f, arts, fp, routing, capabilityRewrites);
1336
1339
  if (typeof order === 'object' && 'deferred' in order)
1337
1340
  return order;
1338
1341
  // One history record per rejection episode. Written HERE, not in
@@ -1366,7 +1369,7 @@ export class Engine {
1366
1369
  * snapshot is registered under the digest (a side effect of `digestOf`),
1367
1370
  * so the order stays resolvable after the live definition map changes.
1368
1371
  */
1369
- buildOrder(def, workflow, runId, f, arts, consumedFingerprint, routing = {}) {
1372
+ buildOrder(def, workflow, runId, f, arts, consumedFingerprint, routing = {}, capabilityRewrites = {}) {
1370
1373
  const step = this.step(def, f.step);
1371
1374
  const consumes = {};
1372
1375
  for (const p of f.inputs) {
@@ -1448,8 +1451,12 @@ export class Engine {
1448
1451
  const defDigest = this.instructionSource.digestOf(def);
1449
1452
  const owes = f.outputs.map((p) => {
1450
1453
  const a = arts.get(p);
1454
+ const declared = owedSchema(step, p);
1451
1455
  return {
1452
1456
  path: p,
1457
+ ...(declared !== undefined
1458
+ ? { schema: declared.schema, schemaAppliesTo: declared.appliesTo }
1459
+ : {}),
1453
1460
  // The TARGET version this claim's next successful producer commit will
1454
1461
  // land, not the currently-committed one: `green()` writes
1455
1462
  // `art.version + 1`, so that is the version a consumer will later see
@@ -1490,9 +1497,14 @@ export class Engine {
1490
1497
  // have to diff it against the run record. A claimed order is never
1491
1498
  // recomposed: composition happens per offer, and this record is what the
1492
1499
  // shift resolved against.
1493
- const offered = composeCapabilities(step.capabilities, routing.modifier);
1500
+ const { offered, reroutedFrom } = applyCapabilityRewrites(composeCapabilities(step.capabilities, routing.modifier), capabilityRewrites);
1494
1501
  if (offered.length > 0)
1495
1502
  order.capabilities = offered;
1503
+ // Only when a rewrite actually fired. `reroutedFrom` is absent on every
1504
+ // ordinary offer, so its presence alone tells a reader the order is not
1505
+ // running on the capability its def asked for.
1506
+ if (reroutedFrom !== undefined)
1507
+ order.reroutedFrom = reroutedFrom;
1496
1508
  if (routing.modifier !== undefined)
1497
1509
  order.modifier = routing.modifier;
1498
1510
  if (routing.escalation !== undefined)
@@ -12,8 +12,7 @@
12
12
  * real installs (macOS defaults to the keychain backend).
13
13
  *
14
14
  * This is deliberately a SEPARATE file from `src/work-settings.ts`'s
15
- * `~/.config/owenloop/settings.json` (or `$XDG_CONFIG_HOME/owenloop/settings.json`
16
- * when set). That file belongs to the EXECUTION plane: `owenloop setup` is its
15
+ * `~/.owenloop/settings.json`. That file belongs to the EXECUTION plane: `owenloop setup` is its
17
16
  * sole writer, and `owenloop work` role resolution and pre-commit verification
18
17
  * are its readers. This file belongs to the CONTROL plane: `owenloop login`
19
18
  * writes it, `owenloop mcp` reads it. Nothing reconciles the two if they
@@ -22,11 +21,9 @@
22
21
  * the two files answer different questions ("what hub does an agent shift run
23
22
  * against" vs. "what hub does the human's MCP session talk to") for two
24
23
  * independently-evolving call paths, and forcing one file to answer both would
25
- * couple them for no benefit. This file is also HOME-rooted, not XDG-aware,
26
- * unlike `settings.json`: `owenloop mcp` is a human-facing control-plane
27
- * process, and there is no separate "XDG vs. HOME" precedence to resolve here
28
- * — the caller supplies `home` directly (see `globalConfigPath`), mirroring
29
- * how `src/cli.ts`'s `workflowHome` resolves the same value.
24
+ * couple them for no benefit. Both files are HOME-rooted siblings in the same
25
+ * directory; their control-plane versus execution-plane responsibilities, not
26
+ * their location, keep them separate.
30
27
  *
31
28
  * Never holds a secret: `hub` is an origin URL, nothing else. A read failure
32
29
  * of any kind (file absent, invalid JSON, wrong shape, blank `hub`, or a
@@ -12,8 +12,7 @@
12
12
  * real installs (macOS defaults to the keychain backend).
13
13
  *
14
14
  * This is deliberately a SEPARATE file from `src/work-settings.ts`'s
15
- * `~/.config/owenloop/settings.json` (or `$XDG_CONFIG_HOME/owenloop/settings.json`
16
- * when set). That file belongs to the EXECUTION plane: `owenloop setup` is its
15
+ * `~/.owenloop/settings.json`. That file belongs to the EXECUTION plane: `owenloop setup` is its
17
16
  * sole writer, and `owenloop work` role resolution and pre-commit verification
18
17
  * are its readers. This file belongs to the CONTROL plane: `owenloop login`
19
18
  * writes it, `owenloop mcp` reads it. Nothing reconciles the two if they
@@ -22,11 +21,9 @@
22
21
  * the two files answer different questions ("what hub does an agent shift run
23
22
  * against" vs. "what hub does the human's MCP session talk to") for two
24
23
  * independently-evolving call paths, and forcing one file to answer both would
25
- * couple them for no benefit. This file is also HOME-rooted, not XDG-aware,
26
- * unlike `settings.json`: `owenloop mcp` is a human-facing control-plane
27
- * process, and there is no separate "XDG vs. HOME" precedence to resolve here
28
- * — the caller supplies `home` directly (see `globalConfigPath`), mirroring
29
- * how `src/cli.ts`'s `workflowHome` resolves the same value.
24
+ * couple them for no benefit. Both files are HOME-rooted siblings in the same
25
+ * directory; their control-plane versus execution-plane responsibilities, not
26
+ * their location, keep them separate.
30
27
  *
31
28
  * Never holds a secret: `hub` is an origin URL, nothing else. A read failure
32
29
  * of any kind (file absent, invalid JSON, wrong shape, blank `hub`, or a
package/dist/src/hub.d.ts CHANGED
@@ -48,7 +48,7 @@
48
48
  * Secret hygiene is a hard rule here: credentials never land in the repo or a
49
49
  * plaintext `.env`. The 0600 file backend below (dir 0700) lives under the
50
50
  * user's config dir, never the project; all paths derive from the
51
- * caller-supplied `env` (HOME / XDG_CONFIG_HOME), never `process.env` directly,
51
+ * caller-supplied `env` (HOME), never `process.env` directly,
52
52
  * so tests fixture `$HOME` and never touch ambient machine state. Both this
53
53
  * file and `.owenloop/hub.json` are written via `writeFileAtomic` — temp file
54
54
  * in the same dir + rename, refusing a symlinked destination (SEC-3). The
@@ -183,7 +183,7 @@ export type CredentialSlotSelector = {
183
183
  account?: string;
184
184
  };
185
185
  /**
186
- * The credential file (`~/.config/owenloop/credentials.json`), v2: origin →
186
+ * The credential file (`~/.owenloop/credentials.json`), v2: origin →
187
187
  * slot → credential. `version` is `2`; a file carrying any other version reads
188
188
  * as an EMPTY store (see `readCredentialFile`) — that is how entries under the
189
189
  * older one-slot-per-origin keying become invisible without any migration code.
@@ -225,7 +225,7 @@ export declare function parseCredential(raw: unknown): Credential | null;
225
225
  /**
226
226
  * The user-level config dir (never the project dir). Derives from the caller's
227
227
  * env via the one shared ladder in `config-dir.ts`:
228
- * `OWENLOOP_CONFIG_DIR` > `$XDG_CONFIG_HOME/owenloop` > `$HOME/.config/owenloop`.
228
+ * `OWENLOOP_CONFIG_DIR` > `$HOME/.owenloop`.
229
229
  */
230
230
  export declare function configDir(env: Record<string, string | undefined>): string;
231
231
  export declare function credentialFilePath(env: Record<string, string | undefined>): string;
@@ -374,7 +374,7 @@ export declare function credentialBackend(env: Record<string, string | undefined
374
374
  * credential it wants.
375
375
  */
376
376
  export type ReadStoredCredentialOpts = CredentialSlotSelector & {
377
- /** Environment to consult (OWENLOOP_NO_KEYCHAIN, HOME/XDG_CONFIG_HOME). Default: `process.env`. */
377
+ /** Environment to consult (OWENLOOP_NO_KEYCHAIN, HOME). Default: `process.env`. */
378
378
  env?: Record<string, string | undefined>;
379
379
  /** Injectable keychain backend (tests / embedding hosts). Ignored when OWENLOOP_NO_KEYCHAIN=1. */
380
380
  keychain?: Keychain;
@@ -410,7 +410,7 @@ export type ReadStoredCredentialOpts = CredentialSlotSelector & {
410
410
  * keychain → file. A keychain-backed read NEVER falls through to the file (that
411
411
  * fallback was the REL-6 shadowing bug), and a corrupt entry reads as absent
412
412
  * (`null`) on either store — never as a reason to consult the other. The file
413
- * backend derives its path from the supplied `env` (HOME / XDG_CONFIG_HOME),
413
+ * backend derives its path from the supplied `env` (HOME),
414
414
  * never `process.env` directly, so a caller passing `opts.env` stays hermetic;
415
415
  * only the top-level default falls back to `process.env`.
416
416
  *
@@ -785,6 +785,208 @@ export declare function asCapabilityRouteRemoved(body: unknown): {
785
785
  * whose `crewName` is `null` is a dangling route and is kept, not dropped.
786
786
  */
787
787
  export declare function asCapabilityRoutes(body: unknown): CapabilityRouteWire[];
788
+ /**
789
+ * One **routing alert** as the hub reports it — an org-scoped record that the
790
+ * hub made a routing decision an operator needs to know about.
791
+ *
792
+ * A routing alert is NOT a capability route and NOT a capability reroute rule:
793
+ * a route and a reroute are both operator-owned CONFIGURATION rows, while an
794
+ * alert is an immutable EVENT the hub wrote about one offer at one instant. The
795
+ * three families share the word "routing" and nothing else.
796
+ *
797
+ * The alert that matters most is `kind: 'binding-gap'`: a step's composed
798
+ * capability (e.g. `build:express`) had no LIVE crew binding, so the hub HELD
799
+ * the offer instead of falling back to name matching. Holding is the intended
800
+ * behavior; this row is how a human learns it happened.
801
+ *
802
+ * `kind` is `'binding-gap' | 'wait-start' | 'fallback' | 'reroute'` on the wire
803
+ * today, but is deliberately NOT narrowed to that union — the same stance
804
+ * `CrewWire.kind` takes. The hub verbs are the enforcement of record, and a kind
805
+ * added there later must widen what the CLI PRINTS, never break the command.
806
+ *
807
+ * `capability` is always the COMPOUND the offer used (`build:express`), not the
808
+ * bare authored capability.
809
+ *
810
+ * `detail` is a JSON metadata string the hub composed for the console. It is
811
+ * forwarded VERBATIM as a string and never parsed here: parsing it would make
812
+ * this CLI a second consumer of an internal shape that no contract pins.
813
+ *
814
+ * `modifier`, `step` and `detail` are `string | null` — a `null` is the hub's
815
+ * own answer ("this alert has no step", "this run carries no modifier"), not a
816
+ * defect, so all three are validated leniently exactly like
817
+ * `CapabilityRouteWire.crewName`.
818
+ *
819
+ * Non-secret: the row names a workflow, a capability and a step — never a token.
820
+ */
821
+ export interface RoutingAlertWire {
822
+ id: string;
823
+ at: number;
824
+ workflow: string;
825
+ kind: string;
826
+ capability: string;
827
+ modifier: string | null;
828
+ step: string | null;
829
+ detail: string | null;
830
+ }
831
+ /**
832
+ * Narrow `GET /api/routing_alerts`' 200 body (`{ text, alerts: [...] }`) to a
833
+ * typed array. An EMPTY array is valid — "this org has recorded no routing
834
+ * alerts" is a normal, and in fact the desirable, answer.
835
+ *
836
+ * **The array is forwarded IN WIRE ORDER and must never be re-sorted.** The
837
+ * order is meaningful and it is not the same order in both modes: unscoped the
838
+ * hub returns the org's alerts NEWEST-FIRST (an inbox), while `?workflow=`
839
+ * scopes to one run AND flips to OLDEST-FIRST (a timeline). A client-side sort
840
+ * would destroy whichever of the two the operator asked for.
841
+ */
842
+ export declare function asRoutingAlerts(body: unknown): RoutingAlertWire[];
843
+ /**
844
+ * `GET /api/run_routing/:wf`'s 200 body, narrowed — one run's routing state with
845
+ * the three adjacent subsystems that explain it joined in at read time.
846
+ *
847
+ * `modifier` is OPTIONAL and its ABSENCE is the signal: a run started without
848
+ * `--modifier` carries no modifier at all, and the hub omits the key rather than
849
+ * sending `''` or `null`. The key is therefore omitted from the narrowed value
850
+ * too, never defaulted — an empty string here would read as "a modifier named
851
+ * nothing", which is not a state the system has.
852
+ *
853
+ * **Validation depth is deliberately uneven, and the split is the point:**
854
+ *
855
+ * - `workflow`, `defName`, `modifier`, `waitPolicy.wait` and every `alerts[]`
856
+ * row are THIS feature's own vocabulary, so they are validated in full.
857
+ * - `resolutionReports[]` and `escalations[]` are rows belonging to the shift
858
+ * -resolution and engine-escalation subsystems, joined here for reading only.
859
+ * Each entry is object-checked and then forwarded VERBATIM (the same stance
860
+ * `instance show` takes for its joined arrays), so an additive change to
861
+ * either subsystem widens what this command prints instead of breaking it.
862
+ *
863
+ * All three arrays must nonetheless be PRESENT. That is the
864
+ * `asCapabilityRouteRemoved.remainingCrewIds` lesson applied again: defaulting
865
+ * an absent array to `[]` would assert "nothing is degraded on this run" — the
866
+ * reassuring reading — off a malformed body, and reassurance is exactly the
867
+ * answer a reader must not be given by accident.
868
+ *
869
+ * `waitPolicy.then` is forwarded verbatim when present for the same reason the
870
+ * joined rows are: its shape is the wait subsystem's to define.
871
+ */
872
+ export interface RunRoutingWire {
873
+ workflow: string;
874
+ defName: string;
875
+ modifier?: string;
876
+ waitPolicy: {
877
+ wait: string;
878
+ then?: unknown;
879
+ };
880
+ alerts: RoutingAlertWire[];
881
+ resolutionReports: unknown[];
882
+ escalations: unknown[];
883
+ }
884
+ /**
885
+ * Narrow `GET /api/run_routing/:wf`'s 200 body. Throws on anything malformed,
886
+ * naming the offending FIELD or INDEX only — no body value is ever echoed.
887
+ *
888
+ * Uses the `malformed success response` wording rather than `malformed
889
+ * response`, matching `get_status`, the other single-resource GET: a body that
890
+ * fails here arrived with a 2xx, and saying so distinguishes it from the hub
891
+ * having refused the request outright.
892
+ */
893
+ export declare function asRunRouting(body: unknown): RunRoutingWire;
894
+ /**
895
+ * One **capability reroute rule** as the hub reports it — an operator-defined,
896
+ * ORDERED statement that reads "when `<capability>` has no LIVE crew binding,
897
+ * offer the work as `<target>` instead".
898
+ *
899
+ * **A reroute is NOT a binding.** It names no crew, grants nobody access, and
900
+ * certifies nothing. It only renames the capability an already-unbound offer
901
+ * goes out under, so the claiming shift resolves the TARGET's model rather than
902
+ * silently falling back to a bare-name row. Whether the target can actually be
903
+ * served is a separate, `capability_routes` question, and there is deliberately
904
+ * no liveness column on this row to imply otherwise.
905
+ *
906
+ * `position` is the rule's rank WITHIN its source capability: the hub walks a
907
+ * source's rules in ascending `position` and takes the first target that has a
908
+ * live binding.
909
+ *
910
+ * Non-secret: the row names two capability strings and when the rule was written.
911
+ */
912
+ export interface CapabilityRerouteWire {
913
+ capability: string;
914
+ target: string;
915
+ position: number;
916
+ createdAt: number;
917
+ }
918
+ /**
919
+ * Narrow `GET /api/capability_reroutes`' 200 body (`{ text, reroutes: [...] }`)
920
+ * to a typed array. An EMPTY array is valid — "this org has configured no
921
+ * reroute rules", which is the default and correct state for most orgs.
922
+ *
923
+ * THE ARRAY KEY IS `reroutes`. It is neither `bindings` (what the sibling
924
+ * `capability_routes` endpoint uses) nor `rules` (what the feature is called in
925
+ * prose). Guessing that key is precisely how `capability list` shipped broken
926
+ * TWICE — see `asCapabilityRoutes` — so it is copied from
927
+ * `hub-core/src/verbs/list-capability-reroutes.ts` rather than inferred.
928
+ *
929
+ * **Rows arrive in the order the hub TRIES them** (`capability`, then
930
+ * `position`, then `target`) and are forwarded exactly as received. The order is
931
+ * SEMANTIC: it is the sequence in which a source's targets are attempted.
932
+ * Re-sorting it — in this function, in a caller, or in a test fixture — would
933
+ * silently misreport which substitution happens first.
934
+ */
935
+ export declare function asCapabilityReroutes(body: unknown): CapabilityRerouteWire[];
936
+ /**
937
+ * `POST /api/add_capability_reroute`'s 200 body, narrowed.
938
+ *
939
+ * NESTED exactly as the wire nests it: the row lives under `reroute`, while
940
+ * `alreadyPresent` and `ruleCount` live at the BODY's top level — the same shape
941
+ * (and the same reason for mirroring it literally) as `CapabilityRouteAddedWire`.
942
+ *
943
+ * - `alreadyPresent` — was this exact `(capability, target)` pair already a
944
+ * rule? The add is idempotent per pair, so a repeat is a 200 no-op rather than
945
+ * an error, and `reroute.createdAt` then echoes the ORIGINAL row.
946
+ * - `ruleCount` — how many rules the SOURCE capability has after the write.
947
+ */
948
+ export interface CapabilityRerouteAddedWire {
949
+ reroute: CapabilityRerouteWire;
950
+ alreadyPresent: boolean;
951
+ ruleCount: number;
952
+ }
953
+ /**
954
+ * Narrow `POST /api/add_capability_reroute`'s 200 body
955
+ * (`{ text, reroute, alreadyPresent, ruleCount }`), naming the offending field
956
+ * only — the same discipline as `asCapabilityRouteAdded`.
957
+ *
958
+ * There is no layered non-null check here of the kind `asCapabilityRouteAdded`
959
+ * applies to `binding.crewName`: a reroute row has no nullable field, because it
960
+ * resolves no crew.
961
+ */
962
+ export declare function asCapabilityRerouteAdded(body: unknown): CapabilityRerouteAddedWire;
963
+ /**
964
+ * Narrow `POST /api/remove_capability_reroute`'s 200 body
965
+ * (`{ text, capability, target, removed, remainingTargets }`).
966
+ *
967
+ * `removed` must be a BOOLEAN — this guard is how the CLI proves the 2xx really
968
+ * was the remove verb's answer. BOTH values are deliberate hub responses:
969
+ * - `true` — the `(capability, target)` rule existed and is now gone;
970
+ * - `false` — there was no such rule, so there was nothing to do. The hub
971
+ * answers 200, never a 404 (the same tolerance `remove_capability_route`
972
+ * has), and that is what makes `routing rule rm` idempotent.
973
+ *
974
+ * `remainingTargets` is deliberately STRICT — PRESENT, an array, and every
975
+ * element a non-empty string. This is the identical asymmetry argued at
976
+ * `asCapabilityRouteRemoved`: defaulting an absent array to `[]` would assert
977
+ * "this capability now HOLDS whenever it is unbound" — the alarming reading, and
978
+ * exactly the signal an operator acts on — off a malformed body. Unlike the
979
+ * capability-route family there is no nullable field to balance it against, so
980
+ * every field here is strict.
981
+ *
982
+ * The stdout shape built from this is documented in `docs/cli.md` under Routing.
983
+ */
984
+ export declare function asCapabilityRerouteRemoved(body: unknown): {
985
+ capability: string;
986
+ target: string;
987
+ removed: boolean;
988
+ remainingTargets: string[];
989
+ };
788
990
  /**
789
991
  * A **crew** as the hub reports it — an org-scoped queue that agent work is
790
992
  * stamped to. `kind` is `'personal' | 'shared' | 'orphan'` on the wire, but is