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,71 @@
1
+ /**
2
+ * `owenloop work settings` — print the resolved settings file: its path, whether it
3
+ * exists, each known knob with its value and provenance, and any unrecognized
4
+ * keys (likely typos). Read-only; there is no write/edit form in v1.
5
+ *
6
+ * This reflects what the FILE supplies — the lowest-precedence tier. It does
7
+ * NOT resolve CLI flags or env vars (those belong to the individual roles at
8
+ * run time); a knob absent from the file prints its built-in default (where one
9
+ * exists) or `unset`.
10
+ *
11
+ * Exit codes: 0 when the settings are valid (including no file at all) · 1 when
12
+ * the file is malformed JSON or a known key has the wrong type · 2 on stray
13
+ * args (there are no options in v1).
14
+ */
15
+ import { DEFAULT_TIER_MAP } from "../agent/model-policy.js";
16
+ import { inspectSettings, KNOWN_SETTINGS_KEYS } from "../settings/settings.js";
17
+ /** Built-in defaults shown for knobs absent from the file (else `unset`). */
18
+ const DEFAULT_NOTE = {
19
+ dispatchCap: '3',
20
+ commandRouting: 'shift',
21
+ defPolicy: 'warn',
22
+ tierMap: JSON.stringify(DEFAULT_TIER_MAP),
23
+ escalateAt: '3',
24
+ escalationExtensionKey: 'delivery',
25
+ };
26
+ function errMsg(err) {
27
+ return err instanceof Error ? err.message : String(err);
28
+ }
29
+ export async function run(args, deps = {}) {
30
+ const out = deps.out ?? ((line) => void process.stdout.write(`${line}\n`));
31
+ const err = deps.err ?? ((line) => void process.stderr.write(`${line}\n`));
32
+ const env = deps.env ?? process.env;
33
+ if (args.length > 0) {
34
+ err(`owenloop work settings: unexpected argument '${args[0]}'`);
35
+ err('usage: owenloop work settings');
36
+ return 2;
37
+ }
38
+ let inspection;
39
+ try {
40
+ inspection = inspectSettings(env);
41
+ }
42
+ catch (e) {
43
+ err(`owenloop work settings: ${errMsg(e)}`);
44
+ return 1;
45
+ }
46
+ const { path, exists, settings, unrecognized } = inspection;
47
+ out(`settings file: ${path}`);
48
+ out(`exists: ${exists ? 'yes' : 'no'}`);
49
+ out('');
50
+ for (const key of KNOWN_SETTINGS_KEYS) {
51
+ const value = settings[key];
52
+ if (value !== undefined) {
53
+ out(` ${key} = ${formatValue(value)} (settings)`);
54
+ }
55
+ else if (DEFAULT_NOTE[key] !== undefined) {
56
+ out(` ${key} = ${DEFAULT_NOTE[key]} (default)`);
57
+ }
58
+ else {
59
+ out(` ${key} = (unset)`);
60
+ }
61
+ }
62
+ if (unrecognized.length > 0) {
63
+ out('');
64
+ out(`unrecognized keys (ignored — likely typos): ${unrecognized.join(', ')}`);
65
+ }
66
+ return 0;
67
+ }
68
+ /** Render a settings value for display: strings bare, everything else JSON. */
69
+ function formatValue(value) {
70
+ return typeof value === 'string' ? value : JSON.stringify(value);
71
+ }
@@ -0,0 +1,13 @@
1
+ import { type ParsedArgs } from '../shift/runtime.ts';
2
+ interface StartArgs extends ParsedArgs {
3
+ all?: boolean;
4
+ crews: string[];
5
+ }
6
+ declare function parseStartArgs(args: string[]): StartArgs;
7
+ declare function resolveSocketPath(flag: string | undefined): {
8
+ path?: string;
9
+ error?: string;
10
+ };
11
+ export declare function shiftDaemonClientPlatformError(command: 'next' | 'status' | 'end', platform?: NodeJS.Platform): string | undefined;
12
+ export declare function run(args: string[]): Promise<number>;
13
+ export { parseStartArgs, resolveSocketPath };
@@ -0,0 +1,250 @@
1
+ /**
2
+ * Public `owenloop shift start|next|status|end` command surface.
3
+ *
4
+ * `start` delegates all origin, credential, settings, cache, spawner, and loop
5
+ * construction to the shift runtime. `next`, `status`, and `end` are thin local
6
+ * socket clients and never contact the hub directly.
7
+ */
8
+ import { loadSettings } from "../settings/settings.js";
9
+ import { resolveStateDir } from "../shift/state.js";
10
+ import { assertShiftDaemonPlatform, resolveStateDirOverride, runShiftRuntime, } from "../shift/runtime.js";
11
+ import { noDaemonMessage, parseNextArgs, parseStateDirArgs, requestShift, ShiftClientError, shiftSocketPath, } from "../shift/client.js";
12
+ import { isShiftError } from "../shift/protocol.js";
13
+ function usage() {
14
+ process.stderr.write('usage: owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]\n' +
15
+ ' [--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]\n' +
16
+ ' [--cache-dir <p>] [--state-dir <p>]\n' +
17
+ ' owenloop shift next [--wait <seconds>] [--state-dir <p>]\n' +
18
+ ' owenloop shift status [--state-dir <p>]\n' +
19
+ ' owenloop shift end [--state-dir <p>]\n');
20
+ }
21
+ function intValue(raw, flag) {
22
+ const value = Number(raw);
23
+ if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
24
+ return `${flag} must be a non-negative integer, got '${raw}'`;
25
+ }
26
+ return value;
27
+ }
28
+ function parseStartArgs(args) {
29
+ const parsed = { crews: [] };
30
+ const valueFlags = new Set(['--origin', '--as', '--name', '--cap', '--max-agents', '--poll-interval', '--cache-dir', '--state-dir']);
31
+ for (let i = 0; i < args.length; i++) {
32
+ const raw = args[i];
33
+ const name = raw.startsWith('--') && raw.includes('=') ? raw.slice(0, raw.indexOf('=')) : raw;
34
+ if (name === '--all') {
35
+ parsed.all = true;
36
+ continue;
37
+ }
38
+ if (name === '--once') {
39
+ parsed.once = true;
40
+ continue;
41
+ }
42
+ if (valueFlags.has(name)) {
43
+ const eq = raw.indexOf('=');
44
+ const value = eq !== -1 ? raw.slice(eq + 1) : args[++i];
45
+ if (value === undefined || value.trim() === '')
46
+ return { crews: parsed.crews, error: `missing value for ${name}` };
47
+ if (name === '--origin')
48
+ parsed.origin = value;
49
+ else if (name === '--as')
50
+ parsed.as = value;
51
+ else if (name === '--name') {
52
+ if (value.trim() === '')
53
+ return { crews: parsed.crews, error: '--name requires a non-empty value' };
54
+ parsed.name = value;
55
+ }
56
+ else if (name === '--cache-dir')
57
+ parsed.cacheDir = value;
58
+ else if (name === '--state-dir')
59
+ parsed.stateDir = value;
60
+ else if (name === '--cap') {
61
+ const n = intValue(value, '--cap');
62
+ if (typeof n !== 'number')
63
+ return { crews: parsed.crews, error: n };
64
+ parsed.cap = n;
65
+ }
66
+ else if (name === '--max-agents') {
67
+ const n = intValue(value, '--max-agents');
68
+ if (typeof n !== 'number')
69
+ return { crews: parsed.crews, error: n };
70
+ parsed.maxAgents = n;
71
+ }
72
+ else if (name === '--poll-interval') {
73
+ const n = intValue(value, '--poll-interval');
74
+ if (typeof n !== 'number')
75
+ return { crews: parsed.crews, error: n };
76
+ parsed.pollIntervalMs = n;
77
+ }
78
+ continue;
79
+ }
80
+ if (raw.startsWith('-'))
81
+ return { crews: parsed.crews, error: `unknown option '${raw}'` };
82
+ const crew = raw.trim();
83
+ if (crew !== '' && !parsed.crews.includes(crew))
84
+ parsed.crews.push(crew);
85
+ }
86
+ if (parsed.all === true && parsed.crews.length > 0) {
87
+ return { crews: parsed.crews, error: '--all cannot be combined with named crews' };
88
+ }
89
+ if (parsed.all !== true && parsed.crews.length === 0) {
90
+ return { crews: parsed.crews, error: 'name at least one crew or pass --all to serve every crew' };
91
+ }
92
+ parsed.serveCrews = parsed.all === true ? [] : parsed.crews;
93
+ return parsed;
94
+ }
95
+ function resolveSocketPath(flag) {
96
+ const env = process.env;
97
+ let settingsStateDir;
98
+ if (flag === undefined && (env['OWENLOOP_STATE_DIR'] === undefined || env['OWENLOOP_STATE_DIR']?.trim() === '')) {
99
+ try {
100
+ settingsStateDir = loadSettings(env).stateDir;
101
+ }
102
+ catch (error) {
103
+ return { error: error instanceof Error ? error.message : String(error) };
104
+ }
105
+ }
106
+ try {
107
+ const stateDir = resolveStateDir(env, resolveStateDirOverride(flag, env, settingsStateDir));
108
+ return { path: shiftSocketPath(stateDir) };
109
+ }
110
+ catch (error) {
111
+ return { error: error instanceof Error ? error.message : String(error) };
112
+ }
113
+ }
114
+ function printJson(value) {
115
+ process.stdout.write(`${JSON.stringify(value)}\n`);
116
+ }
117
+ export function shiftDaemonClientPlatformError(command, platform = process.platform) {
118
+ try {
119
+ assertShiftDaemonPlatform(platform);
120
+ return undefined;
121
+ }
122
+ catch (error) {
123
+ return `owenloop shift ${command}: ${error instanceof Error ? error.message : String(error)}`;
124
+ }
125
+ }
126
+ function rejectUnsupportedDaemonClient(command) {
127
+ const error = shiftDaemonClientPlatformError(command);
128
+ if (error === undefined)
129
+ return false;
130
+ process.stderr.write(`${error}\n`);
131
+ return true;
132
+ }
133
+ async function runNext(args) {
134
+ const parsed = parseNextArgs(args);
135
+ if (parsed.error !== undefined) {
136
+ process.stderr.write(`owenloop shift next: ${parsed.error}\n`);
137
+ usage();
138
+ return 2;
139
+ }
140
+ if (rejectUnsupportedDaemonClient('next'))
141
+ return 1;
142
+ const socket = resolveSocketPath(parsed.stateDir);
143
+ if (socket.error !== undefined || socket.path === undefined) {
144
+ process.stderr.write(`owenloop shift next: ${socket.error ?? 'cannot resolve state directory'}\n`);
145
+ return 1;
146
+ }
147
+ try {
148
+ const response = await requestShift(socket.path, { op: 'next', wait_ms: parsed.waitMs });
149
+ if (isShiftError(response)) {
150
+ process.stderr.write(`${response.error}\n`);
151
+ return 1;
152
+ }
153
+ printJson(response);
154
+ return 0;
155
+ }
156
+ catch (error) {
157
+ process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
158
+ return 1;
159
+ }
160
+ }
161
+ async function runStatus(args) {
162
+ const parsed = parseStateDirArgs(args);
163
+ if (parsed.error !== undefined) {
164
+ process.stderr.write(`owenloop shift status: ${parsed.error}\n`);
165
+ usage();
166
+ return 2;
167
+ }
168
+ if (rejectUnsupportedDaemonClient('status'))
169
+ return 1;
170
+ const socket = resolveSocketPath(parsed.stateDir);
171
+ if (socket.error !== undefined || socket.path === undefined) {
172
+ process.stderr.write(`owenloop shift status: ${socket.error ?? 'cannot resolve state directory'}\n`);
173
+ return 1;
174
+ }
175
+ try {
176
+ const response = await requestShift(socket.path, { op: 'status' });
177
+ if (isShiftError(response)) {
178
+ process.stderr.write(`${response.error}\n`);
179
+ return 1;
180
+ }
181
+ printJson(response);
182
+ return 0;
183
+ }
184
+ catch (error) {
185
+ if (error instanceof ShiftClientError && error.absent) {
186
+ printJson({ status: 'no daemon', socket: socket.path });
187
+ return 0;
188
+ }
189
+ process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
190
+ return 1;
191
+ }
192
+ }
193
+ async function runEnd(args) {
194
+ const parsed = parseStateDirArgs(args);
195
+ if (parsed.error !== undefined) {
196
+ process.stderr.write(`owenloop shift end: ${parsed.error}\n`);
197
+ usage();
198
+ return 2;
199
+ }
200
+ if (rejectUnsupportedDaemonClient('end'))
201
+ return 1;
202
+ const socket = resolveSocketPath(parsed.stateDir);
203
+ if (socket.error !== undefined || socket.path === undefined) {
204
+ process.stderr.write(`owenloop shift end: ${socket.error ?? 'cannot resolve state directory'}\n`);
205
+ return 1;
206
+ }
207
+ try {
208
+ const response = await requestShift(socket.path, { op: 'end' });
209
+ if (isShiftError(response)) {
210
+ process.stderr.write(`${response.error}\n`);
211
+ return 1;
212
+ }
213
+ printJson(response);
214
+ return 0;
215
+ }
216
+ catch (error) {
217
+ if (error instanceof ShiftClientError && error.absent) {
218
+ process.stderr.write(`${noDaemonMessage(socket.path)}\n`);
219
+ return 1;
220
+ }
221
+ process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
222
+ return 1;
223
+ }
224
+ }
225
+ export async function run(args) {
226
+ const [command, ...rest] = args;
227
+ if (command === undefined || command === '--help' || command === '-h' || command === 'help') {
228
+ usage();
229
+ return command === undefined ? 2 : 0;
230
+ }
231
+ if (command === 'start') {
232
+ const parsed = parseStartArgs(rest);
233
+ if (parsed.error !== undefined) {
234
+ process.stderr.write(`owenloop shift start: ${parsed.error}\n`);
235
+ usage();
236
+ return 2;
237
+ }
238
+ return runShiftRuntime(parsed, { daemon: true, role: 'shift' });
239
+ }
240
+ if (command === 'next')
241
+ return runNext(rest);
242
+ if (command === 'status')
243
+ return runStatus(rest);
244
+ if (command === 'end')
245
+ return runEnd(rest);
246
+ process.stderr.write(`owenloop shift: unknown command '${command}'\n`);
247
+ usage();
248
+ return 2;
249
+ }
250
+ export { parseStartArgs, resolveSocketPath };
@@ -0,0 +1,55 @@
1
+ /**
2
+ * Process-lifecycle signal seams shared by the standing roles (`shift`, `hold`).
3
+ *
4
+ * Extracted from `src/roles/shift.ts` (C3) so C4's `hold` reuses the exact
5
+ * same shutdown mechanism instead of inventing a second one. Two seams:
6
+ *
7
+ * - `installSignalHandlers` — first SIGINT/SIGTERM flips the target's
8
+ * `stop(reason?)`; a second signal (either kind) hard-exits 130 (an
9
+ * operator insisting). The role name and the first-signal drain note are
10
+ * parameterized so each role prints its own line; shift's defaults keep its
11
+ * messages byte-identical to C3 (its regression test asserts them).
12
+ * - `watchStdinEof` — fires a callback once when stdin reaches EOF (`end` or
13
+ * `close`). For `hold`, stdin EOF is the parent-session-death signal (a live
14
+ * pipe closing means the interactive session that spawned hold is gone), so
15
+ * it triggers the same final-breath handoff a signal does.
16
+ *
17
+ * Both take injectable hosts (a `process`-shaped slice / a stream-shaped slice)
18
+ * so the wiring is testable without signaling the real process or closing real
19
+ * stdin.
20
+ */
21
+ /** The slice of `process` the signal wiring needs — injectable for tests. */
22
+ export interface SignalHost {
23
+ on(signal: 'SIGINT' | 'SIGTERM', handler: () => void): unknown;
24
+ exit(code: number): void;
25
+ }
26
+ /** Message/behavior knobs for a role's signal wiring. */
27
+ export interface SignalOptions {
28
+ /** Role name for the message prefix `owenloop work <role>:` (default `shift`). */
29
+ role?: string;
30
+ /** First-signal note after `<sig> received — ` (default shift's drain note). */
31
+ drainNote?: string;
32
+ /** Reason handed to `target.stop()` on the first signal (roles that care). */
33
+ stopReason?: string;
34
+ }
35
+ /**
36
+ * Clean-shutdown signal wiring: the first SIGINT/SIGTERM flips
37
+ * `target.stop(reason)`; a second signal hard-exits 130. Exported with an
38
+ * injectable host so the wiring is testable without signaling the test process.
39
+ */
40
+ export declare function installSignalHandlers(target: {
41
+ stop(reason?: string): void;
42
+ }, host: SignalHost, err: (line: string) => void, opts?: SignalOptions): void;
43
+ /** The slice of a readable stream the EOF watcher needs — injectable for tests. */
44
+ export interface StdinHost {
45
+ on(event: 'end' | 'close', handler: () => void): unknown;
46
+ /** Flowing mode is required for `end` to fire on a piped stdin; optional. */
47
+ resume?(): void;
48
+ }
49
+ /**
50
+ * Fire `cb` exactly once when the stream reaches EOF (`end` or `close`,
51
+ * whichever comes first). Calls `resume()` if present so a paused stdin starts
52
+ * flowing (otherwise `end` never arrives). Idempotent — a stream that emits
53
+ * both `end` and `close` still calls back once.
54
+ */
55
+ export declare function watchStdinEof(stream: StdinHost, cb: () => void): void;
@@ -0,0 +1,62 @@
1
+ /**
2
+ * Process-lifecycle signal seams shared by the standing roles (`shift`, `hold`).
3
+ *
4
+ * Extracted from `src/roles/shift.ts` (C3) so C4's `hold` reuses the exact
5
+ * same shutdown mechanism instead of inventing a second one. Two seams:
6
+ *
7
+ * - `installSignalHandlers` — first SIGINT/SIGTERM flips the target's
8
+ * `stop(reason?)`; a second signal (either kind) hard-exits 130 (an
9
+ * operator insisting). The role name and the first-signal drain note are
10
+ * parameterized so each role prints its own line; shift's defaults keep its
11
+ * messages byte-identical to C3 (its regression test asserts them).
12
+ * - `watchStdinEof` — fires a callback once when stdin reaches EOF (`end` or
13
+ * `close`). For `hold`, stdin EOF is the parent-session-death signal (a live
14
+ * pipe closing means the interactive session that spawned hold is gone), so
15
+ * it triggers the same final-breath handoff a signal does.
16
+ *
17
+ * Both take injectable hosts (a `process`-shaped slice / a stream-shaped slice)
18
+ * so the wiring is testable without signaling the real process or closing real
19
+ * stdin.
20
+ */
21
+ const DEFAULT_ROLE = 'shift';
22
+ const DEFAULT_DRAIN_NOTE = 'draining, in-flight children keep running';
23
+ /**
24
+ * Clean-shutdown signal wiring: the first SIGINT/SIGTERM flips
25
+ * `target.stop(reason)`; a second signal hard-exits 130. Exported with an
26
+ * injectable host so the wiring is testable without signaling the test process.
27
+ */
28
+ export function installSignalHandlers(target, host, err, opts = {}) {
29
+ const role = opts.role ?? DEFAULT_ROLE;
30
+ const drainNote = opts.drainNote ?? DEFAULT_DRAIN_NOTE;
31
+ let signalled = false;
32
+ const onSignal = (sig) => {
33
+ if (signalled) {
34
+ err(`owenloop work ${role}: second ${sig} — exiting now`);
35
+ host.exit(130);
36
+ return;
37
+ }
38
+ signalled = true;
39
+ err(`owenloop work ${role}: ${sig} received — ${drainNote}`);
40
+ target.stop(opts.stopReason);
41
+ };
42
+ host.on('SIGINT', () => onSignal('SIGINT'));
43
+ host.on('SIGTERM', () => onSignal('SIGTERM'));
44
+ }
45
+ /**
46
+ * Fire `cb` exactly once when the stream reaches EOF (`end` or `close`,
47
+ * whichever comes first). Calls `resume()` if present so a paused stdin starts
48
+ * flowing (otherwise `end` never arrives). Idempotent — a stream that emits
49
+ * both `end` and `close` still calls back once.
50
+ */
51
+ export function watchStdinEof(stream, cb) {
52
+ let fired = false;
53
+ const fire = () => {
54
+ if (fired)
55
+ return;
56
+ fired = true;
57
+ cb();
58
+ };
59
+ stream.on('end', fire);
60
+ stream.on('close', fire);
61
+ stream.resume?.();
62
+ }
@@ -0,0 +1,21 @@
1
+ export type RecordHubOriginResult = {
2
+ outcome: 'written';
3
+ path: string;
4
+ } | {
5
+ outcome: 'unchanged';
6
+ path: string;
7
+ } | {
8
+ outcome: 'conflict';
9
+ path: string;
10
+ existing: string;
11
+ };
12
+ /**
13
+ * Record `origin` (already `normalizeOrigin`d by the caller) as
14
+ * `settings.hubOrigin`, first-write-wins:
15
+ * - absent/blank `hubOrigin` → merge-write `{ ...settings, hubOrigin: origin }`,
16
+ * creating the settings directory if needed. Unknown keys already in the
17
+ * file are preserved (`inspectSettings` retains them on `settings`).
18
+ * - present, normalizes equal → `unchanged`, no write (file byte-identical).
19
+ * - present, differs (or does not itself normalize) → `conflict`, no write.
20
+ */
21
+ export declare function recordHubOrigin(env: Record<string, string | undefined>, origin: string): RecordHubOriginResult;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * The ONE settings writer in owenloop, provisioning-time only.
3
+ *
4
+ * `settings/settings.ts` is deliberately read-only (see its HARD RULE comment)
5
+ * — every role loads settings, no role writes them. `owenloop work join` is the sole
6
+ * exception: it is a one-time provisioning act, not a runtime write, so its
7
+ * write path lives in this separate module rather than growing a write
8
+ * function onto `settings.ts` itself.
9
+ *
10
+ * FIRST WRITE WINS: `recordHubOrigin` never overwrites a differing existing
11
+ * `hubOrigin`. A box that has already recorded a hub is not silently
12
+ * re-pointed at another one by a second `join` run; the caller (join.ts)
13
+ * surfaces a `conflict` as a non-fatal warning instead.
14
+ */
15
+ import { mkdirSync, writeFileSync } from 'node:fs';
16
+ import { dirname } from 'node:path';
17
+ import { normalizeOrigin } from "../../../../src/hub.js";
18
+ import { inspectSettings, settingsPath } from "./settings.js";
19
+ /**
20
+ * Record `origin` (already `normalizeOrigin`d by the caller) as
21
+ * `settings.hubOrigin`, first-write-wins:
22
+ * - absent/blank `hubOrigin` → merge-write `{ ...settings, hubOrigin: origin }`,
23
+ * creating the settings directory if needed. Unknown keys already in the
24
+ * file are preserved (`inspectSettings` retains them on `settings`).
25
+ * - present, normalizes equal → `unchanged`, no write (file byte-identical).
26
+ * - present, differs (or does not itself normalize) → `conflict`, no write.
27
+ */
28
+ export function recordHubOrigin(env, origin) {
29
+ const path = settingsPath(env);
30
+ const { settings } = inspectSettings(env);
31
+ const existing = settings.hubOrigin;
32
+ if (existing === undefined || existing.trim() === '') {
33
+ mkdirSync(dirname(path), { recursive: true });
34
+ writeFileSync(path, `${JSON.stringify({ ...settings, hubOrigin: origin }, null, 2)}\n`);
35
+ return { outcome: 'written', path };
36
+ }
37
+ let normalizedExisting;
38
+ try {
39
+ normalizedExisting = normalizeOrigin(existing);
40
+ }
41
+ catch {
42
+ return { outcome: 'conflict', path, existing };
43
+ }
44
+ if (normalizedExisting === origin)
45
+ return { outcome: 'unchanged', path };
46
+ return { outcome: 'conflict', path, existing };
47
+ }
@@ -0,0 +1,136 @@
1
+ /**
2
+ * The settings surface — every knob optional, a missing file loading as `{}`.
3
+ * Each field is the lowest-precedence fallback for a role option (a CLI flag
4
+ * or env var always wins over it):
5
+ * - `hubOrigin` — default hub origin when `--origin` is omitted
6
+ * (prepare, shift, hold, exec, release).
7
+ * - `cacheDir` — bundle cache root; overrides the XDG default
8
+ * (see bundle/cache.ts).
9
+ * - `stateDir` — shift in-flight state dir; overrides the XDG default
10
+ * (below `OWENLOOP_STATE_DIR`).
11
+ * - `dispatchCap` — shift max in-flight exec children; below `--cap`,
12
+ * above the built-in default of 3. A positive integer.
13
+ * - `commandRouting` — who runs `executor: 'command'` steps this machine sees.
14
+ * - `defPolicy` — local publication trust policy (`warn` by default).
15
+ */
16
+ export interface Settings {
17
+ /** Default hub origin when `--origin` is omitted. */
18
+ hubOrigin?: string;
19
+ /** Bundle cache root; overrides the XDG default (see bundle/cache.ts). */
20
+ cacheDir?: string;
21
+ /** Shift in-flight state dir; fallback below `--state-dir`/env. */
22
+ stateDir?: string;
23
+ /** Shift dispatch cap (positive integer); fallback below `--cap`, default 3. */
24
+ dispatchCap?: number;
25
+ /**
26
+ * Who runs `executor: 'command'` steps this machine sees: `'shift'` (default)
27
+ * lets the shift auto-dispatch them; `'manual'` leaves them for a human/
28
+ * session to pick up via the pickup window. The C3 shift is the only reader.
29
+ * A per-step `x.owenloop.routing` override can tighten (never loosen) this —
30
+ * most restrictive wins (see src/shift/routing.ts).
31
+ */
32
+ commandRouting?: 'shift' | 'manual';
33
+ /**
34
+ * Publication trust policy for installed workflow definitions. `warn` is the
35
+ * built-in default; `enforce` refuses unsigned/unverifiable definitions and
36
+ * `off` suppresses those warnings for agent orders only. Command workers
37
+ * always require a verified definition regardless of this value.
38
+ */
39
+ defPolicy?: 'enforce' | 'warn' | 'off';
40
+ /** Policy for signed consumed artifact values; defaults to `warn`. */
41
+ artifactPolicy?: 'enforce' | 'warn' | 'off';
42
+ /**
43
+ * Max in-flight `agent-run` children (positive integer, default 4 —
44
+ * `DEFAULT_MAX_AGENTS` in `src/roles/shift.ts`). A SEPARATE
45
+ * budget from `dispatchCap`, which meters `exec` children — an agent turn is
46
+ * long and memory-heavy where a command is short, so one number cannot serve
47
+ * both. Fallback below `--max-agents`.
48
+ */
49
+ maxConcurrentAgents?: number;
50
+ /**
51
+ * Phase 4 — the root under which per-RUN agent working directories live.
52
+ *
53
+ * An `agent-run` child works in `<workRoot>/<workflow>/<run>/`, created on
54
+ * first use. PER RUN, not per step: every step of a run shares one directory,
55
+ * which is what lets a downstream step read what an upstream step wrote, and
56
+ * what makes the removal gate a single question ("does this run still have an
57
+ * open order?") instead of a `consumes` walk.
58
+ *
59
+ * Default when unset: `<cacheDir>/work`. Overridden per order by
60
+ * `OrderPacket.workdir` — the hub always wins, and a hub-supplied workdir is
61
+ * NEVER removed by the reaper, which only ever removes what it created under
62
+ * `workRoot`.
63
+ *
64
+ * Pulled forward from Phase 5, which `docs/agent-runner.md` originally
65
+ * deferred it to: worktree lifetime is not implementable without a work root.
66
+ */
67
+ workRoot?: string;
68
+ /**
69
+ * Phase 4 — an optional local git repo. When set, a per-run work directory is
70
+ * created as `git worktree add` against this repo instead of a plain `mkdir`,
71
+ * and removed with `git worktree remove` instead of a plain `rm -rf`.
72
+ *
73
+ * LOCALLY OPT-IN, deliberately. Nothing in `src/bundle/types.ts` or
74
+ * `src/hub/types.ts` lets a workflow declare a repo, and adding one would be a
75
+ * hub protocol change — an explicit non-goal. So worktree mode is a property
76
+ * of the MACHINE running the shift, not of the workflow.
77
+ */
78
+ workRepo?: string;
79
+ /** Quality-tier to concrete model mapping; merged over the built-in map. */
80
+ tierMap?: Record<string, string>;
81
+ /** Reject count at which the default retry policy escalates. */
82
+ escalateAt?: number;
83
+ /** Extension namespace containing an authored escalation object. */
84
+ escalationExtensionKey?: string;
85
+ }
86
+ /** The known settings keys, in the order `owenloop work settings` prints them. */
87
+ export declare const KNOWN_SETTINGS_KEYS: readonly ["hubOrigin", "cacheDir", "stateDir", "dispatchCap", "commandRouting", "defPolicy", "artifactPolicy", "maxConcurrentAgents", "workRoot", "workRepo", "tierMap", "escalateAt", "escalationExtensionKey"];
88
+ /**
89
+ * A validated load: the typed `settings` (unknown keys retained for forward
90
+ * compatibility — consumers ignore them), plus the list of keys that are NOT
91
+ * recognized so `owenloop work settings` can flag likely typos.
92
+ */
93
+ export interface ValidatedSettings {
94
+ settings: Settings;
95
+ /** Keys present in the file that owenloop does not recognize. */
96
+ unrecognized: string[];
97
+ }
98
+ /** The result of inspecting the settings file: where it is, whether it exists, and its validated contents. */
99
+ export interface SettingsInspection extends ValidatedSettings {
100
+ path: string;
101
+ exists: boolean;
102
+ }
103
+ /**
104
+ * Resolve the settings file path from the caller's env:
105
+ * `$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is set and
106
+ * non-empty, else `$HOME/.config/owenloop/settings.json`. Throws when neither
107
+ * is available rather than guessing a home directory.
108
+ */
109
+ export declare function settingsPath(env: Record<string, string | undefined>): string;
110
+ /**
111
+ * Validate a parsed settings object. Checks the TYPE of every known key
112
+ * (throwing an actionable error naming the key, expected type, received value,
113
+ * and file path on a mismatch) and collects any unrecognized keys. Unknown
114
+ * keys are retained on the returned `settings` (forward compatible) — only
115
+ * their names are reported, never fatal.
116
+ *
117
+ * `dispatchCap` must be a positive integer; `commandRouting` must be one of the
118
+ * two literals. Any other type on a known key is a hard error.
119
+ */
120
+ export declare function validateSettings(raw: unknown, path: string): ValidatedSettings;
121
+ /**
122
+ * Inspect the settings file: resolve its path, whether it exists, and its
123
+ * validated contents. A missing file is not an error (`exists: false`,
124
+ * settings `{}`). Malformed JSON or an invalid known-key type throws a clear,
125
+ * path-named error. This is the single read+validate path that `loadSettings`
126
+ * and the `settings` print role share.
127
+ */
128
+ export declare function inspectSettings(env: Record<string, string | undefined>): SettingsInspection;
129
+ /**
130
+ * Load, parse, and validate the settings file. A missing file yields `{}` (not
131
+ * an error). Malformed JSON or an invalid known-key type throws a clear error
132
+ * rather than silently defaulting — a silent default would mask config bugs.
133
+ * Every consumer that calls `loadSettings` gets known-key type validation for
134
+ * free; unknown keys pass through untouched.
135
+ */
136
+ export declare function loadSettings(env: Record<string, string | undefined>): Settings;