@smoothbricks/nx-plugin 0.4.25 → 0.4.27

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 (348) hide show
  1. package/README.md +1078 -98
  2. package/dist/bin/smoo-nx-bound-failures.d.ts +3 -0
  3. package/dist/bin/smoo-nx-bound-failures.d.ts.map +1 -0
  4. package/dist/bin/smoo-nx-bound-failures.js +31 -0
  5. package/dist/bin/smoo-nx-cargo-hash.js +28 -3
  6. package/dist/bin/smoo-nx-exec.js +16 -85
  7. package/dist/bin/smoo-nx-failures.d.ts +3 -0
  8. package/dist/bin/smoo-nx-failures.d.ts.map +1 -0
  9. package/dist/bin/smoo-nx-failures.js +3 -0
  10. package/dist/bin/smoo-nx-nextest-extract.js +3 -2
  11. package/dist/bin/smoo-nx-test-walks.d.ts +3 -0
  12. package/dist/bin/smoo-nx-test-walks.d.ts.map +1 -0
  13. package/dist/bin/smoo-nx-test-walks.js +34 -0
  14. package/dist/bounded-test-policy.d.ts +7 -1
  15. package/dist/bounded-test-policy.d.ts.map +1 -1
  16. package/dist/bounded-test-policy.js +101 -40
  17. package/dist/build-state-output-policy.d.ts +25 -0
  18. package/dist/build-state-output-policy.d.ts.map +1 -0
  19. package/dist/build-state-output-policy.js +64 -0
  20. package/dist/cargo-closure-input.d.ts +16 -17
  21. package/dist/cargo-closure-input.d.ts.map +1 -1
  22. package/dist/cargo-closure-input.js +37 -44
  23. package/dist/cargo-dev-profile.d.ts +37 -0
  24. package/dist/cargo-dev-profile.d.ts.map +1 -0
  25. package/dist/cargo-dev-profile.js +108 -0
  26. package/dist/cargo-source-hash.d.ts +50 -8
  27. package/dist/cargo-source-hash.d.ts.map +1 -1
  28. package/dist/cargo-source-hash.js +691 -71
  29. package/dist/cargo-toolchain-policy.d.ts +4 -0
  30. package/dist/cargo-toolchain-policy.d.ts.map +1 -1
  31. package/dist/cargo-toolchain-policy.js +5 -0
  32. package/dist/cargo-workspace.d.ts +108 -12
  33. package/dist/cargo-workspace.d.ts.map +1 -1
  34. package/dist/cargo-workspace.js +299 -18
  35. package/dist/cross-check-policy.d.ts +21 -3
  36. package/dist/cross-check-policy.d.ts.map +1 -1
  37. package/dist/cross-check-policy.js +24 -6
  38. package/dist/disk-command-policy.d.ts +7 -0
  39. package/dist/disk-command-policy.d.ts.map +1 -0
  40. package/dist/disk-command-policy.js +98 -0
  41. package/dist/ensure-built-receipt.d.ts +25 -0
  42. package/dist/ensure-built-receipt.d.ts.map +1 -0
  43. package/dist/ensure-built-receipt.js +261 -0
  44. package/dist/ensure-built-witness.d.ts +57 -0
  45. package/dist/ensure-built-witness.d.ts.map +1 -0
  46. package/dist/ensure-built-witness.js +412 -0
  47. package/dist/ensure-built.d.ts +213 -12
  48. package/dist/ensure-built.d.ts.map +1 -1
  49. package/dist/ensure-built.js +624 -177
  50. package/dist/eslint-file-set.d.ts +7 -0
  51. package/dist/eslint-file-set.d.ts.map +1 -0
  52. package/dist/eslint-file-set.js +12 -0
  53. package/dist/executors/bounded-exec/cpu-pool.d.ts +63 -0
  54. package/dist/executors/bounded-exec/cpu-pool.d.ts.map +1 -0
  55. package/dist/executors/bounded-exec/cpu-pool.js +379 -0
  56. package/dist/executors/bounded-exec/cpu-tokens.d.ts +82 -0
  57. package/dist/executors/bounded-exec/cpu-tokens.d.ts.map +1 -0
  58. package/dist/executors/bounded-exec/cpu-tokens.js +114 -0
  59. package/dist/executors/bounded-exec/disk-lease.d.ts +61 -0
  60. package/dist/executors/bounded-exec/disk-lease.d.ts.map +1 -0
  61. package/dist/executors/bounded-exec/disk-lease.js +91 -0
  62. package/dist/executors/bounded-exec/executor.d.ts +45 -2
  63. package/dist/executors/bounded-exec/executor.d.ts.map +1 -1
  64. package/dist/executors/bounded-exec/executor.js +447 -52
  65. package/dist/executors/bounded-exec/gateway-lease.d.ts +52 -0
  66. package/dist/executors/bounded-exec/gateway-lease.d.ts.map +1 -0
  67. package/dist/executors/bounded-exec/gateway-lease.js +143 -0
  68. package/dist/executors/bounded-exec/hang-diagnostics.d.ts +35 -0
  69. package/dist/executors/bounded-exec/hang-diagnostics.d.ts.map +1 -0
  70. package/dist/executors/bounded-exec/hang-diagnostics.js +231 -0
  71. package/dist/executors/bounded-exec/progress.d.ts +35 -0
  72. package/dist/executors/bounded-exec/progress.d.ts.map +1 -0
  73. package/dist/executors/bounded-exec/progress.js +79 -0
  74. package/dist/executors/bounded-exec/ram-temp-fixtures.d.ts +3 -0
  75. package/dist/executors/bounded-exec/ram-temp-fixtures.d.ts.map +1 -0
  76. package/dist/executors/bounded-exec/ram-temp-fixtures.js +12 -0
  77. package/dist/executors/bounded-exec/ram-temp-held.d.ts +91 -0
  78. package/dist/executors/bounded-exec/ram-temp-held.d.ts.map +1 -0
  79. package/dist/executors/bounded-exec/ram-temp-held.js +152 -0
  80. package/dist/executors/bounded-exec/ram-temp.d.ts +223 -0
  81. package/dist/executors/bounded-exec/ram-temp.d.ts.map +1 -0
  82. package/dist/executors/bounded-exec/ram-temp.js +1528 -0
  83. package/dist/executors/bounded-exec/schema.d.ts +29 -11
  84. package/dist/executors/bounded-exec/schema.d.ts.map +1 -1
  85. package/dist/executors/bounded-exec/verdict.d.ts +162 -0
  86. package/dist/executors/bounded-exec/verdict.d.ts.map +1 -0
  87. package/dist/executors/bounded-exec/verdict.js +318 -0
  88. package/dist/executors/shard-timings/executor.d.ts +14 -0
  89. package/dist/executors/shard-timings/executor.d.ts.map +1 -0
  90. package/dist/executors/shard-timings/executor.js +25 -0
  91. package/dist/executors/shard-timings/schema.d.ts +4 -0
  92. package/dist/executors/shard-timings/schema.d.ts.map +1 -0
  93. package/dist/executors/shard-timings/schema.js +1 -0
  94. package/dist/failure-summary.d.ts +5 -0
  95. package/dist/failure-summary.d.ts.map +1 -0
  96. package/dist/failure-summary.js +118 -0
  97. package/dist/generators/create-package/generator.d.ts.map +1 -1
  98. package/dist/generators/create-package/generator.js +6 -2
  99. package/dist/index.d.ts +14 -2
  100. package/dist/index.d.ts.map +1 -1
  101. package/dist/index.js +435 -230
  102. package/dist/managed-assets.d.ts +6 -0
  103. package/dist/managed-assets.d.ts.map +1 -1
  104. package/dist/managed-files/ci-workflow.d.ts +13 -0
  105. package/dist/managed-files/ci-workflow.d.ts.map +1 -1
  106. package/dist/managed-files/ci-workflow.js +44 -13
  107. package/dist/managed-files/files.d.ts +7 -1
  108. package/dist/managed-files/files.d.ts.map +1 -1
  109. package/dist/managed-files/files.js +62 -8
  110. package/dist/managed-files/json-edit.d.ts +21 -0
  111. package/dist/managed-files/json-edit.d.ts.map +1 -0
  112. package/dist/managed-files/json-edit.js +295 -0
  113. package/dist/managed-files/managed-format.d.ts +33 -1
  114. package/dist/managed-files/managed-format.d.ts.map +1 -1
  115. package/dist/managed-files/managed-format.js +82 -2
  116. package/dist/managed-files/pr-preview-cleanup-workflow.d.ts +7 -0
  117. package/dist/managed-files/pr-preview-cleanup-workflow.d.ts.map +1 -1
  118. package/dist/managed-files/pr-preview-cleanup-workflow.js +68 -4
  119. package/dist/managed-files/publish-workflow.d.ts.map +1 -1
  120. package/dist/managed-files/publish-workflow.js +231 -48
  121. package/dist/managed-files/tree.d.ts +5 -0
  122. package/dist/managed-files/tree.d.ts.map +1 -1
  123. package/dist/managed-files/tree.js +5 -3
  124. package/dist/manifest-hash.js +3 -2
  125. package/dist/nextest-code-bound.d.ts +62 -0
  126. package/dist/nextest-code-bound.d.ts.map +1 -0
  127. package/dist/nextest-code-bound.js +154 -0
  128. package/dist/nextest-extraction.d.ts +24 -8
  129. package/dist/nextest-extraction.d.ts.map +1 -1
  130. package/dist/nextest-extraction.js +42 -7
  131. package/dist/package-target-policy.d.ts.map +1 -1
  132. package/dist/package-target-policy.js +3 -5
  133. package/dist/release-config-policy.d.ts.map +1 -1
  134. package/dist/release-config-policy.js +3 -5
  135. package/dist/runtime-input.d.ts +14 -0
  136. package/dist/runtime-input.d.ts.map +1 -0
  137. package/dist/runtime-input.js +15 -0
  138. package/dist/rust-tokens.d.ts +11 -0
  139. package/dist/rust-tokens.d.ts.map +1 -0
  140. package/dist/rust-tokens.js +81 -0
  141. package/dist/task-results.d.ts +6 -0
  142. package/dist/task-results.d.ts.map +1 -0
  143. package/dist/task-results.js +61 -0
  144. package/dist/test-program.d.ts +54 -0
  145. package/dist/test-program.d.ts.map +1 -0
  146. package/dist/test-program.js +292 -0
  147. package/dist/test-timings.d.ts +71 -0
  148. package/dist/test-timings.d.ts.map +1 -0
  149. package/dist/test-timings.js +393 -0
  150. package/dist/test-walk-policy.d.ts +103 -0
  151. package/dist/test-walk-policy.d.ts.map +1 -0
  152. package/dist/test-walk-policy.js +657 -0
  153. package/dist/testing.d.ts +177 -0
  154. package/dist/testing.d.ts.map +1 -0
  155. package/dist/testing.js +824 -0
  156. package/dist/type-guards.d.ts +3 -0
  157. package/dist/type-guards.d.ts.map +1 -0
  158. package/dist/type-guards.js +4 -0
  159. package/dist/typecheck-test-policy.d.ts +8 -5
  160. package/dist/typecheck-test-policy.d.ts.map +1 -1
  161. package/dist/typecheck-test-policy.js +113 -100
  162. package/dist/workspace-config-policy.d.ts +8 -0
  163. package/dist/workspace-config-policy.d.ts.map +1 -1
  164. package/dist/workspace-config-policy.js +175 -63
  165. package/dist/workspace-index.d.ts +12 -0
  166. package/dist/workspace-index.d.ts.map +1 -0
  167. package/dist/workspace-index.js +17 -0
  168. package/dist/workspace-manifest.d.ts +37 -1
  169. package/dist/workspace-manifest.d.ts.map +1 -1
  170. package/executors.json +5 -0
  171. package/loader.js +13 -11
  172. package/managed/raw/envrc +33 -62
  173. package/managed/raw/git-format-staged.yml +30 -35
  174. package/managed/raw/patches/nx@23.2.1.patch +3484 -0
  175. package/managed/raw/tooling/direnv/apple-developer.sh +83 -0
  176. package/managed/raw/tooling/direnv/developer-links.ts +607 -17
  177. package/managed/raw/tooling/direnv/devenv.smoo.nix +314 -92
  178. package/managed/raw/tooling/direnv/github-actions-bootstrap.sh +20 -11
  179. package/managed/raw/tooling/direnv/linked-snapshots.ts +845 -0
  180. package/managed/raw/tooling/direnv/nx-socket-dir.sh +82 -0
  181. package/managed/raw/tooling/direnv/repo-path +14 -2
  182. package/managed/raw/tooling/direnv/setup-environment.ts +1009 -118
  183. package/managed/raw/tooling/direnv/toolchain-stamp.ts +45 -3
  184. package/managed/raw/tooling/direnv/ttsc-env.sh +39 -0
  185. package/managed/raw/tooling/git-hooks/commit-msg.sh +5 -6
  186. package/managed/raw/tooling/git-hooks/pre-commit.sh +7 -6
  187. package/managed/raw/tooling/git-hooks/pre-push.sh +20 -15
  188. package/managed/templates/github/actions/cache-nix-devenv/action.yml +6 -6
  189. package/managed/templates/github/actions/cache-node-modules/action.yml +6 -4
  190. package/managed/templates/github/actions/cache-nx/action.yml +1 -1
  191. package/managed/templates/github/actions/cache-ttsc-plugins/action.yml +1 -1
  192. package/managed/templates/github/actions/forgejo-artifact.cjs +99 -0
  193. package/managed/templates/github/actions/forgejo-download-artifact/action.yml +49 -0
  194. package/managed/templates/github/actions/forgejo-download-artifact/index.cjs +7 -0
  195. package/managed/templates/github/actions/forgejo-upload-artifact/action.yml +65 -0
  196. package/managed/templates/github/actions/forgejo-upload-artifact/index.cjs +7 -0
  197. package/managed/templates/github/actions/setup-devenv/action.yml +21 -3
  198. package/managed/templates/github/workflows/managed-files.yml +1 -2
  199. package/nextest.toml +8 -75
  200. package/package.json +75 -13
  201. package/runtime-input.sh +81 -0
  202. package/src/__tests__/counted-cargo-process.ts +286 -0
  203. package/src/__tests__/counted-cargo.ts +730 -0
  204. package/src/__tests__/fixture-cargo-home.ts +36 -0
  205. package/src/__tests__/fixture-nx-env.ts +157 -2
  206. package/src/__tests__/progress-clock.ts +43 -0
  207. package/src/__tests__/runtime-input.ts +23 -0
  208. package/src/bin/smoo-nx-bound-failures.test.ts +127 -0
  209. package/src/bin/smoo-nx-bound-failures.ts +33 -0
  210. package/src/bin/smoo-nx-cargo-hash.ts +28 -3
  211. package/src/bin/smoo-nx-exec.ts +17 -86
  212. package/src/bin/smoo-nx-failures.ts +4 -0
  213. package/src/bin/smoo-nx-nextest-extract.ts +3 -2
  214. package/src/bin/smoo-nx-test-walks.ts +42 -0
  215. package/src/bounded-test-policy.test.ts +268 -22
  216. package/src/bounded-test-policy.ts +114 -42
  217. package/src/build-state-output-policy.test.ts +115 -0
  218. package/src/build-state-output-policy.ts +90 -0
  219. package/src/bun-bootstrap.test.ts +57 -3
  220. package/src/bun-file-packages.test.ts +47 -0
  221. package/src/cargo-closure-input.test.ts +432 -62
  222. package/src/cargo-closure-input.ts +51 -57
  223. package/src/cargo-dev-profile.ts +137 -0
  224. package/src/cargo-resolve-cache.test.ts +1044 -0
  225. package/src/cargo-source-hash.test.ts +203 -93
  226. package/src/cargo-source-hash.ts +762 -75
  227. package/src/cargo-toolchain-policy.ts +6 -0
  228. package/src/cargo-workspace.test.ts +320 -0
  229. package/src/cargo-workspace.ts +344 -18
  230. package/src/cross-check-policy.test.ts +59 -1
  231. package/src/cross-check-policy.ts +25 -6
  232. package/src/disk-command-policy.test.ts +61 -0
  233. package/src/disk-command-policy.ts +107 -0
  234. package/src/ensure-built-receipt.test.ts +184 -0
  235. package/src/ensure-built-receipt.ts +263 -0
  236. package/src/ensure-built-witness.test.ts +344 -0
  237. package/src/ensure-built-witness.ts +252 -0
  238. package/src/ensure-built.test.ts +1043 -483
  239. package/src/ensure-built.ts +870 -197
  240. package/src/eslint-file-set.ts +9 -0
  241. package/src/executors/bounded-exec/cpu-pool.test.ts +454 -0
  242. package/src/executors/bounded-exec/cpu-pool.ts +417 -0
  243. package/src/executors/bounded-exec/cpu-tokens.test.ts +269 -0
  244. package/src/executors/bounded-exec/cpu-tokens.ts +177 -0
  245. package/src/executors/bounded-exec/disk-lease.test.ts +185 -0
  246. package/src/executors/bounded-exec/disk-lease.ts +139 -0
  247. package/src/executors/bounded-exec/executor-host.test.ts +778 -0
  248. package/src/executors/bounded-exec/executor.test.ts +1116 -63
  249. package/src/executors/bounded-exec/executor.ts +565 -67
  250. package/src/executors/bounded-exec/gateway-lease.ts +176 -0
  251. package/src/executors/bounded-exec/hang-diagnostics.test.ts +285 -0
  252. package/src/executors/bounded-exec/hang-diagnostics.ts +283 -0
  253. package/src/executors/bounded-exec/progress.test.ts +79 -0
  254. package/src/executors/bounded-exec/progress.ts +118 -0
  255. package/src/executors/bounded-exec/ram-temp-fixtures.ts +12 -0
  256. package/src/executors/bounded-exec/ram-temp-held.test.ts +264 -0
  257. package/src/executors/bounded-exec/ram-temp-held.ts +242 -0
  258. package/src/executors/bounded-exec/ram-temp-host.test.ts +605 -0
  259. package/src/executors/bounded-exec/ram-temp.test.ts +674 -0
  260. package/src/executors/bounded-exec/ram-temp.ts +1918 -0
  261. package/src/executors/bounded-exec/schema.json +11 -5
  262. package/src/executors/bounded-exec/schema.ts +27 -11
  263. package/src/executors/bounded-exec/verdict.test.ts +440 -0
  264. package/src/executors/bounded-exec/verdict.ts +433 -0
  265. package/src/executors/shard-timings/executor.ts +36 -0
  266. package/src/executors/shard-timings/schema.json +21 -0
  267. package/src/executors/shard-timings/schema.ts +4 -0
  268. package/src/failure-summary.ts +119 -0
  269. package/src/generators/bounded-test-targets/generator.test.ts +4 -4
  270. package/src/generators/bun-test-tracing/generator.test.ts +2 -2
  271. package/src/generators/create-package/generator.test.ts +6 -0
  272. package/src/generators/create-package/generator.ts +6 -2
  273. package/src/host-controller-wiring.test.ts +31 -0
  274. package/src/index.test.ts +1070 -360
  275. package/src/index.ts +524 -255
  276. package/src/linked-snapshots.nx.test.ts +172 -0
  277. package/src/managed-assets.ts +12 -0
  278. package/src/managed-files/ci-workflow.ts +54 -13
  279. package/src/managed-files/files.ts +65 -9
  280. package/src/managed-files/forgejo-artifact.test.ts +395 -0
  281. package/src/managed-files/generator.test.ts +60 -1
  282. package/src/managed-files/json-edit.test.ts +216 -0
  283. package/src/managed-files/json-edit.ts +290 -0
  284. package/src/managed-files/managed-format-json.test.ts +308 -0
  285. package/src/managed-files/managed-format.ts +90 -2
  286. package/src/managed-files/pr-preview-cleanup-workflow.ts +69 -3
  287. package/src/managed-files/publish-workflow.ts +285 -67
  288. package/src/managed-files/repo-path.test.ts +129 -0
  289. package/src/managed-files/trace-db-artifact.test.ts +7 -0
  290. package/src/managed-files/tree.ts +11 -3
  291. package/src/manifest-hash.ts +3 -2
  292. package/src/nextest-code-bound.test.ts +155 -0
  293. package/src/nextest-code-bound.ts +195 -0
  294. package/src/nextest-extraction.test.ts +37 -5
  295. package/src/nextest-extraction.ts +51 -9
  296. package/src/nextest-partitions.test.ts +495 -0
  297. package/src/nx-cache-bound.test.ts +109 -0
  298. package/src/nx-cache-restore-mtime.test.ts +170 -0
  299. package/src/nx-daemon-claim.test.ts +277 -0
  300. package/src/nx-daemon-idle-cpu.test.ts +81 -0
  301. package/src/nx-daemon-idle-policy.test.ts +51 -0
  302. package/src/nx-daemon-ignore-files.test.ts +210 -0
  303. package/src/nx-daemon-root-normalization.test.ts +105 -0
  304. package/src/nx-daemon-validity.test.ts +925 -0
  305. package/src/nx-dot-input-policy.test.ts +353 -0
  306. package/src/nx-failure-life-cycles.test.ts +207 -0
  307. package/src/nx-files-archive-racy.test.ts +97 -0
  308. package/src/nx-foreign-workspace-env.test.ts +329 -0
  309. package/src/nx-incomplete-run-summary.test.ts +70 -0
  310. package/src/nx-plugin-load-errors.test.ts +120 -0
  311. package/src/nx-project-resolution-cache.test.ts +176 -0
  312. package/src/nx-raw-inputs.test.ts +166 -0
  313. package/src/nx-resident-graph-workers.test.ts +112 -0
  314. package/src/nx-run-information.test.ts +118 -0
  315. package/src/nx-skipped-task-exit.test.ts +180 -0
  316. package/src/nx-state-location.test.ts +63 -0
  317. package/src/nx-store-resolution.test.ts +99 -0
  318. package/src/nx-task-graph-cycles.test.ts +148 -0
  319. package/src/nx-task-output-lease.test.ts +414 -0
  320. package/src/nx-use-local.test.ts +103 -0
  321. package/src/package-target-policy.ts +3 -6
  322. package/src/release-config-policy.ts +3 -6
  323. package/src/runtime-input.test.ts +215 -0
  324. package/src/runtime-input.ts +17 -0
  325. package/src/rust-tokens.ts +78 -0
  326. package/src/serial-group-wiring.test.ts +326 -0
  327. package/src/task-history-namespace.test.ts +181 -0
  328. package/src/task-results.test.ts +226 -0
  329. package/src/task-results.ts +75 -0
  330. package/src/test-program.test.ts +303 -0
  331. package/src/test-program.ts +341 -0
  332. package/src/test-timings.test.ts +240 -0
  333. package/src/test-timings.ts +311 -0
  334. package/src/test-walk-policy.test.ts +585 -0
  335. package/src/test-walk-policy.ts +731 -0
  336. package/src/testing.test.ts +509 -0
  337. package/src/testing.ts +922 -0
  338. package/src/type-guards.ts +4 -0
  339. package/src/typecheck-test-policy.test.ts +496 -11
  340. package/src/typecheck-test-policy.ts +137 -103
  341. package/src/workspace-config-policy.test.ts +212 -13
  342. package/src/workspace-config-policy.ts +101 -73
  343. package/src/workspace-index.ts +18 -0
  344. package/src/workspace-manifest.ts +41 -1
  345. package/test-timings.json +85 -28
  346. package/managed/raw/tooling/direnv/inherited-devenv.ts +0 -615
  347. package/managed/raw/tooling/direnv/shared-caches.sh +0 -53
  348. package/src/__tests__/in-process-nx-index.ts +0 -9
@@ -0,0 +1,1918 @@
1
+ import { type ChildProcess, spawn } from 'node:child_process';
2
+ import { randomUUID } from 'node:crypto';
3
+ import { constants } from 'node:fs';
4
+ import {
5
+ type FileHandle,
6
+ lstat,
7
+ mkdir,
8
+ mkdtemp,
9
+ open,
10
+ readdir,
11
+ readFile,
12
+ rename,
13
+ rm,
14
+ rmdir,
15
+ stat,
16
+ statfs,
17
+ writeFile,
18
+ } from 'node:fs/promises';
19
+ import { Socket } from 'node:net';
20
+ import { basename, join } from 'node:path';
21
+ import { setTimeout as sleep } from 'node:timers/promises';
22
+ import {
23
+ awaitExit,
24
+ type ProcessEntry,
25
+ pidsWorkingIn,
26
+ processTable,
27
+ terminate,
28
+ withDescendants,
29
+ } from '../../testing.js';
30
+ import { isRecord } from '../../type-guards.js';
31
+ import { diskClassOf, type PhaseShare, recordedShare, takeDiskLease } from './disk-lease.js';
32
+ import { GATEWAY_SOCKET } from './gateway-lease.js';
33
+ import {
34
+ captureHeldVerdict,
35
+ type HeldCandidate,
36
+ type HeldContext,
37
+ type HeldVerdict,
38
+ parseHeldVerdict,
39
+ validateHeldVerdict,
40
+ } from './ram-temp-held.js';
41
+
42
+ /**
43
+ * One RAM-backed APFS volume per host user, shared by every test task that runs
44
+ * on the host, so test temp files never reach the SSD.
45
+ *
46
+ * Measured on macOS 26.6:
47
+ * - `hdiutil attach ram://<sectors>` allocates lazily: an attached 8 GiB volume
48
+ * costs ~13 MB until written, so the capacity is a ceiling, not a reservation.
49
+ * - Deleting files does not hand pages back (no TRIM through the RAM device):
50
+ * the volume's cost is its high-water mark until it is detached. That is why
51
+ * the volume is detached as soon as no task holds a lease, rather than kept.
52
+ * - The memory is pageable (it belongs to diskimages-helper), so it reaches the
53
+ * SSD only through swap under memory pressure.
54
+ * - A RAM disk belongs to the legacy DiskImages framework: attaching one starts
55
+ * a `diskimages-helper` that exits on detach, with no AppleDiskImageDevice and
56
+ * no `diskimagesiod`, so it spends none of the AppleDiskImages2 attach budget
57
+ * that cowshed's images and tests draw on (specs/cowshed/01a_apfs.md, "How
58
+ * the APFS host degrades"; measured 2026-10-05).
59
+ * - Attach + format + mount costs ~2 s and is DiskArbitration traffic, so the
60
+ * volume is created once, lazily, and every task takes a subdirectory.
61
+ * - Only DiskArbitration's own mountpoint (`/Volumes/<volume name>`) is safe to
62
+ * ask for: `diskutil mount -mountPoint <dir>` was refused as not privileged
63
+ * (0xf8da0009), and storagekitd escalated it to an administrator dialog whose
64
+ * wait blocked every diskutil on the host. A default mount raised no authd
65
+ * request (log show, 2026-10-04).
66
+ * - Without authorization the volume mounts only `noowners`: launchd refuses a
67
+ * plist from it ("Caller specified a plist with bad ownership/permissions"),
68
+ * so a test that bootstraps a launchd job keeps the plist outside TMPDIR.
69
+ *
70
+ * One kernel lock (`O_EXLOCK` on a file in /private/tmp), dropped by the kernel
71
+ * when its holder dies, admits changes to a small ledger beside it and to the
72
+ * set of lease directories. It is held only to read and publish those: the
73
+ * host-wide probes (`ioreg`, `mount`, the process census), directory cleanup,
74
+ * provisioning and detach run outside it, under claims the ledger publishes.
75
+ * One caller creates or detaches the volume at a time, and a caller that finds
76
+ * either in flight yields and looks again; each dead lease is settled by the
77
+ * one caller that claimed it, and every other caller passes it by. A claim
78
+ * names its owner's pid, so a claim whose owner died is void. Before it
79
+ * removes a lease or detaches the volume, a caller takes the lock again and
80
+ * checks that the volume, the lease directory and its own claim are still as
81
+ * it claimed them. A lease is a directory named after the task process's pid;
82
+ * a lease whose pid is gone is reclaimed by the next task, and the volume is
83
+ * detached when the last lease ends.
84
+ *
85
+ * The volume is created under its final name and never renamed. It is mounted by `mount_apfs` at a
86
+ * private staging directory and marked there; the kernel then unmounts it (`umount`) and `diskutil mount`, the
87
+ * only call that places it at its mountpoint, so it reaches `/Volumes` already marked. A Disk
88
+ * Arbitration rename names whatever volume holds the path it recorded, and a force-unmounted volume
89
+ * leaves a bare directory there on the host's Data volume, so no rename is made. `noowners` lets the
90
+ * marker be written, since a fresh volume's root is owned by root (measured 2026-10-15). A creator that
91
+ * dies part way leaves debris at the staging directory or as an unmounted volume, never an unmarked
92
+ * volume at the mountpoint, which DiskArbitration would make every later volume dodge as "<name> 1".
93
+ * The host's own image list is the only record of what was
94
+ * attached: before creating, a task detaches every RAM disk of this user and
95
+ * this volume's exact size that is mounted nowhere but this volume's names,
96
+ * because a creator killed or deadlined mid-step leaves one behind — measured
97
+ * 2026-10-06: a deadlined `hdiutil attach` whose diskimages-helper finished the
98
+ * attach after `hdiutil` was killed, and a volume mounted with no marker. A
99
+ * disk with a lease directory on it is never detached; its error names it.
100
+ *
101
+ * An image attached from a file below a lease belongs to whoever attached it:
102
+ * cowshed's real-APFS fixtures release theirs under the production per-image
103
+ * lease, from scratch roots outside TMPDIR (specs/cowshed/08_testing.md). This
104
+ * module never detaches one, and never deletes through a mount below a lease.
105
+ * A dead lease that still backs an image or holds a mount is kept, with the
106
+ * volume under it, and every task that takes a lease names it. Where every
107
+ * holder has an identity a cheap `lstat` re-proves (a mount below the lease),
108
+ * the ledger keeps that proof (`ram-temp-held.ts`) and later tasks check it
109
+ * instead of probing the host; any change sends the lease back to a probe.
110
+ * Every disk child runs under a deadline, in its own process group so the
111
+ * deadline also reaches the helper it spawned, so a wedged DiskArbitration
112
+ * fails the task instead of every task waiting on the volume. A detach is the
113
+ * exception: never killed at its deadline, because an interrupted detach can
114
+ * wedge DiskArbitration itself; its wait is bounded and reported by name, and
115
+ * a stray's detach gets the short stray bound, so one wedged stray cannot
116
+ * hold the create claim while a chain of tasks queues behind it.
117
+ *
118
+ * A cowshed sandbox denies writes to /private/tmp (EPERM on the lock), and
119
+ * cannot attach disk images at all; there the task keeps the workspace's own
120
+ * TMPDIR and says so once on stderr.
121
+ */
122
+
123
+ /** macOS `open(2)` flag: take an exclusive flock atomically with the open. Absent from `fs.constants`. */
124
+ const O_EXLOCK = 0x20;
125
+ /** Contended opens yield without occupying a filesystem worker needed by the lock holder. */
126
+ const LOCK_RETRY_MS = 50;
127
+ /**
128
+ * A caller waiting this long on another's creation or detach says so on stderr, and again each
129
+ * time as long again passes: a claim whose owner pid was reused after a crash never voids itself.
130
+ */
131
+ const CLAIM_WAIT_NOTICE_MS = 15_000;
132
+ const SECTOR_BYTES = 512;
133
+ const MIB = 1024 * 1024;
134
+ const GIB = 1024 * MIB;
135
+ /**
136
+ * The revision of the volume's protocol. Checkouts at different revisions run on one host at
137
+ * once, and each is safe only beside its own: revision 1 leases under the kernel lock alone,
138
+ * revision 2 leases and detaches outside it, behind claims in a ledger revision 1 never reads.
139
+ * So no revision shares a volume with another. It names the volume, its lock and its ledger, and
140
+ * adds as many sectors to the RAM disk, whose size and user are what a creator's stray reclaim
141
+ * matches: neither revision detaches the other's disk, mounted or still attaching.
142
+ */
143
+ const RAM_TEMP_REVISION = 2;
144
+ /**
145
+ * The volume's ceiling, plus the revision's sectors. Pages are allocated as they are written and
146
+ * returned when the volume detaches, so this bounds what a runaway suite can take, not what a gate
147
+ * costs. Measured 2026-10-04: a full parallel smoothbricks `lint test build host-controller-test`
148
+ * gate peaked at 1.61 GiB used with 18 concurrent leases; 8 GiB is five times that. That
149
+ * gate also staged cowshed's real-APFS fixture images on the volume, which now stay under
150
+ * /private/tmp, so the peak is an upper bound.
151
+ */
152
+ export const RAM_TEMP_CAPACITY_BYTES = 8 * GIB + RAM_TEMP_REVISION * SECTOR_BYTES;
153
+ /** A failed task with less than this free on the volume is reported as having run out of space. */
154
+ const FULL_FREE_BYTES = 64 * MIB;
155
+ /** `<pid>-<mkdtemp suffix>`: the pid says whether the lease's task is alive. */
156
+ const LEASE_NAME = /^(\d+)-[A-Za-z0-9]{6}$/;
157
+ const MARKER_FILE = '.smoo-ram';
158
+
159
+ export interface CommandOutput {
160
+ status: number;
161
+ stdout: string;
162
+ stderr: string;
163
+ }
164
+
165
+ /** The host programs the volume lifecycle runs. A seam so the state machine is testable without DiskArbitration. */
166
+ export interface HostCommands {
167
+ run(file: string, args: readonly string[], deadlineMs?: number): Promise<CommandOutput>;
168
+ }
169
+
170
+ /**
171
+ * How long a process a task left in its lease gets to exit on SIGTERM before it gets SIGKILL: the
172
+ * time a daemon takes to stop its watcher and its plugin workers, and well under the grace a
173
+ * bounded leg gives its own command.
174
+ */
175
+ const LEFTOVER_GRACE_MS = 5_000;
176
+
177
+ /**
178
+ * The processes still working in a lease directory once its task is over, and how they end. A
179
+ * seam so the volume's state machine is testable without any.
180
+ */
181
+ export interface LeaseProcesses {
182
+ /**
183
+ * End every process whose working directory is in `directory`, and everything those started,
184
+ * and answer each as `<pid> (<command>)`. Every one has exited when this settles; one that
185
+ * would not rejects with its name.
186
+ */
187
+ stopWorkingIn(directory: string): Promise<string[]>;
188
+ }
189
+
190
+ /** The host reads and signals cleanup uses; a seam for process ordering and signal failures. */
191
+ export interface ProcessHost {
192
+ /** The processes whose working directory is `directory` or lies beneath it. */
193
+ workingIn(directory: string): Promise<number[]>;
194
+ /** Every process on the host. */
195
+ table(): Promise<ProcessEntry[]>;
196
+ signal(pid: number, signal: NodeJS.Signals): void;
197
+ }
198
+
199
+ /** A `ps` state in which a process starts nothing: stopped (`T`, `t` when traced) or exited (`Z`). */
200
+ const STARTS_NOTHING = /^[TtZ]/;
201
+
202
+ /**
203
+ * The processes `host` reads. A lease belongs to one task and its command is gone by the time the
204
+ * lease ends, so what still works in it is what the command left behind. A fixture's Nx daemon is
205
+ * the usual one: Nx detaches it into a session of its own, so the process-group kill that ends a
206
+ * timed-out command never reaches it, and a test process that is killed runs no teardown of its
207
+ * own. Deleting the lease asks such a daemon to leave only by deleting its record, which it
208
+ * notices within a second when it is idle and not at all while it is wedged; a signal does not
209
+ * depend on the daemon noticing, and a process left on the volume is what keeps it from
210
+ * detaching.
211
+ *
212
+ * A leftover keeps running while it is looked for, and a child it starts after the process table
213
+ * was read is in no table that was. So each one found is held with SIGSTOP and the table is read
214
+ * again, until a read names nothing that the read before did not already show stopped: a stopped
215
+ * process starts nothing, and whatever it started before it stopped is in every table read after.
216
+ * Discovery waits for stopped-census readiness; the exit grace starts only after SIGTERM.
217
+ * Only then does each get SIGTERM, and SIGCONT to act on it. A child whose parent exited before it
218
+ * could be held has lost its ancestry, so once the stopped-table barrier holds, the lease is asked
219
+ * again what works in it, including when that table names nothing, to recover reparented children.
220
+ */
221
+ export function leaseProcessesOn(host: ProcessHost): LeaseProcesses {
222
+ return {
223
+ async stopWorkingIn(directory) {
224
+ let working = (await host.workingIn(directory)).filter((pid) => pid !== process.pid);
225
+ if (working.length === 0) {
226
+ return [];
227
+ }
228
+ const known = new Map<number, ProcessEntry>();
229
+ let held = new Set<number>();
230
+ let failures: unknown[] | undefined;
231
+ try {
232
+ for (;;) {
233
+ const roots = [...working, ...known.keys()];
234
+ const current = withDescendants(await host.table(), roots).filter((entry) => entry.pid !== process.pid);
235
+ for (const entry of current) {
236
+ known.set(entry.pid, entry);
237
+ }
238
+ if (current.every((entry) => held.has(entry.pid) && STARTS_NOTHING.test(entry.stat))) {
239
+ working = (await host.workingIn(directory)).filter((pid) => pid !== process.pid);
240
+ if (working.every((pid) => held.has(pid))) {
241
+ break;
242
+ }
243
+ }
244
+ for (const entry of current) {
245
+ host.signal(entry.pid, 'SIGSTOP');
246
+ }
247
+ held = new Set(current.filter((entry) => STARTS_NOTHING.test(entry.stat)).map((entry) => entry.pid));
248
+ }
249
+ for (const entry of known.values()) {
250
+ host.signal(entry.pid, 'SIGTERM');
251
+ }
252
+ } catch (error) {
253
+ failures = [error];
254
+ } finally {
255
+ // SIGTERM is pending while stopped. One failed resume must not strand the other holds.
256
+ for (const entry of known.values()) {
257
+ try {
258
+ host.signal(entry.pid, 'SIGCONT');
259
+ } catch (error) {
260
+ failures ??= [];
261
+ failures.push(
262
+ new Error(
263
+ `${entry.pid} (${entry.command}): SIGCONT failed: ${error instanceof Error ? error.message : String(error)}`,
264
+ { cause: error },
265
+ ),
266
+ );
267
+ }
268
+ }
269
+ }
270
+ if (failures !== undefined) {
271
+ if (failures.length === 1) {
272
+ throw failures[0];
273
+ }
274
+ throw new AggregateError(
275
+ failures,
276
+ `processes working in ${directory}: ${failures.map((error) => (error instanceof Error ? error.message : String(error))).join('; ')}`,
277
+ );
278
+ }
279
+ const leftovers = [...known.values()];
280
+ try {
281
+ await awaitExit(leftovers, `processes working in ${directory}`, LEFTOVER_GRACE_MS);
282
+ } catch {
283
+ for (const entry of leftovers) {
284
+ host.signal(entry.pid, 'SIGKILL');
285
+ }
286
+ await awaitExit(leftovers, `processes working in ${directory} after SIGKILL`, LEFTOVER_GRACE_MS);
287
+ }
288
+ return leftovers.map((entry) => `${entry.pid} (${entry.command.slice(0, 160)})`);
289
+ },
290
+ };
291
+ }
292
+
293
+ export const hostLeaseProcesses: LeaseProcesses = leaseProcessesOn({
294
+ workingIn: pidsWorkingIn,
295
+ table: processTable,
296
+ signal: terminate,
297
+ });
298
+
299
+ export interface RamTempPaths {
300
+ /** Where DiskArbitration mounts the volume: `/Volumes/<volumeName>`. Short for sun_path (104 bytes). */
301
+ mountpoint: string;
302
+ lockFile: string;
303
+ /** APFS volume name; names the mountpoint. */
304
+ volumeName: string;
305
+ /** Where the volume is mounted to be marked before Disk Arbitration places it at `mountpoint`. */
306
+ staging: string;
307
+ /** Login name `hdiutil info` reports as the attaching user of this module's RAM disks. */
308
+ user: string;
309
+ }
310
+
311
+ export function ramTempPaths(user: { uid: number; username: string }): RamTempPaths {
312
+ const volumeName = `smoo-ram${RAM_TEMP_REVISION}-${user.uid}`;
313
+ return {
314
+ mountpoint: join('/Volumes', volumeName),
315
+ lockFile: `/private/tmp/${volumeName}.lock`,
316
+ volumeName,
317
+ staging: `/private/tmp/${volumeName}-new`,
318
+ user: user.username,
319
+ };
320
+ }
321
+
322
+ /** An attached RAM disk, as `hdiutil info` lists it. */
323
+ export interface RamDisk {
324
+ /** The whole disk (`/dev/diskN`): detaching it removes its container and volumes. */
325
+ physical: string;
326
+ sectors: number;
327
+ /** Login name of the user that attached it. */
328
+ user: string;
329
+ /** Where its volumes are mounted, if anywhere. */
330
+ mountpoints: string[];
331
+ }
332
+
333
+ export interface RamTempLease {
334
+ /** The task's TMPDIR: a directory on the volume that only this task uses. */
335
+ directory: string;
336
+ mountpoint: string;
337
+ capacityBytes: number;
338
+ }
339
+
340
+ export type RamTempAcquisition =
341
+ /**
342
+ * `held`: dead leases that could not be reclaimed, each with what still holds it. `reaped`: the
343
+ * processes of dead leases that were still working there and were stopped before the lease went.
344
+ */
345
+ | { kind: 'leased'; lease: RamTempLease; held: string[]; reaped: string[] }
346
+ /** Inside a cowshed sandbox: /private/tmp is not writable and no image can attach. */
347
+ | { kind: 'sandboxed'; detail: string };
348
+
349
+ /** A host command or filesystem step failed while the volume was being created, mounted or detached. */
350
+ type ProvisionFailed = { kind: 'provision-failed'; step: string; detail: string };
351
+
352
+ export type RamTempError =
353
+ | ProvisionFailed
354
+ /** A failed task left the volume (nearly) full: the likely cause of its failure. */
355
+ | { kind: 'volume-full'; mountpoint: string; capacityBytes: number; freeBytes: number };
356
+
357
+ export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
358
+
359
+ export function describeRamTempError(error: RamTempError): string {
360
+ switch (error.kind) {
361
+ case 'provision-failed':
362
+ return `RAM temp volume: ${error.step} failed: ${error.detail}`;
363
+ case 'volume-full':
364
+ return `RAM temp volume ${error.mountpoint} is full: ${Math.round(error.freeBytes / MIB)} MiB free of ${Math.round(error.capacityBytes / MIB)} MiB; raise RAM_TEMP_CAPACITY_BYTES in @smoothbricks/nx-plugin`;
365
+ }
366
+ }
367
+
368
+ /** One pass's host attachments: the disk images (backing file and whole disk) and the mount points. */
369
+ interface DiskImage {
370
+ readonly image: string;
371
+ readonly disk: string;
372
+ }
373
+
374
+ interface Inventory {
375
+ readonly images: readonly DiskImage[];
376
+ readonly mounts: readonly string[];
377
+ }
378
+
379
+ /** What is attached from below a path prefix, as one pass sees it. */
380
+ type Holders = (prefix: string) => Promise<Result<string[], RamTempError>>;
381
+
382
+ /** A caller's mark on a claim: its pid says whether it still runs, its token which of its operations made it. */
383
+ interface ClaimOwner {
384
+ readonly pid: number;
385
+ readonly token: string;
386
+ }
387
+
388
+ /** The volume is being created or detached: no other caller takes a lease or detaches meanwhile. */
389
+ interface LifecycleClaim {
390
+ readonly kind: 'create' | 'detach';
391
+ readonly owner: ClaimOwner;
392
+ }
393
+
394
+ /** One caller is settling the lease `name`, as it was when claimed: stopping, probing and removing it. */
395
+ interface LeaseClaim {
396
+ readonly name: string;
397
+ readonly identity: string;
398
+ readonly owner: ClaimOwner;
399
+ }
400
+
401
+ /** A dead lease proved held, and the proof a later pass validates instead of probing the host again. */
402
+ interface HeldEntry {
403
+ readonly lease: string;
404
+ readonly verdict: HeldVerdict;
405
+ }
406
+
407
+ /** What the lock admits changes to, published beside the lock file. Claims of dead owners are void. */
408
+ interface Ledger {
409
+ readonly lifecycle: LifecycleClaim | null;
410
+ readonly claims: readonly LeaseClaim[];
411
+ readonly held: readonly HeldEntry[];
412
+ }
413
+
414
+ const EMPTY_LEDGER: Ledger = { lifecycle: null, claims: [], held: [] };
415
+
416
+ /** The volume as one locked step finds it mounted. */
417
+ interface MountedVolume {
418
+ readonly capacity: number;
419
+ /** This attach of the volume: its root's and its marker's identity, never times that change while it is in use. */
420
+ readonly key: string;
421
+ readonly device: number;
422
+ /** The lease directories on it. */
423
+ readonly leases: readonly string[];
424
+ }
425
+
426
+ /**
427
+ * One acquire or release. `claimed`: the ledger as it last published holds one of its claims.
428
+ * `made`: the lease directory an acquire made, with its identity, until the caller has it.
429
+ */
430
+ interface Operation {
431
+ readonly owner: ClaimOwner;
432
+ claimed: boolean;
433
+ made: { readonly directory: string; readonly identity: string } | null;
434
+ }
435
+
436
+ /** What one locked step publishes, and what it found. */
437
+ interface Step<T> {
438
+ readonly ledger: Ledger;
439
+ readonly value: T;
440
+ }
441
+
442
+ /** A lease a caller claimed to settle, with its identity when claimed. */
443
+ interface Candidate {
444
+ readonly name: string;
445
+ readonly directory: string;
446
+ readonly identity: string;
447
+ /** The caller's own ending lease, whose task reaped it, rather than a dead one. */
448
+ readonly own: boolean;
449
+ }
450
+
451
+ /** A lease kept because something is attached below it, described for the task's output. */
452
+ interface HeldLease {
453
+ readonly name: string;
454
+ readonly text: string;
455
+ }
456
+
457
+ /** A claim step's finding: leases a cached verdict still proves held, and leases this caller now settles. */
458
+ interface Claimed {
459
+ readonly ledger: Ledger;
460
+ readonly held: readonly HeldLease[];
461
+ readonly candidates: readonly Candidate[];
462
+ }
463
+
464
+ /** What settling claimed leases found: those kept, the processes stopped, and the verdicts to publish. */
465
+ interface Settled {
466
+ readonly held: readonly HeldLease[];
467
+ readonly reaped: readonly string[];
468
+ readonly verdicts: readonly HeldEntry[];
469
+ }
470
+
471
+ /** How long a caller has waited on one lifecycle claim, and how many notices it has printed. */
472
+ interface ClaimWait {
473
+ readonly token: string;
474
+ readonly since: number;
475
+ readonly notices: number;
476
+ }
477
+
478
+ type Taken =
479
+ | { readonly kind: 'wait'; readonly claim: LifecycleClaim }
480
+ | { readonly kind: 'create' }
481
+ | {
482
+ readonly kind: 'leased';
483
+ readonly volume: MountedVolume;
484
+ readonly directory: string;
485
+ readonly held: readonly HeldLease[];
486
+ readonly candidates: readonly Candidate[];
487
+ };
488
+
489
+ type Releasing =
490
+ | { readonly kind: 'unmounted' }
491
+ | { readonly kind: 'wait'; readonly claim: LifecycleClaim }
492
+ | {
493
+ readonly kind: 'claimed';
494
+ readonly volume: MountedVolume;
495
+ readonly held: readonly HeldLease[];
496
+ readonly candidates: readonly Candidate[];
497
+ };
498
+
499
+ /** The lock refused for want of permission, as inside a cowshed sandbox; else a volume error. */
500
+ type LockedError = RamTempError | { kind: 'lock-denied'; detail: string };
501
+
502
+ export class RamTempVolume {
503
+ /** The RAM disk's size, which with the attaching user identifies this module's disks on the host. */
504
+ private readonly sectors: number;
505
+ /** The claims and held verdicts the lock admits changes to, beside the lock file. */
506
+ private readonly ledgerPath: string;
507
+
508
+ constructor(
509
+ private readonly paths: RamTempPaths,
510
+ private readonly capacityBytes: number,
511
+ private readonly commands: HostCommands,
512
+ private readonly pid: number = process.pid,
513
+ private readonly isAlive: (pid: number) => boolean = processIsAlive,
514
+ private readonly processes: LeaseProcesses = hostLeaseProcesses,
515
+ ) {
516
+ this.sectors = Math.ceil(capacityBytes / SECTOR_BYTES);
517
+ this.ledgerPath = `${paths.lockFile}.ledger`;
518
+ }
519
+
520
+ /** Take a lease: create the volume if no task holds one, and a private directory on it. */
521
+ async acquire(): Promise<Result<RamTempAcquisition, RamTempError>> {
522
+ const op: Operation = { owner: { pid: this.pid, token: randomUUID() }, claimed: false, made: null };
523
+ let result: Result<RamTempAcquisition, LockedError>;
524
+ try {
525
+ result = await this.lease(op);
526
+ } catch (error) {
527
+ result = failed('lease', errorText(error));
528
+ }
529
+ const ended = await this.end(op);
530
+ if (result.ok) {
531
+ if (ended.ok) {
532
+ return result;
533
+ }
534
+ // Its claims could not be dropped, so the lease is not handed out; the one made goes back.
535
+ const undone = await this.undo(op);
536
+ return { ok: false, error: alsoFailed(ended.error, undone) };
537
+ }
538
+ // The caller gets no lease, so the one made for it goes; a returned lease is never touched.
539
+ const cleanup = [...(ended.ok ? [] : [ended.error]), ...(await this.undo(op))];
540
+ if (result.error.kind !== 'lock-denied') {
541
+ return { ok: false, error: alsoFailed(result.error, cleanup) };
542
+ }
543
+ if (cleanup.length === 0) {
544
+ return { ok: true, value: { kind: 'sandboxed', detail: result.error.detail } };
545
+ }
546
+ const denied: ProvisionFailed = { kind: 'provision-failed', step: 'lock', detail: result.error.detail };
547
+ return { ok: false, error: alsoFailed(denied, cleanup) };
548
+ }
549
+
550
+ /** Make a lease directory for `op`'s caller, recorded so a failed acquire takes it back. */
551
+ private async make(op: Operation): Promise<string> {
552
+ const directory = await mkdtemp(join(this.paths.mountpoint, `${this.pid}-`));
553
+ const identity = await leaseIdentity(directory);
554
+ op.made = identity === null ? null : { directory, identity };
555
+ return directory;
556
+ }
557
+
558
+ /**
559
+ * Undo a failed acquire: take back the lease made for it, which may have been the volume's last
560
+ * with every release already past it, so then detach the volume as the last release would have.
561
+ * Answers what failed on the way.
562
+ */
563
+ private async undo(op: Operation): Promise<RamTempError[]> {
564
+ const made = op.made !== null;
565
+ const unmade = await this.unmake(op);
566
+ if (!unmade.ok) {
567
+ return [unmade.error];
568
+ }
569
+ if (!made) {
570
+ return [];
571
+ }
572
+ const idle = await this.locked(
573
+ op,
574
+ 'detach',
575
+ async (ledger, volume): Promise<Step<MountedVolume | null>> =>
576
+ volume !== null && volume.leases.length === 0 && ledger.lifecycle === null && ledger.claims.length === 0
577
+ ? { ledger: { ...ledger, lifecycle: { kind: 'detach', owner: op.owner } }, value: volume }
578
+ : { ledger, value: null },
579
+ );
580
+ const detached = !idle.ok || idle.value === null ? idle : await this.detach(op, idle.value);
581
+ const failures: RamTempError[] = [];
582
+ if (!detached.ok) {
583
+ failures.push(
584
+ detached.error.kind === 'lock-denied'
585
+ ? { kind: 'provision-failed', step: 'lock', detail: detached.error.detail }
586
+ : detached.error,
587
+ );
588
+ }
589
+ const ended = await this.end(op);
590
+ if (!ended.ok) {
591
+ failures.push(ended.error);
592
+ }
593
+ return failures;
594
+ }
595
+
596
+ /**
597
+ * Take back the lease made for a caller that never got it. No task has used it, so it is empty:
598
+ * `rmdir` removes only that, follows no link, and refuses a directory with a mount on it. A
599
+ * directory that is no longer the one made, by identity, is left where it is and named.
600
+ */
601
+ private async unmake(op: Operation): Promise<Result<void, RamTempError>> {
602
+ const made = op.made;
603
+ if (made === null) {
604
+ return { ok: true, value: undefined };
605
+ }
606
+ try {
607
+ const identity = await leaseIdentity(made.directory);
608
+ if (identity !== null && identity !== made.identity) {
609
+ return failed('lease rollback', `${made.directory} is no longer the lease made for this task; left in place`);
610
+ }
611
+ if (identity !== null) {
612
+ await rmdir(made.directory);
613
+ }
614
+ op.made = null;
615
+ return { ok: true, value: undefined };
616
+ } catch (error) {
617
+ return failed('lease rollback', `${made.directory}: ${errorText(error)}`);
618
+ }
619
+ }
620
+
621
+ private async lease(op: Operation): Promise<Result<RamTempAcquisition, LockedError>> {
622
+ let waited: ClaimWait | null = null;
623
+ for (;;) {
624
+ const taken = await this.locked(op, 'lease', async (ledger, volume): Promise<Step<Taken>> => {
625
+ if (ledger.lifecycle !== null) {
626
+ return { ledger, value: { kind: 'wait', claim: ledger.lifecycle } };
627
+ }
628
+ if (volume === null) {
629
+ return { ledger: { ...ledger, lifecycle: { kind: 'create', owner: op.owner } }, value: { kind: 'create' } };
630
+ }
631
+ // The lease exists before the lock drops, so no release finds the volume empty under it.
632
+ const directory = await this.make(op);
633
+ const claimed = await this.claim(ledger, volume, op.owner, null);
634
+ return {
635
+ ledger: claimed.ledger,
636
+ value: { kind: 'leased', volume, directory, held: claimed.held, candidates: claimed.candidates },
637
+ };
638
+ });
639
+ if (!taken.ok) {
640
+ return taken;
641
+ }
642
+ const value = taken.value;
643
+ switch (value.kind) {
644
+ case 'wait':
645
+ // Another caller is creating or detaching the volume: look again once it has.
646
+ waited = await this.waitOut(value.claim, waited);
647
+ continue;
648
+ case 'create':
649
+ return await this.create(op);
650
+ case 'leased': {
651
+ const settled = await this.settle(op, value.volume, value.candidates);
652
+ if (!settled.ok) {
653
+ return settled;
654
+ }
655
+ if (value.candidates.length > 0) {
656
+ const published = await this.locked(op, 'lease', async (ledger, current) => ({
657
+ ledger: settledLedger(ledger, current, op.owner, settled.value.verdicts),
658
+ value: undefined,
659
+ }));
660
+ if (!published.ok) {
661
+ return published;
662
+ }
663
+ }
664
+ return {
665
+ ok: true,
666
+ value: {
667
+ kind: 'leased',
668
+ lease: {
669
+ directory: value.directory,
670
+ mountpoint: this.paths.mountpoint,
671
+ capacityBytes: value.volume.capacity,
672
+ },
673
+ held: [...value.held, ...settled.value.held].map((lease) => lease.text),
674
+ reaped: [...settled.value.reaped],
675
+ },
676
+ };
677
+ }
678
+ }
679
+ }
680
+ }
681
+
682
+ /** With this caller's creation claim published: provision the volume, then take the first lease on it. */
683
+ private async create(op: Operation): Promise<Result<RamTempAcquisition, LockedError>> {
684
+ const provisioned = await this.provisionVolume();
685
+ if (!provisioned.ok) {
686
+ return provisioned;
687
+ }
688
+ const placed = await this.locked(
689
+ op,
690
+ 'lease',
691
+ async (ledger, volume): Promise<Step<Result<string, RamTempError>>> => {
692
+ const next = withoutClaimsOf(ledger, op.owner);
693
+ if (ledger.lifecycle?.owner.token !== op.owner.token) {
694
+ return {
695
+ ledger: next,
696
+ value: failed(
697
+ 'create',
698
+ `the creation claim in ${this.ledgerPath} was lost while the volume was provisioned`,
699
+ ),
700
+ };
701
+ }
702
+ if (volume === null) {
703
+ return {
704
+ ledger: next,
705
+ value: failed('create', `${this.paths.mountpoint} is not the marked volume once provisioned`),
706
+ };
707
+ }
708
+ return { ledger: next, value: { ok: true, value: await this.make(op) } };
709
+ },
710
+ );
711
+ if (!placed.ok) {
712
+ return placed;
713
+ }
714
+ if (!placed.value.ok) {
715
+ return placed.value;
716
+ }
717
+ return {
718
+ ok: true,
719
+ value: {
720
+ kind: 'leased',
721
+ lease: { directory: placed.value.value, mountpoint: this.paths.mountpoint, capacityBytes: this.capacityBytes },
722
+ held: [],
723
+ reaped: [],
724
+ },
725
+ };
726
+ }
727
+
728
+ /**
729
+ * Stop what the task left working in its lease, before the lease ends: the processes whose
730
+ * working directory is in it and everything they started, answered as `<pid> (<command>)`.
731
+ * Runs outside the volume's lock, which one lease's leftovers must not hold up the others
732
+ * behind, and costs a scan of every process only when the lease still holds anything.
733
+ */
734
+ async reap(lease: RamTempLease): Promise<Result<string[], RamTempError>> {
735
+ try {
736
+ const entries = await readdir(lease.directory).catch((error: unknown) => {
737
+ if (errorCode(error) === 'ENOENT') return [];
738
+ throw error;
739
+ });
740
+ if (entries.length === 0) {
741
+ return { ok: true, value: [] };
742
+ }
743
+ return { ok: true, value: await this.processes.stopWorkingIn(lease.directory) };
744
+ } catch (error) {
745
+ return failed('reap', errorText(error));
746
+ }
747
+ }
748
+
749
+ /** End a lease; the last lease detaches the volume, returning its RAM. */
750
+ async release(lease: RamTempLease): Promise<Result<void, RamTempError>> {
751
+ const op: Operation = { owner: { pid: this.pid, token: randomUUID() }, claimed: false, made: null };
752
+ let result: Result<void, LockedError>;
753
+ try {
754
+ result = await this.releaseLease(op, basename(lease.directory));
755
+ } catch (error) {
756
+ result = failed('release', errorText(error));
757
+ }
758
+ const ended = await this.end(op);
759
+ if (result.ok) {
760
+ return ended;
761
+ }
762
+ const primary: RamTempError =
763
+ result.error.kind === 'lock-denied'
764
+ ? { kind: 'provision-failed', step: 'lock', detail: result.error.detail }
765
+ : result.error;
766
+ return { ok: false, error: alsoFailed(primary, ended.ok ? [] : [ended.error]) };
767
+ }
768
+
769
+ private async releaseLease(op: Operation, own: string): Promise<Result<void, LockedError>> {
770
+ let waited: ClaimWait | null = null;
771
+ for (;;) {
772
+ const taken = await this.locked(op, 'release', async (ledger, volume): Promise<Step<Releasing>> => {
773
+ if (volume === null) {
774
+ return { ledger, value: { kind: 'unmounted' } };
775
+ }
776
+ if (ledger.lifecycle !== null) {
777
+ return { ledger, value: { kind: 'wait', claim: ledger.lifecycle } };
778
+ }
779
+ const claimed = await this.claim(ledger, volume, op.owner, own);
780
+ return {
781
+ ledger: claimed.ledger,
782
+ value: { kind: 'claimed', volume, held: claimed.held, candidates: claimed.candidates },
783
+ };
784
+ });
785
+ if (!taken.ok) {
786
+ return taken;
787
+ }
788
+ const value = taken.value;
789
+ switch (value.kind) {
790
+ case 'unmounted':
791
+ return { ok: true, value: undefined };
792
+ case 'wait':
793
+ waited = await this.waitOut(value.claim, waited);
794
+ continue;
795
+ case 'claimed': {
796
+ const settled = await this.settle(op, value.volume, value.candidates);
797
+ if (!settled.ok) {
798
+ return settled;
799
+ }
800
+ const idle = await this.locked(op, 'release', async (ledger, current): Promise<Step<boolean>> => {
801
+ const next = settledLedger(ledger, current, op.owner, settled.value.verdicts);
802
+ // The last lease is gone, and nobody else settles one or changes the volume: detach it.
803
+ return current?.key === value.volume.key &&
804
+ current.leases.length === 0 &&
805
+ next.lifecycle === null &&
806
+ next.claims.length === 0
807
+ ? { ledger: { ...next, lifecycle: { kind: 'detach', owner: op.owner } }, value: true }
808
+ : { ledger: next, value: false };
809
+ });
810
+ if (!idle.ok) {
811
+ return idle;
812
+ }
813
+ const kept = [...value.held, ...settled.value.held].find((lease) => lease.name === own);
814
+ if (kept !== undefined) {
815
+ return failed('release', kept.text);
816
+ }
817
+ return idle.value ? await this.detach(op, value.volume) : { ok: true, value: undefined };
818
+ }
819
+ }
820
+ }
821
+ }
822
+
823
+ /**
824
+ * Wait out another caller's creation or detach. Liveness of its owner is its pid's, so a crashed
825
+ * owner whose pid was reused holds every caller here; past each `CLAIM_WAIT_NOTICE_MS` on the same
826
+ * claim, stderr names it with the wait so far.
827
+ */
828
+ private async waitOut(claim: LifecycleClaim, waited: ClaimWait | null): Promise<ClaimWait> {
829
+ const now = performance.now();
830
+ const wait = waited?.token === claim.owner.token ? waited : { token: claim.owner.token, since: now, notices: 0 };
831
+ const elapsed = now - wait.since;
832
+ const due = Math.floor(elapsed / CLAIM_WAIT_NOTICE_MS);
833
+ if (due > wait.notices) {
834
+ process.stderr.write(
835
+ `RAM temp volume: waited ${(elapsed / 1000).toFixed(1)} s on the ${claim.kind} claim of pid ${claim.owner.pid} (token ${claim.owner.token}) in ${this.ledgerPath}; if that pid is not ${claim.kind === 'create' ? 'creating' : 'detaching'} ${this.paths.mountpoint}, remove the ledger once no task uses the volume\n`,
836
+ );
837
+ }
838
+ await sleep(LOCK_RETRY_MS);
839
+ return { ...wait, notices: Math.max(wait.notices, due) };
840
+ }
841
+
842
+ /** After a failed task: whether the volume ran out of space, which is then the error to report. */
843
+ async fullness(lease: RamTempLease): Promise<RamTempError | null> {
844
+ try {
845
+ const fs = await statfs(lease.mountpoint);
846
+ const freeBytes = fs.bavail * fs.bsize;
847
+ return freeBytes < FULL_FREE_BYTES
848
+ ? { kind: 'volume-full', mountpoint: lease.mountpoint, capacityBytes: lease.capacityBytes, freeBytes }
849
+ : null;
850
+ } catch {
851
+ return null;
852
+ }
853
+ }
854
+
855
+ private async lock(): Promise<Result<{ close(): Promise<void> }, { code: string | undefined; message: string }>> {
856
+ for (;;) {
857
+ try {
858
+ const handle = await open(
859
+ this.paths.lockFile,
860
+ constants.O_RDWR | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK | O_EXLOCK,
861
+ 0o600,
862
+ );
863
+ return { ok: true, value: handle };
864
+ } catch (error) {
865
+ const code = errorCode(error);
866
+ if (code !== 'EAGAIN' && code !== 'EWOULDBLOCK') {
867
+ return { ok: false, error: { code, message: errorText(error) } };
868
+ }
869
+ // Blocking O_EXLOCK opens consume libuv workers. Four waiters can occupy the entire
870
+ // pool while the holder's read/close waits for a worker, deadlocking every host task.
871
+ await sleep(LOCK_RETRY_MS);
872
+ }
873
+ }
874
+ }
875
+
876
+ /** Drop whatever claims `op` still holds: an operation that failed part way leaves none behind it. */
877
+ private async end(op: Operation): Promise<Result<void, RamTempError>> {
878
+ if (!op.claimed) {
879
+ return { ok: true, value: undefined };
880
+ }
881
+ const dropped = await this.locked(op, 'claim release', async (ledger) => ({
882
+ ledger: withoutClaimsOf(ledger, op.owner),
883
+ value: undefined,
884
+ }));
885
+ if (dropped.ok) {
886
+ return dropped;
887
+ }
888
+ return dropped.error.kind === 'lock-denied'
889
+ ? failed('lock', dropped.error.detail)
890
+ : { ok: false, error: dropped.error };
891
+ }
892
+
893
+ /**
894
+ * One step under the lock: read the ledger, void the claims of dead owners and the verdicts of
895
+ * another volume or a lease that is gone, observe the volume, and publish what `change` returns.
896
+ * `change` reads metadata and takes or names directories; it runs no host command.
897
+ */
898
+ private async locked<T>(
899
+ op: Operation,
900
+ step: string,
901
+ change: (ledger: Ledger, volume: MountedVolume | null) => Promise<Step<T>>,
902
+ ): Promise<Result<T, LockedError>> {
903
+ const lock = await this.lock();
904
+ if (!lock.ok) {
905
+ return lock.error.code === 'EPERM'
906
+ ? { ok: false, error: { kind: 'lock-denied', detail: `${this.paths.lockFile}: ${lock.error.message}` } }
907
+ : failed('lock', lock.error.message);
908
+ }
909
+ try {
910
+ const read = await this.readLedger();
911
+ if (!read.ok) {
912
+ return read;
913
+ }
914
+ const volume = await this.observe();
915
+ const next = await change(prune(read.value.ledger, volume, this.isAlive), volume);
916
+ const text = ledgerText(next.ledger);
917
+ if (text !== (read.value.text ?? ledgerText(EMPTY_LEDGER))) {
918
+ await publishLedger(this.ledgerPath, text);
919
+ }
920
+ op.claimed =
921
+ next.ledger.lifecycle?.owner.token === op.owner.token ||
922
+ next.ledger.claims.some((claim) => claim.owner.token === op.owner.token);
923
+ return { ok: true, value: next.value };
924
+ } catch (error) {
925
+ return failed(step, errorText(error));
926
+ } finally {
927
+ await lock.value.close();
928
+ }
929
+ }
930
+
931
+ /** The ledger as published, and its text; none yet is an empty one. Only this module writes it, whole. */
932
+ private async readLedger(): Promise<Result<{ ledger: Ledger; text: string | null }, RamTempError>> {
933
+ let text: string;
934
+ try {
935
+ const handle = await open(this.ledgerPath, constants.O_RDONLY | constants.O_NOFOLLOW);
936
+ try {
937
+ text = await handle.readFile('utf8');
938
+ } finally {
939
+ await handle.close();
940
+ }
941
+ } catch (error) {
942
+ if (errorCode(error) === 'ENOENT') {
943
+ return { ok: true, value: { ledger: EMPTY_LEDGER, text: null } };
944
+ }
945
+ return failed('ledger', `${this.ledgerPath}: ${errorText(error)}`);
946
+ }
947
+ // Claims that cannot be read cannot be honoured, so no lease or volume change is safe until it is
948
+ // removed; only this module writes it, in one rename, so a malformed one is not its own.
949
+ const refused = (detail: string) =>
950
+ failed<{ ledger: Ledger; text: string | null }>(
951
+ 'ledger',
952
+ `${this.ledgerPath} ${detail}; remove it once no task uses the volume`,
953
+ );
954
+ let wire: unknown;
955
+ try {
956
+ wire = JSON.parse(text);
957
+ } catch (error) {
958
+ return refused(`is not JSON: ${errorText(error)}`);
959
+ }
960
+ const ledger = parseLedger(wire);
961
+ return ledger === undefined ? refused("is not this module's ledger") : { ok: true, value: { ledger, text } };
962
+ }
963
+
964
+ /**
965
+ * The volume when it is mounted at the mountpoint, identified by its marker; else null. Its key
966
+ * names this attach: the root's and the marker's identity and birth, and the marker's change
967
+ * time, which nothing changes once it is written. The root's own times change with every lease.
968
+ */
969
+ private async observe(): Promise<MountedVolume | null> {
970
+ const markerPath = join(this.paths.mountpoint, MARKER_FILE);
971
+ const marker = await readFile(markerPath, 'utf8').catch(() => null);
972
+ if (marker?.trim() !== this.paths.volumeName) {
973
+ return null;
974
+ }
975
+ const [root, parent, mark] = await Promise.all([
976
+ stat(this.paths.mountpoint, { bigint: true }),
977
+ stat(join(this.paths.mountpoint, '..'), { bigint: true }),
978
+ lstat(markerPath, { bigint: true }),
979
+ ]);
980
+ if (root.dev === parent.dev) {
981
+ return null;
982
+ }
983
+ const [fs, names] = await Promise.all([statfs(this.paths.mountpoint), readdir(this.paths.mountpoint)]);
984
+ return {
985
+ capacity: fs.blocks * fs.bsize,
986
+ key: [
987
+ `root ${root.dev}:${root.ino}:${root.birthtimeNs}`,
988
+ `marker ${mark.dev}:${mark.ino}:${mark.birthtimeNs}:${mark.ctimeNs}`,
989
+ ].join(' '),
990
+ device: Number(root.dev),
991
+ leases: names.filter((name) => LEASE_NAME.test(name)),
992
+ };
993
+ }
994
+
995
+ /**
996
+ * Under the lock: claim `own`, the caller's ending lease if any, and every dead lease no other
997
+ * caller is settling. A dead lease whose cached verdict still validates is named held and left
998
+ * unclaimed: that proof costs `lstat` calls, not a host-wide probe, so no caller waits on it.
999
+ */
1000
+ private async claim(ledger: Ledger, volume: MountedVolume, owner: ClaimOwner, own: string | null): Promise<Claimed> {
1001
+ const held: HeldLease[] = [];
1002
+ const candidates: Candidate[] = [];
1003
+ const claims = [...ledger.claims];
1004
+ let verdicts = ledger.held;
1005
+ for (const name of volume.leases) {
1006
+ if ((name !== own && this.isAlive(leasePid(name))) || ledger.claims.some((claim) => claim.name === name)) {
1007
+ continue;
1008
+ }
1009
+ const directory = join(this.paths.mountpoint, name);
1010
+ const identity = await leaseIdentity(directory);
1011
+ if (identity === null) {
1012
+ continue;
1013
+ }
1014
+ const cached = verdicts.find((entry) => entry.lease === name);
1015
+ if (cached !== undefined) {
1016
+ const valid = await validateHeldVerdict(cached.verdict, heldContext(volume, name, identity));
1017
+ if (valid.ok && valid.value) {
1018
+ held.push({
1019
+ name,
1020
+ text: holdingText(
1021
+ directory,
1022
+ cached.verdict.holders.map((proof) => proof.description),
1023
+ ),
1024
+ });
1025
+ continue;
1026
+ }
1027
+ // Changed or unreadable: the verdict goes, and the lease is probed afresh.
1028
+ verdicts = verdicts.filter((entry) => entry !== cached);
1029
+ }
1030
+ claims.push({ name, identity, owner });
1031
+ candidates.push({ name, directory, identity, own: name === own });
1032
+ }
1033
+ return { ledger: { ...ledger, claims, held: verdicts }, held, candidates };
1034
+ }
1035
+
1036
+ /**
1037
+ * Outside the lock: settle the leases this caller claimed. The processes every dead one still
1038
+ * runs are stopped first, and only then is the pass's one inventory read, so no inventory older
1039
+ * than a lease's settled census approves its removal. Anything attached from below a lease keeps
1040
+ * it: an image backed by a file there would be left pinned to a deleted file, and detaching it
1041
+ * here would race the owner that releases it under its own lease; a mount there is backed
1042
+ * elsewhere — a cowshed workspace adopted from a fixture checkout, say — and `rm -r` would
1043
+ * delete its contents through the mount. A kept lease gets a verdict to publish, when its
1044
+ * holders have cheap lifetime keys. A lease nothing holds is removed once the lock confirms it
1045
+ * is as claimed.
1046
+ */
1047
+ private async settle(
1048
+ op: Operation,
1049
+ volume: MountedVolume,
1050
+ candidates: readonly Candidate[],
1051
+ ): Promise<Result<Settled, LockedError>> {
1052
+ if (candidates.length === 0) {
1053
+ return { ok: true, value: { held: [], reaped: [], verdicts: [] } };
1054
+ }
1055
+ const reaped: string[] = [];
1056
+ for (const candidate of candidates) {
1057
+ // Its task is gone, so what works in it is what that task left: stopped before the lease
1058
+ // is removed, even where the removal is refused below. A task reaps its own (`reap`).
1059
+ if (!candidate.own && (await readdir(candidate.directory)).length > 0) {
1060
+ reaped.push(...(await this.processes.stopWorkingIn(candidate.directory)));
1061
+ }
1062
+ }
1063
+ const inventory = await this.readInventory();
1064
+ if (!inventory.ok) {
1065
+ return inventory;
1066
+ }
1067
+ const held: HeldLease[] = [];
1068
+ const verdicts: HeldEntry[] = [];
1069
+ const removable: Candidate[] = [];
1070
+ for (const candidate of candidates) {
1071
+ const below = candidatesBelow(inventory.value, `${candidate.directory}/`);
1072
+ if (below.length === 0) {
1073
+ removable.push(candidate);
1074
+ continue;
1075
+ }
1076
+ const by = below.map((holder) => holder.description);
1077
+ held.push({ name: candidate.name, text: holdingText(candidate.directory, by) });
1078
+ // No verdict for a holder without a cheap lifetime key: the next pass probes it again.
1079
+ const captured = await captureHeldVerdict(heldContext(volume, candidate.name, candidate.identity), below);
1080
+ if (captured.ok && captured.value !== undefined) {
1081
+ verdicts.push({ lease: candidate.name, verdict: captured.value });
1082
+ }
1083
+ }
1084
+ if (removable.length > 0) {
1085
+ const confirmed = await this.locked(
1086
+ op,
1087
+ 'reclaim',
1088
+ async (ledger, current): Promise<Step<Candidate[]>> => ({
1089
+ ledger,
1090
+ value: current?.key === volume.key ? await this.unchanged(ledger, op.owner, removable) : [],
1091
+ }),
1092
+ );
1093
+ if (!confirmed.ok) {
1094
+ return confirmed;
1095
+ }
1096
+ for (const candidate of confirmed.value) {
1097
+ // Nothing holds the lease, so its directories may be made removable first: `rm -r` cannot
1098
+ // empty a readonly one. Only this volume's device is changed (see prepareForRemoval).
1099
+ await prepareForRemoval(candidate.directory, volume.device);
1100
+ await rm(candidate.directory, { recursive: true, force: true });
1101
+ }
1102
+ }
1103
+ return { ok: true, value: { held, reaped, verdicts } };
1104
+ }
1105
+
1106
+ /**
1107
+ * Under the lock: the claimed leases still as claimed — this caller's claim on the same
1108
+ * directory, and a task still gone. Any other is left for a fresh look, never removed.
1109
+ */
1110
+ private async unchanged(ledger: Ledger, owner: ClaimOwner, candidates: readonly Candidate[]): Promise<Candidate[]> {
1111
+ const confirmed: Candidate[] = [];
1112
+ for (const candidate of candidates) {
1113
+ const claimed = ledger.claims.some(
1114
+ (claim) =>
1115
+ claim.name === candidate.name && claim.identity === candidate.identity && claim.owner.token === owner.token,
1116
+ );
1117
+ if (
1118
+ claimed &&
1119
+ (candidate.own || !this.isAlive(leasePid(candidate.name))) &&
1120
+ (await leaseIdentity(candidate.directory)) === candidate.identity
1121
+ ) {
1122
+ confirmed.push(candidate);
1123
+ }
1124
+ }
1125
+ return confirmed;
1126
+ }
1127
+
1128
+ /** Detach what earlier creators left, then attach and provision the volume. */
1129
+ private async provisionVolume(): Promise<Result<void, RamTempError>> {
1130
+ const strays = await this.reclaimStrays(this.holdersPass());
1131
+ if (!strays.ok) {
1132
+ return strays;
1133
+ }
1134
+ const attached = await this.commands.run('/usr/bin/hdiutil', ['attach', '-nomount', `ram://${this.sectors}`]);
1135
+ if (attached.status !== 0) {
1136
+ // A deadlined attach took its helper's process group down with it; one that attached
1137
+ // regardless is a stray the next creator detaches.
1138
+ return failed('hdiutil attach', commandText(attached));
1139
+ }
1140
+ const physical = /^(\/dev\/disk\d+)\b/.exec(attached.stdout)?.[1];
1141
+ if (!physical) {
1142
+ return failed('hdiutil attach', `no device in: ${attached.stdout.trim()}`);
1143
+ }
1144
+ const provisioned = await this.provision(physical);
1145
+ if (provisioned.ok) {
1146
+ return provisioned;
1147
+ }
1148
+ const detached = await this.commands.run('/usr/bin/hdiutil', ['detach', '-force', physical]);
1149
+ // The detach takes every volume of the disk with it. What it leaves at the staging path is a bare
1150
+ // directory on the host's Data volume: removed here, and already absent is done.
1151
+ const detachFailure =
1152
+ detached.status === 0
1153
+ ? null
1154
+ : `hdiutil detach -force ${physical} then failed (${commandText(detached)}), so it stays attached until the next creator reclaims it`;
1155
+ const stagingFailure = await rmdir(this.paths.staging).then(
1156
+ () => null,
1157
+ (error: unknown) =>
1158
+ errorCode(error) === 'ENOENT' ? null : `rmdir ${this.paths.staging} then failed (${errorText(error)})`,
1159
+ );
1160
+ const failures = [detachFailure, stagingFailure].filter((failure): failure is string => failure !== null);
1161
+ return failures.length === 0
1162
+ ? provisioned
1163
+ : failed(provisioned.error.step, [provisioned.error.detail, ...failures].join('; '));
1164
+ }
1165
+
1166
+ /**
1167
+ * Create the volume under its final name, mount it with `mount_apfs` at the private staging
1168
+ * directory, and mark it there. Then `umount` that private mount and let `diskutil mount` place
1169
+ * the volume at the mountpoint: the only call that does, and it runs after the marker, so the
1170
+ * volume never reaches `/Volumes` unmarked. Nothing is renamed (see the module comment). The
1171
+ * staging mount is the kernel's, so the kernel releases it: a Disk Arbitration unmount waits in
1172
+ * its one queue behind its own probe of the fresh RAM disk (5.1 s for the `zfs` probe alone in
1173
+ * `log stream`; 6.5–6.7 s per unmount against 64–69 ms for `umount`, measured 2026-10-15). A
1174
+ * crash before the final mount leaves the volume attached at the staging directory or
1175
+ * unmounted; the next creator's reclaim detaches either.
1176
+ */
1177
+ private async provision(physical: string): Promise<Result<void, ProvisionFailed>> {
1178
+ const container = await this.commands.run('/usr/sbin/diskutil', ['apfs', 'createContainer', physical]);
1179
+ const containerDisk = operationDisk(container.stdout);
1180
+ if (container.status !== 0 || !containerDisk) {
1181
+ return failed('diskutil apfs createContainer', commandText(container));
1182
+ }
1183
+ const added = await this.commands.run('/usr/sbin/diskutil', [
1184
+ 'apfs',
1185
+ 'addVolume',
1186
+ containerDisk,
1187
+ 'APFS',
1188
+ this.paths.volumeName,
1189
+ '-nomount',
1190
+ ]);
1191
+ const volume = operationDisk(added.stdout);
1192
+ if (added.status !== 0 || !volume) {
1193
+ return failed('diskutil apfs addVolume', commandText(added));
1194
+ }
1195
+ const staging = this.paths.staging;
1196
+ try {
1197
+ await mkdir(staging, { recursive: true });
1198
+ } catch (error) {
1199
+ return failed('staging directory', errorText(error));
1200
+ }
1201
+ // `noowners`: a fresh volume's root is owned by root, and the marker write is denied without it.
1202
+ const mounted = await this.commands.run('/sbin/mount_apfs', ['-o', 'nobrowse,noowners', `/dev/${volume}`, staging]);
1203
+ if (mounted.status !== 0) {
1204
+ return failed('mount_apfs (staging)', commandText(mounted));
1205
+ }
1206
+ const atStaging = await this.expectMounted(volume, staging, 'mount_apfs (staging)');
1207
+ if (!atStaging.ok) {
1208
+ return atStaging;
1209
+ }
1210
+ try {
1211
+ await writeFile(join(staging, MARKER_FILE), `${this.paths.volumeName}\n`);
1212
+ } catch (error) {
1213
+ return failed('marker', errorText(error));
1214
+ }
1215
+ const unmounted = await this.commands.run('/sbin/umount', [staging]);
1216
+ if (unmounted.status !== 0) {
1217
+ return failed('umount (staging)', commandText(unmounted));
1218
+ }
1219
+ // No -mountPoint: DiskArbitration names the mountpoint after the volume, and appends " 1" when a
1220
+ // /Volumes entry already holds the name.
1221
+ const placing = await this.commands.run('/usr/sbin/diskutil', ['mount', '-mountOptions', 'nobrowse', volume]);
1222
+ if (placing.status !== 0) {
1223
+ return failed('diskutil mount', commandText(placing));
1224
+ }
1225
+ const placed = await this.expectMounted(volume, this.paths.mountpoint, 'diskutil mount');
1226
+ if (!placed.ok) {
1227
+ return placed;
1228
+ }
1229
+ try {
1230
+ await rmdir(staging);
1231
+ } catch (error) {
1232
+ return failed('staging directory', errorText(error));
1233
+ }
1234
+ return placed;
1235
+ }
1236
+
1237
+ private async expectMounted(volume: string, expected: string, step: string): Promise<Result<void, ProvisionFailed>> {
1238
+ const table = await this.commands.run('/sbin/mount', []);
1239
+ if (table.status !== 0) {
1240
+ return failed('mount (mount table)', commandText(table));
1241
+ }
1242
+ const point = new RegExp(`^/dev/${volume} on (.+) \\(`, 'm').exec(table.stdout)?.[1];
1243
+ return point === expected
1244
+ ? { ok: true, value: undefined }
1245
+ : failed(step, `${volume} mounted at ${point ?? 'nowhere'}, expected ${expected}`);
1246
+ }
1247
+
1248
+ /** This module's RAM disks attached on the host: this user's, of this volume's exact size, mounted nowhere else. */
1249
+ private async attached(): Promise<Result<RamDisk[], ProvisionFailed>> {
1250
+ const info = await this.commands.run('/usr/bin/hdiutil', ['info']);
1251
+ if (info.status !== 0) {
1252
+ return failed('hdiutil info', commandText(info));
1253
+ }
1254
+ const ours = (point: string) => {
1255
+ // DiskArbitration's " 1" suffix: a volume that found its name taken.
1256
+ const name = point.replace(/ \d+$/, '');
1257
+ // hdiutil lists a mount by the kernel's path; `staging` is written as that path, so it compares exactly.
1258
+ return name === this.paths.mountpoint || name === this.paths.staging;
1259
+ };
1260
+ return {
1261
+ ok: true,
1262
+ value: ramDisksIn(info.stdout).filter(
1263
+ (disk) => disk.user === this.paths.user && disk.sectors === this.sectors && disk.mountpoints.every(ours),
1264
+ ),
1265
+ };
1266
+ }
1267
+
1268
+ /**
1269
+ * Detach what earlier creators left attached: no marked volume is mounted, so every RAM disk of
1270
+ * this volume is debris — unformatted, staged, or mounted without its marker. One carrying a
1271
+ * lease, or with anything attached below it, is still in use and stops the creation instead.
1272
+ */
1273
+ private async reclaimStrays(holders: Holders): Promise<Result<void, RamTempError>> {
1274
+ const strays = await this.attached();
1275
+ if (!strays.ok) {
1276
+ return strays;
1277
+ }
1278
+ for (const disk of strays.value) {
1279
+ for (const point of disk.mountpoints) {
1280
+ const leases = await readdir(point).then(
1281
+ (names) => ({ ok: true as const, names: names.filter((name) => LEASE_NAME.test(name)) }),
1282
+ (error: unknown) => ({ ok: false as const, detail: errorText(error) }),
1283
+ );
1284
+ if (!leases.ok) {
1285
+ return failed('reclaim', `${disk.physical} at ${point}: ${leases.detail}`);
1286
+ }
1287
+ if (leases.names.length > 0) {
1288
+ return failed(
1289
+ 'reclaim',
1290
+ `${disk.physical} at ${point} has no marker but carries leases ${leases.names.join(', ')}; not detached`,
1291
+ );
1292
+ }
1293
+ const held = await holders(`${point}/`);
1294
+ if (!held.ok) {
1295
+ return held;
1296
+ }
1297
+ if (held.value.length > 0) {
1298
+ return failed('reclaim', holdingText(point, held.value));
1299
+ }
1300
+ }
1301
+ const detached = await this.commands.run(
1302
+ '/usr/bin/hdiutil',
1303
+ ['detach', '-force', disk.physical],
1304
+ STRAY_DETACH_DEADLINE_MS,
1305
+ );
1306
+ if (detached.status !== 0) {
1307
+ return failed(`hdiutil detach (stray ${disk.physical})`, commandText(detached));
1308
+ }
1309
+ }
1310
+ return { ok: true, value: undefined };
1311
+ }
1312
+
1313
+ /**
1314
+ * With this caller's detach claim published, which no caller takes a lease past. Every lease is
1315
+ * gone, so nothing below the volume should be attached; whatever is would lose its backing file
1316
+ * to the detach. The lock confirms the volume, still empty, and the claim before it goes.
1317
+ */
1318
+ private async detach(op: Operation, volume: MountedVolume): Promise<Result<void, LockedError>> {
1319
+ const inventory = await this.readInventory();
1320
+ if (!inventory.ok) {
1321
+ return inventory;
1322
+ }
1323
+ const held = candidatesBelow(inventory.value, `${this.paths.mountpoint}/`).map((holder) => holder.description);
1324
+ if (held.length > 0) {
1325
+ return failed('detach', holdingText(this.paths.mountpoint, held));
1326
+ }
1327
+ const disks = await this.attached();
1328
+ if (!disks.ok) {
1329
+ return disks;
1330
+ }
1331
+ const disk = disks.value.find((candidate) => candidate.mountpoints.includes(this.paths.mountpoint));
1332
+ if (!disk) {
1333
+ return failed(
1334
+ 'detach',
1335
+ `hdiutil info lists no RAM disk of ${this.paths.user} with ${this.sectors} sectors mounted at ${this.paths.mountpoint}`,
1336
+ );
1337
+ }
1338
+ const unchanged = await this.locked(
1339
+ op,
1340
+ 'detach',
1341
+ async (ledger, current): Promise<Step<boolean>> => ({
1342
+ ledger,
1343
+ value:
1344
+ ledger.lifecycle?.owner.token === op.owner.token &&
1345
+ current?.key === volume.key &&
1346
+ current.leases.length === 0,
1347
+ }),
1348
+ );
1349
+ if (!unchanged.ok) {
1350
+ return unchanged;
1351
+ }
1352
+ if (!unchanged.value) {
1353
+ // A lease or another attach arrived despite the claim: the volume stays for it.
1354
+ return { ok: true, value: undefined };
1355
+ }
1356
+ let detached = await this.commands.run('/usr/bin/hdiutil', ['detach', disk.physical]);
1357
+ if (detached.status !== 0) {
1358
+ detached = await this.commands.run('/usr/bin/hdiutil', ['detach', '-force', disk.physical]);
1359
+ }
1360
+ if (detached.status !== 0) {
1361
+ return failed('hdiutil detach', commandText(detached));
1362
+ }
1363
+ // DiskArbitration removes the /Volumes directory it created when the volume goes.
1364
+ return { ok: true, value: undefined };
1365
+ }
1366
+
1367
+ /** The host's attachments as one pass reads them: one `ioreg` run and one `mount` run. */
1368
+ private async readInventory(): Promise<Result<Inventory, RamTempError>> {
1369
+ const registry = await this.commands.run('/usr/sbin/ioreg', ['-r', '-c', 'AppleDiskImageDevice', '-l', '-w0']);
1370
+ if (registry.status !== 0) {
1371
+ return failed('ioreg (attached disk images)', commandText(registry));
1372
+ }
1373
+ const mounts = await this.commands.run('/sbin/mount', []);
1374
+ if (mounts.status !== 0) {
1375
+ return failed('mount (mount table)', commandText(mounts));
1376
+ }
1377
+ return { ok: true, value: { images: diskImages(registry.stdout), mounts: mountPoints(mounts.stdout) } };
1378
+ }
1379
+
1380
+ /**
1381
+ * The holder check of one creation pass. The first check reads the attachments and every later
1382
+ * check in the pass reads the same ones, so a pass runs `ioreg` and `mount` once however many
1383
+ * disks it visits. What is attached from below a prefix: images whose backing file is there,
1384
+ * and mounts. `hdiutil info` omits attached images while another image attaches or detaches
1385
+ * (measured by cowshed's scratch-root sweep), and tests attach images concurrently.
1386
+ */
1387
+ private holdersPass(): Holders {
1388
+ let inventory: Promise<Result<Inventory, RamTempError>> | undefined;
1389
+ return async (prefix) => {
1390
+ inventory ??= this.readInventory();
1391
+ const read = await inventory;
1392
+ return read.ok
1393
+ ? { ok: true, value: candidatesBelow(read.value, prefix).map((holder) => holder.description) }
1394
+ : read;
1395
+ };
1396
+ }
1397
+ }
1398
+
1399
+ /** What is attached from below `prefix` in `inventory`: images whose backing file is there, and mounts. */
1400
+ function candidatesBelow(inventory: Inventory, prefix: string): HeldCandidate[] {
1401
+ return [
1402
+ ...inventory.images
1403
+ .filter((entry) => entry.image.startsWith(prefix))
1404
+ .map(
1405
+ (entry): HeldCandidate => ({
1406
+ kind: 'image',
1407
+ imagePath: entry.image,
1408
+ diskPath: `/dev/${entry.disk}`,
1409
+ description: `${entry.image} (/dev/${entry.disk})`,
1410
+ }),
1411
+ ),
1412
+ ...inventory.mounts
1413
+ .filter((point) => point.startsWith(prefix))
1414
+ .map((point): HeldCandidate => ({ kind: 'mount', mountpoint: point, description: `${point} (mounted)` })),
1415
+ ];
1416
+ }
1417
+
1418
+ /** The pid a lease directory is named after: whether its task is alive. */
1419
+ function leasePid(name: string): number {
1420
+ return Number(LEASE_NAME.exec(name)?.[1]);
1421
+ }
1422
+
1423
+ /** A lease directory's identity: device, inode and birth, which a directory made again at its path does not share. */
1424
+ async function leaseIdentity(directory: string): Promise<string | null> {
1425
+ try {
1426
+ const info = await lstat(directory, { bigint: true });
1427
+ return `${info.dev}:${info.ino}:${info.birthtimeNs}`;
1428
+ } catch (error) {
1429
+ if (errorCode(error) === 'ENOENT') {
1430
+ return null;
1431
+ }
1432
+ throw error;
1433
+ }
1434
+ }
1435
+
1436
+ /** What a held verdict is bound to: this attach of the volume, and this lease directory on it. */
1437
+ function heldContext(volume: MountedVolume, name: string, identity: string): HeldContext {
1438
+ return { volumeKey: volume.key, leaseKey: `${name} ${identity}`, ramDevice: String(volume.device) };
1439
+ }
1440
+
1441
+ /**
1442
+ * The ledger with the claims of dead owners voided, and the verdicts kept only for leases still on
1443
+ * this attach of the volume. A claim's owner is judged as a lease's is, by its pid.
1444
+ */
1445
+ function prune(ledger: Ledger, volume: MountedVolume | null, isAlive: (pid: number) => boolean): Ledger {
1446
+ return {
1447
+ lifecycle: ledger.lifecycle !== null && isAlive(ledger.lifecycle.owner.pid) ? ledger.lifecycle : null,
1448
+ claims: ledger.claims.filter((claim) => isAlive(claim.owner.pid)),
1449
+ held:
1450
+ volume === null
1451
+ ? []
1452
+ : ledger.held.filter(
1453
+ (entry) => entry.verdict.context.volumeKey === volume.key && volume.leases.includes(entry.lease),
1454
+ ),
1455
+ };
1456
+ }
1457
+
1458
+ function withoutClaimsOf(ledger: Ledger, owner: ClaimOwner): Ledger {
1459
+ return {
1460
+ lifecycle: ledger.lifecycle?.owner.token === owner.token ? null : ledger.lifecycle,
1461
+ claims: ledger.claims.filter((claim) => claim.owner.token !== owner.token),
1462
+ held: ledger.held,
1463
+ };
1464
+ }
1465
+
1466
+ /** The ledger once a caller has settled its claims: they are dropped, and its verdicts replace older ones. */
1467
+ function settledLedger(
1468
+ ledger: Ledger,
1469
+ volume: MountedVolume | null,
1470
+ owner: ClaimOwner,
1471
+ verdicts: readonly HeldEntry[],
1472
+ ): Ledger {
1473
+ const current = verdicts.filter(
1474
+ (entry) => volume !== null && entry.verdict.context.volumeKey === volume.key && volume.leases.includes(entry.lease),
1475
+ );
1476
+ const settled = withoutClaimsOf(ledger, owner);
1477
+ return {
1478
+ ...settled,
1479
+ held: [...settled.held.filter((entry) => !current.some((fresh) => fresh.lease === entry.lease)), ...current],
1480
+ };
1481
+ }
1482
+
1483
+ /** The ledger's wire form, version 1. */
1484
+ function ledgerText(ledger: Ledger): string {
1485
+ return `${JSON.stringify({ version: 1, lifecycle: ledger.lifecycle, claims: ledger.claims, held: ledger.held })}\n`;
1486
+ }
1487
+
1488
+ /** Publish the ledger in one rename, so no reader, and no crash, ever leaves half of it. */
1489
+ async function publishLedger(path: string, text: string): Promise<void> {
1490
+ const staged = `${path}.${randomUUID()}`;
1491
+ try {
1492
+ await writeFile(staged, text, { flag: 'wx', mode: 0o600 });
1493
+ await rename(staged, path);
1494
+ } catch (error) {
1495
+ await rm(staged, { force: true }).catch((cleanup: unknown) => {
1496
+ throw new AggregateError(
1497
+ [error, cleanup],
1498
+ `${staged}: ${errorText(error)}; removing it failed: ${errorText(cleanup)}`,
1499
+ );
1500
+ });
1501
+ throw error;
1502
+ }
1503
+ }
1504
+
1505
+ /**
1506
+ * The ledger in its wire form; undefined when it is not one. A malformed held verdict is dropped,
1507
+ * so its lease is probed afresh; it never stands for a lease nothing holds.
1508
+ */
1509
+ function parseLedger(value: unknown): Ledger | undefined {
1510
+ if (!isRecord(value) || value.version !== 1) {
1511
+ return undefined;
1512
+ }
1513
+ const { lifecycle: lifecycleWire, claims: claimsWire, held: heldWire } = value;
1514
+ if (!Array.isArray(claimsWire) || !Array.isArray(heldWire)) {
1515
+ return undefined;
1516
+ }
1517
+ let lifecycle: LifecycleClaim | null = null;
1518
+ if (lifecycleWire !== null) {
1519
+ if (!isRecord(lifecycleWire)) {
1520
+ return undefined;
1521
+ }
1522
+ const { kind } = lifecycleWire;
1523
+ const owner = parseOwner(lifecycleWire.owner);
1524
+ if ((kind !== 'create' && kind !== 'detach') || owner === undefined) {
1525
+ return undefined;
1526
+ }
1527
+ lifecycle = { kind, owner };
1528
+ }
1529
+ const claims: LeaseClaim[] = [];
1530
+ for (const entry of claimsWire) {
1531
+ if (!isRecord(entry)) {
1532
+ return undefined;
1533
+ }
1534
+ const { name, identity } = entry;
1535
+ const owner = parseOwner(entry.owner);
1536
+ if (typeof name !== 'string' || !LEASE_NAME.test(name) || typeof identity !== 'string' || owner === undefined) {
1537
+ return undefined;
1538
+ }
1539
+ claims.push({ name, identity, owner });
1540
+ }
1541
+ const held: HeldEntry[] = [];
1542
+ for (const entry of heldWire) {
1543
+ if (!isRecord(entry)) {
1544
+ continue;
1545
+ }
1546
+ const { lease } = entry;
1547
+ const verdict = parseHeldVerdict(entry.verdict);
1548
+ if (typeof lease === 'string' && verdict !== undefined) {
1549
+ held.push({ lease, verdict });
1550
+ }
1551
+ }
1552
+ return { lifecycle, claims, held };
1553
+ }
1554
+
1555
+ function parseOwner(value: unknown): ClaimOwner | undefined {
1556
+ if (!isRecord(value)) {
1557
+ return undefined;
1558
+ }
1559
+ const { pid, token } = value;
1560
+ return typeof pid === 'number' && Number.isInteger(pid) && pid > 0 && typeof token === 'string'
1561
+ ? { pid, token }
1562
+ : undefined;
1563
+ }
1564
+
1565
+ /** `directory` stays, with the volume under it: something attached below it still reads its files. */
1566
+ function holdingText(directory: string, holders: readonly string[]): string {
1567
+ return `${directory} is kept: ${holders.join(', ')} still attached from below it; detach through its owner`;
1568
+ }
1569
+
1570
+ /** `primary` stays the error; what its cleanup then failed to undo is named after it, not dropped. */
1571
+ function alsoFailed(primary: RamTempError, cleanup: readonly RamTempError[]): RamTempError {
1572
+ if (cleanup.length === 0) {
1573
+ return primary;
1574
+ }
1575
+ const after = `cleanup then failed: ${cleanup.map(describeRamTempError).join('; ')}`;
1576
+ switch (primary.kind) {
1577
+ case 'provision-failed':
1578
+ return { ...primary, detail: `${primary.detail}; ${after}` };
1579
+ case 'volume-full':
1580
+ return { kind: 'provision-failed', step: 'cleanup', detail: `${describeRamTempError(primary)}; ${after}` };
1581
+ }
1582
+ }
1583
+
1584
+ /**
1585
+ * Give the owner `rwx` on `directory` and on every directory below it, keeping every other mode
1586
+ * bit, so `rm -r` can empty them. Only directories are changed: a link is never descended
1587
+ * (`withFileTypes` reports it as a link), and each directory is opened `O_NOFOLLOW` and changed
1588
+ * through that handle, never by its path. A directory on another device than `device` is refused
1589
+ * before it is changed. Node has no `openat`, so entries are named by path; the walk checks each
1590
+ * directory's identity again after its `readdir`, and a directory swapped under its path stops it.
1591
+ */
1592
+ async function prepareForRemoval(directory: string, device: number): Promise<void> {
1593
+ let handle: FileHandle;
1594
+ try {
1595
+ handle = await open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
1596
+ } catch (error) {
1597
+ // Already gone: `rm -f` ignores that too.
1598
+ if (errorCode(error) === 'ENOENT') {
1599
+ return;
1600
+ }
1601
+ throw error;
1602
+ }
1603
+ try {
1604
+ const info = await handle.stat();
1605
+ if (info.dev !== device) {
1606
+ throw new Error(`${directory} is on device ${info.dev}, not the lease's device ${device}; not changed`);
1607
+ }
1608
+ if ((info.mode & 0o700) !== 0o700) {
1609
+ await handle.chmod((info.mode & 0o7777) | 0o700).catch((error: unknown) => {
1610
+ throw new Error(`${directory}: chmod u+rwx failed: ${errorText(error)}`);
1611
+ });
1612
+ }
1613
+ const entries = await readdir(directory, { withFileTypes: true });
1614
+ const named = await lstat(directory);
1615
+ if (named.dev !== info.dev || named.ino !== info.ino) {
1616
+ throw new Error(`${directory} was replaced while it was walked; not changed further`);
1617
+ }
1618
+ for (const entry of entries) {
1619
+ if (entry.isDirectory()) {
1620
+ await prepareForRemoval(join(directory, entry.name), device);
1621
+ }
1622
+ }
1623
+ } finally {
1624
+ await handle.close();
1625
+ }
1626
+ }
1627
+
1628
+ /**
1629
+ * Every disk image in `ioreg -r -c AppleDiskImageDevice -l -w0` output. Each device starts a
1630
+ * `+-o AppleDiskImageDevice` block; the first `BSD Name` below it is the image's whole disk.
1631
+ */
1632
+ function diskImages(registry: string): DiskImage[] {
1633
+ const images: DiskImage[] = [];
1634
+ for (const block of registry.split(/^\+-o AppleDiskImageDevice/m)) {
1635
+ const url = /"DiskImageURL" = "file:\/\/([^"]+)"/.exec(block)?.[1];
1636
+ const disk = /"BSD Name" = "(disk\d+)"/.exec(block)?.[1];
1637
+ if (url !== undefined && disk !== undefined) {
1638
+ images.push({ image: decodeURIComponent(url), disk });
1639
+ }
1640
+ }
1641
+ return images;
1642
+ }
1643
+
1644
+ /** Mount points in `mount` output (`<device> on <path> (<options>)`). */
1645
+ function mountPoints(table: string): string[] {
1646
+ const points: string[] = [];
1647
+ for (const line of table.split('\n')) {
1648
+ const point = /^\S+ on (.+) \([^)]*\)$/.exec(line)?.[1];
1649
+ if (point !== undefined) {
1650
+ points.push(point);
1651
+ }
1652
+ }
1653
+ return points;
1654
+ }
1655
+
1656
+ /**
1657
+ * Every image in `ioreg` output whose `DiskImageURL` names a file under `prefix`, as
1658
+ * `<backing file> (/dev/diskN)`.
1659
+ */
1660
+ export function imagesBackedUnder(registry: string, prefix: string): string[] {
1661
+ return diskImages(registry)
1662
+ .filter((entry) => entry.image.startsWith(prefix))
1663
+ .map((entry) => `${entry.image} (/dev/${entry.disk})`);
1664
+ }
1665
+
1666
+ /** Mount points in `mount` output (`<device> on <path> (<options>)`) that lie under `prefix`. */
1667
+ export function mountsBelow(table: string, prefix: string): string[] {
1668
+ return mountPoints(table).filter((point) => point.startsWith(prefix));
1669
+ }
1670
+
1671
+ /** The disk `diskutil apfs` reports it created: "Disk from APFS operation: disk271". */
1672
+ export function operationDisk(stdout: string): string | null {
1673
+ return /^Disk from APFS operation: (disk\d+(?:s\d+)?)$/m.exec(stdout)?.[1] ?? null;
1674
+ }
1675
+
1676
+ /**
1677
+ * The RAM disks in `hdiutil info` output. Images are separated by a row of `=`; a RAM disk's
1678
+ * `image-path` is `ram://<sectors>`, and its entity rows are `<dev>\t<content hint>\t<mountpoint>`,
1679
+ * the whole disk first.
1680
+ */
1681
+ export function ramDisksIn(info: string): RamDisk[] {
1682
+ const disks: RamDisk[] = [];
1683
+ for (const block of info.split(/^=+$/m)) {
1684
+ const sectors = /^image-path\s*:\s*ram:\/\/(\d+)\s*$/m.exec(block)?.[1];
1685
+ const user = /^mounting user\s*:\s*(\S+)\s*$/m.exec(block)?.[1];
1686
+ const entities = [...block.matchAll(/^(\/dev\/disk\d+(?:s\d+)*)\t[^\t\n]*(?:\t([^\n]*))?$/gm)];
1687
+ const physical = entities[0]?.[1];
1688
+ if (sectors === undefined || user === undefined || physical === undefined) {
1689
+ continue;
1690
+ }
1691
+ const mountpoints = entities.flatMap((entity) => {
1692
+ const point = entity[2]?.trimEnd();
1693
+ return point ? [point] : [];
1694
+ });
1695
+ disks.push({ physical, sectors: Number(sectors), user, mountpoints });
1696
+ }
1697
+ return disks;
1698
+ }
1699
+
1700
+ /**
1701
+ * A disk child that DiskArbitration never answers would wedge the task, and every task queued
1702
+ * behind the lock, forever; measured: `diskutil mount` hung past 60 s while the host's
1703
+ * DiskArbitration was saturated. Cowshed bounds its disk children the same way.
1704
+ */
1705
+ const HOST_COMMAND_DEADLINE_MS = 120_000;
1706
+
1707
+ /**
1708
+ * How long one creator waits on a stray's detach before it reports the stray by name and
1709
+ * gives the create claim back. A stray detach that makes no progress is DiskArbitration's
1710
+ * wedge, not this volume's: at 120 s a chain of creators each waited the full bound on the
1711
+ * same stray and the claim never moved. The detach itself is never killed (below); the
1712
+ * bound is on the wait, and the next creator finds the stray gone or names it again.
1713
+ */
1714
+ const STRAY_DETACH_DEADLINE_MS = 30_000;
1715
+
1716
+ /** Disk tools delegate their lease and process lifetime to cowshed, with one image policy. */
1717
+ export function diskCommand(
1718
+ file: string,
1719
+ args: readonly string[],
1720
+ deadlineMs: number,
1721
+ ): { args: string[]; lifetime: 'stop-wait' | 'facade-owned' } | null {
1722
+ const program = basename(file);
1723
+ if (program !== 'hdiutil' && program !== 'diskutil') {
1724
+ return null;
1725
+ }
1726
+ // Match SystemCommandRunner's protected-image policy, including its case-sensitive verbs.
1727
+ const image = program === 'hdiutil' || args[0] === 'image' || args[0] === 'eject';
1728
+ return {
1729
+ args: image
1730
+ ? ['disk-command', program, '--', ...args]
1731
+ : ['disk-command', program, '--deadline-ms', String(deadlineMs), '--', ...args],
1732
+ lifetime: image ? 'stop-wait' : 'facade-owned',
1733
+ };
1734
+ }
1735
+
1736
+ /**
1737
+ * The variable naming the cowshed executable that runs `cowshed disk-command`. Unset, it is the installed `cowshed`
1738
+ * on PATH. A repository that tests its own cowshed sets it, on the targets that test it, to that checkout's build:
1739
+ * an installed cowshed that predates a command its own checkout added would fail the very code under test.
1740
+ */
1741
+ export const COWSHED_EXECUTABLE_ENV = 'COWSHED_EXECUTABLE';
1742
+
1743
+ /** Whether this process already said the cowshed gateway is not there to lease disk commands. */
1744
+ let gatewayAbsenceSaid = false;
1745
+
1746
+ /**
1747
+ * How long this process stops asking a gateway that predates leases before it asks again: each
1748
+ * ask costs that gateway's 2 s of silence, and `cowshed setup` may replace it meanwhile. A gateway
1749
+ * that predates only `alone` leases is asked shared for as long.
1750
+ */
1751
+ const PREDATES_RECHECK_MS = 60_000;
1752
+
1753
+ /** When this process last found the gateway at each control socket predating leases, or `alone` ones. */
1754
+ const predatesSeen = new Map<string, { at: number; what: 'leases' | 'alone' }>();
1755
+
1756
+ /**
1757
+ * hdiutil and diskutil delegate process lifetime and disk leasing to cowshed: safe commands
1758
+ * pass their total budget and wait for the facade's actual exit after child reap. Only image
1759
+ * commands have a caller stop-wait deadline; killing an attach or detach can leak its kernel
1760
+ * device until reboot. Never acquire a second lease around the facade. Other leased helpers
1761
+ * take their lease here. Recorded lease waits ask for `alone`; an older gateway is asked
1762
+ * shared at once, and for a minute after.
1763
+ */
1764
+ export function createHostCommands(
1765
+ defaultDeadlineMs: number = HOST_COMMAND_DEADLINE_MS,
1766
+ gatewaySocket: string = GATEWAY_SOCKET,
1767
+ wantedShare: PhaseShare = recordedShare(),
1768
+ cowshed = process.env[COWSHED_EXECUTABLE_ENV] ?? 'cowshed',
1769
+ ): HostCommands {
1770
+ return {
1771
+ async run(file, args, callDeadlineMs) {
1772
+ const deadlineMs = callDeadlineMs ?? defaultDeadlineMs;
1773
+ const disk = diskCommand(file, args, deadlineMs);
1774
+ if (disk !== null) {
1775
+ return runBounded(cowshed, disk.args, deadlineMs, disk.lifetime);
1776
+ }
1777
+ const diskClass = diskClassOf(file);
1778
+ const seen = predatesSeen.get(gatewaySocket);
1779
+ const predates = seen !== undefined && Date.now() - seen.at < PREDATES_RECHECK_MS ? seen.what : null;
1780
+ if (diskClass === null || predates === 'leases') {
1781
+ return runBounded(file, args, deadlineMs);
1782
+ }
1783
+ const command = [file, ...args].join(' ');
1784
+ const bounds = { ackMs: 2_000, afterCloseMs: 5_000, grantMs: deadlineMs };
1785
+ const share = predates === 'alone' ? 'shared' : wantedShare;
1786
+ let lease = await takeDiskLease(gatewaySocket, diskClass, command, bounds, share);
1787
+ if (!lease.granted && lease.cause === 'predates-field' && share === 'alone') {
1788
+ predatesSeen.set(gatewaySocket, { at: Date.now(), what: 'alone' });
1789
+ lease = await takeDiskLease(gatewaySocket, diskClass, command, bounds, 'shared');
1790
+ }
1791
+ if (!lease.granted) {
1792
+ if (lease.cause === 'predates') {
1793
+ predatesSeen.set(gatewaySocket, { at: Date.now(), what: 'leases' });
1794
+ }
1795
+ if (!(lease.cause === 'absent' && gatewayAbsenceSaid)) {
1796
+ gatewayAbsenceSaid ||= lease.cause === 'absent';
1797
+ process.stderr.write(`RAM temp volume: ${file} runs without cowshed's disk lease: ${lease.reason}\n`);
1798
+ }
1799
+ }
1800
+ try {
1801
+ return await runBounded(file, args, deadlineMs);
1802
+ } finally {
1803
+ if (lease.granted) {
1804
+ lease.release();
1805
+ }
1806
+ }
1807
+ },
1808
+ };
1809
+ }
1810
+
1811
+ function runBounded(
1812
+ file: string,
1813
+ args: readonly string[],
1814
+ deadlineMs: number,
1815
+ lifetime: 'kill' | 'stop-wait' | 'facade-owned' = 'kill',
1816
+ ): Promise<CommandOutput> {
1817
+ // `Promise.withResolvers` would read better but needs lib es2024; this package inherits lib
1818
+ // es2022 from tsconfig.base.json.
1819
+ let resolve!: (output: CommandOutput) => void;
1820
+ const promise = new Promise<CommandOutput>((settled) => {
1821
+ resolve = settled;
1822
+ });
1823
+ // Ordinary helpers own their process group. The facade alone owns disk-child termination,
1824
+ // reap and lease custody; a wrapper's exit or signal is not the disk child's exit or signal.
1825
+ const child = spawn(file, [...args], { detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
1826
+ const stdout: Buffer[] = [];
1827
+ const stderr: Buffer[] = [];
1828
+ child.stdout.on('data', (chunk: Buffer) => stdout.push(chunk));
1829
+ child.stderr.on('data', (chunk: Buffer) => stderr.push(chunk));
1830
+ const text = (chunks: Buffer[]) => Buffer.concat(chunks).toString('utf8');
1831
+ // Safe disk commands have no Node timer: the CLI owns the total admission + child budget,
1832
+ // kills only its owned safe child, and returns after reap. Protected image output is already
1833
+ // file-backed in cowshed, so only that caller may close its pipes and stop waiting.
1834
+ const timer =
1835
+ lifetime === 'facade-owned'
1836
+ ? undefined
1837
+ : setTimeout(() => {
1838
+ if (lifetime === 'stop-wait') {
1839
+ child.stdout.destroy();
1840
+ child.stderr.destroy();
1841
+ child.unref();
1842
+ // A piped child's streams are sockets; only a socket can be unref'd.
1843
+ if (child.stdout instanceof Socket) child.stdout.unref();
1844
+ if (child.stderr instanceof Socket) child.stderr.unref();
1845
+ resolve({
1846
+ status: 1,
1847
+ stdout: text(stdout),
1848
+ stderr: [
1849
+ text(stderr),
1850
+ `no answer within ${deadlineMs} ms; cowshed command ${child.pid ?? 'unknown'} left running, not killed: disk-image operations must finish to release their kernel devices`,
1851
+ ]
1852
+ .filter(Boolean)
1853
+ .join('\n'),
1854
+ });
1855
+ return;
1856
+ }
1857
+ resolve({
1858
+ status: 1,
1859
+ stdout: text(stdout),
1860
+ stderr: `no answer within ${deadlineMs} ms; ${killGroup(child)}`,
1861
+ });
1862
+ }, deadlineMs);
1863
+ child.on('error', (error) => {
1864
+ clearTimeout(timer);
1865
+ resolve({ status: 1, stdout: text(stdout), stderr: error.message });
1866
+ });
1867
+ child.on('close', (code, signal) => {
1868
+ clearTimeout(timer);
1869
+ const error = text(stderr);
1870
+ resolve({
1871
+ status: code ?? 1,
1872
+ stdout: text(stdout),
1873
+ stderr: signal === null ? error : [error, `killed by ${signal}`].filter(Boolean).join('\n'),
1874
+ });
1875
+ });
1876
+ return promise;
1877
+ }
1878
+
1879
+ /** SIGKILL the child's whole process group; what happened, for the error. */
1880
+ function killGroup(child: ChildProcess): string {
1881
+ if (child.pid === undefined) {
1882
+ return 'never started';
1883
+ }
1884
+ try {
1885
+ process.kill(-child.pid, 'SIGKILL');
1886
+ return `killed process group ${child.pid}`;
1887
+ } catch (error) {
1888
+ return `killing process group ${child.pid} failed: ${errorText(error)}`;
1889
+ }
1890
+ }
1891
+
1892
+ function processIsAlive(pid: number): boolean {
1893
+ try {
1894
+ process.kill(pid, 0);
1895
+ return true;
1896
+ } catch (error) {
1897
+ // EPERM: alive, owned by someone else.
1898
+ return errorCode(error) === 'EPERM';
1899
+ }
1900
+ }
1901
+
1902
+ function failed<T>(step: string, detail: string): Result<T, ProvisionFailed> {
1903
+ return { ok: false, error: { kind: 'provision-failed', step, detail } };
1904
+ }
1905
+
1906
+ function commandText(output: CommandOutput): string {
1907
+ return `exit ${output.status}: ${(output.stderr || output.stdout).trim()}`;
1908
+ }
1909
+
1910
+ function errorCode(error: unknown): string | undefined {
1911
+ return typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string'
1912
+ ? error.code
1913
+ : undefined;
1914
+ }
1915
+
1916
+ function errorText(error: unknown): string {
1917
+ return error instanceof Error ? error.message : String(error);
1918
+ }