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,45 @@
1
+ /** Module-level, process-wide. One registry per process is the intent. */
2
+ const ADAPTERS = new Map();
3
+ /**
4
+ * Register an adapter under its own `id`. Throws when that id is already taken
5
+ * — two adapters claiming one id is a wiring bug, and silently letting the
6
+ * second win would route work to whichever module happened to import last.
7
+ */
8
+ export function register(adapter) {
9
+ const existing = ADAPTERS.get(adapter.id);
10
+ if (existing !== undefined) {
11
+ throw new Error(`harness adapter '${adapter.id}' is already registered`);
12
+ }
13
+ ADAPTERS.set(adapter.id, adapter);
14
+ }
15
+ /**
16
+ * Remove an adapter by id; returns whether one was there. Exists so a test that
17
+ * registers a fake can clean up in `afterEach` — production code has no reason
18
+ * to unregister.
19
+ */
20
+ export function unregister(id) {
21
+ return ADAPTERS.delete(id);
22
+ }
23
+ /** The adapter registered under `id`, or `undefined` when none is. */
24
+ export function adapterFor(id) {
25
+ return ADAPTERS.get(id);
26
+ }
27
+ /** Every registered adapter id, in registration order. */
28
+ export function registeredHarnessIds() {
29
+ return [...ADAPTERS.keys()];
30
+ }
31
+ /**
32
+ * The built-in default harness id: the FIRST id in the registry, i.e. the first
33
+ * adapter module a composition root imported.
34
+ *
35
+ * Deliberately not a hardcoded literal. A literal default would be a harness
36
+ * VENDOR NAME in neutral code, which the isolation rule forbids outright — and
37
+ * this file is under `src/harness/`, where the rule is enforced by grep. The
38
+ * import-order rule gives the same behavior without the string.
39
+ *
40
+ * Returns `undefined` when nothing is registered; the caller then fails honestly
41
+ * (`'no-harness'`) rather than guessing.
42
+ */
43
+ export function defaultHarnessId() {
44
+ return registeredHarnessIds()[0];
45
+ }
@@ -0,0 +1,181 @@
1
+ /** Where a step attempt is in its life. */
2
+ export type SessionStatus = 'active' | 'turn-ended' | 'submitted' | 'dead';
3
+ /** One line of `sessions.jsonl`. */
4
+ export interface SessionRecord {
5
+ workflow: string;
6
+ run: string;
7
+ step: string;
8
+ /** The composite `<workflow>/<run>` order id — the same string `hold --order`
9
+ * takes. Redundant with `workflow` + `run` by construction; kept because the
10
+ * contract lists it and Phase 6's `owenloop work sessions` display prints it.
11
+ * ALWAYS build it with `orderId()` so the two can never drift. */
12
+ order: string;
13
+ attempt: number;
14
+ /** Adapter id (`HarnessSessionRef.harness`). */
15
+ harness: string;
16
+ /** Provider-native session token (`HarnessSessionRef.token`). Machine-local. */
17
+ token: string;
18
+ cwd: string;
19
+ status: SessionStatus;
20
+ createdAt: number;
21
+ /**
22
+ * PHASE 4 — the reason watermark: the `at` of the NEWEST `ReasonEntry` already
23
+ * delivered into this session, by either a resume or a cold replay.
24
+ *
25
+ * The next re-offer filters `OrderPacket.owes[].reasons` to `at > this` and
26
+ * delivers only what is left, which is what makes a rejection cost a short
27
+ * delta instead of a whole brief.
28
+ *
29
+ * BACKWARD-COMPATIBLE BY CONSTRUCTION, no version bump and no migration:
30
+ * `isSessionRecord` validates only `workflow/run/step/harness/token/status` and
31
+ * carries every other field verbatim, so a record written before Phase 4 simply
32
+ * has no watermark. Absent reads as "nothing delivered yet", which makes the
33
+ * first resume after an upgrade deliver every reason — the safe direction to be
34
+ * wrong, since the alternative would silently swallow feedback.
35
+ *
36
+ * NOT part of the record key. The key stays `(workflow, run, step)` and
37
+ * `attempt` stays outside it, per Phase 1.
38
+ */
39
+ deliveredReasonAt?: number;
40
+ updatedAt: number;
41
+ }
42
+ export interface SessionStoreOptions {
43
+ /** Called once per skipped corrupt line. Default writes to stderr. */
44
+ warn?: (line: string) => void;
45
+ /** Test barrier invoked under the writer lock after a retirement snapshot. */
46
+ afterWriterSnapshot?: () => void;
47
+ /** Compaction threshold in bytes, checked after each append. Default 2 MB. */
48
+ maxBytes?: number;
49
+ /** Clock used to detect an abandoned unterminated tail. Default `Date.now`. */
50
+ now?: () => number;
51
+ /** Unchanged-tail grace before one warning is emitted. Default 5 seconds. */
52
+ unterminatedTailGraceMs?: number;
53
+ /** Injectable durability primitive for focused tests. Default `fsyncSync`. */
54
+ sync?: (fd: number) => void;
55
+ }
56
+ /** Default compaction threshold — plan §3's 2 MB. */
57
+ export declare const DEFAULT_MAX_BYTES = 2000000;
58
+ /** Grace for a concurrent writer to finish an unterminated JSONL append. */
59
+ export declare const DEFAULT_UNTERMINATED_TAIL_GRACE_MS = 5000;
60
+ /** `<cacheDir>/sessions.jsonl`. */
61
+ export declare function sessionsPath(cacheDir: string): string;
62
+ /** The composite order id `<workflow>/<run>` — the one place it is built. */
63
+ export declare function orderId(workflow: string, run: string): string;
64
+ /**
65
+ * Every valid record in `file`, oldest first. A missing/unreadable file reads as
66
+ * `[]`. A trailing newline is the record-commit marker: an unterminated final
67
+ * tail may be a concurrent writer still appending. File modification time starts
68
+ * the grace, so a recently modified tail is ignored silently while an already-old
69
+ * tail warns on the first read even in a fresh process. File identity, size, tail,
70
+ * or modification changes restart the observation; a newline clears it. Blank lines are
71
+ * skipped silently; every other unusable COMPLETE line is skipped and reported
72
+ * through `warn` with its 1-indexed line number. Never throws.
73
+ */
74
+ export declare function readSessions(file: string, opts?: SessionStoreOptions): SessionRecord[];
75
+ /**
76
+ * The newest record for `(workflow, run, step)`, or `null` when the file is
77
+ * missing or holds no match. Scans forward and keeps the LAST match (last-wins).
78
+ * Side-effect-free — it never writes, never compacts, and never throws.
79
+ */
80
+ export declare function latestFor(file: string, workflow: string, run: string, step: string): SessionRecord | null;
81
+ /**
82
+ * Rewrite `file` with only the last record per `(workflow, run, step)`,
83
+ * preserving FIRST-SEEN key order, via temp file + rename. Corrupt lines are
84
+ * dropped in the process (they were already unreadable). A missing file is a
85
+ * no-op. The complete read/rewrite/rename transaction shares the same lock as
86
+ * append, so a successful append cannot be replaced by this snapshot.
87
+ */
88
+ export declare function compact(file: string, opts?: SessionStoreOptions): void;
89
+ /**
90
+ * PHASE 4 — retire every session of one RUN by appending a `dead` row per step.
91
+ *
92
+ * THE INVARIANT IT ENFORCES: session lifetime equals cwd lifetime. When the
93
+ * per-run work directory is removed, the work those sessions were revising is
94
+ * gone, so resuming into a freshly recreated (and empty) directory at the same
95
+ * path would hand the agent a conversation about files that no longer exist. The
96
+ * `prev.status !== 'dead'` precondition in `src/agent/loop.ts` is what refuses
97
+ * the resume; this function is what makes the status say `dead`.
98
+ *
99
+ * WHY A NEW ROW RATHER THAN A REWRITE: the store is append-only and last-wins per
100
+ * `(workflow, run, step)`, so appending a copy with `status: 'dead'` shadows the
101
+ * live row without rewriting history. The shared writer lock serializes each
102
+ * appended retirement with append/compaction transactions from other processes.
103
+ *
104
+ * IDEMPOTENT: a key whose newest row is already `dead` is skipped, so a sweep
105
+ * that reaps the same run twice appends nothing the second time.
106
+ *
107
+ * SCOPE: the newest row per `(workflow, run, step)` for the given run, across
108
+ * EVERY step of that run — the work directory is per-run, so every step's session
109
+ * lived in it.
110
+ *
111
+ * FAILURE STANCE: `appendSession` PROPAGATES (see the header), and so does this.
112
+ * The caller — the work-directory reaper — must be able to see the failure,
113
+ * because retiring the sessions is a precondition of removing the directory, not
114
+ * a side note.
115
+ *
116
+ * Returns the step names actually marked, so a sweep can log a count.
117
+ */
118
+ export declare function markRunSessionsDead(file: string, workflow: string, run: string, now: number, opts?: SessionStoreOptions): string[];
119
+ /**
120
+ * PHASE 6, ITEM 4 — retire the `active` sessions of runs that are no longer
121
+ * running, so a crash or a reboot does not leave the store claiming a turn is in
122
+ * flight when no process exists.
123
+ *
124
+ * WHAT IS BROKEN WITHOUT THIS. `src/agent/loop.ts` writes `status: 'active'` when
125
+ * a turn starts and rewrites it at turn end. A worker killed mid-turn — SIGKILL,
126
+ * a panic, a reboot — never reaches the rewrite, so the newest row for that step
127
+ * says `active` forever. Nothing else ever corrects it.
128
+ *
129
+ * ── WHY THIS IS NOT `markRunSessionsDead` ────────────────────────────────────
130
+ *
131
+ * `markRunSessionsDead` retires EVERY non-`dead` newest row of a run. Reusing it
132
+ * here would destroy exactly the capability this phase has to keep working:
133
+ * `src/agent/loop.ts` refuses to resume a session whose previous status is
134
+ * `dead`, and a `turn-ended` or `submitted` row is a COMPLETED turn whose
135
+ * provider-side session is intact. A reboot does not invalidate one. Leaving
136
+ * those rows alone is precisely what "resume still works after a reboot" means.
137
+ *
138
+ * So ONLY `active` rows are eligible, and only for runs absent from
139
+ * `liveRunIds`.
140
+ *
141
+ * ── WHY RETIRING AN ORPHANED `active` ROW IS THE RIGHT DIRECTION TO BE WRONG ──
142
+ *
143
+ * An interrupted turn is the state you least want to resume into: the harness may
144
+ * have half-applied tool calls the worker has no record of, so a resumed session
145
+ * would carry a model that believes work happened which did not. The cost of
146
+ * retiring it is one cold replay. The cost of resuming it is silent divergence.
147
+ *
148
+ * ── KNOWN FALSE POSITIVE, STATED RATHER THAN ENGINEERED AROUND ───────────────
149
+ *
150
+ * An `owenloop work agent-run` started BY HAND, outside the shift, has no child record
151
+ * in the shift state dir, so a shift booting at that moment sees its `active` row
152
+ * as orphaned and retires it. The cost is one cold replay on a hand-run debugging
153
+ * session. Two things keep it small: the caller invokes this at BOOT only, which
154
+ * narrows the window to an instant, and every retirement is returned so the
155
+ * caller can log it with its `(workflow, run, step)`. Do NOT add a pid field to
156
+ * `SessionRecord` to close this — the record is deliberately machine-portable
157
+ * metadata, and the shift state dir is already the system of record for liveness.
158
+ *
159
+ * IDEMPOTENT: the rows it appends are `dead`, so a second call finds nothing
160
+ * `active` left and appends nothing.
161
+ *
162
+ * FAILURE STANCE: `appendSession` propagates, and so does this — same as
163
+ * `markRunSessionsDead`.
164
+ *
165
+ * @param liveRunIds run ids with a live `agent-run` child RIGHT NOW. A run in
166
+ * this set is skipped whatever its status.
167
+ * @returns the records that were retired, as they were BEFORE retirement, so the
168
+ * caller can log what it took away.
169
+ */
170
+ export declare function reconcileActiveSessions(file: string, liveRunIds: ReadonlySet<string>, now: number, opts?: SessionStoreOptions): SessionRecord[];
171
+ /**
172
+ * Append one record, then compact when the file has grown past `maxBytes`.
173
+ *
174
+ * The cross-process writer lock covers the WHOLE transaction: abandoned-tail
175
+ * quarantine, append, size check, and optional compaction rename. If a crashed
176
+ * writer left bytes without the JSONL commit newline, a leading newline commits
177
+ * only that fragment as corrupt before the new complete record. Append and lock
178
+ * failures PROPAGATE; post-append compaction remains best-effort because the
179
+ * appended line is already committed by its trailing JSONL newline in the original log.
180
+ */
181
+ export declare function appendSession(file: string, rec: SessionRecord, opts?: SessionStoreOptions): void;