clinkx 1.1.2 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (309) hide show
  1. package/CHANGELOG.md +63 -0
  2. package/README.md +67 -14
  3. package/clinkx-workflows/dist/allowed-roots.js +2 -0
  4. package/clinkx-workflows/dist/allowed-roots.js.map +1 -1
  5. package/clinkx-workflows/dist/architecture-arena/admission.d.ts +16 -0
  6. package/clinkx-workflows/dist/architecture-arena/admission.js +107 -0
  7. package/clinkx-workflows/dist/architecture-arena/admission.js.map +1 -0
  8. package/clinkx-workflows/dist/architecture-arena/contract.d.ts +1368 -0
  9. package/clinkx-workflows/dist/architecture-arena/contract.js +254 -0
  10. package/clinkx-workflows/dist/architecture-arena/contract.js.map +1 -0
  11. package/clinkx-workflows/dist/architecture-arena/runtime.d.ts +53 -0
  12. package/clinkx-workflows/dist/architecture-arena/runtime.js +511 -0
  13. package/clinkx-workflows/dist/architecture-arena/runtime.js.map +1 -0
  14. package/clinkx-workflows/dist/architecture-comparison/admission.d.ts +17 -1
  15. package/clinkx-workflows/dist/architecture-comparison/admission.js +27 -4
  16. package/clinkx-workflows/dist/architecture-comparison/admission.js.map +1 -1
  17. package/clinkx-workflows/dist/architecture-comparison/contract.d.ts +59 -62
  18. package/clinkx-workflows/dist/architecture-comparison/contract.js +4 -21
  19. package/clinkx-workflows/dist/architecture-comparison/contract.js.map +1 -1
  20. package/clinkx-workflows/dist/architecture-comparison/runtime.d.ts +4 -3
  21. package/clinkx-workflows/dist/architecture-comparison/runtime.js +22 -67
  22. package/clinkx-workflows/dist/architecture-comparison/runtime.js.map +1 -1
  23. package/clinkx-workflows/dist/artifacts.d.ts +19 -4
  24. package/clinkx-workflows/dist/artifacts.js +16 -7
  25. package/clinkx-workflows/dist/artifacts.js.map +1 -1
  26. package/clinkx-workflows/dist/backend.d.ts +30 -0
  27. package/clinkx-workflows/dist/child-env.d.ts +3 -1
  28. package/clinkx-workflows/dist/child-env.js +6 -2
  29. package/clinkx-workflows/dist/child-env.js.map +1 -1
  30. package/clinkx-workflows/dist/clink-client.d.ts +8 -2
  31. package/clinkx-workflows/dist/clink-client.js +4 -2
  32. package/clinkx-workflows/dist/clink-client.js.map +1 -1
  33. package/clinkx-workflows/dist/config.d.ts +28 -5
  34. package/clinkx-workflows/dist/config.js +137 -20
  35. package/clinkx-workflows/dist/config.js.map +1 -1
  36. package/clinkx-workflows/dist/contained-file.js +9 -0
  37. package/clinkx-workflows/dist/contained-file.js.map +1 -1
  38. package/clinkx-workflows/dist/context-preflight.d.ts +6 -0
  39. package/clinkx-workflows/dist/context-preflight.js.map +1 -1
  40. package/clinkx-workflows/dist/council-execution-policy.d.ts +3 -1
  41. package/clinkx-workflows/dist/council-execution-policy.js +4 -0
  42. package/clinkx-workflows/dist/council-execution-policy.js.map +1 -1
  43. package/clinkx-workflows/dist/dashboard/contracts.d.ts +586 -586
  44. package/clinkx-workflows/dist/dashboard/progress-report-contract.d.ts +28 -28
  45. package/clinkx-workflows/dist/dashboard/session-log-contract.d.ts +32 -32
  46. package/clinkx-workflows/dist/dashboard/session-log-identity.js +2 -1
  47. package/clinkx-workflows/dist/dashboard/session-log-identity.js.map +1 -1
  48. package/clinkx-workflows/dist/dashboard-ui/assets/index-DRId2DVA.js +119 -0
  49. package/clinkx-workflows/dist/dashboard-ui/assets/style-CHAw57y5.css +1 -0
  50. package/clinkx-workflows/dist/dashboard-ui/index.html +2 -2
  51. package/clinkx-workflows/dist/delegate-signature.d.ts +4 -3
  52. package/clinkx-workflows/dist/delegate-signature.js +4 -3
  53. package/clinkx-workflows/dist/delegate-signature.js.map +1 -1
  54. package/clinkx-workflows/dist/durable-file.d.ts +69 -0
  55. package/clinkx-workflows/dist/durable-file.js +145 -0
  56. package/clinkx-workflows/dist/durable-file.js.map +1 -0
  57. package/clinkx-workflows/dist/engine.d.ts +42 -7
  58. package/clinkx-workflows/dist/engine.js +196 -24
  59. package/clinkx-workflows/dist/engine.js.map +1 -1
  60. package/clinkx-workflows/dist/ping-pong/admission.d.ts +127 -0
  61. package/clinkx-workflows/dist/ping-pong/admission.js +522 -0
  62. package/clinkx-workflows/dist/ping-pong/admission.js.map +1 -0
  63. package/clinkx-workflows/dist/ping-pong/contract.d.ts +2539 -0
  64. package/clinkx-workflows/dist/ping-pong/contract.js +819 -0
  65. package/clinkx-workflows/dist/ping-pong/contract.js.map +1 -0
  66. package/clinkx-workflows/dist/ping-pong/control.d.ts +67 -0
  67. package/clinkx-workflows/dist/ping-pong/control.js +12 -0
  68. package/clinkx-workflows/dist/ping-pong/control.js.map +1 -0
  69. package/clinkx-workflows/dist/ping-pong/runtime-handle.d.ts +24 -0
  70. package/clinkx-workflows/dist/ping-pong/runtime-handle.js +55 -0
  71. package/clinkx-workflows/dist/ping-pong/runtime-handle.js.map +1 -0
  72. package/clinkx-workflows/dist/ping-pong/runtime.d.ts +235 -0
  73. package/clinkx-workflows/dist/ping-pong/runtime.js +1183 -0
  74. package/clinkx-workflows/dist/ping-pong/runtime.js.map +1 -0
  75. package/clinkx-workflows/dist/ping-pong/settle.d.ts +57 -0
  76. package/clinkx-workflows/dist/ping-pong/settle.js +58 -0
  77. package/clinkx-workflows/dist/ping-pong/settle.js.map +1 -0
  78. package/clinkx-workflows/dist/ping-pong/sidecar.d.ts +65 -0
  79. package/clinkx-workflows/dist/ping-pong/sidecar.js +138 -0
  80. package/clinkx-workflows/dist/ping-pong/sidecar.js.map +1 -0
  81. package/clinkx-workflows/dist/plan-review/publication.d.ts +2 -1
  82. package/clinkx-workflows/dist/plan-review/publication.js +5 -6
  83. package/clinkx-workflows/dist/plan-review/publication.js.map +1 -1
  84. package/clinkx-workflows/dist/plan-review/snapshot.d.ts +3 -2
  85. package/clinkx-workflows/dist/plan-review/snapshot.js +8 -8
  86. package/clinkx-workflows/dist/plan-review/snapshot.js.map +1 -1
  87. package/clinkx-workflows/dist/recipe-host.d.ts +315 -0
  88. package/clinkx-workflows/dist/recipe-host.js +183 -0
  89. package/clinkx-workflows/dist/recipe-host.js.map +1 -0
  90. package/clinkx-workflows/dist/recipe-seats.d.ts +96 -0
  91. package/clinkx-workflows/dist/recipe-seats.js +163 -0
  92. package/clinkx-workflows/dist/recipe-seats.js.map +1 -0
  93. package/clinkx-workflows/dist/recipe-shared/evidence.d.ts +67 -0
  94. package/clinkx-workflows/dist/recipe-shared/evidence.js +111 -0
  95. package/clinkx-workflows/dist/recipe-shared/evidence.js.map +1 -0
  96. package/clinkx-workflows/dist/reducers/index.d.ts +9 -1
  97. package/clinkx-workflows/dist/reducers/index.js +30 -0
  98. package/clinkx-workflows/dist/reducers/index.js.map +1 -1
  99. package/clinkx-workflows/dist/root-path-validation.d.ts +12 -0
  100. package/clinkx-workflows/dist/root-path-validation.js +63 -0
  101. package/clinkx-workflows/dist/root-path-validation.js.map +1 -0
  102. package/clinkx-workflows/dist/rosters.d.ts +1 -0
  103. package/clinkx-workflows/dist/rosters.js +16 -6
  104. package/clinkx-workflows/dist/rosters.js.map +1 -1
  105. package/clinkx-workflows/dist/run-lock-reclaim.d.ts +44 -0
  106. package/clinkx-workflows/dist/run-lock-reclaim.js +86 -0
  107. package/clinkx-workflows/dist/run-lock-reclaim.js.map +1 -0
  108. package/clinkx-workflows/dist/server.js +5 -2
  109. package/clinkx-workflows/dist/server.js.map +1 -1
  110. package/clinkx-workflows/dist/state-schema.d.ts +24 -0
  111. package/clinkx-workflows/dist/state-schema.js +4 -1
  112. package/clinkx-workflows/dist/state-schema.js.map +1 -1
  113. package/clinkx-workflows/dist/state.d.ts +185 -4
  114. package/clinkx-workflows/dist/state.js +684 -88
  115. package/clinkx-workflows/dist/state.js.map +1 -1
  116. package/clinkx-workflows/dist/transport.d.ts +2 -1
  117. package/clinkx-workflows/dist/transport.js +5 -0
  118. package/clinkx-workflows/dist/transport.js.map +1 -1
  119. package/clinkx-workflows/dist/validators/architecture-arena.d.ts +6 -0
  120. package/clinkx-workflows/dist/validators/architecture-arena.js +16 -0
  121. package/clinkx-workflows/dist/validators/architecture-arena.js.map +1 -0
  122. package/clinkx-workflows/dist/validators/index.js +4 -0
  123. package/clinkx-workflows/dist/validators/index.js.map +1 -1
  124. package/clinkx-workflows/dist/validators/ping-pong.d.ts +6 -0
  125. package/clinkx-workflows/dist/validators/ping-pong.js +10 -0
  126. package/clinkx-workflows/dist/validators/ping-pong.js.map +1 -0
  127. package/clinkx-workflows/dist/workflow-completion.d.ts +83 -0
  128. package/clinkx-workflows/dist/workflow-completion.js +250 -0
  129. package/clinkx-workflows/dist/workflow-completion.js.map +1 -0
  130. package/clinkx-workflows/dist/workflow-tools.d.ts +53 -6
  131. package/clinkx-workflows/dist/workflow-tools.js +1123 -65
  132. package/clinkx-workflows/dist/workflow-tools.js.map +1 -1
  133. package/clinkx-workflows/dist/workflow-verification-contract.d.ts +4 -4
  134. package/clinkx-workflows/templates/architecture-arena/candidate.txt +39 -0
  135. package/clinkx-workflows/templates/architecture-arena/judge.txt +34 -0
  136. package/clinkx-workflows/templates/ping-pong/implement.txt +14 -0
  137. package/clinkx-workflows/templates/ping-pong/remediate.txt +14 -0
  138. package/clinkx-workflows/templates/ping-pong/review.txt +27 -0
  139. package/clinkx-workflows/workflows/architecture-arena.yaml +127 -0
  140. package/clinkx-workflows/workflows/ping-pong.yaml +158 -0
  141. package/dist/allowed-roots.d.ts +1 -1
  142. package/dist/allowed-roots.js +124 -14
  143. package/dist/allowed-roots.js.map +1 -1
  144. package/dist/context-builder/bundle.js +4 -3
  145. package/dist/context-builder/bundle.js.map +1 -1
  146. package/dist/context-builder/config.d.ts +1 -0
  147. package/dist/context-builder/config.js +21 -9
  148. package/dist/context-builder/config.js.map +1 -1
  149. package/dist/context-builder/delegate-packet.d.ts +1 -0
  150. package/dist/context-builder/delegate-packet.js +66 -7
  151. package/dist/context-builder/delegate-packet.js.map +1 -1
  152. package/dist/context-builder/delegate-validation.d.ts +12 -3
  153. package/dist/context-builder/delegate-validation.js +23 -13
  154. package/dist/context-builder/delegate-validation.js.map +1 -1
  155. package/dist/context-builder/external-gaps.d.ts +14 -3
  156. package/dist/context-builder/external-gaps.js +124 -18
  157. package/dist/context-builder/external-gaps.js.map +1 -1
  158. package/dist/context-builder/handler.js +108 -191
  159. package/dist/context-builder/handler.js.map +1 -1
  160. package/dist/context-builder/mutation-lock.d.ts +4 -0
  161. package/dist/context-builder/mutation-lock.js +7 -1
  162. package/dist/context-builder/mutation-lock.js.map +1 -1
  163. package/dist/context-builder/review-coverage.js +27 -1
  164. package/dist/context-builder/review-coverage.js.map +1 -1
  165. package/dist/context-builder/secrets.js +1 -1
  166. package/dist/context-builder/secrets.js.map +1 -1
  167. package/dist/context-builder/storage.d.ts +10 -2
  168. package/dist/context-builder/storage.js +213 -16
  169. package/dist/context-builder/storage.js.map +1 -1
  170. package/dist/context-builder/versions.d.ts +10 -4
  171. package/dist/context-builder/versions.js +10 -4
  172. package/dist/context-builder/versions.js.map +1 -1
  173. package/dist/context-builder/workflow-runner.js +33 -24
  174. package/dist/context-builder/workflow-runner.js.map +1 -1
  175. package/dist/dashboard-cli.d.ts +8 -0
  176. package/dist/dashboard-cli.js +155 -86
  177. package/dist/dashboard-cli.js.map +1 -1
  178. package/dist/dashboard-companion/client.d.ts +10 -0
  179. package/dist/dashboard-companion/client.js +43 -1
  180. package/dist/dashboard-companion/client.js.map +1 -1
  181. package/dist/dashboard-companion/config.d.ts +19 -1
  182. package/dist/dashboard-companion/config.js +104 -3
  183. package/dist/dashboard-companion/config.js.map +1 -1
  184. package/dist/dashboard-companion/protocol.d.ts +16 -0
  185. package/dist/dashboard-companion/protocol.js +38 -1
  186. package/dist/dashboard-companion/protocol.js.map +1 -1
  187. package/dist/dashboard-companion/workstation-binding.d.ts +69 -0
  188. package/dist/dashboard-companion/workstation-binding.js +192 -0
  189. package/dist/dashboard-companion/workstation-binding.js.map +1 -0
  190. package/dist/dashboard-gateway/admin-cli.d.ts +10 -0
  191. package/dist/dashboard-gateway/admin-cli.js +266 -0
  192. package/dist/dashboard-gateway/admin-cli.js.map +1 -0
  193. package/dist/dashboard-gateway/config.d.ts +50 -0
  194. package/dist/dashboard-gateway/config.js +235 -1
  195. package/dist/dashboard-gateway/config.js.map +1 -1
  196. package/dist/dashboard-gateway/connection-registry.d.ts +100 -0
  197. package/dist/dashboard-gateway/connection-registry.js +228 -0
  198. package/dist/dashboard-gateway/connection-registry.js.map +1 -0
  199. package/dist/dashboard-gateway/control-plane/account-auth.d.ts +78 -0
  200. package/dist/dashboard-gateway/control-plane/account-auth.js +198 -0
  201. package/dist/dashboard-gateway/control-plane/account-auth.js.map +1 -0
  202. package/dist/dashboard-gateway/control-plane/billing.d.ts +264 -0
  203. package/dist/dashboard-gateway/control-plane/billing.js +787 -0
  204. package/dist/dashboard-gateway/control-plane/billing.js.map +1 -0
  205. package/dist/dashboard-gateway/control-plane/contracts.d.ts +1293 -0
  206. package/dist/dashboard-gateway/control-plane/contracts.js +280 -0
  207. package/dist/dashboard-gateway/control-plane/contracts.js.map +1 -0
  208. package/dist/dashboard-gateway/control-plane/cookies.d.ts +13 -0
  209. package/dist/dashboard-gateway/control-plane/cookies.js +46 -0
  210. package/dist/dashboard-gateway/control-plane/cookies.js.map +1 -0
  211. package/dist/dashboard-gateway/control-plane/credentials.d.ts +63 -0
  212. package/dist/dashboard-gateway/control-plane/credentials.js +66 -0
  213. package/dist/dashboard-gateway/control-plane/credentials.js.map +1 -0
  214. package/dist/dashboard-gateway/control-plane/entitlements.d.ts +118 -0
  215. package/dist/dashboard-gateway/control-plane/entitlements.js +329 -0
  216. package/dist/dashboard-gateway/control-plane/entitlements.js.map +1 -0
  217. package/dist/dashboard-gateway/control-plane/errors.d.ts +17 -0
  218. package/dist/dashboard-gateway/control-plane/errors.js +23 -0
  219. package/dist/dashboard-gateway/control-plane/errors.js.map +1 -0
  220. package/dist/dashboard-gateway/control-plane/hosts.d.ts +6 -0
  221. package/dist/dashboard-gateway/control-plane/hosts.js +16 -0
  222. package/dist/dashboard-gateway/control-plane/hosts.js.map +1 -0
  223. package/dist/dashboard-gateway/control-plane/http.d.ts +34 -0
  224. package/dist/dashboard-gateway/control-plane/http.js +331 -0
  225. package/dist/dashboard-gateway/control-plane/http.js.map +1 -0
  226. package/dist/dashboard-gateway/control-plane/schema.d.ts +9 -0
  227. package/dist/dashboard-gateway/control-plane/schema.js +247 -0
  228. package/dist/dashboard-gateway/control-plane/schema.js.map +1 -0
  229. package/dist/dashboard-gateway/control-plane/secrets.d.ts +20 -0
  230. package/dist/dashboard-gateway/control-plane/secrets.js +39 -0
  231. package/dist/dashboard-gateway/control-plane/secrets.js.map +1 -0
  232. package/dist/dashboard-gateway/control-plane/store.d.ts +579 -0
  233. package/dist/dashboard-gateway/control-plane/store.js +1115 -0
  234. package/dist/dashboard-gateway/control-plane/store.js.map +1 -0
  235. package/dist/dashboard-gateway/cookie-boundary.d.ts +60 -0
  236. package/dist/dashboard-gateway/cookie-boundary.js +205 -0
  237. package/dist/dashboard-gateway/cookie-boundary.js.map +1 -0
  238. package/dist/dashboard-gateway/index.js +271 -494
  239. package/dist/dashboard-gateway/index.js.map +1 -1
  240. package/dist/dashboard-gateway/main.js +7 -2
  241. package/dist/dashboard-gateway/main.js.map +1 -1
  242. package/dist/dashboard-gateway/routing.d.ts +43 -0
  243. package/dist/dashboard-gateway/routing.js +65 -0
  244. package/dist/dashboard-gateway/routing.js.map +1 -0
  245. package/dist/dashboard-gateway/tenant-gateway.d.ts +56 -0
  246. package/dist/dashboard-gateway/tenant-gateway.js +989 -0
  247. package/dist/dashboard-gateway/tenant-gateway.js.map +1 -0
  248. package/dist/dashboard-gateway/tenant-main.d.ts +41 -0
  249. package/dist/dashboard-gateway/tenant-main.js +303 -0
  250. package/dist/dashboard-gateway/tenant-main.js.map +1 -0
  251. package/dist/dashboard-gateway/tunnel-errors.d.ts +16 -0
  252. package/dist/dashboard-gateway/tunnel-errors.js +22 -0
  253. package/dist/dashboard-gateway/tunnel-errors.js.map +1 -0
  254. package/dist/dashboard-gateway/tunnel-http.d.ts +21 -0
  255. package/dist/dashboard-gateway/tunnel-http.js +175 -0
  256. package/dist/dashboard-gateway/tunnel-http.js.map +1 -0
  257. package/dist/handler.d.ts +6 -0
  258. package/dist/handler.js +17 -1
  259. package/dist/handler.js.map +1 -1
  260. package/dist/local-clink-backend.d.ts +2 -1
  261. package/dist/local-clink-backend.js +28 -4
  262. package/dist/local-clink-backend.js.map +1 -1
  263. package/dist/parsers/extract.d.ts +19 -1
  264. package/dist/parsers/extract.js +68 -3
  265. package/dist/parsers/extract.js.map +1 -1
  266. package/dist/pipeline.d.ts +17 -1
  267. package/dist/pipeline.js +34 -6
  268. package/dist/pipeline.js.map +1 -1
  269. package/dist/process-group.d.ts +65 -0
  270. package/dist/process-group.js +153 -0
  271. package/dist/process-group.js.map +1 -0
  272. package/dist/progress-report/schema.d.ts +23 -23
  273. package/dist/project-verification/files.js +1 -1
  274. package/dist/project-verification/files.js.map +1 -1
  275. package/dist/project-verification/process.js +23 -44
  276. package/dist/project-verification/process.js.map +1 -1
  277. package/dist/project-verification/service.js +9 -1
  278. package/dist/project-verification/service.js.map +1 -1
  279. package/dist/prompt.d.ts +7 -0
  280. package/dist/prompt.js +18 -1
  281. package/dist/prompt.js.map +1 -1
  282. package/dist/recipe-host/git-trust.d.ts +43 -0
  283. package/dist/recipe-host/git-trust.js +360 -0
  284. package/dist/recipe-host/git-trust.js.map +1 -0
  285. package/dist/recipe-host/git.d.ts +42 -0
  286. package/dist/recipe-host/git.js +207 -0
  287. package/dist/recipe-host/git.js.map +1 -0
  288. package/dist/recipe-host/native-recipe-host.d.ts +127 -0
  289. package/dist/recipe-host/native-recipe-host.js +880 -0
  290. package/dist/recipe-host/native-recipe-host.js.map +1 -0
  291. package/dist/recipe-host/seat-cwd.d.ts +16 -0
  292. package/dist/recipe-host/seat-cwd.js +170 -0
  293. package/dist/recipe-host/seat-cwd.js.map +1 -0
  294. package/dist/registry.d.ts +1 -1
  295. package/dist/registry.js +5 -1
  296. package/dist/registry.js.map +1 -1
  297. package/dist/runner.d.ts +43 -1
  298. package/dist/runner.js +234 -35
  299. package/dist/runner.js.map +1 -1
  300. package/dist/server.js +21 -6
  301. package/dist/server.js.map +1 -1
  302. package/docs/configuration.md +181 -15
  303. package/docs/engineering-recipes.md +291 -0
  304. package/docs/security.md +87 -0
  305. package/docs/verification/project-checks.md +24 -2
  306. package/package.json +5 -1
  307. package/scripts/provider-doctor-core.mjs +21 -5
  308. package/clinkx-workflows/dist/dashboard-ui/assets/index-BdpmbPps.js +0 -115
  309. package/clinkx-workflows/dist/dashboard-ui/assets/style-Im5i1iAs.css +0 -1
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Serializes the one destructive step of `run.lock` acquisition: deleting a
3
+ * same-host dead-PID lock. Ported from `src/progress-report/lock.ts`, which the
4
+ * workflows package cannot import.
5
+ */
6
+ export declare const RUN_LOCK_STEAL_SUFFIX = ".steal";
7
+ export declare function runLockStealPath(lockPath: string): string;
8
+ /** The fields of a `run.lock` record that identify one acquisition. */
9
+ export interface RunLockIdentity {
10
+ readonly pid: number;
11
+ readonly hostname: string;
12
+ readonly startedAt: string;
13
+ readonly token?: string;
14
+ }
15
+ export type DeadRunLockReclaimOutcome =
16
+ /** The observed lock is gone: we unlinked it, or someone already had. */
17
+ {
18
+ readonly kind: "reclaimed";
19
+ }
20
+ /** `run.lock` no longer holds the observed acquisition; nothing was deleted. */
21
+ | {
22
+ readonly kind: "superseded";
23
+ }
24
+ /** `run.lock.steal` already exists: another reclaimer is active, or it is stranded. */
25
+ | {
26
+ readonly kind: "steal_lock_busy";
27
+ readonly stealPath: string;
28
+ };
29
+ /**
30
+ * Delete a dead-PID `run.lock`, but only one reclaimer at a time, and only if
31
+ * the lock on disk is still the acquisition the caller judged dead.
32
+ *
33
+ * `O_EXCL` on `run.lock` arbitrates creation only. Without this, two
34
+ * contenders can both judge the SAME dead lock, the first unlinks, recreates
35
+ * and owns it, and the second's already-justified unlink then deletes the
36
+ * first's LIVE lock and lets the second own the run too. Holding
37
+ * `run.lock.steal` across the identity re-read and the unlink makes the
38
+ * check-and-delete indivisible with respect to other reclaimers.
39
+ *
40
+ * Residual, accepted: a process that dies while holding `run.lock.steal`
41
+ * strands it, which disables automatic dead-PID reclaim for that run until an
42
+ * operator removes the file. Normal acquisition of an absent lock is unaffected.
43
+ */
44
+ export declare function reclaimDeadRunLock(lockPath: string, observed: RunLockIdentity): Promise<DeadRunLockReclaimOutcome>;
@@ -0,0 +1,86 @@
1
+ import { open, readFile, unlink } from "node:fs/promises";
2
+ import { logger } from "./logger.js";
3
+ /**
4
+ * Serializes the one destructive step of `run.lock` acquisition: deleting a
5
+ * same-host dead-PID lock. Ported from `src/progress-report/lock.ts`, which the
6
+ * workflows package cannot import.
7
+ */
8
+ export const RUN_LOCK_STEAL_SUFFIX = ".steal";
9
+ export function runLockStealPath(lockPath) {
10
+ return `${lockPath}${RUN_LOCK_STEAL_SUFFIX}`;
11
+ }
12
+ /**
13
+ * Legacy locks predate `token`, so their identity falls back to the tuple a
14
+ * fresh acquisition can never reproduce: a new owner always writes a token.
15
+ */
16
+ function identityKey(record) {
17
+ const token = record["token"];
18
+ if (typeof token === "string" && token !== "") {
19
+ return JSON.stringify(["token", token]);
20
+ }
21
+ return JSON.stringify(["legacy", record["pid"], record["hostname"], record["startedAt"]]);
22
+ }
23
+ /**
24
+ * Delete a dead-PID `run.lock`, but only one reclaimer at a time, and only if
25
+ * the lock on disk is still the acquisition the caller judged dead.
26
+ *
27
+ * `O_EXCL` on `run.lock` arbitrates creation only. Without this, two
28
+ * contenders can both judge the SAME dead lock, the first unlinks, recreates
29
+ * and owns it, and the second's already-justified unlink then deletes the
30
+ * first's LIVE lock and lets the second own the run too. Holding
31
+ * `run.lock.steal` across the identity re-read and the unlink makes the
32
+ * check-and-delete indivisible with respect to other reclaimers.
33
+ *
34
+ * Residual, accepted: a process that dies while holding `run.lock.steal`
35
+ * strands it, which disables automatic dead-PID reclaim for that run until an
36
+ * operator removes the file. Normal acquisition of an absent lock is unaffected.
37
+ */
38
+ export async function reclaimDeadRunLock(lockPath, observed) {
39
+ const stealPath = runLockStealPath(lockPath);
40
+ let handle;
41
+ try {
42
+ handle = await open(stealPath, "wx", 0o600);
43
+ }
44
+ catch (error) {
45
+ if (error.code === "EEXIST") {
46
+ return { kind: "steal_lock_busy", stealPath };
47
+ }
48
+ throw new Error(`Could not create run lock reclaim file ${stealPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
49
+ }
50
+ try {
51
+ let current;
52
+ try {
53
+ current = JSON.parse(await readFile(lockPath, "utf-8"));
54
+ }
55
+ catch (error) {
56
+ if (error.code === "ENOENT") {
57
+ return { kind: "reclaimed" };
58
+ }
59
+ // Unreadable or replaced mid-write: not provably the dead acquisition.
60
+ return { kind: "superseded" };
61
+ }
62
+ if (typeof current !== "object" ||
63
+ current === null ||
64
+ identityKey(current) !== identityKey({ ...observed })) {
65
+ return { kind: "superseded" };
66
+ }
67
+ try {
68
+ await unlink(lockPath);
69
+ }
70
+ catch (error) {
71
+ if (error.code !== "ENOENT") {
72
+ throw error;
73
+ }
74
+ }
75
+ return { kind: "reclaimed" };
76
+ }
77
+ finally {
78
+ // A rejected close() must not skip the unlink: stranding our own steal file
79
+ // would disable reclaim for this run by accident.
80
+ await handle.close().catch(() => undefined);
81
+ await unlink(stealPath).catch((error) => {
82
+ logger.warn({ stealPath, err: error instanceof Error ? error.message : String(error) }, "could not remove run lock reclaim file; dead-PID reclaim for this run is disabled until it is deleted");
83
+ });
84
+ }
85
+ }
86
+ //# sourceMappingURL=run-lock-reclaim.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run-lock-reclaim.js","sourceRoot":"","sources":["../src/run-lock-reclaim.ts"],"names":[],"mappings":"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"}
@@ -8,7 +8,7 @@
8
8
  import { readdirSync, readFileSync, statSync } from "node:fs";
9
9
  import { join, extname } from "node:path";
10
10
  import { Server } from "@modelcontextprotocol/sdk/server/index.js";
11
- import { getChildConfigPath, getRunsDir, hasExplicitWorkspaceRoot, resolveWorkspaceRoot, } from "./config.js";
11
+ import { getChildConfigPath, getRunsDir, hasExplicitWorkspaceRoot, homeTreeStorageRootWarnings, resolveWorkspaceRoot, } from "./config.js";
12
12
  import { logger } from "./logger.js";
13
13
  import { reconcileStaleRunDirectories } from "./state.js";
14
14
  import { ClinkSession, resolveClinkChildRuntime } from "./transport.js";
@@ -111,6 +111,10 @@ export function createWorkflowServer(options) {
111
111
  "This root governs plan_file containment and the workflow child process cwd, so workflow behavior " +
112
112
  "depends on the cwd the MCP client spawned this server with. Set CLINKX_WORKFLOWS_WORKSPACE_ROOT explicitly.");
113
113
  }
114
+ const childRuntime = resolveClinkChildRuntime();
115
+ for (const warning of homeTreeStorageRootWarnings()) {
116
+ logger.warn({ env_var: warning.envVar, value: warning.value, relation: warning.relation }, warning.message);
117
+ }
114
118
  // One-time startup reconcile of runs frozen as running/pending with no live
115
119
  // worker (fire-and-forget: bounded, idempotent, never blocks startup).
116
120
  try {
@@ -121,7 +125,6 @@ export function createWorkflowServer(options) {
121
125
  catch (err) {
122
126
  logger.warn({ err: err instanceof Error ? err.message : String(err) }, "startup stale workflow run reconcile could not be scheduled");
123
127
  }
124
- const childRuntime = resolveClinkChildRuntime();
125
128
  // Normalize empty arrays to undefined — an empty list would suppress schema
126
129
  // hints while still enabling validation (rejecting all adapter names).
127
130
  const explicit = options?.availableCliNames;
@@ -1 +1 @@
1
- {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
@@ -32,6 +32,15 @@ export type CallState = "pending" | "running" | "succeeded" | "failed" | "cancel
32
32
  export type RunStatus = "pending" | "running" | "succeeded" | "failed" | "cancelled";
33
33
  /** Failure classification for diagnostics and retry decisions. */
34
34
  export type FailureClass = "transient" | "permanent";
35
+ /**
36
+ * Structured failure provenance recorded by the engine from in-process
37
+ * evidence, never from message text. `busy_before_spawn` is the root
38
+ * pipeline's fail-fast semaphore rejection (nothing was spawned). Absent means
39
+ * unknown: legacy runs and the stdio transport, which serializes errors to text.
40
+ */
41
+ export type CallFailureKind = "busy_before_spawn";
42
+ /** Persisted state is untrusted on read: only the exact known literal counts. */
43
+ export declare function parseCallFailureKind(value: unknown): CallFailureKind | undefined;
35
44
  /** The canonical run-level terminal fields overwritten by a generic resume. */
36
45
  export interface PreviousTerminalEnvelope {
37
46
  readonly status: "succeeded" | "failed" | "cancelled";
@@ -51,6 +60,8 @@ export interface CallStateEntry {
51
60
  readonly completedAt?: string | undefined;
52
61
  readonly durationMs?: number | undefined;
53
62
  readonly failureClass?: FailureClass | undefined;
63
+ /** Set only on a failed call with structured provenance; cleared by later emits. */
64
+ readonly failureKind?: CallFailureKind | undefined;
54
65
  readonly errorMessage?: string | undefined;
55
66
  /**
56
67
  * Pointer to output file for large outputs (>10KB).
@@ -199,4 +210,17 @@ export interface RunState {
199
210
  * runs that did not use a roster.
200
211
  */
201
212
  readonly rosterName?: string | undefined;
213
+ /**
214
+ * Opaque identity of the execution that last bound this state (create or
215
+ * resume), stamped right after bind and carried by every later publication.
216
+ * Lets a pinned wait/status resolve a terminal run after a restart or
217
+ * registry eviction. Omitted on older state and before the first bind.
218
+ */
219
+ readonly executionId?: string | undefined;
220
+ /**
221
+ * completedAt of the terminal envelope this build published for executionId.
222
+ * An older build resuming the run carries executionId forward but not a
223
+ * matching witness, so a pinned read cannot settle on its outcome.
224
+ */
225
+ readonly executionCompletedAt?: string | undefined;
202
226
  }
@@ -17,5 +17,8 @@
17
17
  * Persistent resume requires CLINKX_WORKFLOWS_CHILD_CONFIG_PATH;
18
18
  * ambient-config runs are non-resumable.
19
19
  */
20
- export {};
20
+ /** Persisted state is untrusted on read: only the exact known literal counts. */
21
+ export function parseCallFailureKind(value) {
22
+ return value === "busy_before_spawn" ? value : undefined;
23
+ }
21
24
  //# sourceMappingURL=state-schema.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"state-schema.js","sourceRoot":"","sources":["../src/state-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}
1
+ {"version":3,"file":"state-schema.js","sourceRoot":"","sources":["../src/state-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA0CH,iFAAiF;AACjF,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,KAAK,KAAK,mBAAmB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC"}
@@ -1,12 +1,16 @@
1
+ import { WorkflowError } from "./errors.js";
2
+ import { type RecipeStateDraft, type RecipeStateV1 } from "./ping-pong/contract.js";
3
+ import { type RecipeTerminalEnvelope } from "./ping-pong/settle.js";
1
4
  import type { EngineHooks, EngineResumeState } from "./engine.js";
2
5
  import type { NormalizedWorkflowDefinition } from "./definition-normalizer.js";
3
- import type { FailureClass, RunState } from "./state-schema.js";
6
+ import type { FailureClass, RunState, RunStatus } from "./state-schema.js";
4
7
  import { type WorkflowContext } from "./context-preflight.js";
5
8
  import type { WorkflowContextBuilderLifecycleTransition } from "./context-builder-lifecycle-router.js";
6
9
  import type { WorkflowContextPolicy } from "./context-mode-resolver.js";
7
10
  import { type ResolvedRoster } from "./roster-contract.js";
8
11
  import { type PlanReviewContextProvenance, type PlanReviewRunState } from "./plan-review/run-state.js";
9
12
  import { type CouncilPlanReviewError } from "./plan-review/publication.js";
13
+ import { type FileWriter } from "./durable-file.js";
10
14
  /**
11
15
  * Reader-side staleness floor the shipped cadence is designed against; the
12
16
  * dashboard observer derives its own threshold from the declared interval.
@@ -53,6 +57,8 @@ export interface CreateWorkflowStateOptions {
53
57
  readonly initialContextPolicy?: WorkflowContextPolicy | undefined;
54
58
  readonly resolvedRoster?: ResolvedRoster | undefined;
55
59
  readonly rosterName?: string | undefined;
60
+ /** Test seam; production omits it and gets the durable writer. */
61
+ readonly fileWriter?: FileWriter | undefined;
56
62
  }
57
63
  /**
58
64
  * Warn-only signal recorded at create() when a sibling run with byte-identical
@@ -67,9 +73,59 @@ export interface ResumeWorkflowStateOptions {
67
73
  readonly runId: string;
68
74
  readonly runDir?: string | undefined;
69
75
  readonly debugKeepArtifacts?: boolean | undefined;
76
+ /** Test seam; production omits it and gets the durable writer. */
77
+ readonly fileWriter?: FileWriter | undefined;
78
+ }
79
+ /** Why `WorkflowStateStore.reopen()` refused; nothing was written in any case. */
80
+ export type RecipeReopenFailure = "run_busy" | "not_found" | "not_recipe" | "not_awaiting_decision" | "integrity";
81
+ /**
82
+ * The terminal recipe sidecar for a failed/cancelled settlement could not be
83
+ * committed, so `state.json` was left active rather than claiming an outcome
84
+ * the sidecar does not record. Once run.lock is released the run is an
85
+ * orphan: reconcile fails it, or cancel_workflow records it.
86
+ */
87
+ export declare class RecipeTerminalUnrecordedError extends WorkflowError {
88
+ readonly intent: "succeeded" | "failed" | "cancelled";
89
+ constructor(intent: "succeeded" | "failed" | "cancelled", cause: unknown);
90
+ }
91
+ export declare class RecipeReopenError extends WorkflowError {
92
+ readonly reason: RecipeReopenFailure;
93
+ /** Current sidecar position, when one could be read. */
94
+ readonly current?: {
95
+ readonly phase: string;
96
+ readonly revision: number;
97
+ readonly status: RunStatus;
98
+ } | undefined;
99
+ constructor(reason: RecipeReopenFailure, message: string,
100
+ /** Current sidecar position, when one could be read. */
101
+ current?: {
102
+ readonly phase: string;
103
+ readonly revision: number;
104
+ readonly status: RunStatus;
105
+ } | undefined);
106
+ }
107
+ export interface ReopenRecipeRunOptions {
108
+ readonly runId: string;
109
+ readonly runDir?: string | undefined;
110
+ readonly debugKeepArtifacts?: boolean | undefined;
111
+ /** Test seam; production omits it and gets the durable writer. */
112
+ readonly fileWriter?: FileWriter | undefined;
70
113
  }
71
114
  export declare function classifyRunDirectory(runDirPath: string): RunDirectoryClassification;
72
115
  export declare function pruneRunDirectories(runsRootDir: string, options?: PruneRunDirectoriesOptions): Promise<PruneRunDirectoriesResult>;
116
+ export type RecipeRunPrePruneDecision = "allow" | "veto";
117
+ export interface RecipeRunPrePruneContext {
118
+ readonly runId: string;
119
+ readonly runDir: string;
120
+ }
121
+ export type RecipeRunPrePruneObserver = (context: RecipeRunPrePruneContext) => Promise<RecipeRunPrePruneDecision> | RecipeRunPrePruneDecision;
122
+ /**
123
+ * Install the root host's pre-prune observer for recipe runs (CONTRACTS C5).
124
+ * It runs under the prune lock immediately before a run directory holding
125
+ * `recipe-state.json` is removed; "veto" keeps the directory. Process-local,
126
+ * like `setWorkflowActivityObserver`.
127
+ */
128
+ export declare function setRecipeRunPrePruneObserver(observer: RecipeRunPrePruneObserver | undefined): void;
73
129
  export declare class WorkflowStateStore {
74
130
  readonly runDir: string;
75
131
  /** Portable journal identity; absent only for a legacy or failed-open run. */
@@ -95,10 +151,74 @@ export declare class WorkflowStateStore {
95
151
  private heartbeatError;
96
152
  private readonly persistInvocationAuditV2;
97
153
  private readonly persistObservedInvocation;
154
+ /** Last committed recipe sidecar; `undefined` until loaded or when absent. */
155
+ private recipeStateCache;
156
+ private recipeStateLoaded;
157
+ private readonly writer;
98
158
  private constructor();
99
159
  static create(options: CreateWorkflowStateOptions): Promise<WorkflowStateStore>;
100
160
  static resume(options: ResumeWorkflowStateOptions): Promise<WorkflowStateStore>;
161
+ /**
162
+ * Reopen a paused recipe run for a control or decision execution (CONTRACTS
163
+ * 0-2 step 4, 0-7). Acquires `run.lock` with a heartbeat, verifies the
164
+ * workflow and inputs snapshot hashes, and requires terminal `succeeded`
165
+ * plus a sidecar at `awaiting_decision`. Read-only: nothing is written until
166
+ * the caller validates and calls `beginRecipeExecution()`. Calls are never
167
+ * generically rewritten, and the child-config fingerprint is not consulted
168
+ * (a pause can outlive adapter edits; the snapshots pin the definition).
169
+ * On refusal the lock is released and a `RecipeReopenError` is thrown.
170
+ */
171
+ static reopen(options: ReopenRecipeRunOptions): Promise<WorkflowStateStore>;
101
172
  get runState(): RunState;
173
+ /** The writer every file of this run goes through (durable in production). */
174
+ get fileWriter(): FileWriter;
175
+ /** Last committed recipe sidecar held by this store (reopen loads it; commits refresh it). */
176
+ get recipeState(): RecipeStateV1 | undefined;
177
+ /**
178
+ * Turn a reopened terminal envelope into a new active execution: status
179
+ * `running`, terminal fields and the previous execution id cleared. The
180
+ * caller then binds the new id (`bindExecution` via the run owner) before
181
+ * any sidecar commit. A crash in between leaves `running` with no id, which
182
+ * reconcile fails rather than settling the old pin.
183
+ */
184
+ beginRecipeExecution(): Promise<void>;
185
+ /**
186
+ * Commit `recipe-state.json` on this store's write chain under its
187
+ * `run.lock` (CONTRACTS 0-7). The store stamps `execution_id` (the bound
188
+ * id; unbound -> error), `revision` (previous + 1), `updated_at` and
189
+ * `unresolved_operations`, enforces the phase machine and the 0-4 byte
190
+ * budget, and returns the committed state. Over budget throws
191
+ * `RecipeStateCapacityError`; a non-terminal write may use 1 MiB minus the
192
+ * 64 KiB terminal reserve. State.json is not touched.
193
+ */
194
+ commitRecipeState(draft: RecipeStateDraft): Promise<RecipeStateV1>;
195
+ /**
196
+ * Terminal recipe commit in ONE critical section: the terminal sidecar first,
197
+ * then the matching terminal `state.json` (`qualified`/`stopped` ->
198
+ * succeeded, `failed` -> failed, `cancelled` -> cancelled). A crash between
199
+ * the two is rolled forward by reconcile. Used by control executions
200
+ * (decision stop, deadline, paused cancel) and by the runtime for a terminal
201
+ * stop it publishes itself.
202
+ */
203
+ commitRecipeTerminal(draft: RecipeStateDraft, options?: {
204
+ readonly error?: string | undefined;
205
+ readonly failureClass?: FailureClass | undefined;
206
+ }): Promise<RecipeStateV1>;
207
+ /**
208
+ * D1 terminal precedence for a recipe run, inside the write chain: the
209
+ * terminal fields to publish INSTEAD of `intent`, or `undefined` to publish
210
+ * `intent` as the caller would. A committed terminal sidecar of this
211
+ * execution decides; a non-terminal one is terminalized first (cancelled or
212
+ * failed), so the sidecar is never behind the state that settles it. A
213
+ * failed sidecar commit throws `RecipeTerminalUnrecordedError` and the
214
+ * caller must leave state.json active, as after a crash between the two
215
+ * writes. Non-recipe runs return `undefined` without any I/O.
216
+ */
217
+ private recipeTerminalOverrideLocked;
218
+ /** Runs inside the write chain. */
219
+ private recipeAuthorityLocked;
220
+ /** Runs inside the write chain; never enqueue from here. */
221
+ private writeRecipeStateLocked;
102
222
  /**
103
223
  * Open a new generic resume attempt before any context preflight or provider
104
224
  * setup. Provider-call attempt counters remain untouched; only the run-level
@@ -109,6 +229,11 @@ export declare class WorkflowStateStore {
109
229
  * deliberately left unchanged here.
110
230
  */
111
231
  beginResumeAttempt(): Promise<void>;
232
+ /**
233
+ * Persist the bound execution identity. Every later write clones this.state,
234
+ * so the id rides each subsequent publication; a resume overwrites it.
235
+ */
236
+ bindExecution(executionId: string): Promise<void>;
112
237
  markCancelled(reason?: string): Promise<void>;
113
238
  /**
114
239
  * Idempotently mark the run failed. Only applies when the current status is
@@ -167,9 +292,10 @@ export declare class WorkflowStateStore {
167
292
  private enqueueWrite;
168
293
  private writeState;
169
294
  }
170
- export declare function readRunStateForStatus(runId: string): Promise<{
295
+ export declare function readRunStateForStatus(runId: string, containedRead?: boolean): Promise<{
171
296
  state: RunState;
172
297
  lock: RunLockStatus;
298
+ stateDigest?: string;
173
299
  } | null>;
174
300
  /**
175
301
  * Reap a run that has no live worker (orphaned/stale/prior-process) by writing a
@@ -192,11 +318,49 @@ export declare function readRunStateForStatus(runId: string): Promise<{
192
318
  * The caller re-reads to report already_terminal.
193
319
  * - "cancelled" — lock acquired and run was pending/running; terminal
194
320
  * "cancelled" state is written and the lock removed.
321
+ * - "settled" — recipe runs only: the sidecar of this execution already
322
+ * recorded a terminal outcome, so that outcome's status is
323
+ * written instead of "cancelled" (first committed terminal
324
+ * intent wins, D1).
325
+ * - "recipe_state_unavailable" — recipe runs only: the sidecar could not be
326
+ * read, or its terminal record could not be committed;
327
+ * nothing is written (fail closed).
195
328
  *
196
329
  * NOTE: This intentionally does NOT use WorkflowStateStore.resume() (which
197
330
  * recovers + re-locks the run — the wrong intent here).
198
331
  */
199
- export declare function reapRunCancelled(runId: string): Promise<"cancelled" | "skipped" | "locked" | "ownership_unknown">;
332
+ export interface ReapRunCancelledOptions {
333
+ /**
334
+ * Runs under the acquired `run.lock` after the run is re-verified
335
+ * non-terminal and before the terminal write (CONTRACTS 0-7 orphan cancel).
336
+ * Its disposition decides that write; a throw counts as `unavailable`, so
337
+ * nothing is written.
338
+ */
339
+ readonly beforeWrite?: ((context: RecipeOrphanCancelContext) => Promise<RecipeOrphanCancelDisposition | void>) | undefined;
340
+ /** Test seam; production omits it and gets the durable writer. */
341
+ readonly fileWriter?: FileWriter | undefined;
342
+ }
343
+ export interface RecipeOrphanCancelContext {
344
+ readonly runDir: string;
345
+ readonly state: RunState;
346
+ readonly fileWriter?: FileWriter | undefined;
347
+ }
348
+ export type RecipeOrphanCancelDisposition =
349
+ /** Write terminal `cancelled`. */
350
+ {
351
+ readonly kind: "cancel";
352
+ }
353
+ /** Write the outcome a committed terminal sidecar of this execution records. */
354
+ | {
355
+ readonly kind: "settled";
356
+ readonly envelope: RecipeTerminalEnvelope;
357
+ }
358
+ /** Write nothing: the sidecar is unreadable or its record failed. */
359
+ | {
360
+ readonly kind: "unavailable";
361
+ readonly reason: string;
362
+ };
363
+ export declare function reapRunCancelled(runId: string, options?: ReapRunCancelledOptions): Promise<"cancelled" | "settled" | "skipped" | "locked" | "ownership_unknown" | "recipe_state_unavailable">;
200
364
  /**
201
365
  * Terminalize run directories frozen as running/pending with no live worker.
202
366
  *
@@ -219,4 +383,21 @@ export declare function reapRunCancelled(runId: string): Promise<"cancelled" | "
219
383
  * once, then release. Idempotent: reconciled runs are terminal `failed` and
220
384
  * count as skipped_terminal on re-scan.
221
385
  */
222
- export declare function reconcileStaleRunDirectories(runsRootDir: string): Promise<ReconcileStaleRunDirectoriesResult>;
386
+ export declare function reconcileStaleRunDirectories(runsRootDir: string, options?: {
387
+ readonly fileWriter?: FileWriter | undefined;
388
+ }): Promise<ReconcileStaleRunDirectoriesResult>;
389
+ export declare const RECIPE_ROLL_FORWARD_FAILED_ERROR = "Reconciled: recipe sidecar recorded a failed outcome";
390
+ /**
391
+ * `reapRunCancelled` beforeWrite hook for an orphaned ping-pong run (CONTRACTS
392
+ * 0-7, D1), under the lock. Only a sidecar of THIS execution is ever written
393
+ * or decides:
394
+ * - a terminal one settles the run with its own outcome's status;
395
+ * - a non-terminal one records terminal `stopped(cancelled)` (every operation
396
+ * without a result becomes `uncertain`; `effects_stopped` only when none
397
+ * remain), then the run is cancelled;
398
+ * - absent, another execution's, or an unbound state: the sidecar bytes stay
399
+ * as they are and the run is cancelled;
400
+ * - unreadable, or a record that cannot be committed: `unavailable`, and the
401
+ * reap writes nothing.
402
+ */
403
+ export declare function recordRecipeOrphanCancel(context: RecipeOrphanCancelContext): Promise<RecipeOrphanCancelDisposition>;