owenloop 0.4.1 → 0.5.1

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 (282) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +182 -53
  3. package/bin/owenloop.mjs +50 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +176 -0
  5. package/dist/packages/work/src/agent/brief.js +197 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +141 -0
  7. package/dist/packages/work/src/agent/loop.js +669 -0
  8. package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
  9. package/dist/packages/work/src/agent/model-policy.js +138 -0
  10. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  11. package/dist/packages/work/src/agent/workdir.js +319 -0
  12. package/dist/packages/work/src/bundle/cache.d.ts +92 -0
  13. package/dist/packages/work/src/bundle/cache.js +338 -0
  14. package/dist/packages/work/src/bundle/fetch.d.ts +87 -0
  15. package/dist/packages/work/src/bundle/fetch.js +345 -0
  16. package/dist/packages/work/src/bundle/types.d.ts +164 -0
  17. package/dist/packages/work/src/bundle/types.js +1 -0
  18. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  19. package/dist/packages/work/src/consumed-verifier.js +205 -0
  20. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  21. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  22. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  23. package/dist/packages/work/src/credentials/reader.js +32 -0
  24. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  25. package/dist/packages/work/src/credentials/resolve.js +56 -0
  26. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  27. package/dist/packages/work/src/exec/instructions.js +323 -0
  28. package/dist/packages/work/src/exec/loop.d.ts +40 -0
  29. package/dist/packages/work/src/exec/loop.js +332 -0
  30. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  31. package/dist/packages/work/src/exec/payload.js +54 -0
  32. package/dist/packages/work/src/exec/receipt.d.ts +41 -0
  33. package/dist/packages/work/src/exec/receipt.js +32 -0
  34. package/dist/packages/work/src/exec/runner.d.ts +71 -0
  35. package/dist/packages/work/src/exec/runner.js +256 -0
  36. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  37. package/dist/packages/work/src/harness/child-env.js +134 -0
  38. package/dist/packages/work/src/harness/claude.d.ts +140 -0
  39. package/dist/packages/work/src/harness/claude.js +837 -0
  40. package/dist/packages/work/src/harness/codex.d.ts +111 -0
  41. package/dist/packages/work/src/harness/codex.js +1024 -0
  42. package/dist/packages/work/src/harness/contract.d.ts +308 -0
  43. package/dist/packages/work/src/harness/contract.js +32 -0
  44. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  45. package/dist/packages/work/src/harness/fake.js +91 -0
  46. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  47. package/dist/packages/work/src/harness/jsonrpc-stdio.js +351 -0
  48. package/dist/packages/work/src/harness/permissions.d.ts +75 -0
  49. package/dist/packages/work/src/harness/permissions.js +182 -0
  50. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  51. package/dist/packages/work/src/harness/registry.js +45 -0
  52. package/dist/packages/work/src/harness/session-store.d.ts +181 -0
  53. package/dist/packages/work/src/harness/session-store.js +523 -0
  54. package/dist/packages/work/src/harness/types.d.ts +29 -0
  55. package/dist/packages/work/src/harness/types.js +14 -0
  56. package/dist/packages/work/src/harnesses.d.ts +38 -0
  57. package/dist/packages/work/src/harnesses.js +38 -0
  58. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  59. package/dist/packages/work/src/hold/loop.js +23 -0
  60. package/dist/packages/work/src/hold/mcp.d.ts +75 -0
  61. package/dist/packages/work/src/hold/mcp.js +264 -0
  62. package/dist/packages/work/src/hub/client.d.ts +23 -0
  63. package/dist/packages/work/src/hub/client.js +91 -0
  64. package/dist/packages/work/src/hub/types.d.ts +326 -0
  65. package/dist/packages/work/src/hub/types.js +26 -0
  66. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  67. package/dist/packages/work/src/lease/loop.js +277 -0
  68. package/dist/packages/work/src/main.d.ts +1 -0
  69. package/dist/packages/work/src/main.js +48 -0
  70. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  71. package/dist/packages/work/src/mcp/server.js +320 -0
  72. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  73. package/dist/packages/work/src/owenloop-bin.js +18 -0
  74. package/dist/packages/work/src/roles/agent-run.d.ts +124 -0
  75. package/dist/packages/work/src/roles/agent-run.js +529 -0
  76. package/dist/packages/work/src/roles/exec.d.ts +48 -0
  77. package/dist/packages/work/src/roles/exec.js +228 -0
  78. package/dist/packages/work/src/roles/hold.d.ts +72 -0
  79. package/dist/packages/work/src/roles/hold.js +363 -0
  80. package/dist/packages/work/src/roles/join.d.ts +18 -0
  81. package/dist/packages/work/src/roles/join.js +204 -0
  82. package/dist/packages/work/src/roles/lint.d.ts +58 -0
  83. package/dist/packages/work/src/roles/lint.js +234 -0
  84. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  85. package/dist/packages/work/src/roles/prepare.js +249 -0
  86. package/dist/packages/work/src/roles/release.d.ts +48 -0
  87. package/dist/packages/work/src/roles/release.js +137 -0
  88. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  89. package/dist/packages/work/src/roles/sessions.js +180 -0
  90. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  91. package/dist/packages/work/src/roles/settings.js +71 -0
  92. package/dist/packages/work/src/roles/shift.d.ts +13 -0
  93. package/dist/packages/work/src/roles/shift.js +250 -0
  94. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  95. package/dist/packages/work/src/roles/signals.js +62 -0
  96. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  97. package/dist/packages/work/src/settings/provision.js +47 -0
  98. package/dist/packages/work/src/settings/settings.d.ts +136 -0
  99. package/dist/packages/work/src/settings/settings.js +155 -0
  100. package/dist/packages/work/src/shift/client.d.ts +24 -0
  101. package/dist/packages/work/src/shift/client.js +124 -0
  102. package/dist/packages/work/src/shift/loop.d.ts +131 -0
  103. package/dist/packages/work/src/shift/loop.js +751 -0
  104. package/dist/packages/work/src/shift/protocol.d.ts +95 -0
  105. package/dist/packages/work/src/shift/protocol.js +24 -0
  106. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  107. package/dist/packages/work/src/shift/routing.js +50 -0
  108. package/dist/packages/work/src/shift/runtime.d.ts +45 -0
  109. package/dist/packages/work/src/shift/runtime.js +337 -0
  110. package/dist/packages/work/src/shift/server.d.ts +23 -0
  111. package/dist/packages/work/src/shift/server.js +716 -0
  112. package/dist/packages/work/src/shift/spawn.d.ts +109 -0
  113. package/dist/packages/work/src/shift/spawn.js +158 -0
  114. package/dist/packages/work/src/shift/state.d.ts +79 -0
  115. package/dist/packages/work/src/shift/state.js +385 -0
  116. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  117. package/dist/packages/work/src/submit-proof.js +93 -0
  118. package/dist/packages/work/src/usage.d.ts +6 -0
  119. package/dist/packages/work/src/usage.js +175 -0
  120. package/dist/src/add.d.ts +189 -0
  121. package/dist/src/add.js +300 -0
  122. package/dist/src/archive.d.ts +97 -0
  123. package/dist/src/archive.js +591 -0
  124. package/dist/src/bundle/index.d.ts +64 -0
  125. package/dist/src/bundle/index.js +508 -0
  126. package/dist/src/bundle/manifest.d.ts +50 -0
  127. package/dist/src/bundle/manifest.js +435 -0
  128. package/dist/src/bundle/runtime.d.ts +26 -0
  129. package/dist/src/bundle/runtime.js +64 -0
  130. package/dist/src/bundle/tar.d.ts +62 -0
  131. package/dist/src/bundle/tar.js +238 -0
  132. package/dist/src/bundle/types.d.ts +105 -0
  133. package/dist/src/bundle/types.js +21 -0
  134. package/dist/{cli.d.ts → src/cli.d.ts} +92 -7
  135. package/dist/src/cli.js +5968 -0
  136. package/dist/{credentials.d.ts → src/credentials.d.ts} +22 -15
  137. package/dist/{credentials.js → src/credentials.js} +35 -31
  138. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  139. package/dist/src/crypto/allowed-signers.js +307 -0
  140. package/dist/src/crypto/canonical.d.ts +8 -0
  141. package/dist/src/crypto/canonical.js +92 -0
  142. package/dist/src/crypto/chain.d.ts +65 -0
  143. package/dist/src/crypto/chain.js +377 -0
  144. package/dist/src/crypto/dsse.d.ts +209 -0
  145. package/dist/src/crypto/dsse.js +282 -0
  146. package/dist/src/crypto/enrollment.d.ts +78 -0
  147. package/dist/src/crypto/enrollment.js +186 -0
  148. package/dist/src/crypto/index.d.ts +48 -0
  149. package/dist/src/crypto/index.js +44 -0
  150. package/dist/src/crypto/keys.d.ts +258 -0
  151. package/dist/src/crypto/keys.js +908 -0
  152. package/dist/src/crypto/org-root.d.ts +33 -0
  153. package/dist/src/crypto/org-root.js +78 -0
  154. package/dist/src/crypto/origin-rules.d.ts +56 -0
  155. package/dist/src/crypto/origin-rules.js +143 -0
  156. package/dist/src/crypto/policy-floor.d.ts +98 -0
  157. package/dist/src/crypto/policy-floor.js +353 -0
  158. package/dist/src/crypto/records.d.ts +316 -0
  159. package/dist/src/crypto/records.js +157 -0
  160. package/dist/src/crypto/scope.d.ts +49 -0
  161. package/dist/src/crypto/scope.js +83 -0
  162. package/dist/src/crypto/ssh.d.ts +171 -0
  163. package/dist/src/crypto/ssh.js +396 -0
  164. package/dist/src/crypto/submission.d.ts +33 -0
  165. package/dist/src/crypto/submission.js +47 -0
  166. package/dist/src/crypto/trust-roots.d.ts +29 -0
  167. package/dist/src/crypto/trust-roots.js +39 -0
  168. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  169. package/dist/src/crypto/verify-consumed.js +259 -0
  170. package/dist/src/crypto/verify-origin.d.ts +50 -0
  171. package/dist/src/crypto/verify-origin.js +151 -0
  172. package/dist/src/crypto/verify-publication.d.ts +60 -0
  173. package/dist/src/crypto/verify-publication.js +150 -0
  174. package/dist/{defs.d.ts → src/defs.d.ts} +24 -1
  175. package/dist/{defs.js → src/defs.js} +181 -61
  176. package/dist/{engine.d.ts → src/engine.d.ts} +105 -9
  177. package/dist/{engine.js → src/engine.js} +251 -47
  178. package/dist/{factory.d.ts → src/factory.d.ts} +16 -0
  179. package/dist/{factory.js → src/factory.js} +16 -4
  180. package/dist/src/global-config.d.ts +59 -0
  181. package/dist/src/global-config.js +84 -0
  182. package/dist/{hub.d.ts → src/hub.d.ts} +280 -31
  183. package/dist/{hub.js → src/hub.js} +493 -52
  184. package/dist/src/index.d.ts +47 -0
  185. package/dist/src/index.js +41 -0
  186. package/dist/src/install.d.ts +538 -0
  187. package/dist/src/install.js +1981 -0
  188. package/dist/src/lock.d.ts +38 -0
  189. package/dist/src/lock.js +325 -0
  190. package/dist/src/mcp/serve.d.ts +109 -0
  191. package/dist/{mcp → src/mcp}/serve.js +335 -75
  192. package/dist/{mcp → src/mcp}/server.d.ts +6 -9
  193. package/dist/{mcp → src/mcp}/server.js +18 -10
  194. package/dist/{model.d.ts → src/model.d.ts} +15 -0
  195. package/dist/{model.js → src/model.js} +112 -2
  196. package/dist/src/order-resolver.d.ts +184 -0
  197. package/dist/src/order-resolver.js +252 -0
  198. package/dist/src/package-version.d.ts +10 -0
  199. package/dist/src/package-version.js +42 -0
  200. package/dist/{paths.d.ts → src/paths.d.ts} +14 -1
  201. package/dist/{paths.js → src/paths.js} +18 -0
  202. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  203. package/dist/src/schemas/index.d.ts +1416 -0
  204. package/dist/src/schemas/index.js +31 -0
  205. package/dist/src/schemas/order.v1.schema.json +106 -0
  206. package/dist/src/schemas/origin.v1.schema.json +68 -0
  207. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  208. package/dist/src/schemas/publication.v1.schema.json +31 -0
  209. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  210. package/dist/src/schemas/submission.v1.schema.json +61 -0
  211. package/dist/src/store/def-source.d.ts +52 -0
  212. package/dist/src/store/def-source.js +335 -0
  213. package/dist/src/store/index-file.d.ts +69 -0
  214. package/dist/src/store/index-file.js +151 -0
  215. package/dist/src/store/index.d.ts +27 -0
  216. package/dist/src/store/index.js +22 -0
  217. package/dist/src/store/ingestor.d.ts +43 -0
  218. package/dist/src/store/ingestor.js +211 -0
  219. package/dist/src/store/install.d.ts +228 -0
  220. package/dist/src/store/install.js +555 -0
  221. package/dist/src/store/instruction-source.d.ts +49 -0
  222. package/dist/src/store/instruction-source.js +298 -0
  223. package/dist/src/store/origin-evidence.d.ts +21 -0
  224. package/dist/src/store/origin-evidence.js +66 -0
  225. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  226. package/dist/src/store/pre-commit-verifier.js +418 -0
  227. package/dist/src/store/resolve.d.ts +138 -0
  228. package/dist/src/store/resolve.js +363 -0
  229. package/dist/src/store/types.d.ts +288 -0
  230. package/dist/src/store/types.js +356 -0
  231. package/dist/{types.d.ts → src/types.d.ts} +58 -24
  232. package/dist/{untar.d.ts → src/untar.d.ts} +8 -23
  233. package/dist/src/untar.js +38 -0
  234. package/dist/{util.d.ts → src/util.d.ts} +3 -2
  235. package/dist/{util.js → src/util.js} +3 -2
  236. package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
  237. package/dist/{owenwork.js → src/work-settings.js} +27 -27
  238. package/docs/agent-runner.md +86 -0
  239. package/docs/authoring.md +150 -59
  240. package/docs/bundles.md +250 -0
  241. package/docs/cli.md +1758 -163
  242. package/docs/crypto.md +816 -0
  243. package/docs/design.md +374 -52
  244. package/docs/embedding.md +135 -27
  245. package/docs/wire-contracts.md +380 -0
  246. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  247. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  248. package/examples/workflows/judges/gate-sharpness.md +39 -0
  249. package/examples/workflows/judges/security.md +34 -0
  250. package/package.json +22 -8
  251. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  252. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  253. package/plugins/claude-code/plugin/.mcp.json +14 -0
  254. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  255. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  256. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  257. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  258. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  259. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  260. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  261. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  262. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  263. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  264. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  265. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  266. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  267. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  268. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
  269. package/dist/add.d.ts +0 -384
  270. package/dist/add.js +0 -834
  271. package/dist/cli.js +0 -3270
  272. package/dist/index.d.ts +0 -32
  273. package/dist/index.js +0 -23
  274. package/dist/lock.d.ts +0 -80
  275. package/dist/lock.js +0 -217
  276. package/dist/mcp/serve.d.ts +0 -84
  277. package/dist/untar.js +0 -164
  278. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  279. /package/dist/{schema.js → src/schema.js} +0 -0
  280. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  281. /package/dist/{store.js → src/store.js} +0 -0
  282. /package/dist/{types.js → src/types.js} +0 -0
@@ -0,0 +1,385 @@
1
+ /**
2
+ * Durable Shift dispatch state.
3
+ *
4
+ * Every dispatch is reserved before spawn. A reservation counts against capacity
5
+ * and same-run deduplication, and carries a start-gate token. The child waits on
6
+ * that gate before entering the CLI. The Shift replaces the reservation with a
7
+ * PID-bearing child record, then opens the gate. A crash before PID persistence
8
+ * leaves a gated child that exits when the abandoned reservation is reaped; a
9
+ * crash after PID persistence leaves enough state for restart reconciliation to
10
+ * open the gate safely.
11
+ */
12
+ import { closeSync, existsSync, fsyncSync, ftruncateSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
13
+ import { randomBytes } from 'node:crypto';
14
+ import { basename, join } from 'node:path';
15
+ export const DEFAULT_RESERVATION_MAX_AGE_MS = 2 * 60_000;
16
+ export function resolveStateDir(env, override) {
17
+ if (override !== undefined && override.trim() !== '')
18
+ return override;
19
+ const xdg = env['XDG_STATE_HOME'];
20
+ if (xdg !== undefined && xdg.trim() !== '')
21
+ return join(xdg, 'owenloop', 'exec');
22
+ const home = env['HOME'];
23
+ if (home !== undefined && home.trim() !== '')
24
+ return join(home, '.local', 'state', 'owenloop', 'exec');
25
+ throw new Error('cannot locate a state directory: set OWENLOOP_STATE_DIR, XDG_STATE_HOME, or HOME');
26
+ }
27
+ function safeRun(run) {
28
+ return run.replace(/[^A-Za-z0-9_.-]/g, '_');
29
+ }
30
+ function recordFile(stateDir, run) {
31
+ return join(stateDir, `${safeRun(run)}.json`);
32
+ }
33
+ function gateFile(stateDir, token) {
34
+ if (!/^[a-f0-9]{32}$/u.test(token))
35
+ throw new Error('invalid child start-gate token');
36
+ return join(stateDir, `.${token}.gate`);
37
+ }
38
+ function syncDirectory(dir) {
39
+ if (process.platform === 'win32')
40
+ return;
41
+ const fd = openSync(dir, 'r');
42
+ try {
43
+ fsyncSync(fd);
44
+ }
45
+ finally {
46
+ closeSync(fd);
47
+ }
48
+ }
49
+ function durableExclusiveWrite(path, value) {
50
+ const fd = openSync(path, 'wx');
51
+ let failure;
52
+ try {
53
+ writeFileSync(fd, value);
54
+ fsyncSync(fd);
55
+ }
56
+ catch (error) {
57
+ failure = error;
58
+ }
59
+ try {
60
+ closeSync(fd);
61
+ }
62
+ catch (error) {
63
+ if (failure === undefined)
64
+ failure = error;
65
+ }
66
+ if (failure !== undefined) {
67
+ try {
68
+ rmSync(path, { force: true });
69
+ }
70
+ catch {
71
+ // Preserve the original write or close failure.
72
+ }
73
+ throw failure;
74
+ }
75
+ syncDirectory(join(path, '..'));
76
+ }
77
+ function durableRemove(path) {
78
+ rmSync(path, { force: true });
79
+ syncDirectory(join(path, '..'));
80
+ }
81
+ function atomicWrite(path, value) {
82
+ const dir = join(path, '..');
83
+ mkdirSync(dir, { recursive: true });
84
+ const tmp = join(dir, `.${randomBytes(8).toString('hex')}-${process.pid}-${Date.now()}.tmp`);
85
+ durableExclusiveWrite(tmp, value);
86
+ try {
87
+ renameSync(tmp, path);
88
+ syncDirectory(dir);
89
+ }
90
+ catch (error) {
91
+ try {
92
+ unlinkSync(tmp);
93
+ }
94
+ catch {
95
+ // Preserve the original write failure.
96
+ }
97
+ throw error;
98
+ }
99
+ }
100
+ function writeStateRecord(stateDir, record) {
101
+ atomicWrite(recordFile(stateDir, record.run), JSON.stringify(record));
102
+ }
103
+ /** Persist a child record atomically. State persistence is correctness-sensitive and throws on failure. */
104
+ export function writeChildRecord(stateDir, record) {
105
+ writeStateRecord(stateDir, record);
106
+ }
107
+ /** Create the durable capacity reservation and closed start gate before spawn. */
108
+ export function reserveChild(stateDir, request) {
109
+ ensureStateDir(stateDir);
110
+ const token = randomBytes(16).toString('hex');
111
+ const gatePath = gateFile(stateDir, token);
112
+ const reservation = {
113
+ recordType: 'reservation',
114
+ workflow: request.workflow,
115
+ run: request.run,
116
+ reservedAt: request.reservedAt,
117
+ token,
118
+ childKind: request.childKind,
119
+ ...(request.step !== undefined ? { step: request.step } : {}),
120
+ };
121
+ durableExclusiveWrite(gatePath, 'wait\n');
122
+ try {
123
+ // Exclusive create is the same-run reservation point. A stale, live, or even
124
+ // corrupt existing record blocks dispatch rather than being overwritten.
125
+ durableExclusiveWrite(recordFile(stateDir, reservation.run), JSON.stringify(reservation));
126
+ }
127
+ catch (error) {
128
+ try {
129
+ durableRemove(gatePath);
130
+ }
131
+ catch {
132
+ // Preserve the reservation write failure.
133
+ }
134
+ throw error;
135
+ }
136
+ return { reservation, gatePath };
137
+ }
138
+ function isReservation(record) {
139
+ return record.recordType === 'reservation';
140
+ }
141
+ export class ShiftStateRecordError extends Error {
142
+ path;
143
+ constructor(path, detail) {
144
+ super(`cannot reconcile Shift state record '${path}': ${detail}; ` +
145
+ 'dispatch is disabled until the record is repaired or removed after verifying that no child still owns the slot');
146
+ this.name = 'ShiftStateRecordError';
147
+ this.path = path;
148
+ }
149
+ }
150
+ function readOneStateRecord(path) {
151
+ let raw;
152
+ try {
153
+ raw = readFileSync(path, 'utf8');
154
+ }
155
+ catch (error) {
156
+ if (error.code === 'ENOENT')
157
+ return undefined;
158
+ const code = error.code;
159
+ throw new ShiftStateRecordError(path, `the canonical record is unreadable${code === undefined ? '' : ` (${code})`}`);
160
+ }
161
+ let parsed;
162
+ try {
163
+ parsed = JSON.parse(raw);
164
+ }
165
+ catch {
166
+ throw new ShiftStateRecordError(path, 'the canonical record is truncated or is not valid JSON');
167
+ }
168
+ if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
169
+ throw new ShiftStateRecordError(path, 'the canonical record is not a JSON object');
170
+ }
171
+ if (typeof parsed['workflow'] !== 'string' || parsed['workflow'] === '' ||
172
+ typeof parsed['run'] !== 'string' || parsed['run'] === '') {
173
+ throw new ShiftStateRecordError(path, 'the canonical record is missing workflow or run identity');
174
+ }
175
+ if (basename(path) !== `${safeRun(parsed['run'])}.json`) {
176
+ throw new ShiftStateRecordError(path, 'the canonical record pathname does not match its run identity');
177
+ }
178
+ if (parsed['recordType'] === 'reservation') {
179
+ if (typeof parsed['reservedAt'] !== 'number' ||
180
+ !Number.isInteger(parsed['reservedAt']) ||
181
+ parsed['reservedAt'] < 0 ||
182
+ typeof parsed['token'] !== 'string' ||
183
+ !/^[a-f0-9]{32}$/u.test(parsed['token']) ||
184
+ (parsed['childKind'] !== 'exec' && parsed['childKind'] !== 'agent-run') ||
185
+ (parsed['step'] !== undefined && typeof parsed['step'] !== 'string')) {
186
+ throw new ShiftStateRecordError(path, 'the canonical reservation fields are malformed');
187
+ }
188
+ return parsed;
189
+ }
190
+ if (parsed['recordType'] !== undefined ||
191
+ typeof parsed['pid'] !== 'number' ||
192
+ !Number.isInteger(parsed['pid']) ||
193
+ parsed['pid'] <= 0 ||
194
+ typeof parsed['spawnedAt'] !== 'number' ||
195
+ !Number.isInteger(parsed['spawnedAt']) ||
196
+ parsed['spawnedAt'] < 0 ||
197
+ (parsed['kind'] !== undefined && parsed['kind'] !== 'exec' && parsed['kind'] !== 'agent-run') ||
198
+ (parsed['def'] !== undefined && typeof parsed['def'] !== 'string') ||
199
+ (parsed['hash'] !== undefined && typeof parsed['hash'] !== 'string') ||
200
+ (parsed['step'] !== undefined && typeof parsed['step'] !== 'string') ||
201
+ (parsed['gateToken'] !== undefined && (typeof parsed['gateToken'] !== 'string' ||
202
+ !/^[a-f0-9]{32}$/u.test(parsed['gateToken'])))) {
203
+ throw new ShiftStateRecordError(path, 'the canonical child fields are malformed');
204
+ }
205
+ return parsed;
206
+ }
207
+ function readStateRecords(stateDir) {
208
+ let names;
209
+ try {
210
+ names = readdirSync(stateDir)
211
+ .filter((name) => name.endsWith('.json') && name !== '.dispatch.lock.owner.json')
212
+ .sort();
213
+ }
214
+ catch (error) {
215
+ if (error.code === 'ENOENT')
216
+ return [];
217
+ throw error;
218
+ }
219
+ return names
220
+ .map((name) => readOneStateRecord(join(stateDir, name)))
221
+ .filter((record) => record !== undefined);
222
+ }
223
+ /** Read only PID-bearing records for status and compatibility callers. */
224
+ export function readChildRecords(stateDir) {
225
+ return readStateRecords(stateDir).filter((record) => !(isReservation(record)));
226
+ }
227
+ export function readChildReservations(stateDir) {
228
+ return readStateRecords(stateDir).filter((record) => isReservation(record));
229
+ }
230
+ /** Replace the matching reservation with a PID-bearing record before work starts. */
231
+ export function finalizeChildReservation(stateDir, reservation, child) {
232
+ const current = readOneStateRecord(recordFile(stateDir, reservation.run));
233
+ if (current === undefined ||
234
+ !isReservation(current) ||
235
+ current.token !== reservation.token) {
236
+ throw new Error(`child reservation for ${reservation.workflow}/${reservation.run} is missing or was replaced`);
237
+ }
238
+ const record = {
239
+ workflow: reservation.workflow,
240
+ run: reservation.run,
241
+ ...child,
242
+ gateToken: reservation.token,
243
+ };
244
+ writeStateRecord(stateDir, record);
245
+ return record;
246
+ }
247
+ function signalGate(path, signal, allowMissing) {
248
+ let fd;
249
+ try {
250
+ fd = openSync(path, 'r+');
251
+ }
252
+ catch (error) {
253
+ if (allowMissing && error.code === 'ENOENT')
254
+ return false;
255
+ throw error;
256
+ }
257
+ try {
258
+ ftruncateSync(fd, 0);
259
+ writeFileSync(fd, `${signal}\n`);
260
+ fsyncSync(fd);
261
+ }
262
+ finally {
263
+ closeSync(fd);
264
+ }
265
+ return true;
266
+ }
267
+ /** Open a child's gate only after the PID-bearing record is durable. */
268
+ export function startReservedChild(stateDir, record) {
269
+ if (record.gateToken === undefined)
270
+ return;
271
+ signalGate(gateFile(stateDir, record.gateToken), 'start', false);
272
+ }
273
+ /** Cancel a gated child and remove the matching reservation/record. */
274
+ export function cancelReservedChild(stateDir, reservation) {
275
+ const path = gateFile(stateDir, reservation.token);
276
+ try {
277
+ signalGate(path, 'cancel', true);
278
+ }
279
+ finally {
280
+ durableRemove(path);
281
+ const current = readOneStateRecord(recordFile(stateDir, reservation.run));
282
+ const matchesReservation = current !== undefined &&
283
+ isReservation(current) &&
284
+ current.token === reservation.token;
285
+ const matchesFinalized = current !== undefined &&
286
+ !isReservation(current) &&
287
+ current.gateToken === reservation.token;
288
+ if (matchesReservation || matchesFinalized)
289
+ durableRemove(recordFile(stateDir, reservation.run));
290
+ }
291
+ }
292
+ /**
293
+ * Delete one run's in-flight state. A still-gated reservation or finalized child
294
+ * is cancelled first so an external run-ended signal cannot leave a worker gate
295
+ * behind that later opens without a capacity record.
296
+ */
297
+ export function removeChildRecord(stateDir, run) {
298
+ const path = recordFile(stateDir, run);
299
+ const current = readOneStateRecord(path);
300
+ if (current !== undefined && isReservation(current)) {
301
+ cancelReservedChild(stateDir, current);
302
+ return;
303
+ }
304
+ if (current?.gateToken !== undefined) {
305
+ const gatePath = gateFile(stateDir, current.gateToken);
306
+ try {
307
+ signalGate(gatePath, 'cancel', true);
308
+ }
309
+ finally {
310
+ durableRemove(gatePath);
311
+ }
312
+ }
313
+ durableRemove(path);
314
+ }
315
+ export const defaultIsAlive = (pid) => {
316
+ if (!Number.isInteger(pid) || pid <= 0)
317
+ return false;
318
+ try {
319
+ process.kill(pid, 0);
320
+ return true;
321
+ }
322
+ catch (error) {
323
+ return error.code !== 'ESRCH';
324
+ }
325
+ };
326
+ /**
327
+ * Reconcile live children and durable reservations. Fresh reservations count as
328
+ * occupied capacity. An expired reservation is cancelled before its record is
329
+ * removed, so a child that was spawned but never finalized cannot begin work.
330
+ */
331
+ export function reconcileInFlight(stateDir, arg) {
332
+ const options = typeof arg === 'function' ? { isAlive: arg } : (arg ?? {});
333
+ const isAlive = options.isAlive ?? defaultIsAlive;
334
+ const now = options.now ?? Date.now();
335
+ const maxAge = options.reservationMaxAgeMs ?? DEFAULT_RESERVATION_MAX_AGE_MS;
336
+ const byRun = new Map();
337
+ for (const record of readStateRecords(stateDir))
338
+ byRun.set(record.run, record);
339
+ const live = [];
340
+ const reserved = [];
341
+ const reaped = [];
342
+ const abandoned = [];
343
+ for (const record of byRun.values()) {
344
+ if (isReservation(record)) {
345
+ // The worker removes its gate when its monotonic wait expires. A missing
346
+ // gate therefore proves that this reservation cannot start work, even if
347
+ // wall-clock rollback makes its persisted age look fresh.
348
+ const gateExists = existsSync(gateFile(stateDir, record.token));
349
+ // A persisted wall-clock timestamp from the future cannot be aged safely
350
+ // after a clock rollback. Cancel the reservation instead of letting a
351
+ // negative elapsed interval occupy capacity indefinitely.
352
+ if (gateExists && record.reservedAt <= now && now - record.reservedAt < maxAge) {
353
+ reserved.push(record);
354
+ continue;
355
+ }
356
+ cancelReservedChild(stateDir, record);
357
+ abandoned.push(record);
358
+ continue;
359
+ }
360
+ if (!isAlive(record.pid)) {
361
+ removeChildRecord(stateDir, record.run);
362
+ reaped.push(record);
363
+ continue;
364
+ }
365
+ if (record.gateToken !== undefined) {
366
+ // A restart after PID persistence but before the parent opened the gate can
367
+ // safely finish the handoff: the durable PID record is the prerequisite.
368
+ signalGate(gateFile(stateDir, record.gateToken), 'start', true);
369
+ const settled = { ...record };
370
+ delete settled.gateToken;
371
+ writeStateRecord(stateDir, settled);
372
+ live.push(settled);
373
+ }
374
+ else {
375
+ live.push(record);
376
+ }
377
+ }
378
+ return { live, reserved, reaped, abandoned };
379
+ }
380
+ /** Ensure the state directory exists and is readable. Failure is fatal to dispatch safety. */
381
+ export function ensureStateDir(stateDir) {
382
+ if (!existsSync(stateDir))
383
+ mkdirSync(stateDir, { recursive: true });
384
+ readdirSync(stateDir);
385
+ }
@@ -0,0 +1,36 @@
1
+ import { PrincipalKeyManager } from '../../../src/crypto/index.ts';
2
+ import type { SshProcessAdapter } from '../../../src/crypto/ssh.ts';
3
+ import type { OrderPacket } from './hub/types.ts';
4
+ export type SubmissionKeyManager = Pick<PrincipalKeyManager, 'inspect' | 'resolveRef' | 'withSigningKey'>;
5
+ export interface SubmitProofOptions {
6
+ origin: string;
7
+ order: OrderPacket;
8
+ path: string;
9
+ value: unknown;
10
+ /** Exact target version issued by a version-aware, retry-safe hub protocol. */
11
+ version?: number;
12
+ now: () => number;
13
+ warn: (line: string) => void;
14
+ principalKeys?: SubmissionKeyManager;
15
+ env?: Record<string, string | undefined>;
16
+ /** Injectable ssh-keygen seam for hermetic callers and tests. */
17
+ sshProcess?: SshProcessAdapter;
18
+ }
19
+ /**
20
+ * Sign one driver submit at the transport boundary. A missing machine key is
21
+ * deliberately an unsigned fallback for WP-D2; signer/tool failures still
22
+ * propagate because silently dropping a configured key would hide corruption.
23
+ */
24
+ export declare function buildSubmitProof(opts: SubmitProofOptions): Promise<string | undefined>;
25
+ /**
26
+ * Resolve the version named by the next submission from authoritative lifecycle
27
+ * metadata only. A judge approval attests the already-submitted version captured
28
+ * in the claim fingerprint and does not increment it. A producer submit requires
29
+ * an explicit target version issued by a retry-safe hub protocol: `owes[].version`
30
+ * is immutable claim-time state and becomes stale after a refinement, lost
31
+ * response, unsigned commit, or holder restart. Without an explicit target,
32
+ * callers must submit without a proof rather than sign a process-local guess.
33
+ */
34
+ export declare function outputVersionForSubmission(order: OrderPacket, path: string, explicit?: number): number | undefined;
35
+ /** Reset the process-local warning latch for hermetic tests. */
36
+ export declare function resetSubmitProofWarningForTests(): void;
@@ -0,0 +1,93 @@
1
+ import { DSSE_SSH_NAMESPACE, PrincipalKeyManager, buildSubmissionRecord, createSshSigner, signSubmission, } from "../../../src/crypto/index.js";
2
+ let warnedUnsigned = false;
3
+ /**
4
+ * Sign one driver submit at the transport boundary. A missing machine key is
5
+ * deliberately an unsigned fallback for WP-D2; signer/tool failures still
6
+ * propagate because silently dropping a configured key would hide corruption.
7
+ */
8
+ export async function buildSubmitProof(opts) {
9
+ const version = outputVersionForSubmission(opts.order, opts.path, opts.version);
10
+ if (version === undefined) {
11
+ warnUnsigned(opts.warn, `order ${opts.order.workflow}/${opts.order.run} omitted authoritative version metadata for output '${opts.path}'; submitting without a proof`);
12
+ return undefined;
13
+ }
14
+ const consumedFingerprint = submissionFingerprint(opts.order, opts.warn);
15
+ if (consumedFingerprint === undefined)
16
+ return undefined;
17
+ let keys;
18
+ try {
19
+ keys = opts.principalKeys ?? new PrincipalKeyManager({ env: opts.env ?? process.env });
20
+ }
21
+ catch (error) {
22
+ warnUnsigned(opts.warn, `machine signing is unavailable (${errorMessage(error)}); submitting without a proof`);
23
+ return undefined;
24
+ }
25
+ const ref = keys.resolveRef(opts.origin, 'machine');
26
+ if (ref === null) {
27
+ warnUnsigned(opts.warn, `no machine signing key for ${opts.origin}; submitting without a proof`);
28
+ return undefined;
29
+ }
30
+ const inspected = await keys.inspect(ref);
31
+ if (!inspected.exists || inspected.publicKey === undefined) {
32
+ warnUnsigned(opts.warn, `machine signing key for ${opts.origin} is unavailable; submitting without a proof`);
33
+ return undefined;
34
+ }
35
+ const record = buildSubmissionRecord({
36
+ run: opts.order.run,
37
+ workflow: opts.order.workflow,
38
+ defDigest: opts.order.defDigest,
39
+ step: opts.order.step,
40
+ key: opts.order.key,
41
+ ...(opts.order.index !== undefined ? { index: opts.order.index } : {}),
42
+ produced: [{ artifact: opts.path, version, value: opts.value }],
43
+ consumedFingerprint,
44
+ producerKeyId: inspected.publicKey.keyid,
45
+ timestamp: opts.now(),
46
+ });
47
+ return keys.withSigningKey(ref, async (keyPath) => {
48
+ const signer = createSshSigner({
49
+ namespace: DSSE_SSH_NAMESPACE,
50
+ signKeyPath: keyPath,
51
+ ...(opts.sshProcess !== undefined ? { process: opts.sshProcess } : {}),
52
+ });
53
+ return signSubmission(record, signer);
54
+ });
55
+ }
56
+ function submissionFingerprint(order, warn) {
57
+ if (order.consumedFingerprint !== undefined)
58
+ return order.consumedFingerprint;
59
+ if (order.inputs.length > 0 || Object.keys(order.consumes).length > 0) {
60
+ warnUnsigned(warn, `order ${order.workflow}/${order.run} omitted its consumed fingerprint; submitting without a proof`);
61
+ return undefined;
62
+ }
63
+ return {};
64
+ }
65
+ /**
66
+ * Resolve the version named by the next submission from authoritative lifecycle
67
+ * metadata only. A judge approval attests the already-submitted version captured
68
+ * in the claim fingerprint and does not increment it. A producer submit requires
69
+ * an explicit target version issued by a retry-safe hub protocol: `owes[].version`
70
+ * is immutable claim-time state and becomes stale after a refinement, lost
71
+ * response, unsigned commit, or holder restart. Without an explicit target,
72
+ * callers must submit without a proof rather than sign a process-local guess.
73
+ */
74
+ export function outputVersionForSubmission(order, path, explicit) {
75
+ if (explicit !== undefined)
76
+ return explicit;
77
+ if (order.judge === path)
78
+ return order.consumedFingerprint?.[path];
79
+ return undefined;
80
+ }
81
+ function errorMessage(error) {
82
+ return error instanceof Error ? error.message : String(error);
83
+ }
84
+ function warnUnsigned(warn, reason) {
85
+ if (warnedUnsigned)
86
+ return;
87
+ warnedUnsigned = true;
88
+ warn(`owenloop: ${reason}`);
89
+ }
90
+ /** Reset the process-local warning latch for hermetic tests. */
91
+ export function resetSubmitProofWarningForTests() {
92
+ warnedUnsigned = false;
93
+ }
@@ -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";