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
@@ -0,0 +1,86 @@
1
+ /**
2
+ * What to spawn: the order to run. `run` IS the order id (hub verb contract);
3
+ * `workflow` pairs with it (every hub verb needs both). The hub `origin` is NOT
4
+ * here — it is captured by `createDefaultSpawner` (one hub per shift), so the
5
+ * loop, which knows only the order, calls the seam without carrying it.
6
+ */
7
+ export interface SpawnSpec {
8
+ workflow: string;
9
+ run: string;
10
+ /**
11
+ * Which role the detached child runs (Phase 3). Absent ⇒ `'exec'`, so every
12
+ * pre-Phase-3 caller and every faked spawner in the existing tests keeps its
13
+ * exact meaning.
14
+ *
15
+ * - `'exec'` — a COMMAND order; the child runs `owenloop work exec`.
16
+ * - `'agent-run'` — an AGENT order; the child runs `owenloop work agent-run` and
17
+ * hosts the step agent itself. This is the ONLY agent path.
18
+ */
19
+ kind?: 'exec' | 'agent-run';
20
+ /**
21
+ * The harness id to host the step agent in, for `kind: 'agent-run'` only.
22
+ * Absent carries no `--harness` flag, leaving the child to resolve the id
23
+ * from `OWENLOOP_HARNESS`, the step def, or its built-in default. Ignored for
24
+ * `'exec'` (a command order has no step agent).
25
+ */
26
+ harness?: string;
27
+ }
28
+ /** The result the loop records: the child's pid. */
29
+ export interface SpawnResult {
30
+ pid: number;
31
+ }
32
+ /** The spawn seam. Injected; faked in tests. */
33
+ export type Spawner = (spec: SpawnSpec) => SpawnResult;
34
+ /** The fully-resolved spawn arguments — pure data, asserted directly in tests. */
35
+ export interface SpawnPlan {
36
+ command: string;
37
+ args: string[];
38
+ options: {
39
+ detached: true;
40
+ stdio: 'ignore';
41
+ env: NodeJS.ProcessEnv;
42
+ };
43
+ }
44
+ /**
45
+ * Resolve the single packaged `bin/owenloop.mjs` from this module's URL.
46
+ *
47
+ * Source-driven tests import `packages/work/src/**`, while installed/runtime
48
+ * execution imports `dist/packages/work/src/**`; those layouts are one parent
49
+ * level apart. Choose the existing candidate so detached children use the root
50
+ * binary in both layouts.
51
+ */
52
+ export declare function resolveOwenloopBin(): string;
53
+ /**
54
+ * Build the argv + options for a detached
55
+ * `owenloop work exec <workflow>/<run> --origin <url>`. Pure — no spawn, no I/O — so
56
+ * tests assert the shape without launching anything. Runs the bin under the
57
+ * current Node (`execPath`), matching the `owenloop work exec <order-id>` arg contract
58
+ * (the composite `<workflow>/<run>` carries both ids in one positional).
59
+ *
60
+ * The account is NOT an argv flag — it rides `options.env.OWENLOOP_ACCOUNT`.
61
+ * `env` starts from `process.env` so the detached child keeps the parent's
62
+ * environment inheritance (which is otherwise implicit when `env` is unset),
63
+ * then sets the resolved account on top.
64
+ *
65
+ * `shiftId` (W7, trailing — after `execPath` so existing positional
66
+ * callers are unaffected), when non-empty, appends `--shift <cid>` so the
67
+ * spawned `owenloop work exec` child self-declares which Shift dispatched it
68
+ * (advisory only, D8/INV-82). Omitted/empty carries no flag at all.
69
+ *
70
+ * Phase 3 (D6) widens this ONE seam rather than adding a second: `spec.kind`
71
+ * selects the role positional (`exec` vs `agent-run`) and `spec.harness`
72
+ * appends `--harness <id>` on the `agent-run` branch. Everything else — the
73
+ * composite order positional, `--origin`, `--shift`, and every spawn option
74
+ * — is identical for both kinds, so an agent-run child is detached,
75
+ * stdio-ignored, and account-scoped exactly like an exec child.
76
+ */
77
+ export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account: string, binPath: string, execPath?: string, shiftId?: string): SpawnPlan;
78
+ /**
79
+ * The default detached spawner. Captures the resolved hub `origin`, the
80
+ * resolved `account`, the packaged bin path, and the dispatching Shift's
81
+ * `shiftId` once at construction; each spawn threads them into the
82
+ * child's argv + spawn env. `execPath` is passed explicitly (rather than
83
+ * relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
84
+ * — can be supplied positionally.
85
+ */
86
+ export declare function createDefaultSpawner(origin: string, account: string, binPath?: string, shiftId?: string): Spawner;
@@ -0,0 +1,100 @@
1
+ /**
2
+ * The detached-exec spawn seam (plan decision 6).
3
+ *
4
+ * Every order the shift dispatches becomes a DETACHED
5
+ * `owenloop work exec <workflow>/<run> --origin <url>` child: `detached: true`,
6
+ * `stdio: 'ignore'`, `unref()` — so the child is its own process-group leader and
7
+ * survives the parent's death (SP5-verified kernel reparenting). The shift meters
8
+ * and hands off; the child self-leases (C5). Both ids ride the argv as the
9
+ * composite `<workflow>/<run>` order-id `owenloop work exec` parses, and `--origin`
10
+ * is passed through so the detached child reaches the SAME hub the shift is
11
+ * parked at without re-reading settings. The shift-resolved account rides the
12
+ * child's spawn ENV as `OWENLOOP_ACCOUNT` (exec has no `--as` flag — the spawn
13
+ * env is the contract), selecting which Scoped Identity credential slot
14
+ * (agent:<account>) exec reads.
15
+ *
16
+ * `Spawner` is an injected seam; unit tests always fake it and NEVER spawn a
17
+ * real child. The default impl's argv/option construction is factored into the
18
+ * pure `buildSpawnPlan` so a test can assert the exact shape as data.
19
+ */
20
+ import { existsSync } from 'node:fs';
21
+ import { spawn } from 'node:child_process';
22
+ import { fileURLToPath } from 'node:url';
23
+ /**
24
+ * Resolve the single packaged `bin/owenloop.mjs` from this module's URL.
25
+ *
26
+ * Source-driven tests import `packages/work/src/**`, while installed/runtime
27
+ * execution imports `dist/packages/work/src/**`; those layouts are one parent
28
+ * level apart. Choose the existing candidate so detached children use the root
29
+ * binary in both layouts.
30
+ */
31
+ export function resolveOwenloopBin() {
32
+ const candidates = [
33
+ new URL('../../../../bin/owenloop.mjs', import.meta.url),
34
+ new URL('../../../../../bin/owenloop.mjs', import.meta.url),
35
+ ].map((url) => fileURLToPath(url));
36
+ return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
37
+ }
38
+ /**
39
+ * Build the argv + options for a detached
40
+ * `owenloop work exec <workflow>/<run> --origin <url>`. Pure — no spawn, no I/O — so
41
+ * tests assert the shape without launching anything. Runs the bin under the
42
+ * current Node (`execPath`), matching the `owenloop work exec <order-id>` arg contract
43
+ * (the composite `<workflow>/<run>` carries both ids in one positional).
44
+ *
45
+ * The account is NOT an argv flag — it rides `options.env.OWENLOOP_ACCOUNT`.
46
+ * `env` starts from `process.env` so the detached child keeps the parent's
47
+ * environment inheritance (which is otherwise implicit when `env` is unset),
48
+ * then sets the resolved account on top.
49
+ *
50
+ * `shiftId` (W7, trailing — after `execPath` so existing positional
51
+ * callers are unaffected), when non-empty, appends `--shift <cid>` so the
52
+ * spawned `owenloop work exec` child self-declares which Shift dispatched it
53
+ * (advisory only, D8/INV-82). Omitted/empty carries no flag at all.
54
+ *
55
+ * Phase 3 (D6) widens this ONE seam rather than adding a second: `spec.kind`
56
+ * selects the role positional (`exec` vs `agent-run`) and `spec.harness`
57
+ * appends `--harness <id>` on the `agent-run` branch. Everything else — the
58
+ * composite order positional, `--origin`, `--shift`, and every spawn option
59
+ * — is identical for both kinds, so an agent-run child is detached,
60
+ * stdio-ignored, and account-scoped exactly like an exec child.
61
+ */
62
+ export function buildSpawnPlan(spec, origin, account, binPath, execPath = process.execPath, shiftId) {
63
+ const role = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
64
+ return {
65
+ command: execPath,
66
+ args: [
67
+ binPath,
68
+ 'work',
69
+ role,
70
+ `${spec.workflow}/${spec.run}`,
71
+ '--origin',
72
+ origin,
73
+ ...(shiftId !== undefined && shiftId !== '' ? ['--shift', shiftId] : []),
74
+ ...(role === 'agent-run' && spec.harness !== undefined && spec.harness !== ''
75
+ ? ['--harness', spec.harness]
76
+ : []),
77
+ ],
78
+ options: { detached: true, stdio: 'ignore', env: { ...process.env, OWENLOOP_ACCOUNT: account } },
79
+ };
80
+ }
81
+ /**
82
+ * The default detached spawner. Captures the resolved hub `origin`, the
83
+ * resolved `account`, the packaged bin path, and the dispatching Shift's
84
+ * `shiftId` once at construction; each spawn threads them into the
85
+ * child's argv + spawn env. `execPath` is passed explicitly (rather than
86
+ * relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
87
+ * — can be supplied positionally.
88
+ */
89
+ export function createDefaultSpawner(origin, account, binPath = resolveOwenloopBin(), shiftId) {
90
+ return (spec) => {
91
+ const plan = buildSpawnPlan(spec, origin, account, binPath, process.execPath, shiftId);
92
+ const child = spawn(plan.command, plan.args, plan.options);
93
+ child.unref();
94
+ if (child.pid === undefined) {
95
+ const role = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
96
+ throw new Error(`spawn of 'owenloop work ${role} ${spec.workflow}/${spec.run}' returned no pid`);
97
+ }
98
+ return { pid: child.pid };
99
+ };
100
+ }
@@ -0,0 +1,77 @@
1
+ /** One dispatched order the shift meters against capacity.
2
+ *
3
+ * Two kinds, and BOTH are real local processes tracked by a live pid:
4
+ * - `exec` (default; absent `kind` for legacy records) — a detached
5
+ * `owenloop work exec` command child, tracked by `kill(pid, 0)`.
6
+ * - `agent-run` — a detached `owenloop work agent-run` child hosting the step
7
+ * agent itself, tracked exactly the same way.
8
+ *
9
+ * There is no pid-less kind any more. The removed `'agent'` kind recorded a
10
+ * stamped Step Agent file handed to an out-of-process Shift: no local
11
+ * child, a `0` sentinel pid, and a coarse TTL standing in for liveness. With
12
+ * the stamp path gone nothing produces such a record, so a leftover one on disk
13
+ * fails the pid probe and is reaped on the next reconcile — which is correct.
14
+ *
15
+ * `def/hash/step` are dispatch provenance (which cached def revision and step
16
+ * this child was dispatched for); they are absent for command orders. */
17
+ export interface ChildRecord {
18
+ workflow: string;
19
+ run: string;
20
+ /** The child's live pid. */
21
+ pid: number;
22
+ spawnedAt: number;
23
+ /** Dispatch kind; absent = `'exec'` (back-compat with pre-split records). */
24
+ kind?: 'exec' | 'agent-run';
25
+ def?: string;
26
+ hash?: string;
27
+ step?: string;
28
+ }
29
+ /**
30
+ * Resolve the state dir: `override` → `$XDG_STATE_HOME/owenloop/exec` →
31
+ * `$HOME/.local/state/owenloop/exec`. Throws when none is available (same
32
+ * stance as the cache/settings resolvers — never guess a home dir). Tests pass
33
+ * an explicit `override` pointing at a temp dir.
34
+ */
35
+ export declare function resolveStateDir(env: Record<string, string | undefined>, override?: string): string;
36
+ /** Persist a child record (atomic temp+rename). Fail-open. */
37
+ export declare function writeChildRecord(stateDir: string, rec: ChildRecord): void;
38
+ /** Read every child record in the state dir. Corrupt files are skipped, a
39
+ * missing dir reads as empty. Fail-open. */
40
+ export declare function readChildRecords(stateDir: string): ChildRecord[];
41
+ /** Delete a child record by run id. Fail-open. */
42
+ export declare function removeChildRecord(stateDir: string, run: string): void;
43
+ /** A liveness probe over a pid. Injectable so tests never touch real pids. */
44
+ export type Liveness = (pid: number) => boolean;
45
+ /**
46
+ * Default liveness probe: `process.kill(pid, 0)` sends no signal, only checks
47
+ * existence/permissions. `ESRCH` ⇒ the process is gone (dead). `EPERM` ⇒ it
48
+ * exists but is owned by another user (count as alive — pid reuse aside, a live
49
+ * foreign process at that pid is not ours to reap). Any other error ⇒ alive
50
+ * (conservative: don't reap on an ambiguous signal).
51
+ */
52
+ export declare const defaultIsAlive: Liveness;
53
+ export interface Reconciliation {
54
+ /** Records whose child is still alive — these count as in-flight. */
55
+ live: ChildRecord[];
56
+ /** Records whose child is gone — reaped (record deleted) this pass. */
57
+ reaped: ChildRecord[];
58
+ }
59
+ /** Injectable knobs for `reconcileInFlight` (all optional; real defaults). */
60
+ export interface ReconcileOptions {
61
+ /** pid liveness probe (default `defaultIsAlive`). */
62
+ isAlive?: Liveness;
63
+ }
64
+ /**
65
+ * Scan the state dir, decide each record's liveness, delete the dead ones, and
66
+ * return the live/reaped split. Deduped by run id (last record for a run wins)
67
+ * so a stray double-write can never double-count capacity.
68
+ *
69
+ * Liveness is UNIFORM: every record names a real local child, so every record
70
+ * is live exactly while `kill(pid, 0)` says its pid is.
71
+ *
72
+ * Back-compat: the second positional arg still accepts a bare `Liveness`
73
+ * (pre-split callers passed `reconcileInFlight(dir, isAlive)`).
74
+ */
75
+ export declare function reconcileInFlight(stateDir: string, arg?: Liveness | ReconcileOptions): Reconciliation;
76
+ /** Ensure the state dir exists so the first read doesn't churn. Fail-open. */
77
+ export declare function ensureStateDir(stateDir: string): void;
@@ -0,0 +1,162 @@
1
+ /**
2
+ * In-flight tracking for detached exec children (plan decision 7).
3
+ *
4
+ * The shift spawns `owenloop work exec <run>` DETACHED — the child survives a shift
5
+ * restart (kernel reparenting, SP5-verified). So the shift cannot trust its own
6
+ * memory to know what is in flight across a restart; it reconstructs that from
7
+ * durable local records instead. A state dir holds one JSON record per spawned
8
+ * child — `{ workflow, run, pid, spawnedAt, def?, hash?, step? }` — and on every
9
+ * sweep (and startup) we scan the records, probe each pid with `kill(pid, 0)`,
10
+ * count the live ones as in-flight, and reap the dead ones.
11
+ *
12
+ * The design docs disdain PID files for broker/discovery plumbing of
13
+ * harness-managed processes; these are shift-spawned children, so local
14
+ * bookkeeping is the legitimate mechanism, not that anti-pattern. Metering off
15
+ * this count is an EFFICIENCY mechanism only — engine race-safety plus the
16
+ * pickup/lease TTLs are the correctness backstop — so a rare pid-reuse miscount
17
+ * is acceptable and never a bug to chase.
18
+ *
19
+ * Every fs op is FAIL-OPEN: a broken state dir degrades metering (the shift may
20
+ * over- or under-count in flight), it never kills the loop.
21
+ */
22
+ import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
23
+ import { join } from 'node:path';
24
+ /**
25
+ * Resolve the state dir: `override` → `$XDG_STATE_HOME/owenloop/exec` →
26
+ * `$HOME/.local/state/owenloop/exec`. Throws when none is available (same
27
+ * stance as the cache/settings resolvers — never guess a home dir). Tests pass
28
+ * an explicit `override` pointing at a temp dir.
29
+ */
30
+ export function resolveStateDir(env, override) {
31
+ if (override !== undefined && override.trim() !== '')
32
+ return override;
33
+ const xdg = env['XDG_STATE_HOME'];
34
+ if (xdg !== undefined && xdg.trim() !== '')
35
+ return join(xdg, 'owenloop', 'exec');
36
+ const home = env['HOME'];
37
+ if (home !== undefined && home.trim() !== '')
38
+ return join(home, '.local', 'state', 'owenloop', 'exec');
39
+ throw new Error('cannot locate a state directory: set OWENLOOP_STATE_DIR, XDG_STATE_HOME, or HOME');
40
+ }
41
+ /** Map a run id onto a safe record filename (hub run ids are already safe; this
42
+ * is defense in depth against a `/`, `\`, or `..` sneaking in). */
43
+ function recordFile(stateDir, run) {
44
+ const safe = run.replace(/[^A-Za-z0-9_.-]/g, '_');
45
+ return join(stateDir, `${safe}.json`);
46
+ }
47
+ /** Persist a child record (atomic temp+rename). Fail-open. */
48
+ export function writeChildRecord(stateDir, rec) {
49
+ try {
50
+ mkdirSync(stateDir, { recursive: true });
51
+ const file = recordFile(stateDir, rec.run);
52
+ const tmp = join(stateDir, `.${Math.random().toString(36).slice(2)}-${process.pid}-${Date.now()}.tmp`);
53
+ writeFileSync(tmp, JSON.stringify(rec));
54
+ try {
55
+ renameSync(tmp, file);
56
+ }
57
+ catch (err) {
58
+ try {
59
+ unlinkSync(tmp);
60
+ }
61
+ catch {
62
+ // best-effort cleanup
63
+ }
64
+ throw err;
65
+ }
66
+ }
67
+ catch {
68
+ // fail-open: a lost record degrades metering, never kills the loop.
69
+ }
70
+ }
71
+ /** Read every child record in the state dir. Corrupt files are skipped, a
72
+ * missing dir reads as empty. Fail-open. */
73
+ export function readChildRecords(stateDir) {
74
+ let names;
75
+ try {
76
+ names = readdirSync(stateDir).filter((f) => f.endsWith('.json'));
77
+ }
78
+ catch {
79
+ return [];
80
+ }
81
+ const records = [];
82
+ for (const name of names) {
83
+ try {
84
+ const rec = JSON.parse(readFileSync(join(stateDir, name), 'utf8'));
85
+ if (rec && typeof rec.run === 'string' && typeof rec.pid === 'number' && typeof rec.workflow === 'string') {
86
+ records.push(rec);
87
+ }
88
+ }
89
+ catch {
90
+ // skip corrupt record
91
+ }
92
+ }
93
+ return records;
94
+ }
95
+ /** Delete a child record by run id. Fail-open. */
96
+ export function removeChildRecord(stateDir, run) {
97
+ try {
98
+ rmSync(recordFile(stateDir, run), { force: true });
99
+ }
100
+ catch {
101
+ // best-effort
102
+ }
103
+ }
104
+ /**
105
+ * Default liveness probe: `process.kill(pid, 0)` sends no signal, only checks
106
+ * existence/permissions. `ESRCH` ⇒ the process is gone (dead). `EPERM` ⇒ it
107
+ * exists but is owned by another user (count as alive — pid reuse aside, a live
108
+ * foreign process at that pid is not ours to reap). Any other error ⇒ alive
109
+ * (conservative: don't reap on an ambiguous signal).
110
+ */
111
+ export const defaultIsAlive = (pid) => {
112
+ if (!Number.isInteger(pid) || pid <= 0)
113
+ return false;
114
+ try {
115
+ process.kill(pid, 0);
116
+ return true;
117
+ }
118
+ catch (err) {
119
+ return err.code !== 'ESRCH';
120
+ }
121
+ };
122
+ /**
123
+ * Scan the state dir, decide each record's liveness, delete the dead ones, and
124
+ * return the live/reaped split. Deduped by run id (last record for a run wins)
125
+ * so a stray double-write can never double-count capacity.
126
+ *
127
+ * Liveness is UNIFORM: every record names a real local child, so every record
128
+ * is live exactly while `kill(pid, 0)` says its pid is.
129
+ *
130
+ * Back-compat: the second positional arg still accepts a bare `Liveness`
131
+ * (pre-split callers passed `reconcileInFlight(dir, isAlive)`).
132
+ */
133
+ export function reconcileInFlight(stateDir, arg) {
134
+ const opts = typeof arg === 'function' ? { isAlive: arg } : (arg ?? {});
135
+ const isAlive = opts.isAlive ?? defaultIsAlive;
136
+ const byRun = new Map();
137
+ for (const rec of readChildRecords(stateDir))
138
+ byRun.set(rec.run, rec);
139
+ const live = [];
140
+ const reaped = [];
141
+ for (const rec of byRun.values()) {
142
+ const alive = isAlive(rec.pid);
143
+ if (alive) {
144
+ live.push(rec);
145
+ }
146
+ else {
147
+ removeChildRecord(stateDir, rec.run);
148
+ reaped.push(rec);
149
+ }
150
+ }
151
+ return { live, reaped };
152
+ }
153
+ /** Ensure the state dir exists so the first read doesn't churn. Fail-open. */
154
+ export function ensureStateDir(stateDir) {
155
+ try {
156
+ if (!existsSync(stateDir))
157
+ mkdirSync(stateDir, { recursive: true });
158
+ }
159
+ catch {
160
+ // fail-open
161
+ }
162
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Single source of the CLI usage text. Printed by `--help`/`help` (to stdout,
3
+ * exit 0) and on a dispatch error (to stderr, exit 2). Keeping it in one place
4
+ * means the help output and the error output never drift apart.
5
+ */
6
+ export declare const USAGE = "owenloop work \u2014 execution-side CLI companion to owenloop\n\nUsage:\n owenloop work hold --order <id> [options] hold an order with a heartbeating lease\n owenloop work exec <order-id> [options] run a command order in a self-leasing loop\n owenloop work agent-run <order-id> [options] host an agent order's step agent in a\n harness, in a self-leasing loop\n owenloop work prepare <workflow> [--origin <url>]\n fetch, cache & normalize step specs\n owenloop work lint <workflow-name | path> lint x.harness option bags in a def\n owenloop work sessions [--all] [--json] list this machine's recorded harness\n sessions and how to re-open them\n owenloop work release --session <id> [options] drain a session's held claims\n owenloop work settings print the resolved settings file\n owenloop work join <code> [--hub <origin>] [--as <account>]\n redeem a join code and store the Scoped\n Identity credential (one-time provisioning)\n\nOptions:\n -h, --help show this help and exit 0\n --version print the owenloop work version and exit 0\n\n root shift options (run as owenloop shift start <crew...> | --all):\n <crew...> serve only these crews (positional, space\n separated); or --all for every crew on the key\n --all serve every crew on the key\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account to read + hand\n to dispatched holds/execs (default 'default')\n --name <n> Shift name (default <hostname>/<cwd>)\n --cap <n> max in-flight exec children (default 3)\n --poll-interval <ms> wake poll cadence (default 5000)\n --once bootstrap wake + one sweep, then exit (demo/e2e)\n --max-agents <n> max in-flight agent-run children, separate from\n --cap (default 4; else settings.maxConcurrentAgents)\n --cache-dir/--state-dir <p> override the resolved dirs\n\n hold options:\n --order <workflow>/<run> the order to hold (or --order <run> --workflow)\n --workflow <wf> required when --order is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account (default\n 'default'; the shift stamps this into born-bound\n holds)\n --session <id> session-holder tag (else env OWENLOOP_SESSION;\n else an anon:<hostname>:<pid> fallback \u2014 a\n holder is always sent)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --ignore-stdin don't final-breath on stdin EOF (detached use)\n --mcp run as a stdio-MCP work-holder: tools get_order /\n submit, lease kept warm underneath (mutually\n exclusive with --ignore-stdin \u2014 stdin is the\n transport)\n\n exec options (usually spawned by shift, not run by hand):\n <workflow>/<run> the command order to run (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n\n agent-run options (spawned by the shift, not run by hand):\n <workflow>/<run> the agent order to host (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --harness <id> which registered harness hosts the step agent\n (else env OWENLOOP_HARNESS, else the step def's\n 'harness' field, else the first registered one)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --submit-grace <ms> after the turn ends, how long to keep asking the\n hub whether the agent's submit landed (default\n 15000). Task completion comes from the HUB, never\n from the harness stream.\n --confirm-interval <ms> poll cadence inside that grace (default 1000)\n\n release options:\n --session <id> session whose claims to drain (else env\n OWENLOOP_SESSION). Agent-held claims re-offer;\n exec-held claims are drain-exempt (B3).\n --origin <url> hub origin (else settings.hubOrigin)\n\n settings (no options in v1):\n prints the resolved settings file path, whether it exists, each known\n knob (hubOrigin, cacheDir, stateDir, dispatchCap, commandRouting,\n maxConcurrentAgents, workRoot, workRepo) with its value + provenance,\n and any unrecognized keys.\n settings.dispatchCap/stateDir are the lowest-precedence\n fallbacks for shift's --cap/--state-dir. NO secrets ever\n live in settings \u2014 credentials stay in owenloop's own store.\n\n sessions options:\n --all include 'dead' sessions (hidden by default \u2014\n a dead session can no longer be resumed)\n --json print the raw newest-per-step records, tokens\n included, instead of the table\n --cache-dir <p> override the resolved cache dir\n\n join options:\n --hub <origin> hub to redeem against (else settings.hubOrigin;\n one of the two is REQUIRED \u2014 the code never\n chooses the hub)\n --as <account> credential account to store under (default:\n the Scoped Identity name the hub returns)\n\n shift/hold/exec/prepare/release env:\n credentials come from owenloop's store \u2014 each role reads the\n agent:<account> slot for its origin (never the human slot); a\n missing slot refuses with a runnable 'owenloop login' command.\n OWENLOOP_ACCOUNT Scoped Identity account for exec/prepare/release\n (default 'default'; shift uses --as, and\n stamps it onto dispatched holds/execs)\n OWENLOOP_TOKEN dev-only bearer override \u2014 when set, used\n verbatim and the store + account are\n bypassed (NOT the primary path)\n OWENLOOP_CACHE_DIR cache root\n OWENLOOP_STATE_DIR shift in-flight state dir\n OWENLOOP_SESSION hold session-holder tag / release drain target\n OWENLOOP_SHIFT_ID dispatching Shift's self-declared id for\n hold/exec/agent-run's --shift (advisory\n only, never for auth/routing/dispatch)\n OWENLOOP_HARNESS agent-run harness id; below --harness, above\n the step def's 'harness' field\n OWENLOOP_WORK_ROOT root for per-RUN agent work dirs\n (<workRoot>/<workflow>/<run>); above\n settings.workRoot, default <cacheDir>/work.\n A hub-supplied OrderPacket.workdir still\n wins, and is never reaped.\n OWENLOOP_WORK_REPO local git repo to cut per-run work dirs from\n as worktrees instead of plain dirs; above\n settings.workRepo, default off\n\n Credentials / accounts:\n owenloop work's RUNTIME roles (shift/hold/exec/prepare/release) are READ-ONLY\n over owenloop's credential store \u2014 they never write credentials. Each\n role reads the agent:<account> slot for its origin (never the human\n slot); the account defaults to 'default'. 'owenloop work join' is the one\n deliberate provisioning-time writer: it stores the Scoped Identity token a hub\n redeem returns via owenloop's public storeCredential, once, at join time\n \u2014 not a runtime write.\n store / connect an account (run owenloop; owenloop work never writes it):\n owenloop login --hub <origin> --as agent:<account>\n (use --as agent for the default account)\n or provision a fresh box from a hub-issued join code:\n owenloop work join <code> --hub <origin>\n select an account at run time:\n --as <account> on shift / hold\n OWENLOOP_ACCOUNT on exec / prepare / release\n (shift resolves once and threads both channels)\n owenloop work does NOT list stored accounts \u2014 enumerating an origin's accounts\n is an owenloop-side capability; check owenloop for which slots are stored.\n\nExit codes:\n 0 success / help / version / lint clean or warnings-only\n 1 runtime failure (fetch/hub error, cache write) / lint found an error\n 2 usage error (unknown or missing role, missing required arg)\n 3 role not implemented yet (skeleton stub \u2014 lands in a later delivery)\n";
@@ -0,0 +1,175 @@
1
+ /**
2
+ * Single source of the CLI usage text. Printed by `--help`/`help` (to stdout,
3
+ * exit 0) and on a dispatch error (to stderr, exit 2). Keeping it in one place
4
+ * means the help output and the error output never drift apart.
5
+ */
6
+ export const USAGE = `owenloop work — execution-side CLI companion to owenloop
7
+
8
+ Usage:
9
+ owenloop work hold --order <id> [options] hold an order with a heartbeating lease
10
+ owenloop work exec <order-id> [options] run a command order in a self-leasing loop
11
+ owenloop work agent-run <order-id> [options] host an agent order's step agent in a
12
+ harness, in a self-leasing loop
13
+ owenloop work prepare <workflow> [--origin <url>]
14
+ fetch, cache & normalize step specs
15
+ owenloop work lint <workflow-name | path> lint x.harness option bags in a def
16
+ owenloop work sessions [--all] [--json] list this machine's recorded harness
17
+ sessions and how to re-open them
18
+ owenloop work release --session <id> [options] drain a session's held claims
19
+ owenloop work settings print the resolved settings file
20
+ owenloop work join <code> [--hub <origin>] [--as <account>]
21
+ redeem a join code and store the Scoped
22
+ Identity credential (one-time provisioning)
23
+
24
+ Options:
25
+ -h, --help show this help and exit 0
26
+ --version print the owenloop work version and exit 0
27
+
28
+ root shift options (run as owenloop shift start <crew...> | --all):
29
+ <crew...> serve only these crews (positional, space
30
+ separated); or --all for every crew on the key
31
+ --all serve every crew on the key
32
+ --origin <url> hub origin (else settings.hubOrigin)
33
+ --as <account> Scoped Identity credential account to read + hand
34
+ to dispatched holds/execs (default 'default')
35
+ --name <n> Shift name (default <hostname>/<cwd>)
36
+ --cap <n> max in-flight exec children (default 3)
37
+ --poll-interval <ms> wake poll cadence (default 5000)
38
+ --once bootstrap wake + one sweep, then exit (demo/e2e)
39
+ --max-agents <n> max in-flight agent-run children, separate from
40
+ --cap (default 4; else settings.maxConcurrentAgents)
41
+ --cache-dir/--state-dir <p> override the resolved dirs
42
+
43
+ hold options:
44
+ --order <workflow>/<run> the order to hold (or --order <run> --workflow)
45
+ --workflow <wf> required when --order is a bare run id
46
+ --origin <url> hub origin (else settings.hubOrigin)
47
+ --as <account> Scoped Identity credential account (default
48
+ 'default'; the shift stamps this into born-bound
49
+ holds)
50
+ --session <id> session-holder tag (else env OWENLOOP_SESSION;
51
+ else an anon:<hostname>:<pid> fallback — a
52
+ holder is always sent)
53
+ --shift <id> dispatching Shift's self-declared id (else
54
+ env OWENLOOP_SHIFT_ID); advisory only
55
+ --heartbeat-interval <ms> lease renew cadence (default 60000)
56
+ --jump-tolerance <ms> wall-gap slack before a tick is treated as a
57
+ clock jump / laptop sleep (default 30000)
58
+ --ignore-stdin don't final-breath on stdin EOF (detached use)
59
+ --mcp run as a stdio-MCP work-holder: tools get_order /
60
+ submit, lease kept warm underneath (mutually
61
+ exclusive with --ignore-stdin — stdin is the
62
+ transport)
63
+
64
+ exec options (usually spawned by shift, not run by hand):
65
+ <workflow>/<run> the command order to run (positional order-id;
66
+ or a bare <run> plus --workflow <wf>)
67
+ --workflow <wf> required when the order-id is a bare run id
68
+ --origin <url> hub origin (else settings.hubOrigin)
69
+ --shift <id> dispatching Shift's self-declared id (else
70
+ env OWENLOOP_SHIFT_ID); advisory only
71
+ --heartbeat-interval <ms> lease renew cadence (default 60000)
72
+ --jump-tolerance <ms> wall-gap slack before a tick is treated as a
73
+ clock jump / laptop sleep (default 30000)
74
+
75
+ agent-run options (spawned by the shift, not run by hand):
76
+ <workflow>/<run> the agent order to host (positional order-id;
77
+ or a bare <run> plus --workflow <wf>)
78
+ --workflow <wf> required when the order-id is a bare run id
79
+ --origin <url> hub origin (else settings.hubOrigin)
80
+ --harness <id> which registered harness hosts the step agent
81
+ (else env OWENLOOP_HARNESS, else the step def's
82
+ 'harness' field, else the first registered one)
83
+ --shift <id> dispatching Shift's self-declared id (else
84
+ env OWENLOOP_SHIFT_ID); advisory only
85
+ --heartbeat-interval <ms> lease renew cadence (default 60000)
86
+ --jump-tolerance <ms> wall-gap slack before a tick is treated as a
87
+ clock jump / laptop sleep (default 30000)
88
+ --submit-grace <ms> after the turn ends, how long to keep asking the
89
+ hub whether the agent's submit landed (default
90
+ 15000). Task completion comes from the HUB, never
91
+ from the harness stream.
92
+ --confirm-interval <ms> poll cadence inside that grace (default 1000)
93
+
94
+ release options:
95
+ --session <id> session whose claims to drain (else env
96
+ OWENLOOP_SESSION). Agent-held claims re-offer;
97
+ exec-held claims are drain-exempt (B3).
98
+ --origin <url> hub origin (else settings.hubOrigin)
99
+
100
+ settings (no options in v1):
101
+ prints the resolved settings file path, whether it exists, each known
102
+ knob (hubOrigin, cacheDir, stateDir, dispatchCap, commandRouting,
103
+ maxConcurrentAgents, workRoot, workRepo) with its value + provenance,
104
+ and any unrecognized keys.
105
+ settings.dispatchCap/stateDir are the lowest-precedence
106
+ fallbacks for shift's --cap/--state-dir. NO secrets ever
107
+ live in settings — credentials stay in owenloop's own store.
108
+
109
+ sessions options:
110
+ --all include 'dead' sessions (hidden by default —
111
+ a dead session can no longer be resumed)
112
+ --json print the raw newest-per-step records, tokens
113
+ included, instead of the table
114
+ --cache-dir <p> override the resolved cache dir
115
+
116
+ join options:
117
+ --hub <origin> hub to redeem against (else settings.hubOrigin;
118
+ one of the two is REQUIRED — the code never
119
+ chooses the hub)
120
+ --as <account> credential account to store under (default:
121
+ the Scoped Identity name the hub returns)
122
+
123
+ shift/hold/exec/prepare/release env:
124
+ credentials come from owenloop's store — each role reads the
125
+ agent:<account> slot for its origin (never the human slot); a
126
+ missing slot refuses with a runnable 'owenloop login' command.
127
+ OWENLOOP_ACCOUNT Scoped Identity account for exec/prepare/release
128
+ (default 'default'; shift uses --as, and
129
+ stamps it onto dispatched holds/execs)
130
+ OWENLOOP_TOKEN dev-only bearer override — when set, used
131
+ verbatim and the store + account are
132
+ bypassed (NOT the primary path)
133
+ OWENLOOP_CACHE_DIR cache root
134
+ OWENLOOP_STATE_DIR shift in-flight state dir
135
+ OWENLOOP_SESSION hold session-holder tag / release drain target
136
+ OWENLOOP_SHIFT_ID dispatching Shift's self-declared id for
137
+ hold/exec/agent-run's --shift (advisory
138
+ only, never for auth/routing/dispatch)
139
+ OWENLOOP_HARNESS agent-run harness id; below --harness, above
140
+ the step def's 'harness' field
141
+ OWENLOOP_WORK_ROOT root for per-RUN agent work dirs
142
+ (<workRoot>/<workflow>/<run>); above
143
+ settings.workRoot, default <cacheDir>/work.
144
+ A hub-supplied OrderPacket.workdir still
145
+ wins, and is never reaped.
146
+ OWENLOOP_WORK_REPO local git repo to cut per-run work dirs from
147
+ as worktrees instead of plain dirs; above
148
+ settings.workRepo, default off
149
+
150
+ Credentials / accounts:
151
+ owenloop work's RUNTIME roles (shift/hold/exec/prepare/release) are READ-ONLY
152
+ over owenloop's credential store — they never write credentials. Each
153
+ role reads the agent:<account> slot for its origin (never the human
154
+ slot); the account defaults to 'default'. 'owenloop work join' is the one
155
+ deliberate provisioning-time writer: it stores the Scoped Identity token a hub
156
+ redeem returns via owenloop's public storeCredential, once, at join time
157
+ — not a runtime write.
158
+ store / connect an account (run owenloop; owenloop work never writes it):
159
+ owenloop login --hub <origin> --as agent:<account>
160
+ (use --as agent for the default account)
161
+ or provision a fresh box from a hub-issued join code:
162
+ owenloop work join <code> --hub <origin>
163
+ select an account at run time:
164
+ --as <account> on shift / hold
165
+ OWENLOOP_ACCOUNT on exec / prepare / release
166
+ (shift resolves once and threads both channels)
167
+ owenloop work does NOT list stored accounts — enumerating an origin's accounts
168
+ is an owenloop-side capability; check owenloop for which slots are stored.
169
+
170
+ Exit codes:
171
+ 0 success / help / version / lint clean or warnings-only
172
+ 1 runtime failure (fetch/hub error, cache write) / lint found an error
173
+ 2 usage error (unknown or missing role, missing required arg)
174
+ 3 role not implemented yet (skeleton stub — lands in a later delivery)
175
+ `;