owenloop 0.4.1 → 0.5.0

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 (154) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +58 -31
  3. package/bin/owenloop.mjs +2 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +172 -0
  5. package/dist/packages/work/src/agent/brief.js +193 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +135 -0
  7. package/dist/packages/work/src/agent/loop.js +542 -0
  8. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  9. package/dist/packages/work/src/agent/workdir.js +319 -0
  10. package/dist/packages/work/src/bundle/cache.d.ts +90 -0
  11. package/dist/packages/work/src/bundle/cache.js +324 -0
  12. package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
  13. package/dist/packages/work/src/bundle/fetch.js +325 -0
  14. package/dist/packages/work/src/bundle/types.d.ts +160 -0
  15. package/dist/packages/work/src/bundle/types.js +1 -0
  16. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  17. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  18. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  19. package/dist/packages/work/src/credentials/reader.js +32 -0
  20. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  21. package/dist/packages/work/src/credentials/resolve.js +56 -0
  22. package/dist/packages/work/src/exec/loop.d.ts +29 -0
  23. package/dist/packages/work/src/exec/loop.js +215 -0
  24. package/dist/packages/work/src/exec/receipt.d.ts +38 -0
  25. package/dist/packages/work/src/exec/receipt.js +21 -0
  26. package/dist/packages/work/src/exec/runner.d.ts +65 -0
  27. package/dist/packages/work/src/exec/runner.js +185 -0
  28. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  29. package/dist/packages/work/src/harness/child-env.js +127 -0
  30. package/dist/packages/work/src/harness/claude.d.ts +128 -0
  31. package/dist/packages/work/src/harness/claude.js +635 -0
  32. package/dist/packages/work/src/harness/codex.d.ts +110 -0
  33. package/dist/packages/work/src/harness/codex.js +896 -0
  34. package/dist/packages/work/src/harness/contract.d.ts +283 -0
  35. package/dist/packages/work/src/harness/contract.js +32 -0
  36. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  37. package/dist/packages/work/src/harness/fake.js +90 -0
  38. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  39. package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
  40. package/dist/packages/work/src/harness/permissions.d.ts +62 -0
  41. package/dist/packages/work/src/harness/permissions.js +93 -0
  42. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  43. package/dist/packages/work/src/harness/registry.js +45 -0
  44. package/dist/packages/work/src/harness/session-store.d.ts +163 -0
  45. package/dist/packages/work/src/harness/session-store.js +319 -0
  46. package/dist/packages/work/src/harness/types.d.ts +29 -0
  47. package/dist/packages/work/src/harness/types.js +14 -0
  48. package/dist/packages/work/src/harnesses.d.ts +38 -0
  49. package/dist/packages/work/src/harnesses.js +38 -0
  50. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  51. package/dist/packages/work/src/hold/loop.js +23 -0
  52. package/dist/packages/work/src/hold/mcp.d.ts +55 -0
  53. package/dist/packages/work/src/hold/mcp.js +149 -0
  54. package/dist/packages/work/src/hub/client.d.ts +22 -0
  55. package/dist/packages/work/src/hub/client.js +78 -0
  56. package/dist/packages/work/src/hub/types.d.ts +290 -0
  57. package/dist/packages/work/src/hub/types.js +28 -0
  58. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  59. package/dist/packages/work/src/lease/loop.js +277 -0
  60. package/dist/packages/work/src/main.d.ts +1 -0
  61. package/dist/packages/work/src/main.js +48 -0
  62. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  63. package/dist/packages/work/src/mcp/server.js +320 -0
  64. package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
  65. package/dist/packages/work/src/roles/agent-run.js +447 -0
  66. package/dist/packages/work/src/roles/exec.d.ts +40 -0
  67. package/dist/packages/work/src/roles/exec.js +203 -0
  68. package/dist/packages/work/src/roles/hold.d.ts +68 -0
  69. package/dist/packages/work/src/roles/hold.js +324 -0
  70. package/dist/packages/work/src/roles/join.d.ts +18 -0
  71. package/dist/packages/work/src/roles/join.js +204 -0
  72. package/dist/packages/work/src/roles/lint.d.ts +59 -0
  73. package/dist/packages/work/src/roles/lint.js +200 -0
  74. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  75. package/dist/packages/work/src/roles/prepare.js +249 -0
  76. package/dist/packages/work/src/roles/release.d.ts +48 -0
  77. package/dist/packages/work/src/roles/release.js +137 -0
  78. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  79. package/dist/packages/work/src/roles/sessions.js +180 -0
  80. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  81. package/dist/packages/work/src/roles/settings.js +66 -0
  82. package/dist/packages/work/src/roles/shift.d.ts +12 -0
  83. package/dist/packages/work/src/roles/shift.js +228 -0
  84. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  85. package/dist/packages/work/src/roles/signals.js +62 -0
  86. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  87. package/dist/packages/work/src/settings/provision.js +47 -0
  88. package/dist/packages/work/src/settings/settings.d.ts +120 -0
  89. package/dist/packages/work/src/settings/settings.js +116 -0
  90. package/dist/packages/work/src/shift/client.d.ts +24 -0
  91. package/dist/packages/work/src/shift/client.js +124 -0
  92. package/dist/packages/work/src/shift/loop.d.ts +120 -0
  93. package/dist/packages/work/src/shift/loop.js +468 -0
  94. package/dist/packages/work/src/shift/protocol.d.ts +91 -0
  95. package/dist/packages/work/src/shift/protocol.js +24 -0
  96. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  97. package/dist/packages/work/src/shift/routing.js +50 -0
  98. package/dist/packages/work/src/shift/runtime.d.ts +43 -0
  99. package/dist/packages/work/src/shift/runtime.js +274 -0
  100. package/dist/packages/work/src/shift/server.d.ts +23 -0
  101. package/dist/packages/work/src/shift/server.js +716 -0
  102. package/dist/packages/work/src/shift/spawn.d.ts +86 -0
  103. package/dist/packages/work/src/shift/spawn.js +100 -0
  104. package/dist/packages/work/src/shift/state.d.ts +77 -0
  105. package/dist/packages/work/src/shift/state.js +162 -0
  106. package/dist/packages/work/src/usage.d.ts +6 -0
  107. package/dist/packages/work/src/usage.js +175 -0
  108. package/dist/{cli.d.ts → src/cli.d.ts} +18 -3
  109. package/dist/{cli.js → src/cli.js} +770 -114
  110. package/dist/{credentials.d.ts → src/credentials.d.ts} +18 -12
  111. package/dist/{credentials.js → src/credentials.js} +14 -12
  112. package/dist/{defs.js → src/defs.js} +36 -36
  113. package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
  114. package/dist/{engine.js → src/engine.js} +14 -14
  115. package/dist/{hub.d.ts → src/hub.d.ts} +205 -10
  116. package/dist/{hub.js → src/hub.js} +370 -12
  117. package/dist/{index.d.ts → src/index.d.ts} +1 -1
  118. package/dist/{index.js → src/index.js} +1 -1
  119. package/dist/{mcp → src/mcp}/serve.d.ts +5 -4
  120. package/dist/{mcp → src/mcp}/serve.js +168 -31
  121. package/dist/{mcp → src/mcp}/server.d.ts +6 -9
  122. package/dist/{mcp → src/mcp}/server.js +6 -9
  123. package/dist/{model.js → src/model.js} +1 -1
  124. package/dist/{types.d.ts → src/types.d.ts} +18 -18
  125. package/dist/{util.d.ts → src/util.d.ts} +3 -2
  126. package/dist/{util.js → src/util.js} +3 -2
  127. package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
  128. package/dist/{owenwork.js → src/work-settings.js} +27 -27
  129. package/docs/authoring.md +93 -53
  130. package/docs/cli.md +597 -76
  131. package/docs/design.md +33 -33
  132. package/docs/embedding.md +10 -9
  133. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  134. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  135. package/examples/workflows/judges/gate-sharpness.md +39 -0
  136. package/examples/workflows/judges/security.md +34 -0
  137. package/package.json +17 -8
  138. /package/dist/{add.d.ts → src/add.d.ts} +0 -0
  139. /package/dist/{add.js → src/add.js} +0 -0
  140. /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
  141. /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
  142. /package/dist/{factory.js → src/factory.js} +0 -0
  143. /package/dist/{lock.d.ts → src/lock.d.ts} +0 -0
  144. /package/dist/{lock.js → src/lock.js} +0 -0
  145. /package/dist/{model.d.ts → src/model.d.ts} +0 -0
  146. /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
  147. /package/dist/{paths.js → src/paths.js} +0 -0
  148. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  149. /package/dist/{schema.js → src/schema.js} +0 -0
  150. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  151. /package/dist/{store.js → src/store.js} +0 -0
  152. /package/dist/{types.js → src/types.js} +0 -0
  153. /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
  154. /package/dist/{untar.js → src/untar.js} +0 -0
@@ -1,23 +1,23 @@
1
1
  /**
2
- * owenwork settings file writer — the ONE place the owenloop CLI writes into a
3
- * sibling tool's config.
2
+ * execution settings file writer — the ONE place the root `owenloop` CLI writes
3
+ * into the execution-side settings file.
4
4
  *
5
- * `owenwork` (the wiring that runs orders) reads its settings from
6
- * `$XDG_CONFIG_HOME/owenwork/settings.json` (else `$HOME/.config/owenwork/
7
- * settings.json`) and, by design, NEVER writes them — the owenloop CLI's `setup`
8
- * command is the writer, so a fresh `owenloop setup` can point owenwork at the
9
- * hub it just authenticated against.
5
+ * `owenloop work` reads its settings from `$XDG_CONFIG_HOME/owenloop/
6
+ * settings.json` (else `$HOME/.config/owenloop/settings.json`) and, by design,
7
+ * NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
8
+ * `owenloop setup` can point `owenloop work` at the hub it just authenticated
9
+ * against.
10
10
  *
11
11
  * This module writes exactly ONE key — `hubOrigin` — and preserves every other
12
- * key byte-for-byte (forward-compat with owenwork's own `cacheDir`, `agentsDir`,
13
- * `stateDir`, `dispatchCap`, `commandRouting`, and any future/unknown key). It
14
- * never writes a secret: nothing secret is in scope here by construction (the
15
- * hub ORIGIN is public).
12
+ * key byte-for-byte (forward-compat with the execution settings' `cacheDir`,
13
+ * `agentsDir`, `stateDir`, `dispatchCap`, `commandRouting`, and any future or
14
+ * unknown key). It never writes a secret: nothing secret is in scope here by
15
+ * construction (the hub ORIGIN is public).
16
16
  *
17
17
  * Corrupt-file policy: a settings file that exists but does not parse as a JSON
18
18
  * OBJECT is a hard error naming the path — the writer refuses to CLOBBER a file
19
- * it cannot safely merge into. That mirrors owenwork's own validator wording
20
- * family ("not an object").
19
+ * it cannot safely merge into. That mirrors the work settings validator's
20
+ * wording family ("not an object").
21
21
  *
22
22
  * Imports only node builtins, `writeFileAtomic` from hub.ts, and `CliError` from
23
23
  * util.ts — no CLI/engine closure.
@@ -27,21 +27,21 @@ import { dirname, join } from 'node:path';
27
27
  import { writeFileAtomic } from "./hub.js";
28
28
  import { CliError } from "./util.js";
29
29
  /**
30
- * The owenwork settings file path for this environment. `XDG_CONFIG_HOME` (when
31
- * set and non-blank) wins over `HOME`, matching owenwork's own resolution and
30
+ * The execution settings file path for this environment. `XDG_CONFIG_HOME` (when
31
+ * set and non-blank) wins over `HOME`, matching owenloop's own resolution and
32
32
  * the owenloop credential store's `configDir`. Throws when neither is set.
33
33
  */
34
- export function owenworkSettingsPath(env) {
34
+ export function owenloopSettingsPath(env) {
35
35
  const xdg = env.XDG_CONFIG_HOME;
36
36
  if (xdg && xdg.trim() !== '')
37
- return join(xdg, 'owenwork', 'settings.json');
37
+ return join(xdg, 'owenloop', 'settings.json');
38
38
  const home = env.HOME;
39
39
  if (home && home.trim() !== '')
40
- return join(home, '.config', 'owenwork', 'settings.json');
41
- throw new CliError('cannot locate a config directory for owenwork settings: set HOME or XDG_CONFIG_HOME');
40
+ return join(home, '.config', 'owenloop', 'settings.json');
41
+ throw new CliError('cannot locate a config directory for execution settings: set HOME or XDG_CONFIG_HOME');
42
42
  }
43
43
  /**
44
- * Read and parse the owenwork settings file at `path`.
44
+ * Read and parse the execution settings file at `path`.
45
45
  *
46
46
  * - Missing file → `null` (an absent settings file is not an error; the writer
47
47
  * creates one).
@@ -50,7 +50,7 @@ export function owenworkSettingsPath(env) {
50
50
  * `null`, a number, a string) → a hard `CliError` naming the path. The writer
51
51
  * must never clobber a file it cannot merge into.
52
52
  */
53
- export function readOwenworkSettingsRaw(path) {
53
+ export function readOwenloopSettingsRaw(path) {
54
54
  if (!existsSync(path))
55
55
  return null;
56
56
  let parsed;
@@ -58,24 +58,24 @@ export function readOwenworkSettingsRaw(path) {
58
58
  parsed = JSON.parse(readFileSync(path, 'utf8'));
59
59
  }
60
60
  catch {
61
- throw new CliError(`owenwork settings file at ${path} is not valid JSON — fix or remove it before running setup`);
61
+ throw new CliError(`execution settings file at ${path} is not valid JSON — fix or remove it before running setup`);
62
62
  }
63
63
  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
64
- throw new CliError(`owenwork settings file at ${path} is not a JSON object — fix or remove it before running setup`);
64
+ throw new CliError(`execution settings file at ${path} is not a JSON object — fix or remove it before running setup`);
65
65
  }
66
66
  return parsed;
67
67
  }
68
68
  /**
69
- * Set ONLY the `hubOrigin` key in the owenwork settings file to `origin`,
69
+ * Set ONLY the `hubOrigin` key in the execution settings file to `origin`,
70
70
  * preserving every other key. Read the existing file (a parse failure is a hard
71
71
  * `CliError` — never clobber), spread it, overwrite `hubOrigin`, `mkdir -p` the
72
72
  * directory, and write atomically (temp + rename via `writeFileAtomic`). The
73
73
  * file is pretty-printed with a trailing newline. Returns the path and the
74
74
  * previous `hubOrigin` (if any).
75
75
  */
76
- export function writeOwenworkHubOrigin(env, origin) {
77
- const path = owenworkSettingsPath(env);
78
- const existing = readOwenworkSettingsRaw(path);
76
+ export function writeOwenloopHubOrigin(env, origin) {
77
+ const path = owenloopSettingsPath(env);
78
+ const existing = readOwenloopSettingsRaw(path);
79
79
  const previous = existing !== undefined && existing !== null && typeof existing.hubOrigin === 'string' ? existing.hubOrigin : undefined;
80
80
  const merged = { ...(existing ?? {}), hubOrigin: origin };
81
81
  mkdirSync(dirname(path), { recursive: true });
package/docs/authoring.md CHANGED
@@ -78,12 +78,12 @@ steps:
78
78
  # to the engine, passed through on the order
79
79
  # (see below)
80
80
  workdir: … # opaque hint passed through on the order; omitted when unset
81
- worker: agent # opaque executor label (default: agent); see below
82
- command: … # required when worker: command; opaque, never shelled out
81
+ executor: agent # opaque executor value (default: agent); see below
82
+ command: … # required when executor: command; opaque, never shelled out
83
83
  spec: # optional opaque config map, shape-checked like x: (a plain map)
84
84
  anything: goes # contents never read by the engine; see below
85
- labels: [nightly, batch] # optional routing labels for peer-orchestrator
86
- # claim filtering (tick --label); empty = absent; see below
85
+ capabilities: [nightly, batch] # optional routing capabilities for peer-orchestrator
86
+ # claim filtering (tick --capability); empty = absent; see below
87
87
  x: # optional; opaque extension map, passed through
88
88
  anything: goes # untouched onto the order (Order.x); see design.md §27.3
89
89
  ```
@@ -91,7 +91,7 @@ steps:
91
91
  ## `model:` — quality tiers, not vendor ids
92
92
 
93
93
  The engine never calls a model; `model:` is an opaque string that rides the
94
- order to whatever dispatches your workers (an agent skill, a runner, your own
94
+ order to whatever dispatches your Step Agents (an agent skill, a runner, your own
95
95
  loop). Portable workflows should declare **intent** with one of four tier
96
96
  names and let the dispatcher bind them to the host it runs on — Claude Code,
97
97
  Codex, Gemini CLI, whatever:
@@ -112,87 +112,127 @@ a literal model id. Pin an exact model when you need reproducibility — just
112
112
  know the def is now host-specific, on purpose. Omit `model:` entirely and the
113
113
  dispatcher uses its default.
114
114
 
115
- ## `worker:` — declaring the executor
115
+ ## `executor:` — declaring the executor
116
116
 
117
117
  Every step in every def written before this feature dispatches to an LLM
118
- agent — that's still the default, and omitting `worker:` entirely leaves a
119
- def byte-for-byte unchanged. `worker:` lets a step opt into a *different*
118
+ agent — that's still the default, and omitting `executor:` entirely leaves a
119
+ def byte-for-byte unchanged. `executor:` lets a step opt into a *different*
120
120
  kind of executor instead: a shell command, a webhook, a browser-automation
121
121
  runner, anything a dispatcher on the other end of `tick` knows how to run.
122
- The engine never executes anything itself — `worker:` is an opaque label
122
+ The engine never executes anything itself — `executor:` is an opaque field
123
123
  that rides the order (same pass-through contract as `model`) for whatever
124
- drives your workers to switch on.
124
+ drives your Step Agents to switch on.
125
125
 
126
126
  ```yaml
127
127
  steps:
128
128
  - name: tester
129
129
  consumes: [reviewed_plan]
130
130
  produces: [result]
131
- worker: command # opaque to the engine; default is 'agent'
132
- command: npm test # required when worker: command; never parsed or shelled out
131
+ executor: command # opaque to the engine; default is 'agent'
132
+ command: npm test # required when executor: command; never parsed or shelled out
133
133
  spec: # optional opaque config for the dispatcher
134
134
  timeout: 300
135
135
  workdir: .
136
- body: "" # not required for worker: command
136
+ body: "" # not required for executor: command
137
137
  ```
138
138
 
139
139
  Two shape rules, both enforced at load time, everything else opaque:
140
140
 
141
- - **`worker: command` requires `command:`.** A `command`-worker step with no
141
+ - **`executor: command` requires `command:`.** A `command`-executor step with no
142
142
  `command:` is a load-time `DefError` — the dispatcher would have nothing to
143
143
  run.
144
- - **`worker: agent` (explicit) requires a real `body:`.** Omitting `worker:`
144
+ - **`executor: agent` (explicit) requires a real `body:`.** Omitting `executor:`
145
145
  still defaults to `'agent'` and still needs no body-shape check beyond
146
146
  today's behavior — this rule only fires when a step *explicitly* writes
147
- `worker: agent` and leaves `body:` empty, which is almost certainly a
147
+ `executor: agent` and leaves `body:` empty, which is almost certainly a
148
148
  mistake (an agent step with no prompt).
149
149
 
150
- Any other `worker` value (`browser-automation`, `webhook`, your own label) is
150
+ Any other `executor` value (`browser-automation`, `webhook`, your own executor value) is
151
151
  fully opaque — no `body:`/`command:` requirement at all. A definition can
152
- optionally declare `workers: [agent, command]` at the top level as a typo
152
+ optionally declare `executors: [agent, command]` at the top level as a typo
153
153
  guard; when present, `validateDef` rejects any step (or judge — see below)
154
- whose effective worker (after the `agent` default) isn't in the list:
154
+ whose effective executor (after the `agent` default) isn't in the list:
155
155
 
156
156
  ```yaml
157
157
  name: my-workflow
158
- workers: [agent, command] # optional allow-list; absent = any worker string accepted
158
+ executors: [agent, command] # optional allow-list; absent = any executor string accepted
159
159
  ```
160
160
 
161
161
  `command:` and `spec:` are opaque the same way `x:` is: `command` is
162
162
  shape-checked as a string, `spec` as a plain map, and neither is ever read or
163
- interpreted by the engine beyond that. All three (`worker`, `command`,
163
+ interpreted by the engine beyond that. All three (`executor`, `command`,
164
164
  `spec`) ride through `buildOrder` onto the emitted `Order` untouched, exactly
165
165
  like `model` and `workdir`. See [`docs/design.md` §27.4](design.md) for the
166
166
  full contract.
167
167
 
168
- ## `labels:` — routing a step to a particular tick caller
169
-
170
- `labels:` is an optional list of opaque strings on a step. It exists so several
171
- orchestrators ticking the *same* database can split the work between them: a
172
- tick caller may pass one or more `--label <x>` filters (CLI) or
173
- `engine.tick(wf, { labels: [...] })` (embedding), and a step is left for a
168
+ ## `capabilities:` — logical capability tags
169
+
170
+ `capabilities:` is an optional list of strings on a step naming what that step
171
+ *needs* — `gpu`, `repo-access` — not where it runs. They are part of **your**
172
+ vocabulary as a def author: a capability tag, chosen to describe the work.
173
+ An empty `capabilities:` list normalizes to absent.
174
+
175
+ **Never write a crew name in a def.** A crew is a deployment fact belonging to
176
+ one org on one hub; a def is portable. The indirection below is what keeps the
177
+ two apart.
178
+
179
+ **Golden path: most defs need no capabilities at all.** A step **without capabilities** routes
180
+ to the run's `defaultCrew` param if one was given, else to the starter's
181
+ personal crew. That is the default path, and it is the right one until you have
182
+ a fleet with genuinely different machines in it. Capabilities and routes are the
183
+ "advanced: teams & fleets" path — reach for a capability only when a step needs a
184
+ *specific* kind of machine.
185
+
186
+ ### On a hub: an admin binds each capability to a crew
187
+
188
+ On a hub, every capability a step uses must be **bound to at least one crew by an org
189
+ admin** — `owenloop capability bind <capability> <crew>`, or Console → Settings → Capabilities.
190
+ A capability may bind several crews, and each `capability bind` ADDS one. See
191
+ [capability routes](cli.md#capability-routes) for the commands.
192
+
193
+ - **An unbound capability fails the run at `start_run`**, with an error naming the
194
+ capability and carrying the exact fix command. That fail-fast is deliberate: the
195
+ old behavior was an order that sat unserved forever. Route is **explicit
196
+ only** — there is no implicit fallback in which an unbound capability routes
197
+ somewhere by itself.
198
+ - **Routes are live, and that is the headline.** Adding a crew to a capability
199
+ widens who serves it at the next poll of every in-flight run; removing the
200
+ capability's **last live** route pauses the steps that use it until it is bound
201
+ again. As an author this means your def does **not** need re-publishing when
202
+ the fleet moves: the operator ADDS the new crew — from that moment both crews
203
+ serve the capability — and then REMOVES the old one, and your running work follows
204
+ across without a restart.
205
+
206
+ ### Locally: capabilities are a tick filter
207
+
208
+ The local/OSS engine has no capability route table; there, the same capabilities act as a
209
+ work-splitting filter so several orchestrators ticking the *same* database can
210
+ divide the work. A tick caller may pass one or more `--capability <x>` filters (CLI)
211
+ or `engine.tick(wf, { capabilities: [...] })` (embedding), and a step is left for a
174
212
  *different* caller only when **both** the caller's filter and the step's own
175
- `labels:` are non-empty and share no value — that step's firings defer with
176
- reason `label-mismatch` until a caller whose filter matches (or a caller with
177
- no filter at all) ticks it. An empty `labels:` list normalizes to absent.
213
+ `capabilities:` are non-empty and share no value — that step's firings defer with
214
+ reason `capability-mismatch` until a caller whose filter matches (or a caller with
215
+ no filter at all) ticks it.
178
216
 
179
- Two consequences are worth stating plainly:
217
+ Capabilities are logical tags in both worlds; only the hub adds the route
218
+ indirection. Two consequences of the local filter are worth stating plainly:
180
219
 
181
220
  - **Routing, not authorization.** A caller that passes *no* filter claims every
182
- step, labeled or not — and any worker that can reach the database can tick
183
- without a filter. Labels are a work-splitting convenience, never a security
184
- boundary; never rely on them to keep a step away from a worker that shouldn't
221
+ step, with capabilities or not — and any Step Agent that can reach the database can tick
222
+ without a filter. Locally, capabilities are a work-splitting convenience, never a security
223
+ boundary; never rely on them to keep a step away from a Step Agent that shouldn't
185
224
  run it.
186
- - **Starvation hazard.** If every live caller ticks with a label filter and
187
- none of them intersects a given step's labels, that step's orders sit
188
- deferred forever with `label-mismatch` — no caller ever claims them.
189
- Operators running labeled callers should monitor the deferred/blocked entries
225
+ - **Starvation hazard.** If every live caller ticks with a capability filter and
226
+ none of them intersects a given step's capabilities, that step's orders sit
227
+ deferred forever with `capability-mismatch` — no caller ever claims them.
228
+ Operators running capability-filtered callers should monitor the deferred/blocked entries
190
229
  (each folded deferral in a `TickResult` carries its `reason`) so a
191
230
  permanently unclaimed step is caught rather than silently stuck.
192
231
 
193
- `labels:` is distinct from [`worker:`](#worker--declaring-the-executor):
194
- `worker:` says what *kind* of executor should run an order once it's claimed;
195
- `labels:` says *which tick caller* is allowed to claim it in the first place.
232
+ `capabilities:` is distinct from [`executor:`](#executor--declaring-the-executor):
233
+ `executor:` says what *kind* of executor should run an order once it's claimed;
234
+ `capabilities:` says *which* caller may claim it in the first place — a tick filter
235
+ locally, a bound crew on a hub.
196
236
 
197
237
  ## `produces:` vs `generates:`
198
238
 
@@ -235,23 +275,23 @@ steps:
235
275
  # reads the producer's inputs (question)
236
276
  - name: ci-gate
237
277
  body: "unused by a command judge, but still a required field" # every
238
- # judge needs body/bodyFile regardless of worker
239
- worker: command # judges can be deterministic too — same
240
- command: scripts/ci-gate.sh # worker:/command: contract as a normal step
278
+ # judge needs body/bodyFile regardless of executor
279
+ executor: command # judges can be deterministic too — same
280
+ command: scripts/ci-gate.sh # executor:/command: contract as a normal step
241
281
  maxAttempts: 5 # producer's cap (default for every produce on this step)
242
282
  # — also bounds judge-reject → rebuild loops; `report`
243
283
  # above could set its own maxAttempts: to override it
244
284
  ```
245
285
 
246
- A judge entry accepts the same `worker:`/`command:`/`spec:` fields as a
247
- normal step (see [`worker:` above](#worker--declaring-the-executor)) — a
286
+ A judge entry accepts the same `executor:`/`command:`/`spec:` fields as a
287
+ normal step (see [`executor:` above](#executor--declaring-the-executor)) — a
248
288
  judge can be a deterministic check (a script's exit status) instead of an
249
289
  LLM verdict. Note `body:`/`bodyFile:` is still required on every judge
250
- regardless of `worker:` — that requirement is orthogonal to this feature and
251
- applies even to a `worker: command` judge (the field just goes unread by a
290
+ regardless of `executor:` — that requirement is orthogonal to this feature and
291
+ applies even to a `executor: command` judge (the field just goes unread by a
252
292
  non-agent dispatcher).
253
293
 
254
- Each judge is a real step under the hood — it fires its own worker order
294
+ Each judge is a real step under the hood — it fires its own Worker order
255
295
  through the normal pipeline, with its own throttles (`cadence:`,
256
296
  `maxRunsPerDay:`) and retry/timeout behavior. When `researcher` commits
257
297
  `report`, it lands `submitted` (not `green`) instead — schema-valid, but
@@ -365,7 +405,7 @@ for brand-new combined workflows where nothing downstream expects the original s
365
405
  names.
366
406
 
367
407
  **`calls:` (Mode 2, runtime)** delegates to a **separate child instance** at runtime
368
- instead of inlining. The `calls:` step is machine-handled — it never emits a worker
408
+ instead of inlining. The `calls:` step is machine-handled — it never emits a Worker
369
409
  job. Use it to embed an existing workflow as a black box, keeping its internals hidden.
370
410
 
371
411
  ```yaml
@@ -392,7 +432,7 @@ steps:
392
432
  ```
393
433
 
394
434
  The engine spawns the child when the gate inputs are green, greens the parent's
395
- `calls:` output when the child's declared output greens (no worker run), and re-provides
435
+ `calls:` output when the child's declared output greens (no Worker run), and re-provides
396
436
  inputs to the existing child if a gate input changes — it never spawns a duplicate.
397
437
 
398
438
  | | `include:` (Mode 1) | `calls:` (Mode 2) |
@@ -429,7 +469,7 @@ By default a step fires when its consumed inputs are all green (`inputsGreen`).
429
469
  evaluator*: a final step that inspects the finished workflow and greens an `outcome`.
430
470
  - **`idle`** — fire when the workflow has made no progress for longer than `idleAfter`
431
471
  (required). Use for a watchdog, a stuck-detector, or a timeout handler.
432
- - **`[allGreen, idle]`** — both. The worker reads `order.cause` (`'allGreen'` or
472
+ - **`[allGreen, idle]`** — both. The Step Agent reads `order.cause` (`'allGreen'` or
433
473
  `'idle'`) to branch.
434
474
 
435
475
  ```yaml
@@ -446,7 +486,7 @@ carry an empty input fingerprint, so a commit can never satisfy it, and
446
486
  `owenloop lint` hard-errors on it. Declare the step's output under
447
487
  `produces:`/`generates:` only.
448
488
 
449
- **Alarms.** A worker that needs a heartbeat or a deadline can call
489
+ **Alarms.** A Step Agent that needs a heartbeat or a deadline can call
450
490
  `engine.setAlarm(workflow, step, at)` with an absolute timestamp — it overrides the
451
491
  relative `idleAfter` window and survives a process restart.
452
492
  `engine.nextAlarm(workflow)` tells an external scheduler when to wake the instance.