owenloop 0.5.3 → 0.5.4

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 (38) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +6 -2
  3. package/dist/packages/work/src/agent/brief.d.ts +6 -0
  4. package/dist/packages/work/src/agent/brief.js +46 -2
  5. package/dist/packages/work/src/agent/loop.js +3 -0
  6. package/dist/packages/work/src/exec/loop.js +153 -9
  7. package/dist/packages/work/src/harness/child-env.js +8 -0
  8. package/dist/packages/work/src/harness/claude.js +18 -5
  9. package/dist/packages/work/src/harness/codex.js +7 -0
  10. package/dist/packages/work/src/harness/contract.d.ts +22 -3
  11. package/dist/packages/work/src/harness/contract.js +22 -3
  12. package/dist/packages/work/src/settings/settings.d.ts +12 -4
  13. package/dist/packages/work/src/settings/settings.js +14 -11
  14. package/dist/src/cli.js +203 -6
  15. package/dist/src/config-dir.d.ts +62 -0
  16. package/dist/src/config-dir.js +87 -0
  17. package/dist/src/crypto/trust-roots.d.ts +8 -4
  18. package/dist/src/crypto/trust-roots.js +18 -12
  19. package/dist/src/defs.js +57 -16
  20. package/dist/src/engine.js +25 -3
  21. package/dist/src/hub.d.ts +5 -1
  22. package/dist/src/hub.js +7 -8
  23. package/dist/src/paths.d.ts +47 -4
  24. package/dist/src/paths.js +36 -5
  25. package/dist/src/work-settings.d.ts +8 -5
  26. package/dist/src/work-settings.js +15 -12
  27. package/docs/authoring.md +40 -13
  28. package/docs/bundles.md +9 -0
  29. package/docs/cli.md +121 -24
  30. package/docs/crypto.md +8 -8
  31. package/docs/design.md +20 -2
  32. package/docs/embedding.md +5 -4
  33. package/docs/wire-contracts.md +3 -2
  34. package/package.json +1 -1
  35. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  36. package/plugins/claude-code/plugin/.mcp.json +1 -1
  37. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  38. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
package/dist/src/hub.d.ts CHANGED
@@ -222,7 +222,11 @@ export declare function keychainServiceFor(normalizedOrigin: string): string;
222
222
  * instead of a clean miss.
223
223
  */
224
224
  export declare function parseCredential(raw: unknown): Credential | null;
225
- /** The user-level config dir (never the project dir). Derives from the caller's env. */
225
+ /**
226
+ * The user-level config dir (never the project dir). Derives from the caller's
227
+ * env via the one shared ladder in `config-dir.ts`:
228
+ * `OWENLOOP_CONFIG_DIR` > `$XDG_CONFIG_HOME/owenloop` > `$HOME/.config/owenloop`.
229
+ */
226
230
  export declare function configDir(env: Record<string, string | undefined>): string;
227
231
  export declare function credentialFilePath(env: Record<string, string | undefined>): string;
228
232
  /**
package/dist/src/hub.js CHANGED
@@ -69,6 +69,7 @@ import { createHash, randomBytes } from 'node:crypto';
69
69
  import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
70
70
  import { basename, dirname, join } from 'node:path';
71
71
  import { parse as parseYaml } from 'yaml';
72
+ import { owenloopConfigDir } from "./config-dir.js";
72
73
  import { hashDef, parseDef } from "./defs.js";
73
74
  import { mkdirRefusingSymlink } from "./util.js";
74
75
  // ---- server-parity def content hash ------------------------------------------
@@ -277,15 +278,13 @@ export function parseCredential(raw) {
277
278
  }
278
279
  return null;
279
280
  }
280
- /** The user-level config dir (never the project dir). Derives from the caller's env. */
281
+ /**
282
+ * The user-level config dir (never the project dir). Derives from the caller's
283
+ * env via the one shared ladder in `config-dir.ts`:
284
+ * `OWENLOOP_CONFIG_DIR` > `$XDG_CONFIG_HOME/owenloop` > `$HOME/.config/owenloop`.
285
+ */
281
286
  export function configDir(env) {
282
- const xdg = env.XDG_CONFIG_HOME;
283
- if (xdg && xdg.trim() !== '')
284
- return join(xdg, 'owenloop');
285
- const home = env.HOME;
286
- if (home && home.trim() !== '')
287
- return join(home, '.config', 'owenloop');
288
- throw new Error('cannot locate a config directory: set HOME or XDG_CONFIG_HOME');
287
+ return owenloopConfigDir(env);
289
288
  }
290
289
  export function credentialFilePath(env) {
291
290
  return join(configDir(env), 'credentials.json');
@@ -37,13 +37,56 @@ export interface WorkdirFromParts {
37
37
  stem: string;
38
38
  path: string;
39
39
  mode: ConsumeMode;
40
+ /**
41
+ * Where the stem was found, which decides where the ENGINE reads the value.
42
+ *
43
+ * - `consume` — the stem names one of the step's own consumes. The value
44
+ * comes out of the resolved consume map for the firing.
45
+ * - `input` — the stem names one of the DEFINITION's declared inputs and
46
+ * the step does not consume it. The value comes out of the instance's
47
+ * artifact table, and the firing defers while that input is still owed.
48
+ *
49
+ * A consume always wins: the loop below tries consumes first at every split
50
+ * boundary, so a step that genuinely consumes an input keeps the old
51
+ * behaviour and nothing about an existing def changes meaning.
52
+ */
53
+ source: 'consume' | 'input';
40
54
  }
41
55
  /**
42
- * Split a workdirFrom expression by the longest prefix that names one of the
43
- * step's own consumes. Artifact stems may contain dots, so the consume list is
44
- * the closed grammar that makes the split deterministic at def-load time.
56
+ * Split a workdirFrom expression by the longest prefix that names either one of
57
+ * the step's own consumes or one of the definition's declared inputs. Artifact
58
+ * stems may contain dots, so those two name lists are the closed grammar that
59
+ * makes the split deterministic at def-load time.
60
+ *
61
+ * ## Why an input stem is admissible, when the value becomes a filesystem path
62
+ *
63
+ * `validateDef` used to require the stem be a plain CONSUME, on the stated
64
+ * grounds that the value must have "passed the engine's consume-side
65
+ * verification gate before a worker can cd into it". That reasoning does not
66
+ * survive contact with what actually crosses the wire:
67
+ *
68
+ * - The engine resolves `workdirFrom` ITSELF, inside the claim transaction
69
+ * (`engine.ts`, `emitOrder`), and ships the resolved STRING as
70
+ * `OrderPacket.workdir` — declared in `packages/work/src/hub/types.ts` as an
71
+ * "Opaque location hint — the worker's cwd when set".
72
+ * - Nothing verifies that field. `consumesProof` covers `order.consumes`
73
+ * entries and only those (`consumed-verifier.ts`, `parseProofMap`), and the
74
+ * command worker takes `order.workdir ?? opts.cwd` with no check at all
75
+ * (`packages/work/src/exec/loop.ts`).
76
+ *
77
+ * So the consume gate never protected the cwd at runtime — by the time the
78
+ * value reaches a worker it is an unverified string in an unverified field
79
+ * either way. The old rule constrained who may AUTHOR the value (a producer
80
+ * step) rather than what a worker will trust, and this widens that authorship
81
+ * to include the human who starts the run. Both are inside the same trust
82
+ * boundary: principals authorized to start or serve runs on this hub.
83
+ *
84
+ * What actually bounds the cwd is machine-side and belongs to the operator, not
85
+ * to the def — a shift refuses an order whose workdir falls outside the roots
86
+ * its operator declared. That check is the runtime protection; this grammar is
87
+ * an authoring question.
45
88
  */
46
- export declare function parseWorkdirFrom(raw: string, consumes: readonly ConsumePattern[]): WorkdirFromParts | null;
89
+ export declare function parseWorkdirFrom(raw: string, consumes: readonly ConsumePattern[], inputs?: readonly string[]): WorkdirFromParts | null;
47
90
  /** Parse a produce declaration. */
48
91
  export declare function parseProduce(raw: string): ProducePattern;
49
92
  /**
package/dist/src/paths.js CHANGED
@@ -65,11 +65,40 @@ export function parseConsume(raw) {
65
65
  return { raw: r, mode: 'plain', stem: r, suffix: '' };
66
66
  }
67
67
  /**
68
- * Split a workdirFrom expression by the longest prefix that names one of the
69
- * step's own consumes. Artifact stems may contain dots, so the consume list is
70
- * the closed grammar that makes the split deterministic at def-load time.
68
+ * Split a workdirFrom expression by the longest prefix that names either one of
69
+ * the step's own consumes or one of the definition's declared inputs. Artifact
70
+ * stems may contain dots, so those two name lists are the closed grammar that
71
+ * makes the split deterministic at def-load time.
72
+ *
73
+ * ## Why an input stem is admissible, when the value becomes a filesystem path
74
+ *
75
+ * `validateDef` used to require the stem be a plain CONSUME, on the stated
76
+ * grounds that the value must have "passed the engine's consume-side
77
+ * verification gate before a worker can cd into it". That reasoning does not
78
+ * survive contact with what actually crosses the wire:
79
+ *
80
+ * - The engine resolves `workdirFrom` ITSELF, inside the claim transaction
81
+ * (`engine.ts`, `emitOrder`), and ships the resolved STRING as
82
+ * `OrderPacket.workdir` — declared in `packages/work/src/hub/types.ts` as an
83
+ * "Opaque location hint — the worker's cwd when set".
84
+ * - Nothing verifies that field. `consumesProof` covers `order.consumes`
85
+ * entries and only those (`consumed-verifier.ts`, `parseProofMap`), and the
86
+ * command worker takes `order.workdir ?? opts.cwd` with no check at all
87
+ * (`packages/work/src/exec/loop.ts`).
88
+ *
89
+ * So the consume gate never protected the cwd at runtime — by the time the
90
+ * value reaches a worker it is an unverified string in an unverified field
91
+ * either way. The old rule constrained who may AUTHOR the value (a producer
92
+ * step) rather than what a worker will trust, and this widens that authorship
93
+ * to include the human who starts the run. Both are inside the same trust
94
+ * boundary: principals authorized to start or serve runs on this hub.
95
+ *
96
+ * What actually bounds the cwd is machine-side and belongs to the operator, not
97
+ * to the def — a shift refuses an order whose workdir falls outside the roots
98
+ * its operator declared. That check is the runtime protection; this grammar is
99
+ * an authoring question.
71
100
  */
72
- export function parseWorkdirFrom(raw, consumes) {
101
+ export function parseWorkdirFrom(raw, consumes, inputs = []) {
73
102
  const r = raw.trim();
74
103
  for (let boundary = r.lastIndexOf('.'); boundary > 0; boundary = r.lastIndexOf('.', boundary - 1)) {
75
104
  const stem = r.slice(0, boundary);
@@ -78,7 +107,9 @@ export function parseWorkdirFrom(raw, consumes) {
78
107
  continue;
79
108
  const consume = consumes.find((c) => c.stem === stem);
80
109
  if (consume)
81
- return { raw: r, stem, path, mode: consume.mode };
110
+ return { raw: r, stem, path, mode: consume.mode, source: 'consume' };
111
+ if (inputs.includes(stem))
112
+ return { raw: r, stem, path, mode: 'plain', source: 'input' };
82
113
  }
83
114
  return null;
84
115
  }
@@ -2,8 +2,9 @@
2
2
  * execution settings file writer — the ONE place the root `owenloop` CLI writes
3
3
  * into the execution-side settings file.
4
4
  *
5
- * `owenloop work` reads its settings from `$XDG_CONFIG_HOME/owenloop/
6
- * settings.json` (else `$HOME/.config/owenloop/settings.json`) and, by design,
5
+ * `owenloop work` reads its settings from `$OWENLOOP_CONFIG_DIR/settings.json`
6
+ * (else `$XDG_CONFIG_HOME/owenloop/settings.json`, else
7
+ * `$HOME/.config/owenloop/settings.json`) and, by design,
7
8
  * NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
8
9
  * `owenloop setup` can point `owenloop work` at the hub it just authenticated
9
10
  * against.
@@ -23,9 +24,11 @@
23
24
  * util.ts — no CLI/engine closure.
24
25
  */
25
26
  /**
26
- * The execution settings file path for this environment. `XDG_CONFIG_HOME` (when
27
- * set and non-blank) wins over `HOME`, matching owenloop's own resolution and
28
- * the owenloop credential store's `configDir`. Throws when neither is set.
27
+ * The execution settings file path for this environment, through the one shared
28
+ * ladder in `config-dir.ts`: `OWENLOOP_CONFIG_DIR` (absolute, used verbatim)
29
+ * wins over `$XDG_CONFIG_HOME/owenloop`, which wins over
30
+ * `$HOME/.config/owenloop`. Throws as a `CliError` when no rung yields a value,
31
+ * so the CLI reports it as an operator error rather than a crash.
29
32
  */
30
33
  export declare function owenloopSettingsPath(env: Record<string, string | undefined>): string;
31
34
  /**
@@ -2,8 +2,9 @@
2
2
  * execution settings file writer — the ONE place the root `owenloop` CLI writes
3
3
  * into the execution-side settings file.
4
4
  *
5
- * `owenloop work` reads its settings from `$XDG_CONFIG_HOME/owenloop/
6
- * settings.json` (else `$HOME/.config/owenloop/settings.json`) and, by design,
5
+ * `owenloop work` reads its settings from `$OWENLOOP_CONFIG_DIR/settings.json`
6
+ * (else `$XDG_CONFIG_HOME/owenloop/settings.json`, else
7
+ * `$HOME/.config/owenloop/settings.json`) and, by design,
7
8
  * NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
8
9
  * `owenloop setup` can point `owenloop work` at the hub it just authenticated
9
10
  * against.
@@ -24,21 +25,23 @@
24
25
  */
25
26
  import { existsSync, mkdirSync, readFileSync } from 'node:fs';
26
27
  import { dirname, join } from 'node:path';
28
+ import { owenloopConfigDir } from "./config-dir.js";
27
29
  import { writeFileAtomic } from "./hub.js";
28
30
  import { CliError } from "./util.js";
29
31
  /**
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
- * the owenloop credential store's `configDir`. Throws when neither is set.
32
+ * The execution settings file path for this environment, through the one shared
33
+ * ladder in `config-dir.ts`: `OWENLOOP_CONFIG_DIR` (absolute, used verbatim)
34
+ * wins over `$XDG_CONFIG_HOME/owenloop`, which wins over
35
+ * `$HOME/.config/owenloop`. Throws as a `CliError` when no rung yields a value,
36
+ * so the CLI reports it as an operator error rather than a crash.
33
37
  */
34
38
  export function owenloopSettingsPath(env) {
35
- const xdg = env.XDG_CONFIG_HOME;
36
- if (xdg && xdg.trim() !== '')
37
- return join(xdg, 'owenloop', 'settings.json');
38
- const home = env.HOME;
39
- if (home && home.trim() !== '')
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');
39
+ try {
40
+ return join(owenloopConfigDir(env), 'settings.json');
41
+ }
42
+ catch (err) {
43
+ throw new CliError(`cannot locate a config directory for execution settings: ${err instanceof Error ? err.message : String(err)}`);
44
+ }
42
45
  }
43
46
  /**
44
47
  * Read and parse the execution settings file at `path`.
package/docs/authoring.md CHANGED
@@ -113,36 +113,61 @@ a literal model id. Pin an exact model when you need reproducibility — just
113
113
  know the def is now host-specific, on purpose. Omit `model:` entirely and the
114
114
  dispatcher uses its default.
115
115
 
116
- ## `workdirFrom:` — resolve a local workdir from a consumed value
116
+ ## `workdirFrom:` — resolve a local workdir from a consumed value or a declared input
117
117
 
118
- `workdirFrom:` sets the existing `Order.workdir` from a nested field in a green,
119
- plain consumed artifact. The grammar is `<consumedStem>.<dotted.value.path>`:
118
+ `workdirFrom:` sets the existing `Order.workdir` from a nested field in a green
119
+ artifact. The grammar is `<stem>.<dotted.value.path>`, and the stem may name
120
+ either one of the step's own plain consumes or one of the definition's declared
121
+ inputs:
120
122
 
121
123
  ```yaml
124
+ inputs:
125
+ - name: target # where the run should do its work
126
+ seedOwed: true
122
127
  steps:
123
128
  - name: provisioner
124
- consumes: [proposal]
129
+ consumes: [] # a command step that creates the worktree
125
130
  produces: [workspace]
131
+ workdirFrom: target.path
126
132
  - name: builder
127
133
  consumes: [workspace]
128
134
  produces: [pr]
129
135
  workdirFrom: workspace.payload.worktreePath
130
136
  ```
131
137
 
132
- The stem named before the dotted value path must also appear in the step's
133
- `consumes:` list, and the consume must be plain rather than map (`[$i]`) or
134
- reduce (`[*]`). The engine resolves the longest consumed-stem prefix when an
138
+ A consume always wins when a stem could be read either way, so a step that
139
+ consumes the artifact it takes its workdir from keeps reading out of that
140
+ firing's consume binding. The consume must be plain rather than map (`[$i]`) or
141
+ reduce (`[*]`). The engine resolves the longest matching stem prefix when an
135
142
  artifact stem itself contains dots. `workdir:` and `workdirFrom:` are mutually
136
143
  exclusive.
137
144
 
138
- At order-build time the engine walks the consumed value using the dotted path.
145
+ Reach for the **input** form when the step cannot consume the value. The clearest
146
+ case is a `command` step: command orders are gated with the hard consumed-artifact
147
+ rule, which refuses any consumed value that carries no producer signature — and a
148
+ human-supplied seed input never has one. Naming the input in `workdirFrom:`
149
+ routes the value through `Order.workdir`, a spawn parameter the engine resolves
150
+ itself, rather than through `consumes`. This is also the only way a
151
+ run-supplied value reaches a `command:` string's context, because a command's
152
+ argv is passed to `/bin/sh -c` verbatim and is never interpolated.
153
+
154
+ Naming an input creates an ordering edge without a consume: while that input is
155
+ still owed, the firing defers with `workdir-unresolved` and detail
156
+ `input '<name>' is not green yet`, exactly as a consume would have made it wait.
157
+ The value does not appear in `Order.consumes`.
158
+
159
+ At order-build time the engine walks the resolved value using the dotted path.
139
160
  A missing field, non-object intermediate, array, non-string final value, empty
140
161
  string, or whitespace-only string defers the firing with reason
141
162
  `workdir-unresolved`; the engine emits no order and inserts no run. The engine
142
163
  passes a valid path through unchanged: the engine does not resolve or normalize
143
164
  a relative path and does not change the worker's current-directory semantics.
144
165
  The producer and worker must therefore run on the same machine. A permanently
145
- unresolvable path remains deferred until the producer supplies a valid value.
166
+ unresolvable path remains deferred until a valid value arrives.
167
+
168
+ `Order.workdir` is an opaque location hint that no proof covers, whichever form
169
+ produced it. What bounds where a worker may actually run is machine-side and
170
+ belongs to the operator running the shift, not to the definition.
146
171
 
147
172
  ## `executor:` — declaring the executor
148
173
 
@@ -269,10 +294,12 @@ indirection. Two consequences of the local filter are worth stating plainly:
269
294
  permanently unclaimed step is caught rather than silently stuck.
270
295
 
271
296
  A `workdirFrom` firing can also remain deferred forever with
272
- `workdir-unresolved`. That reason means the producing step has not supplied a
273
- usable nested path: the value is missing, has an invalid shape, or is not a
274
- non-empty string. Fix the producing step or its artifact value; changing the
275
- consumer's worker does not bypass the engine's workdir resolution check.
297
+ `workdir-unresolved`. That reason means no usable nested path has been supplied:
298
+ the artifact is not green yet, or its value is missing, has an invalid shape, or
299
+ is not a non-empty string. Fix whoever supplies that artifact — the producing
300
+ step for a consumed stem, or the human starting the run for a declared input.
301
+ Changing the consumer's worker does not bypass the engine's workdir resolution
302
+ check.
276
303
 
277
304
  `capabilities:` is distinct from [`executor:`](#executor--declaring-the-executor):
278
305
  `executor:` says what *kind* of executor should run an order once it's claimed;
package/docs/bundles.md CHANGED
@@ -263,6 +263,15 @@ command inherits the directory the operator was standing in when they ran
263
263
  `owenloop shift start`. Nothing is enforced today: a future release will
264
264
  require a step to declare that inheritance explicitly.
265
265
 
266
+ `workdirFrom:` is how a run tells a command step *where* to work. Its stem may
267
+ name a declared input, not only a consumed artifact, and that is the only
268
+ channel a run-supplied value has into a command step: `consumes:` is refused for
269
+ a human seed by the hard consumed-artifact gate above, and the `command:` string
270
+ reaches `/bin/sh -c` as authored bytes with no interpolation. A command step
271
+ that would otherwise be pinned to the one directory its shift was started in can
272
+ therefore take a project root per run — see
273
+ [authoring.md](authoring.md#workdirfrom--resolve-a-local-workdir-from-a-consumed-value-or-a-declared-input).
274
+
266
275
  **Where the fallback is recorded.** When it fires, `owenloop work exec` writes
267
276
  one warning per spawn naming the step, the workflow and run ids, and the
268
277
  resolved absolute path. That warning goes to the exec worker's own stderr.
package/docs/cli.md CHANGED
@@ -170,9 +170,18 @@ accepted `shift next` records attendance and makes the next presence ping due,
170
170
  but attendance is advisory and observability-only. Attendance never changes
171
171
  routing, dispatch, or lease behavior.
172
172
 
173
- The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
174
- `XDG_CONFIG_HOME` is set to a non-blank value; otherwise it is
175
- `$HOME/.config/owenloop/settings.json`.
173
+ <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/`.
176
185
 
177
186
  ### `shift start <crew...>`
178
187
 
@@ -225,25 +234,46 @@ starts the shift and every agent order that shift dispatches runs on that
225
234
  adapter. To run two adapters at once, start two shifts:
226
235
 
227
236
  ```bash
228
- OWENLOOP_HARNESS=claude-code XDG_CONFIG_HOME=~/.config/owenloop-shifts/claude owenloop shift start build --state-dir ~/.local/state/owenloop/claude
237
+ OWENLOOP_HARNESS=claude-code OWENLOOP_CONFIG_DIR=~/.config/owenloop-shifts/claude/owenloop owenloop shift start build --state-dir ~/.local/state/owenloop/claude
229
238
  ```
230
239
 
231
240
  ```bash
232
- OWENLOOP_HARNESS=codex XDG_CONFIG_HOME=~/.config/owenloop-shifts/codex owenloop shift start build --state-dir ~/.local/state/owenloop/codex
241
+ OWENLOOP_HARNESS=codex OWENLOOP_CONFIG_DIR=~/.config/owenloop-shifts/codex/owenloop owenloop shift start build --state-dir ~/.local/state/owenloop/codex
233
242
  ```
234
243
 
235
244
  Both shifts may serve the SAME crew. The hub does not route by harness — it
236
245
  offers an order to any shift whose crew is bound to the order's capability, and
237
246
  whichever shift claims it first runs it on its own adapter.
238
247
 
239
- **Per-shift `XDG_CONFIG_HOME` is not optional when the adapters differ.** The
240
- settings file resolves from `XDG_CONFIG_HOME` (see above), and it carries
248
+ **A per-shift config directory is not optional when the adapters differ.** The
249
+ settings file resolves from the config directory (see above), and it carries
241
250
  `capabilityModels` — a map of composed capability to `{model, effort}` whose
242
251
  model ids are strings the SHIFT'S OWN adapter accepts. Two shifts on different
243
252
  adapters need different model ids for the same capability, so they need
244
- different settings files, so they need different `XDG_CONFIG_HOME` values. A
245
- shared config directory would give both shifts one adapter's model ids, and the
246
- shift holding the wrong adapter fails at the vendor API on its first order.
253
+ different settings files, so they need different config directories. A shared
254
+ config directory would give both shifts one adapter's model ids, and the shift
255
+ holding the wrong adapter fails at the vendor API on its first order.
256
+
257
+ **Use `OWENLOOP_CONFIG_DIR` for this, not `XDG_CONFIG_HOME`.** Both resolve the
258
+ settings file, and `OWENLOOP_CONFIG_DIR` wins — but `XDG_CONFIG_HOME` is a
259
+ machine-wide contract that `gh`, `git`, `gcloud`, `npm`, and most of the rest of
260
+ a developer's toolchain also read, and a shift spreads its ENTIRE environment
261
+ into every worker it dispatches, which passes it on to every command step's
262
+ child process. Scoping a shift with `XDG_CONFIG_HOME` therefore relocates the
263
+ configuration of every tool the workflow's own scripts shell out to. Measured,
264
+ not theorized: on one delivery run this stranded `gh`'s stored credential, and
265
+ the workflow's merge gate spent its full 40-minute wall clock deferring on a CI
266
+ probe that could not authenticate, followed by four consecutive merge failures
267
+ reading `could not resolve a pull request handle for the branch`. Nothing was
268
+ wrong with either script. `OWENLOOP_CONFIG_DIR` scopes owenloop and only
269
+ owenloop.
270
+
271
+ `OWENLOOP_CONFIG_DIR` names the owenloop config directory ITSELF — the directory
272
+ that directly holds `settings.json`, `credentials.json`, and `allowed_signers`.
273
+ No `owenloop` path segment is appended to it, unlike the `XDG_CONFIG_HOME` rung.
274
+ It must be an ABSOLUTE path: a relative one would resolve against whatever
275
+ working directory a step happens to have, and `workdirFrom` gives every step its
276
+ own.
247
277
 
248
278
  Give each shift its own `--state-dir` as well. The state directory holds the
249
279
  control socket (`shift.sock`), and a second shift starting against a socket
@@ -449,9 +479,8 @@ only the root `owenloop shift` command; `owenloop work` has no standing-daemon a
449
479
  `hold --mcp` remains because the machine-attached hold mount still exists.
450
480
  Run `owenloop work --help` for the full role-specific usage.
451
481
 
452
- The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
453
- `XDG_CONFIG_HOME` is set to a non-blank value; otherwise it is
454
- `$HOME/.config/owenloop/settings.json`.
482
+ The execution settings file is `<config>/settings.json` (see
483
+ [the config-directory ladder](#config-dir)).
455
484
 
456
485
  | subcommand | what it does |
457
486
  |---|---|
@@ -816,9 +845,8 @@ signed or explicitly unsigned sidecar.
816
845
  ### Definition publication policy
817
846
 
818
847
  `defPolicy` is the local execution and installation policy for workflow
819
- publication signatures. The settings file is
820
- `$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is non-blank,
821
- otherwise `$HOME/.config/owenloop/settings.json`. To set the policy in the
848
+ publication signatures. The settings file is `<config>/settings.json` (see
849
+ [the config-directory ladder](#config-dir)). To set the policy in the
822
850
  settings file, write a JSON object such as:
823
851
 
824
852
  ```json
@@ -1022,9 +1050,8 @@ when `defPolicy=off`, and only then runs the origin check. Unsigned,
1022
1050
  unverifiable, or invalid publication evidence never reaches the shell. An
1023
1051
  origin mode of `off` and every policy-floor preset leave that gate unchanged.
1024
1052
 
1025
- The local SSHSIG trust root is
1026
- `$XDG_CONFIG_HOME/owenloop/allowed_signers`, or
1027
- `$HOME/.config/owenloop/allowed_signers` when `XDG_CONFIG_HOME` is blank. A
1053
+ The local SSHSIG trust root is `<config>/allowed_signers` (see
1054
+ [the config-directory ladder](#config-dir)). A
1028
1055
  missing or malformed trust root is `unverifiable`, not `unsigned`.
1029
1056
 
1030
1057
  ### The two store roots
@@ -1261,7 +1288,7 @@ checks both journal locations and dispatches by journal version; a v2 store
1261
1288
  journal uses `index.json` metadata and a v1 GitHub journal uses
1262
1289
  `installed.json` ledger corroboration.
1263
1290
 
1264
- ## Hub (`login` / `connect` / `push` / `start` / `publish` / `logout`)
1291
+ ## Hub (`login` / `connect` / `push` / `start` / `cancel` / `instance` / `publish` / `logout`)
1265
1292
 
1266
1293
  These commands authenticate, publish, and start workflows on a hosted **hub** (default
1267
1294
  `https://api.owenloop.com`). `login` and `logout` retain the generic resolver:
@@ -1325,6 +1352,77 @@ usage errors before credential or network access. The command does not claim,
1325
1352
  dispatch, close, or otherwise drive work—the standing Shift discovers the run
1326
1353
  through its normal crew inbox.
1327
1354
 
1355
+ ### `cancel` — stop a running instance
1356
+
1357
+ `owenloop cancel <workflow>` sends `POST /api/cancel_run` and prints whether the
1358
+ instance was cancelled, its resulting status, and the runs whose leases were
1359
+ closed. `--reason <text>` is optional and recorded on the hub's audit row; like
1360
+ `--crew`/`--title` on `start`, a bare `--reason` or `--reason=` is a local usage
1361
+ error before credential or network access. Hub resolution matches `start`: the
1362
+ project binding wins, and an explicit `--hub` must agree with it.
1363
+
1364
+ This is the counterpart to `start`, and the only local way out of a run that can
1365
+ no longer make progress — a step whose worktree was deleted, or an instance
1366
+ pinned to a def version its shift can no longer satisfy. Such a run is otherwise
1367
+ re-offered forever and permanently occupies one of a shift's dispatch slots,
1368
+ because nothing else on the machine can move it to a terminal state.
1369
+
1370
+ Three properties come from the hub verb, not from this command:
1371
+
1372
+ - **Human-role-only.** `cancel_run` has no agent-scope entry, so an agent
1373
+ credential is refused by the hub. `cancel` therefore always reads the `human`
1374
+ credential slot and does not accept `--as`.
1375
+ - **Idempotent.** Cancelling an instance that already reached a terminal state
1376
+ writes nothing and returns `cancelled: false` plus the state it found. That is
1377
+ a success and exits 0 — a retried cancel must not look like a failure.
1378
+ - **Receipt says `failed`.** The receipt `outcome` union is only `done|failed`,
1379
+ so a cancel composes its receipt as `failed`. The true cancel fact lives in the
1380
+ instance's distinct `cancelled` status and an `action: 'cancel'` audit row.
1381
+ `cancel` prints the status rather than the receipt outcome, so its output does
1382
+ not imply the run failed on its own.
1383
+
1384
+ ### `instance show` — read a hub instance's live state
1385
+
1386
+ `owenloop instance show <workflow>` sends `GET /api/status/:wf` and prints the
1387
+ instance's state: `done`, the `debts` it still owes, the steps that are
1388
+ `eligible` or `blocked`, the runs `inFlight`, and `defDrift`.
1389
+
1390
+ It answers the question no other local command can: **why is this run not
1391
+ moving?** Two of its fields are the entire diagnosis, and both are invisible
1392
+ from the outside because each one looks exactly like an idle shift:
1393
+
1394
+ - **`defDrift: true`** — a hub instance is PINNED to the def version it started
1395
+ on. Publishing a new bundle does not affect a run already in flight. This is
1396
+ the field that explains "I fixed the def and republished, and the run still
1397
+ does the old thing."
1398
+ - **`waitingOnCapabilities`** — a step whose capability has no crew bound is
1399
+ never offered to anyone. Present only when something is actually parked;
1400
+ `getStatus` omits the field otherwise, and `instance show` omits it too rather
1401
+ than printing `[]`, which would read as "asked, and the answer is none."
1402
+
1403
+ Naming, because two obvious names were already taken by different commands:
1404
+
1405
+ - `owenloop status` is the **local** engine's status and takes `--db`. It has no
1406
+ hub credential and rejects `--hub`.
1407
+ - `owenloop runs <workflow>` already lists runs from the **local** sqlite store.
1408
+
1409
+ `instance` is the hub's own word for a started workflow (`setInstanceStatus`,
1410
+ `listInstancesWithStatus`, `cancel_run`'s "already-terminal instance"), so the
1411
+ hub object and the local object keep separate commands instead of one command
1412
+ whose meaning flips on a flag.
1413
+
1414
+ **Only `show` exists, and that is a hub limitation.** `getStatus` is the one
1415
+ instance-read verb with a REST route. `listInstancesWithStatus` (which would
1416
+ back `instance list`) and `listReceipts` / `getReceiptDetail` (where a
1417
+ reviewer's reject reason actually lives) are exposed only over tRPC for the
1418
+ console. Reaching either from the CLI requires new routes in
1419
+ `apps/hub-edge/src/api/routes.ts` and a hub deploy. The subcommand form exists
1420
+ so they can arrive as `instance list` without renaming anything.
1421
+
1422
+ Like `cancel`, it reads the `human` slot, never consults `--as`, and resolves
1423
+ the hub through the project binding so an ambient `OWENLOOP_HUB` cannot redirect
1424
+ the read to a different control plane.
1425
+
1328
1426
  **Publishing hub resolution.** `connect`, `push`, and `publish` resolve their
1329
1427
  target in this order:
1330
1428
 
@@ -1334,9 +1432,8 @@ target in this order:
1334
1432
  - with the file credential backend, exactly one origin containing a valid
1335
1433
  human-slot credential is selected automatically;
1336
1434
  - Keychain and external-command credential backends cannot enumerate their
1337
- origins, so the validated `hubOrigin` in
1338
- `$XDG_CONFIG_HOME/owenloop/settings.json` (or
1339
- `~/.config/owenloop/settings.json`) is used, and the requested credential
1435
+ origins, so the validated `hubOrigin` in `<config>/settings.json` (see
1436
+ [the config-directory ladder](#config-dir)) is used, and the requested credential
1340
1437
  slot must exist there before the command proceeds.
1341
1438
  4. If nothing safe resolves, the command exits 2 without network or publication
1342
1439
  output effects.
@@ -1409,7 +1506,7 @@ empty `agent:ci` fails rather than quietly pushing as you. `logout` without
1409
1506
  (`security`, service `owenloop:<hub origin>`, one item per slot, with the slot
1410
1507
  name as the account) with the secret fed over stdin, never on the command line.
1411
1508
  Elsewhere — or with `OWENLOOP_NO_KEYCHAIN=1` — it falls back to a `0600` file at
1412
- `$XDG_CONFIG_HOME/owenloop/credentials.json` (or `~/.config/owenloop/…`) inside
1509
+ `<config>/credentials.json` (see [the config-directory ladder](#config-dir)) inside
1413
1510
  a `0700` directory, keyed `hubs[origin][slot]`. Either way the token is never
1414
1511
  written into the repo or a `.env`. `login`'s JSON reports `storage: "keychain" |
1415
1512
  "file"` and `kind`, and prints **no token value** to stdout/stderr. A credential
package/docs/crypto.md CHANGED
@@ -523,17 +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
527
- `$XDG_CONFIG_HOME/owenloop/allowed_signers` when
528
- `XDG_CONFIG_HOME` is non-blank, or `$HOME/.config/owenloop/allowed_signers`
529
- otherwise. A missing or malformed trust root produces the distinct
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
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
535
- `$XDG_CONFIG_HOME/owenloop/settings.json` (or
536
- `$HOME/.config/owenloop/settings.json`), for example:
534
+ Set `defPolicy` in the JSON settings file at `<config>/settings.json` (same
535
+ ladder as the trust root above), for example:
537
536
 
538
537
  ```json
539
538
  {
@@ -713,7 +712,8 @@ whole organization.
713
712
  ### Local anchor and envelope files
714
713
 
715
714
  The optional filesystem loader derives paths from injected environment state:
716
- `XDG_CONFIG_HOME` wins over `HOME`; there is no ambient home-directory lookup.
715
+ `OWENLOOP_CONFIG_DIR` wins over `XDG_CONFIG_HOME`, which wins over `HOME`;
716
+ there is no ambient home-directory lookup.
717
717
  The local layout is:
718
718
 
719
719
  ```text
package/docs/design.md CHANGED
@@ -964,8 +964,26 @@ verdict, so the worker issues neither verb and the reap path re-offers the order
964
964
  Command receipts may also carry a bounded JSON payload emitted by a stdout line
965
965
  beginning with `##owenloop:payload##`. The last marker line wins, and the 64 KiB
966
966
  JSON-text cap protects the runner because the runner does not buffer full stdout.
967
- A valid plain-step payload reject is delivered only after every owed receipt has
968
- been submitted. The reject request contains `workflow`, `run`, `path`, and `text`;
967
+ A valid plain-step payload reject is delivered BEFORE any owed receipt is
968
+ submitted. The hub refuses a reject from a run whose claim has closed, and a
969
+ step's last owed submit is what closes it — so the reverse order made every
970
+ reject from a single-owed-path step undeliverable. What follows the reject
971
+ depends on the hub's own answer, in its `closed` field:
972
+
973
+ - `closed: true` — the rejected path was one of this firing's consumed inputs,
974
+ so the hub closed the run `no_work`. The owed paths stay debts and the step
975
+ re-fires against the rebuilt input. No receipt is submitted: an artifact
976
+ derived from an input the same command just declared bad is what the engine's
977
+ dead-input cascade would discard anyway. This is also why the ordering cannot
978
+ born-reject a later submit — there is no later submit.
979
+ - `closed: false` — the rejected path was not consumed by this firing, so the
980
+ claim and the consume fingerprint are both intact and every owed receipt is
981
+ submitted normally.
982
+
983
+ A reject that is refused or throws submits nothing at all, so a gate can never
984
+ green the path its own reject was protesting.
985
+
986
+ The reject request contains `workflow`, `run`, `path`, and `text`;
969
987
  the hub derives the rejecting actor and the client cannot provide `by`.
970
988
 
971
989
  This worker transport does not change `assertAuthority`: the engine continues to