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,523 @@
1
+ /**
2
+ * Session store — the append-only JSONL record of which harness session belongs
3
+ * to which step attempt, so a rejected step can be RESUMED instead of restarted.
4
+ *
5
+ * Layout: one JSON object per line at `<cacheDir>/sessions.jsonl`
6
+ * (`sessionsPath`). The cache dir comes from the EXISTING `resolveCacheDir`
7
+ * (`src/bundle/cache.ts`); this phase adds NO new settings key.
8
+ *
9
+ * MACHINE-LOCAL BY DESIGN. A provider session token has no meaning off the
10
+ * machine that created it, so these records are NEVER sent to the hub —
11
+ * structurally guaranteed here by the absence of any `src/hub/` import, and
12
+ * socially by this comment. Nothing in this file talks to a network.
13
+ *
14
+ * LAST-WINS per `(workflow, run, step)`: a later line beats an earlier one.
15
+ * `attempt` is CARRIED BY the record and is deliberately NOT part of the key —
16
+ * a re-attempt appends a new record with the same key and a higher `attempt`,
17
+ * which correctly shadows the old one.
18
+ *
19
+ * FAILURE STANCE, three different answers on purpose:
20
+ * - READ is fail-open: a missing file reads as `[]` (mirrors `readChildRecords`
21
+ * in `src/shift/state.ts`), and a corrupt line is skipped and reported
22
+ * through the injectable `warn` callback, never thrown. A store that cannot
23
+ * be parsed must degrade a resume into a replay, not break the worker.
24
+ * - APPEND PROPAGATES. Unlike the shift's advisory metering records, a lost
25
+ * session token silently degrades a Phase 4 resume into a cold replay — real
26
+ * work thrown away — so the caller must see the failure.
27
+ * - `active` is the safety-critical boundary. Its complete JSONL row is fsynced
28
+ * before provider work may proceed. Other lifecycle rows retain ordinary
29
+ * append durability; losing one degrades to conservative retirement/replay.
30
+ * - COMPACTION is best-effort after a committed append, but a successful
31
+ * compaction fsyncs its replacement before rename so it cannot erase a
32
+ * previously durable `active` row across a host crash.
33
+ *
34
+ * DEVIATION FROM PLAN §3, stated deliberately: plan §3 says "compact on load if
35
+ * > 2 MB". This module compacts on the WRITE path instead — `appendSession`
36
+ * appends, stats the file, and compacts past `maxBytes`. Reasons: `latestFor`
37
+ * stays side-effect-free (a read never becomes a writer, and never fails on a
38
+ * read-only filesystem), and a small `maxBytes` lets tests exercise compaction
39
+ * without writing 2 MB. The 2 MB default is unchanged.
40
+ *
41
+ * WRITER SERIALIZATION: every append, retirement, and compaction takes one
42
+ * cross-process writer lock for its complete read/append/size-check/rename
43
+ * transaction. A completed append can therefore never be replaced or shadowed
44
+ * by another process's stale snapshot. The shared SQLite lock database persists;
45
+ * process exit or crash releases its kernel lock without pathname deletion.
46
+ *
47
+ * Logging follows the house rule (there are zero `console.*` calls anywhere in
48
+ * `src/`): the library takes an injectable callback and the default writes to
49
+ * stderr, so tests stay silent and assertable.
50
+ */
51
+ import { closeSync, fstatSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
52
+ import { join } from 'node:path';
53
+ import { acquireFileLockSync, releaseFileLock } from "../../../../src/lock.js";
54
+ const STATUSES = new Set(['active', 'turn-ended', 'submitted', 'dead']);
55
+ /** Default compaction threshold — plan §3's 2 MB. */
56
+ export const DEFAULT_MAX_BYTES = 2_000_000;
57
+ /** Grace for a concurrent writer to finish an unterminated JSONL append. */
58
+ export const DEFAULT_UNTERMINATED_TAIL_GRACE_MS = 5_000;
59
+ /** Process-local observations; session files remain the only persisted state. */
60
+ const tailObservations = new Map();
61
+ /** `<cacheDir>/sessions.jsonl`. */
62
+ export function sessionsPath(cacheDir) {
63
+ return join(cacheDir, 'sessions.jsonl');
64
+ }
65
+ /** The composite order id `<workflow>/<run>` — the one place it is built. */
66
+ export function orderId(workflow, run) {
67
+ return `${workflow}/${run}`;
68
+ }
69
+ function defaultWarn(line) {
70
+ process.stderr.write(`${line}\n`);
71
+ }
72
+ /** Identity of a step attempt slot. `attempt` is intentionally not in the key.
73
+ * JSON-encoded rather than joined on a separator character so no combination of
74
+ * workflow/run/step values can collide into one key. */
75
+ function keyOf(workflow, run, step) {
76
+ return JSON.stringify([workflow, run, step]);
77
+ }
78
+ function isNonEmptyString(v) {
79
+ return typeof v === 'string' && v !== '';
80
+ }
81
+ /**
82
+ * Validate one parsed line. Checks exactly the fields whose absence would make
83
+ * the record unusable for a resume: the three key fields plus the harness and
84
+ * token it exists to carry, and a `status` inside the four literals. Everything
85
+ * else is carried verbatim.
86
+ */
87
+ function isSessionRecord(v) {
88
+ if (typeof v !== 'object' || v === null || Array.isArray(v))
89
+ return false;
90
+ const r = v;
91
+ if (!isNonEmptyString(r['workflow']))
92
+ return false;
93
+ if (!isNonEmptyString(r['run']))
94
+ return false;
95
+ if (!isNonEmptyString(r['step']))
96
+ return false;
97
+ if (!isNonEmptyString(r['harness']))
98
+ return false;
99
+ if (!isNonEmptyString(r['token']))
100
+ return false;
101
+ if (typeof r['status'] !== 'string' || !STATUSES.has(r['status']))
102
+ return false;
103
+ return true;
104
+ }
105
+ /** Flush a directory entry update where the platform exposes directory fsync. */
106
+ function syncDirectory(dir, sync = fsyncSync) {
107
+ if (process.platform === 'win32')
108
+ return;
109
+ const fd = openSync(dir, 'r');
110
+ try {
111
+ sync(fd);
112
+ }
113
+ finally {
114
+ closeSync(fd);
115
+ }
116
+ }
117
+ /** Atomic durable write used by compaction. The replacement bytes are fsynced
118
+ * before rename, then the directory entry is fsynced. Fs errors propagate to
119
+ * the caller; `compactIfNeededUnlocked` decides whether best-effort compaction
120
+ * may swallow them. */
121
+ function atomicWrite(filePath, content, opts) {
122
+ const dir = join(filePath, '..');
123
+ const sync = opts.sync ?? fsyncSync;
124
+ mkdirSync(dir, { recursive: true });
125
+ const tmp = join(dir, `.${Math.random().toString(36).slice(2)}-${process.pid}-${Date.now()}.tmp`);
126
+ const fd = openSync(tmp, 'wx');
127
+ let failure;
128
+ try {
129
+ writeFileSync(fd, content);
130
+ sync(fd);
131
+ }
132
+ catch (error) {
133
+ failure = error;
134
+ }
135
+ try {
136
+ closeSync(fd);
137
+ }
138
+ catch (error) {
139
+ if (failure === undefined)
140
+ failure = error;
141
+ }
142
+ if (failure !== undefined) {
143
+ try {
144
+ unlinkSync(tmp);
145
+ }
146
+ catch {
147
+ // Preserve the original write or close failure.
148
+ }
149
+ throw failure;
150
+ }
151
+ try {
152
+ renameSync(tmp, filePath);
153
+ syncDirectory(dir, sync);
154
+ }
155
+ catch (err) {
156
+ try {
157
+ unlinkSync(tmp);
158
+ }
159
+ catch {
160
+ // best-effort cleanup
161
+ }
162
+ throw err;
163
+ }
164
+ }
165
+ /**
166
+ * Every valid record in `file`, oldest first. A missing/unreadable file reads as
167
+ * `[]`. A trailing newline is the record-commit marker: an unterminated final
168
+ * tail may be a concurrent writer still appending. File modification time starts
169
+ * the grace, so a recently modified tail is ignored silently while an already-old
170
+ * tail warns on the first read even in a fresh process. File identity, size, tail,
171
+ * or modification changes restart the observation; a newline clears it. Blank lines are
172
+ * skipped silently; every other unusable COMPLETE line is skipped and reported
173
+ * through `warn` with its 1-indexed line number. Never throws.
174
+ */
175
+ export function readSessions(file, opts = {}) {
176
+ const warn = opts.warn ?? defaultWarn;
177
+ let raw;
178
+ let metadata;
179
+ let fd;
180
+ try {
181
+ fd = openSync(file, 'r');
182
+ raw = readFileSync(fd, 'utf8');
183
+ const stat = fstatSync(fd);
184
+ metadata = {
185
+ identity: `${stat.dev}:${stat.ino}`,
186
+ size: stat.size,
187
+ mtimeMs: stat.mtimeMs,
188
+ };
189
+ }
190
+ catch {
191
+ tailObservations.delete(file);
192
+ return []; // fail-open: no store yet is the normal first-run case
193
+ }
194
+ finally {
195
+ if (fd !== undefined) {
196
+ try {
197
+ closeSync(fd);
198
+ }
199
+ catch {
200
+ // The bytes and metadata were already captured; a close failure cannot
201
+ // make a resumable record safer, so preserve the read path's fail-open stance.
202
+ }
203
+ }
204
+ }
205
+ const out = [];
206
+ const lines = raw.split('\n');
207
+ const hasUncommittedTail = raw !== '' && !raw.endsWith('\n');
208
+ if (!hasUncommittedTail) {
209
+ tailObservations.delete(file);
210
+ }
211
+ else {
212
+ const tail = lines.at(-1) ?? '';
213
+ if (tail.trim() === '') {
214
+ tailObservations.delete(file);
215
+ }
216
+ else {
217
+ const now = (opts.now ?? Date.now)();
218
+ const graceMs = opts.unterminatedTailGraceMs ?? DEFAULT_UNTERMINATED_TAIL_GRACE_MS;
219
+ const observed = tailObservations.get(file);
220
+ const sameObservation = observed !== undefined
221
+ && observed.identity === metadata.identity
222
+ && observed.size === metadata.size
223
+ && observed.mtimeMs === metadata.mtimeMs
224
+ && observed.tail === tail;
225
+ if (!sameObservation) {
226
+ // mtime is persisted by the filesystem, so an abandoned tail can be
227
+ // recognized on the first read of a fresh one-shot process. Clamp a
228
+ // future timestamp to `now` for clock skew and injected test clocks.
229
+ const firstSeenAt = Math.min(now, metadata.mtimeMs);
230
+ const next = {
231
+ ...metadata,
232
+ tail,
233
+ firstSeenAt,
234
+ warned: false,
235
+ };
236
+ tailObservations.set(file, next);
237
+ if (now - firstSeenAt >= graceMs) {
238
+ warn(`owenloop work sessions: persistent unterminated record at ${file}:${lines.length}`);
239
+ next.warned = true;
240
+ }
241
+ }
242
+ else if (observed !== undefined && !observed.warned && now - observed.firstSeenAt >= graceMs) {
243
+ warn(`owenloop work sessions: persistent unterminated record at ${file}:${lines.length}`);
244
+ observed.warned = true;
245
+ }
246
+ }
247
+ }
248
+ for (let i = 0; i < lines.length; i++) {
249
+ const line = lines[i];
250
+ if (line === undefined)
251
+ continue; // noUncheckedIndexedAccess
252
+ if (hasUncommittedTail && i === lines.length - 1)
253
+ continue;
254
+ if (line.trim() === '')
255
+ continue; // blank lines are not corruption
256
+ let parsed;
257
+ try {
258
+ parsed = JSON.parse(line);
259
+ }
260
+ catch {
261
+ warn(`owenloop work sessions: skipping corrupt record at ${file}:${i + 1}`);
262
+ continue;
263
+ }
264
+ if (!isSessionRecord(parsed)) {
265
+ warn(`owenloop work sessions: skipping corrupt record at ${file}:${i + 1}`);
266
+ continue;
267
+ }
268
+ out.push(parsed);
269
+ }
270
+ return out;
271
+ }
272
+ /**
273
+ * The newest record for `(workflow, run, step)`, or `null` when the file is
274
+ * missing or holds no match. Scans forward and keeps the LAST match (last-wins).
275
+ * Side-effect-free — it never writes, never compacts, and never throws.
276
+ */
277
+ export function latestFor(file, workflow, run, step) {
278
+ const want = keyOf(workflow, run, step);
279
+ let best = null;
280
+ for (const rec of readSessions(file)) {
281
+ if (keyOf(rec.workflow, rec.run, rec.step) === want)
282
+ best = rec;
283
+ }
284
+ return best;
285
+ }
286
+ /** The lock shared by append and compaction for one session log. */
287
+ function writerLockPath(file) {
288
+ return `${file}.lock`;
289
+ }
290
+ /** Run one complete writer transaction under the cross-process session lock. */
291
+ function withWriterLock(file, operation) {
292
+ const lock = acquireFileLockSync(writerLockPath(file), {
293
+ waitMs: 30_000,
294
+ label: 'owenloop session-store write',
295
+ });
296
+ try {
297
+ return operation();
298
+ }
299
+ finally {
300
+ releaseFileLock(lock);
301
+ }
302
+ }
303
+ /** True when an existing nonempty log does not end at a JSONL commit marker. */
304
+ function needsRecordSeparator(file) {
305
+ const stat = statSync(file, { throwIfNoEntry: false });
306
+ if (stat === undefined || stat.size === 0)
307
+ return false;
308
+ const fd = openSync(file, 'r');
309
+ try {
310
+ const last = Buffer.allocUnsafe(1);
311
+ const read = readSync(fd, last, 0, 1, stat.size - 1);
312
+ return read !== 1 || last[0] !== 0x0a;
313
+ }
314
+ finally {
315
+ closeSync(fd);
316
+ }
317
+ }
318
+ /** Lock must already be held by the caller. */
319
+ function compactUnlocked(file, opts) {
320
+ const records = readSessions(file, opts);
321
+ if (records.length === 0)
322
+ return;
323
+ const byKey = new Map();
324
+ for (const rec of records) {
325
+ // Map preserves first-insertion order across re-set, which is exactly the
326
+ // first-seen key order we want to keep.
327
+ byKey.set(keyOf(rec.workflow, rec.run, rec.step), rec);
328
+ }
329
+ const body = [...byKey.values()].map((r) => JSON.stringify(r)).join('\n');
330
+ atomicWrite(file, `${body}\n`, opts);
331
+ }
332
+ /** Lock must already be held. Append exactly one committed JSONL row.
333
+ * `active` is fsynced before returning because provider work is gated on this
334
+ * call. Later statuses use ordinary close-to-flush durability. */
335
+ function appendSessionUnlocked(file, rec, opts) {
336
+ const separator = needsRecordSeparator(file) ? '\n' : '';
337
+ const existed = statSync(file, { throwIfNoEntry: false }) !== undefined;
338
+ const fd = openSync(file, 'a');
339
+ let failure;
340
+ try {
341
+ writeFileSync(fd, `${separator}${JSON.stringify(rec)}\n`);
342
+ if (rec.status === 'active') {
343
+ const sync = opts.sync ?? fsyncSync;
344
+ sync(fd);
345
+ if (!existed)
346
+ syncDirectory(join(file, '..'), sync);
347
+ }
348
+ }
349
+ catch (error) {
350
+ failure = error;
351
+ }
352
+ try {
353
+ closeSync(fd);
354
+ }
355
+ catch (error) {
356
+ if (failure === undefined)
357
+ failure = error;
358
+ }
359
+ if (failure !== undefined)
360
+ throw failure;
361
+ }
362
+ /** Lock must already be held. Compaction remains best-effort after committed JSONL appends. */
363
+ function compactIfNeededUnlocked(file, opts) {
364
+ const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
365
+ try {
366
+ if (statSync(file).size > maxBytes)
367
+ compactUnlocked(file, opts);
368
+ }
369
+ catch {
370
+ // An un-compacted (or unstatable) file still contains the committed rows.
371
+ }
372
+ }
373
+ /**
374
+ * Rewrite `file` with only the last record per `(workflow, run, step)`,
375
+ * preserving FIRST-SEEN key order, via temp file + rename. Corrupt lines are
376
+ * dropped in the process (they were already unreadable). A missing file is a
377
+ * no-op. The complete read/rewrite/rename transaction shares the same lock as
378
+ * append, so a successful append cannot be replaced by this snapshot.
379
+ */
380
+ export function compact(file, opts = {}) {
381
+ withWriterLock(file, () => compactUnlocked(file, opts));
382
+ }
383
+ /**
384
+ * PHASE 4 — retire every session of one RUN by appending a `dead` row per step.
385
+ *
386
+ * THE INVARIANT IT ENFORCES: session lifetime equals cwd lifetime. When the
387
+ * per-run work directory is removed, the work those sessions were revising is
388
+ * gone, so resuming into a freshly recreated (and empty) directory at the same
389
+ * path would hand the agent a conversation about files that no longer exist. The
390
+ * `prev.status !== 'dead'` precondition in `src/agent/loop.ts` is what refuses
391
+ * the resume; this function is what makes the status say `dead`.
392
+ *
393
+ * WHY A NEW ROW RATHER THAN A REWRITE: the store is append-only and last-wins per
394
+ * `(workflow, run, step)`, so appending a copy with `status: 'dead'` shadows the
395
+ * live row without rewriting history. The shared writer lock serializes each
396
+ * appended retirement with append/compaction transactions from other processes.
397
+ *
398
+ * IDEMPOTENT: a key whose newest row is already `dead` is skipped, so a sweep
399
+ * that reaps the same run twice appends nothing the second time.
400
+ *
401
+ * SCOPE: the newest row per `(workflow, run, step)` for the given run, across
402
+ * EVERY step of that run — the work directory is per-run, so every step's session
403
+ * lived in it.
404
+ *
405
+ * FAILURE STANCE: `appendSession` PROPAGATES (see the header), and so does this.
406
+ * The caller — the work-directory reaper — must be able to see the failure,
407
+ * because retiring the sessions is a precondition of removing the directory, not
408
+ * a side note.
409
+ *
410
+ * Returns the step names actually marked, so a sweep can log a count.
411
+ */
412
+ export function markRunSessionsDead(file, workflow, run, now, opts = {}) {
413
+ mkdirSync(join(file, '..'), { recursive: true });
414
+ return withWriterLock(file, () => {
415
+ const newest = new Map();
416
+ for (const rec of readSessions(file, opts)) {
417
+ if (rec.workflow !== workflow || rec.run !== run)
418
+ continue;
419
+ newest.set(keyOf(rec.workflow, rec.run, rec.step), rec);
420
+ }
421
+ opts.afterWriterSnapshot?.();
422
+ const marked = [];
423
+ for (const rec of newest.values()) {
424
+ if (rec.status === 'dead')
425
+ continue; // already retired — nothing to append
426
+ appendSessionUnlocked(file, { ...rec, status: 'dead', updatedAt: now }, opts);
427
+ marked.push(rec.step);
428
+ }
429
+ if (marked.length > 0)
430
+ compactIfNeededUnlocked(file, opts);
431
+ return marked;
432
+ });
433
+ }
434
+ /**
435
+ * PHASE 6, ITEM 4 — retire the `active` sessions of runs that are no longer
436
+ * running, so a crash or a reboot does not leave the store claiming a turn is in
437
+ * flight when no process exists.
438
+ *
439
+ * WHAT IS BROKEN WITHOUT THIS. `src/agent/loop.ts` writes `status: 'active'` when
440
+ * a turn starts and rewrites it at turn end. A worker killed mid-turn — SIGKILL,
441
+ * a panic, a reboot — never reaches the rewrite, so the newest row for that step
442
+ * says `active` forever. Nothing else ever corrects it.
443
+ *
444
+ * ── WHY THIS IS NOT `markRunSessionsDead` ────────────────────────────────────
445
+ *
446
+ * `markRunSessionsDead` retires EVERY non-`dead` newest row of a run. Reusing it
447
+ * here would destroy exactly the capability this phase has to keep working:
448
+ * `src/agent/loop.ts` refuses to resume a session whose previous status is
449
+ * `dead`, and a `turn-ended` or `submitted` row is a COMPLETED turn whose
450
+ * provider-side session is intact. A reboot does not invalidate one. Leaving
451
+ * those rows alone is precisely what "resume still works after a reboot" means.
452
+ *
453
+ * So ONLY `active` rows are eligible, and only for runs absent from
454
+ * `liveRunIds`.
455
+ *
456
+ * ── WHY RETIRING AN ORPHANED `active` ROW IS THE RIGHT DIRECTION TO BE WRONG ──
457
+ *
458
+ * An interrupted turn is the state you least want to resume into: the harness may
459
+ * have half-applied tool calls the worker has no record of, so a resumed session
460
+ * would carry a model that believes work happened which did not. The cost of
461
+ * retiring it is one cold replay. The cost of resuming it is silent divergence.
462
+ *
463
+ * ── KNOWN FALSE POSITIVE, STATED RATHER THAN ENGINEERED AROUND ───────────────
464
+ *
465
+ * An `owenloop work agent-run` started BY HAND, outside the shift, has no child record
466
+ * in the shift state dir, so a shift booting at that moment sees its `active` row
467
+ * as orphaned and retires it. The cost is one cold replay on a hand-run debugging
468
+ * session. Two things keep it small: the caller invokes this at BOOT only, which
469
+ * narrows the window to an instant, and every retirement is returned so the
470
+ * caller can log it with its `(workflow, run, step)`. Do NOT add a pid field to
471
+ * `SessionRecord` to close this — the record is deliberately machine-portable
472
+ * metadata, and the shift state dir is already the system of record for liveness.
473
+ *
474
+ * IDEMPOTENT: the rows it appends are `dead`, so a second call finds nothing
475
+ * `active` left and appends nothing.
476
+ *
477
+ * FAILURE STANCE: `appendSession` propagates, and so does this — same as
478
+ * `markRunSessionsDead`.
479
+ *
480
+ * @param liveRunIds run ids with a live `agent-run` child RIGHT NOW. A run in
481
+ * this set is skipped whatever its status.
482
+ * @returns the records that were retired, as they were BEFORE retirement, so the
483
+ * caller can log what it took away.
484
+ */
485
+ export function reconcileActiveSessions(file, liveRunIds, now, opts = {}) {
486
+ mkdirSync(join(file, '..'), { recursive: true });
487
+ return withWriterLock(file, () => {
488
+ const newest = new Map();
489
+ for (const rec of readSessions(file, opts)) {
490
+ newest.set(keyOf(rec.workflow, rec.run, rec.step), rec);
491
+ }
492
+ opts.afterWriterSnapshot?.();
493
+ const retired = [];
494
+ for (const rec of newest.values()) {
495
+ if (rec.status !== 'active')
496
+ continue; // a completed turn is still resumable
497
+ if (liveRunIds.has(rec.run))
498
+ continue; // its worker is alive; the row is true
499
+ appendSessionUnlocked(file, { ...rec, status: 'dead', updatedAt: now }, opts);
500
+ retired.push(rec);
501
+ }
502
+ if (retired.length > 0)
503
+ compactIfNeededUnlocked(file, opts);
504
+ return retired;
505
+ });
506
+ }
507
+ /**
508
+ * Append one record, then compact when the file has grown past `maxBytes`.
509
+ *
510
+ * The cross-process writer lock covers the WHOLE transaction: abandoned-tail
511
+ * quarantine, append, size check, and optional compaction rename. If a crashed
512
+ * writer left bytes without the JSONL commit newline, a leading newline commits
513
+ * only that fragment as corrupt before the new complete record. Append and lock
514
+ * failures PROPAGATE; post-append compaction remains best-effort because the
515
+ * appended line is already committed by its trailing JSONL newline in the original log.
516
+ */
517
+ export function appendSession(file, rec, opts = {}) {
518
+ mkdirSync(join(file, '..'), { recursive: true });
519
+ withWriterLock(file, () => {
520
+ appendSessionUnlocked(file, rec, opts);
521
+ compactIfNeededUnlocked(file, opts);
522
+ });
523
+ }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Neutral harness-side types that are NOT part of the runtime session contract.
3
+ *
4
+ * `contract.ts` holds the things a running session needs (`StartArgs`,
5
+ * `AgentEvent`, `HarnessSessionRef`, `StepPermissions`). This file holds the
6
+ * things a harness declares ABOUT step definitions — today just `LintFinding`,
7
+ * the shape `owenloop work lint` prints.
8
+ *
9
+ * ISOLATION RULE applies here exactly as it does to every other file under
10
+ * `src/harness/`: no vendor name in this file, comments included. The adapter
11
+ * modules are the only allowlisted exceptions, and the allowlist lives in
12
+ * `test/harness-isolation.test.ts`, not here.
13
+ */
14
+ /**
15
+ * One finding from linting a single step's harness option bag (`x.harness`).
16
+ *
17
+ * `field` is the bag key the finding anchors to (`model`, `maxTurns`, …) and is
18
+ * absent when the finding is about the bag as a whole. The caller renders the
19
+ * location — `src/roles/lint.ts` prints `x.harness.<field>` — so a finding
20
+ * carries the field NAME and never a rendered path.
21
+ */
22
+ export interface LintFinding {
23
+ severity: 'error' | 'warning';
24
+ /** The step the finding is about. */
25
+ step: string;
26
+ /** The bag field it anchors to, when applicable (e.g. `model`, `maxTurns`). */
27
+ field?: string;
28
+ message: string;
29
+ }
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Neutral harness-side types that are NOT part of the runtime session contract.
3
+ *
4
+ * `contract.ts` holds the things a running session needs (`StartArgs`,
5
+ * `AgentEvent`, `HarnessSessionRef`, `StepPermissions`). This file holds the
6
+ * things a harness declares ABOUT step definitions — today just `LintFinding`,
7
+ * the shape `owenloop work lint` prints.
8
+ *
9
+ * ISOLATION RULE applies here exactly as it does to every other file under
10
+ * `src/harness/`: no vendor name in this file, comments included. The adapter
11
+ * modules are the only allowlisted exceptions, and the allowlist lives in
12
+ * `test/harness-isolation.test.ts`, not here.
13
+ */
14
+ export {};
@@ -0,0 +1,38 @@
1
+ /**
2
+ * THE composition root for the harness registry — the one file in `src/` that
3
+ * names the adapter modules, and the only file that decides which adapter is the
4
+ * default.
5
+ *
6
+ * WHY THIS FILE EXISTS. `src/harness/registry.ts` starts empty and deliberately
7
+ * forbids a barrel, so somebody has to import each adapter module for its
8
+ * `register(...)` side effect to fire. Through Phase 5 that somebody was TWO
9
+ * files — `src/roles/agent-run.ts` and `src/roles/lint.ts` — each carrying the
10
+ * same import pair, kept in the same order BY HAND. Phase 6 collapsed them into
11
+ * this module for two reasons:
12
+ *
13
+ * 1. ORDER IS LOAD-BEARING AND MUST HAVE ONE OWNER. `defaultHarnessId()`
14
+ * returns `registeredHarnessIds()[0]`, i.e. whichever adapter registered
15
+ * first. Two roots meant two places that had to agree, and a reorder in one
16
+ * of them would silently change which harness runs a step that names none.
17
+ * One file, one order, and `test/vendor-gate.test.ts` asserts the resulting
18
+ * default explicitly so an accidental reorder fails a test.
19
+ * 2. IT KEEPS THE VENDOR-NAMING SURFACE SMALL. `test/vendor-gate.test.ts`
20
+ * allowlists the files under `src/`/`bin/` that may name a harness vendor.
21
+ * Consolidating drops that allowlist from five entries to four.
22
+ *
23
+ * SAFE BY ESM SEMANTICS: module evaluation is cached, so each adapter's
24
+ * `register(...)` fires exactly once no matter how many modules import this one.
25
+ *
26
+ * IMPORT ORDER — DO NOT SORT THIS BLOCK. The FIRST id registered is the default
27
+ * harness. `claude.ts` is first and `claude-code` is therefore the default; that
28
+ * matches the pre-consolidation order in `src/roles/agent-run.ts` and is pinned
29
+ * by a test.
30
+ *
31
+ * Importers: `src/roles/agent-run.ts` (the worker), `src/roles/lint.ts` (lint
32
+ * judges a harness-less step by the SAME default that will run it), and
33
+ * `src/roles/sessions.ts` (it maps a recorded harness id to that adapter's
34
+ * resume command). A new caller of `adapterFor` / `defaultHarnessId` imports
35
+ * THIS module — it does not add adapter imports of its own.
36
+ */
37
+ import './harness/claude.ts';
38
+ import './harness/codex.ts';
@@ -0,0 +1,38 @@
1
+ /**
2
+ * THE composition root for the harness registry — the one file in `src/` that
3
+ * names the adapter modules, and the only file that decides which adapter is the
4
+ * default.
5
+ *
6
+ * WHY THIS FILE EXISTS. `src/harness/registry.ts` starts empty and deliberately
7
+ * forbids a barrel, so somebody has to import each adapter module for its
8
+ * `register(...)` side effect to fire. Through Phase 5 that somebody was TWO
9
+ * files — `src/roles/agent-run.ts` and `src/roles/lint.ts` — each carrying the
10
+ * same import pair, kept in the same order BY HAND. Phase 6 collapsed them into
11
+ * this module for two reasons:
12
+ *
13
+ * 1. ORDER IS LOAD-BEARING AND MUST HAVE ONE OWNER. `defaultHarnessId()`
14
+ * returns `registeredHarnessIds()[0]`, i.e. whichever adapter registered
15
+ * first. Two roots meant two places that had to agree, and a reorder in one
16
+ * of them would silently change which harness runs a step that names none.
17
+ * One file, one order, and `test/vendor-gate.test.ts` asserts the resulting
18
+ * default explicitly so an accidental reorder fails a test.
19
+ * 2. IT KEEPS THE VENDOR-NAMING SURFACE SMALL. `test/vendor-gate.test.ts`
20
+ * allowlists the files under `src/`/`bin/` that may name a harness vendor.
21
+ * Consolidating drops that allowlist from five entries to four.
22
+ *
23
+ * SAFE BY ESM SEMANTICS: module evaluation is cached, so each adapter's
24
+ * `register(...)` fires exactly once no matter how many modules import this one.
25
+ *
26
+ * IMPORT ORDER — DO NOT SORT THIS BLOCK. The FIRST id registered is the default
27
+ * harness. `claude.ts` is first and `claude-code` is therefore the default; that
28
+ * matches the pre-consolidation order in `src/roles/agent-run.ts` and is pinned
29
+ * by a test.
30
+ *
31
+ * Importers: `src/roles/agent-run.ts` (the worker), `src/roles/lint.ts` (lint
32
+ * judges a harness-less step by the SAME default that will run it), and
33
+ * `src/roles/sessions.ts` (it maps a recorded harness id to that adapter's
34
+ * resume command). A new caller of `adapterFor` / `defaultHarnessId` imports
35
+ * THIS module — it does not add adapter imports of its own.
36
+ */
37
+ import "./harness/claude.js";
38
+ import "./harness/codex.js";
@@ -0,0 +1,36 @@
1
+ /**
2
+ * The `hold` loop (C4) — keeps one order's lease alive on behalf of an
3
+ * interactive session, and performs the final-breath handoff on shutdown.
4
+ *
5
+ * The cadence/backoff/clock-jump/final-breath CORE moved to `src/lease/loop.ts`
6
+ * in C5 (plan decision 4) so `hold` and the self-leasing `exec` share ONE
7
+ * implementation. This module is now a thin adapter: it fixes the role prefix to
8
+ * `'hold'` (so every emitted message string is byte-identical to C4) and
9
+ * re-exports the loop's public surface under the hold names its callers and
10
+ * tests already import. `hold` never reads the order packet, so it omits
11
+ * `onOrder`; its `stop(reason?)` always releases (the session died — hand the
12
+ * order back).
13
+ *
14
+ * See `src/lease/loop.ts` for the full lifecycle documentation.
15
+ */
16
+ import { type LeaseLoopOptions, type LeaseOutcome, type StopOptions } from '../lease/loop.ts';
17
+ /** The hold run's outcome — the lease outcome under the hold name. */
18
+ export type HoldOutcome = LeaseOutcome;
19
+ /**
20
+ * hold's options are the lease options minus the one internal it fixes (`role`).
21
+ * `onOrder` stays available: the CLI `hold` never wires it (it doesn't read the
22
+ * packet), but the D2 `hold --mcp` mount does — its `get_order` tool returns the
23
+ * order packet the loop's first contact already fetched.
24
+ */
25
+ export type HoldLoopOptions = Omit<LeaseLoopOptions, 'role'>;
26
+ export interface HoldLoop {
27
+ run(): Promise<HoldOutcome>;
28
+ /**
29
+ * Stop the loop. `stopOpts.release:false` skips the final-breath release — the
30
+ * `hold --mcp` submit tool passes it once a submit CLOSES the run (the claim is
31
+ * already gone, so releasing would be a confusing no-op). The CLI hold's signal
32
+ * path passes no opts, so it still releases (the session died — hand it back).
33
+ */
34
+ stop(reason?: string, stopOpts?: StopOptions): void;
35
+ }
36
+ export declare function createHoldLoop(opts: HoldLoopOptions): HoldLoop;