@smoothbricks/nx-plugin 0.5.6 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (440) hide show
  1. package/README.md +1095 -360
  2. package/dist/.build-inputs.json +138 -0
  3. package/dist/bin/smoo-nx-cargo-toolchain.d.ts +3 -0
  4. package/dist/bin/smoo-nx-cargo-toolchain.d.ts.map +1 -0
  5. package/dist/bin/smoo-nx-cargo-toolchain.js +8 -0
  6. package/dist/bin/smoo-nx-forbidden-spellings.d.ts +3 -0
  7. package/dist/bin/smoo-nx-forbidden-spellings.d.ts.map +1 -0
  8. package/dist/bin/smoo-nx-forbidden-spellings.js +32 -0
  9. package/dist/bin/smoo-nx-nextest-timings.d.ts +3 -0
  10. package/dist/bin/smoo-nx-nextest-timings.d.ts.map +1 -0
  11. package/dist/bin/smoo-nx-nextest-timings.js +28 -0
  12. package/dist/bounded-test-policy.d.ts +1 -1
  13. package/dist/bounded-test-policy.d.ts.map +1 -1
  14. package/dist/bounded-test-policy.js +14 -15
  15. package/dist/build-state-output-policy.d.ts +95 -1
  16. package/dist/build-state-output-policy.d.ts.map +1 -1
  17. package/dist/build-state-output-policy.js +368 -30
  18. package/dist/bun-lock-scope.d.ts +44 -0
  19. package/dist/bun-lock-scope.d.ts.map +1 -0
  20. package/dist/bun-lock-scope.js +97 -0
  21. package/dist/cargo-build-script-env.d.ts +49 -0
  22. package/dist/cargo-build-script-env.d.ts.map +1 -0
  23. package/dist/cargo-build-script-env.js +324 -0
  24. package/dist/cargo-closure-input.d.ts +31 -4
  25. package/dist/cargo-closure-input.d.ts.map +1 -1
  26. package/dist/cargo-closure-input.js +66 -6
  27. package/dist/cargo-retention-hook.d.ts +17 -0
  28. package/dist/cargo-retention-hook.d.ts.map +1 -0
  29. package/dist/cargo-retention-hook.js +85 -0
  30. package/dist/cargo-source-hash.d.ts +25 -7
  31. package/dist/cargo-source-hash.d.ts.map +1 -1
  32. package/dist/cargo-source-hash.js +108 -43
  33. package/dist/cargo-toolchain-paths.d.ts +40 -0
  34. package/dist/cargo-toolchain-paths.d.ts.map +1 -0
  35. package/dist/cargo-toolchain-paths.js +84 -0
  36. package/dist/cargo-toolchain-policy.d.ts +25 -8
  37. package/dist/cargo-toolchain-policy.d.ts.map +1 -1
  38. package/dist/cargo-toolchain-policy.js +39 -5
  39. package/dist/cargo-workspace.d.ts +10 -4
  40. package/dist/cargo-workspace.d.ts.map +1 -1
  41. package/dist/cargo-workspace.js +65 -95
  42. package/dist/cross-check-policy.d.ts +9 -9
  43. package/dist/cross-check-policy.d.ts.map +1 -1
  44. package/dist/cross-check-policy.js +11 -11
  45. package/dist/disk-command-policy.d.ts.map +1 -1
  46. package/dist/disk-command-policy.js +1 -0
  47. package/dist/ensure-built-receipt.d.ts +13 -5
  48. package/dist/ensure-built-receipt.d.ts.map +1 -1
  49. package/dist/ensure-built-receipt.js +126 -47
  50. package/dist/ensure-built-witness.d.ts +27 -8
  51. package/dist/ensure-built-witness.d.ts.map +1 -1
  52. package/dist/ensure-built-witness.js +45 -15
  53. package/dist/ensure-built.d.ts.map +1 -1
  54. package/dist/ensure-built.js +9 -1
  55. package/dist/eslint-config-closure.d.ts +7 -0
  56. package/dist/eslint-config-closure.d.ts.map +1 -0
  57. package/dist/eslint-config-closure.js +346 -0
  58. package/dist/executors/all-verdicts/executor.d.ts +35 -0
  59. package/dist/executors/all-verdicts/executor.d.ts.map +1 -0
  60. package/dist/executors/all-verdicts/executor.js +133 -0
  61. package/dist/executors/all-verdicts/schema.d.ts +10 -0
  62. package/dist/executors/all-verdicts/schema.d.ts.map +1 -0
  63. package/dist/executors/all-verdicts/schema.js +2 -0
  64. package/dist/executors/bounded-exec/bounds.d.ts +56 -0
  65. package/dist/executors/bounded-exec/bounds.d.ts.map +1 -0
  66. package/dist/executors/bounded-exec/bounds.js +43 -0
  67. package/dist/executors/bounded-exec/cpu-pool.d.ts +33 -36
  68. package/dist/executors/bounded-exec/cpu-pool.d.ts.map +1 -1
  69. package/dist/executors/bounded-exec/cpu-pool.js +54 -119
  70. package/dist/executors/bounded-exec/executor.d.ts +19 -12
  71. package/dist/executors/bounded-exec/executor.d.ts.map +1 -1
  72. package/dist/executors/bounded-exec/executor.js +371 -239
  73. package/dist/executors/bounded-exec/gateway-lease.d.ts +22 -19
  74. package/dist/executors/bounded-exec/gateway-lease.d.ts.map +1 -1
  75. package/dist/executors/bounded-exec/gateway-lease.js +81 -28
  76. package/dist/executors/bounded-exec/hang-diagnostics.d.ts +18 -1
  77. package/dist/executors/bounded-exec/hang-diagnostics.d.ts.map +1 -1
  78. package/dist/executors/bounded-exec/hang-diagnostics.js +148 -30
  79. package/dist/executors/bounded-exec/lease-wait.d.ts +43 -0
  80. package/dist/executors/bounded-exec/lease-wait.d.ts.map +1 -0
  81. package/dist/executors/bounded-exec/lease-wait.js +68 -0
  82. package/dist/executors/bounded-exec/lock-wait.d.ts +51 -0
  83. package/dist/executors/bounded-exec/lock-wait.d.ts.map +1 -0
  84. package/dist/executors/bounded-exec/lock-wait.js +108 -0
  85. package/dist/executors/bounded-exec/owned-subtree.d.ts +84 -0
  86. package/dist/executors/bounded-exec/owned-subtree.d.ts.map +1 -0
  87. package/dist/executors/bounded-exec/owned-subtree.js +178 -0
  88. package/dist/executors/bounded-exec/progress.d.ts +4 -1
  89. package/dist/executors/bounded-exec/progress.d.ts.map +1 -1
  90. package/dist/executors/bounded-exec/progress.js +5 -2
  91. package/dist/executors/bounded-exec/ram-attach.d.ts +19 -0
  92. package/dist/executors/bounded-exec/ram-attach.d.ts.map +1 -0
  93. package/dist/executors/bounded-exec/ram-attach.js +207 -0
  94. package/dist/executors/bounded-exec/ram-detach.d.ts +25 -0
  95. package/dist/executors/bounded-exec/ram-detach.d.ts.map +1 -0
  96. package/dist/executors/bounded-exec/ram-detach.js +207 -0
  97. package/dist/executors/bounded-exec/ram-temp-fixtures.d.ts +76 -0
  98. package/dist/executors/bounded-exec/ram-temp-fixtures.d.ts.map +1 -1
  99. package/dist/executors/bounded-exec/ram-temp-fixtures.js +296 -0
  100. package/dist/executors/bounded-exec/ram-temp.d.ts +388 -88
  101. package/dist/executors/bounded-exec/ram-temp.d.ts.map +1 -1
  102. package/dist/executors/bounded-exec/ram-temp.js +1213 -399
  103. package/dist/executors/bounded-exec/run-cpu-pool.d.ts +4 -4
  104. package/dist/executors/bounded-exec/run-cpu-pool.d.ts.map +1 -1
  105. package/dist/executors/bounded-exec/run-cpu-pool.js +20 -30
  106. package/dist/executors/bounded-exec/runner-hook.js +14 -5
  107. package/dist/executors/bounded-exec/runner-lifecycle.d.ts +14 -1
  108. package/dist/executors/bounded-exec/runner-lifecycle.d.ts.map +1 -1
  109. package/dist/executors/bounded-exec/runner-lifecycle.js +27 -6
  110. package/dist/executors/bounded-exec/{cpu-tokens.d.ts → runner-sizing.d.ts} +14 -42
  111. package/dist/executors/bounded-exec/runner-sizing.d.ts.map +1 -0
  112. package/dist/executors/bounded-exec/{cpu-tokens.js → runner-sizing.js} +5 -35
  113. package/dist/executors/bounded-exec/runtime-pin.d.ts +73 -0
  114. package/dist/executors/bounded-exec/runtime-pin.d.ts.map +1 -0
  115. package/dist/executors/bounded-exec/runtime-pin.js +167 -0
  116. package/dist/executors/bounded-exec/schema.d.ts +18 -1
  117. package/dist/executors/bounded-exec/schema.d.ts.map +1 -1
  118. package/dist/executors/bounded-exec/verdict.d.ts +40 -11
  119. package/dist/executors/bounded-exec/verdict.d.ts.map +1 -1
  120. package/dist/executors/bounded-exec/verdict.js +88 -19
  121. package/dist/executors/cargo-zigbuild/executor.d.ts +21 -0
  122. package/dist/executors/cargo-zigbuild/executor.d.ts.map +1 -1
  123. package/dist/executors/cargo-zigbuild/executor.js +67 -12
  124. package/dist/executors/clean-outputs/executor.js +1 -0
  125. package/dist/executors/scriptc-native/executor.d.ts +79 -0
  126. package/dist/executors/scriptc-native/executor.d.ts.map +1 -0
  127. package/dist/executors/scriptc-native/executor.js +367 -0
  128. package/dist/executors/scriptc-native/ffi-paths.d.ts +9 -0
  129. package/dist/executors/scriptc-native/ffi-paths.d.ts.map +1 -0
  130. package/dist/executors/scriptc-native/ffi-paths.js +25 -0
  131. package/dist/executors/scriptc-native/schema.d.ts +34 -0
  132. package/dist/executors/scriptc-native/schema.d.ts.map +1 -0
  133. package/dist/executors/scriptc-native/schema.js +1 -0
  134. package/dist/executors/typescript-emit/executor.d.ts +3 -1
  135. package/dist/executors/typescript-emit/executor.d.ts.map +1 -1
  136. package/dist/executors/typescript-emit/executor.js +164 -33
  137. package/dist/forbidden-spelling-policy.d.ts +56 -0
  138. package/dist/forbidden-spelling-policy.d.ts.map +1 -0
  139. package/dist/forbidden-spelling-policy.js +176 -0
  140. package/dist/generators/create-package/generator.d.ts.map +1 -1
  141. package/dist/generators/create-package/generator.js +3 -4
  142. package/dist/graph-input-contract.d.ts +14 -0
  143. package/dist/graph-input-contract.d.ts.map +1 -1
  144. package/dist/graph-input-contract.js +67 -2
  145. package/dist/index.d.ts +23 -6
  146. package/dist/index.d.ts.map +1 -1
  147. package/dist/index.js +676 -215
  148. package/dist/managed-assets.d.ts +2 -0
  149. package/dist/managed-assets.d.ts.map +1 -1
  150. package/dist/managed-files/files.d.ts +3 -3
  151. package/dist/managed-files/files.d.ts.map +1 -1
  152. package/dist/managed-files/files.js +28 -3
  153. package/dist/managed-files/managed-format.d.ts.map +1 -1
  154. package/dist/managed-files/managed-format.js +1 -0
  155. package/dist/nextest-code-bound.js +1 -0
  156. package/dist/nextest-timings.d.ts +35 -0
  157. package/dist/nextest-timings.d.ts.map +1 -0
  158. package/dist/nextest-timings.js +168 -0
  159. package/dist/owned-installation.d.ts +6 -5
  160. package/dist/owned-installation.d.ts.map +1 -1
  161. package/dist/owned-installation.js +150 -26
  162. package/dist/package-target-policy.d.ts.map +1 -1
  163. package/dist/package-target-policy.js +2 -3
  164. package/dist/process-children.d.ts +7 -0
  165. package/dist/process-children.d.ts.map +1 -0
  166. package/dist/process-children.darwin.d.ts +7 -0
  167. package/dist/process-children.darwin.d.ts.map +1 -0
  168. package/dist/process-children.darwin.js +13 -0
  169. package/dist/process-children.js +14 -0
  170. package/dist/process-children.linux.d.ts +8 -0
  171. package/dist/process-children.linux.d.ts.map +1 -0
  172. package/dist/process-children.linux.js +25 -0
  173. package/dist/process-group.d.ts +108 -0
  174. package/dist/process-group.d.ts.map +1 -0
  175. package/dist/process-group.js +171 -0
  176. package/dist/process-listing.d.ts +7 -0
  177. package/dist/process-listing.d.ts.map +1 -0
  178. package/dist/process-listing.js +51 -0
  179. package/dist/producer-receipts.d.ts +8 -2
  180. package/dist/producer-receipts.d.ts.map +1 -1
  181. package/dist/producer-receipts.js +75 -48
  182. package/dist/task-graph-policy.d.ts +21 -0
  183. package/dist/task-graph-policy.d.ts.map +1 -0
  184. package/dist/task-graph-policy.js +91 -0
  185. package/dist/test-timings.js +4 -4
  186. package/dist/test-walk-policy.d.ts +14 -5
  187. package/dist/test-walk-policy.d.ts.map +1 -1
  188. package/dist/test-walk-policy.js +8 -2
  189. package/dist/testing.d.ts +73 -28
  190. package/dist/testing.d.ts.map +1 -1
  191. package/dist/testing.js +217 -223
  192. package/dist/tool-bins.d.ts +33 -0
  193. package/dist/tool-bins.d.ts.map +1 -0
  194. package/dist/tool-bins.js +72 -0
  195. package/dist/typecheck-test-policy.d.ts.map +1 -1
  196. package/dist/typecheck-test-policy.js +3 -4
  197. package/dist/wait-why-policy.d.ts +28 -0
  198. package/dist/wait-why-policy.d.ts.map +1 -0
  199. package/dist/wait-why-policy.js +223 -0
  200. package/dist/workspace-config-policy.d.ts +14 -8
  201. package/dist/workspace-config-policy.d.ts.map +1 -1
  202. package/dist/workspace-config-policy.js +60 -16
  203. package/dist/workspace-manifest.d.ts +41 -6
  204. package/dist/workspace-manifest.d.ts.map +1 -1
  205. package/dist/workspace-manifest.js +57 -0
  206. package/executors.json +21 -1
  207. package/loader.js +2 -0
  208. package/managed/raw/envrc +11 -0
  209. package/managed/raw/patches/nx@23.2.1.patch +2840 -199
  210. package/managed/raw/patches/ttsc@0.34.1.patch +119 -0
  211. package/managed/raw/tooling/direnv/cargo-fetch-bound.ts +245 -0
  212. package/managed/raw/tooling/direnv/cargo-fetch-run.ts +299 -0
  213. package/managed/raw/tooling/direnv/compiler-variables.sh +42 -0
  214. package/managed/raw/tooling/direnv/developer-links.ts +464 -25
  215. package/managed/raw/tooling/direnv/devenv.smoo.nix +78 -38
  216. package/managed/raw/tooling/direnv/github-actions-bootstrap.sh +14 -12
  217. package/managed/raw/tooling/direnv/installed-bun-links.ts +308 -0
  218. package/managed/raw/tooling/direnv/linked-snapshots.ts +62 -3
  219. package/managed/raw/tooling/direnv/nx-socket-dir.sh +56 -17
  220. package/managed/raw/tooling/direnv/repo-path +68 -6
  221. package/managed/raw/tooling/direnv/secret-references.ts +13 -4
  222. package/managed/raw/tooling/direnv/setup-environment.ts +128 -537
  223. package/managed/raw/tooling/direnv/toolchain-stamp.ts +4 -2
  224. package/managed/raw/tooling/direnv/ttsc-env.sh +9 -0
  225. package/managed/raw/tooling/direnv/uv-relocation.ts +227 -0
  226. package/managed/raw/tooling/git-hooks/commit-msg.sh +2 -1
  227. package/managed/raw/tooling/git-hooks/pre-commit.sh +2 -1
  228. package/managed/raw/tooling/git-hooks/pre-push.sh +2 -1
  229. package/managed/templates/github/actions/cache-ttsc-plugins/action.yml +85 -7
  230. package/managed/templates/github/actions/save-nix-devenv/action.yml +12 -2
  231. package/managed/templates/github/actions/setup-devenv/action.yml +2 -0
  232. package/package.json +77 -13
  233. package/src/bin/smoo-nx-cargo-toolchain.ts +11 -0
  234. package/src/bin/smoo-nx-forbidden-spellings.ts +33 -0
  235. package/src/bin/smoo-nx-nextest-timings.ts +31 -0
  236. package/src/bounded-test-policy.ts +12 -14
  237. package/src/build-state-output-policy.ts +458 -34
  238. package/src/bun-lock-scope.ts +108 -0
  239. package/src/cargo-build-script-env.ts +265 -0
  240. package/src/cargo-closure-input.ts +74 -7
  241. package/src/cargo-retention-hook.ts +94 -0
  242. package/src/cargo-source-hash.ts +138 -41
  243. package/src/cargo-toolchain-paths.ts +95 -0
  244. package/src/cargo-toolchain-policy.ts +49 -5
  245. package/src/cargo-workspace.ts +72 -123
  246. package/src/cross-check-policy.ts +12 -10
  247. package/src/disk-command-policy.ts +1 -0
  248. package/src/ensure-built-receipt.ts +132 -39
  249. package/src/ensure-built-witness.ts +62 -10
  250. package/src/ensure-built.ts +11 -1
  251. package/src/eslint-config-closure.ts +357 -0
  252. package/src/executors/all-verdicts/executor.ts +164 -0
  253. package/src/executors/all-verdicts/schema.json +22 -0
  254. package/src/executors/all-verdicts/schema.ts +10 -0
  255. package/src/executors/bounded-exec/bounds.ts +76 -0
  256. package/src/executors/bounded-exec/cpu-pool.ts +51 -117
  257. package/src/executors/bounded-exec/executor.ts +423 -259
  258. package/src/executors/bounded-exec/gateway-lease.ts +82 -33
  259. package/src/executors/bounded-exec/hang-diagnostics.ts +173 -31
  260. package/src/executors/bounded-exec/lease-wait.ts +89 -0
  261. package/src/executors/bounded-exec/lock-wait.ts +141 -0
  262. package/src/executors/bounded-exec/owned-subtree.ts +235 -0
  263. package/src/executors/bounded-exec/progress.ts +9 -3
  264. package/src/executors/bounded-exec/ram-attach.ts +238 -0
  265. package/src/executors/bounded-exec/ram-detach.ts +226 -0
  266. package/src/executors/bounded-exec/ram-temp-fixtures.ts +358 -0
  267. package/src/executors/bounded-exec/ram-temp-registry.txt +440 -0
  268. package/src/executors/bounded-exec/ram-temp.ts +1497 -460
  269. package/src/executors/bounded-exec/run-cpu-pool.ts +22 -30
  270. package/src/executors/bounded-exec/runner-hook.ts +14 -6
  271. package/src/executors/bounded-exec/runner-lifecycle.ts +31 -8
  272. package/src/executors/bounded-exec/{cpu-tokens.ts → runner-sizing.ts} +13 -59
  273. package/src/executors/bounded-exec/runtime-pin.ts +232 -0
  274. package/src/executors/bounded-exec/schema.json +11 -2
  275. package/src/executors/bounded-exec/schema.ts +19 -1
  276. package/src/executors/bounded-exec/verdict.ts +137 -34
  277. package/src/executors/cargo-zigbuild/executor.ts +82 -8
  278. package/src/executors/clean-outputs/executor.ts +1 -0
  279. package/src/executors/scriptc-native/executor.ts +394 -0
  280. package/src/executors/scriptc-native/ffi-paths.ts +29 -0
  281. package/src/executors/scriptc-native/schema.json +60 -0
  282. package/src/executors/scriptc-native/schema.ts +34 -0
  283. package/src/executors/typescript-emit/executor.ts +205 -38
  284. package/src/forbidden-spelling-policy.ts +226 -0
  285. package/src/generators/create-package/generator.ts +7 -7
  286. package/src/graph-input-contract.ts +61 -2
  287. package/src/index.ts +792 -225
  288. package/src/managed-assets.ts +3 -0
  289. package/src/managed-files/files.ts +28 -3
  290. package/src/managed-files/managed-format.ts +1 -0
  291. package/src/nextest-code-bound.ts +1 -0
  292. package/src/nextest-timings.ts +106 -0
  293. package/src/owned-installation.ts +150 -23
  294. package/src/package-target-policy.ts +2 -3
  295. package/src/process-children.darwin.ts +14 -0
  296. package/src/process-children.linux.ts +33 -0
  297. package/src/process-children.ts +22 -0
  298. package/src/process-group.ts +209 -0
  299. package/src/process-listing.ts +54 -0
  300. package/src/producer-receipts.ts +68 -45
  301. package/src/task-graph-policy.ts +98 -0
  302. package/src/test-walk-policy.ts +23 -8
  303. package/src/testing.ts +240 -232
  304. package/src/tool-bins.ts +108 -0
  305. package/src/typecheck-test-policy.ts +2 -3
  306. package/src/wait-why-policy.ts +226 -0
  307. package/src/workspace-config-policy.ts +63 -15
  308. package/src/workspace-manifest.ts +89 -6
  309. package/test-timings.json +123 -98
  310. package/dist/bin/smoo-nx-failures.d.ts +0 -3
  311. package/dist/bin/smoo-nx-failures.d.ts.map +0 -1
  312. package/dist/bin/smoo-nx-failures.js +0 -3
  313. package/dist/bin/smoo-nx-nextest-extract.d.ts +0 -3
  314. package/dist/bin/smoo-nx-nextest-extract.d.ts.map +0 -1
  315. package/dist/bin/smoo-nx-nextest-extract.js +0 -42
  316. package/dist/executors/bounded-exec/cpu-tokens.d.ts.map +0 -1
  317. package/dist/failure-summary.d.ts +0 -5
  318. package/dist/failure-summary.d.ts.map +0 -1
  319. package/dist/failure-summary.js +0 -118
  320. package/dist/nextest-extraction.d.ts +0 -117
  321. package/dist/nextest-extraction.d.ts.map +0 -1
  322. package/dist/nextest-extraction.js +0 -303
  323. package/managed/raw/patches/ttsc@0.30.4.patch +0 -2255
  324. package/src/__tests__/cargo-closure-filesets.ts +0 -94
  325. package/src/__tests__/cargo-closure-fixture.ts +0 -113
  326. package/src/__tests__/counted-cargo-process.ts +0 -286
  327. package/src/__tests__/counted-cargo.ts +0 -713
  328. package/src/__tests__/directory-change.ts +0 -27
  329. package/src/__tests__/fixture-cargo-home.ts +0 -36
  330. package/src/__tests__/fixture-nx-env.ts +0 -193
  331. package/src/__tests__/owned-installation.ts +0 -13
  332. package/src/__tests__/past-tick.ts +0 -12
  333. package/src/__tests__/progress-clock.ts +0 -43
  334. package/src/__tests__/runtime-input.ts +0 -23
  335. package/src/bin/smoo-nx-bound-failures.test.ts +0 -127
  336. package/src/bin/smoo-nx-failures.ts +0 -4
  337. package/src/bin/smoo-nx-nextest-extract.ts +0 -44
  338. package/src/bounded-test-policy.test.ts +0 -1029
  339. package/src/build-state-output-policy.test.ts +0 -115
  340. package/src/bun-bootstrap.test.ts +0 -102
  341. package/src/bun-file-packages.test.ts +0 -47
  342. package/src/cargo-closure-filesets.test.ts +0 -63
  343. package/src/cargo-closure-input.property.test.ts +0 -50
  344. package/src/cargo-closure-input.test.ts +0 -506
  345. package/src/cargo-closure-key.test.ts +0 -240
  346. package/src/cargo-resolve-cache.test.ts +0 -1181
  347. package/src/cargo-source-hash.test.ts +0 -707
  348. package/src/cargo-workspace.test.ts +0 -615
  349. package/src/cross-check-policy.test.ts +0 -316
  350. package/src/disk-command-policy.test.ts +0 -61
  351. package/src/ensure-built-receipt.test.ts +0 -279
  352. package/src/ensure-built-witness.test.ts +0 -688
  353. package/src/ensure-built.test.ts +0 -1462
  354. package/src/executors/bounded-exec/cargo-progress-host.test.ts +0 -332
  355. package/src/executors/bounded-exec/cpu-pool.test.ts +0 -684
  356. package/src/executors/bounded-exec/cpu-tokens.test.ts +0 -519
  357. package/src/executors/bounded-exec/disk-lease.test.ts +0 -219
  358. package/src/executors/bounded-exec/executor-host.test.ts +0 -800
  359. package/src/executors/bounded-exec/executor.test.ts +0 -1819
  360. package/src/executors/bounded-exec/go-progress-host.test.ts +0 -171
  361. package/src/executors/bounded-exec/hang-diagnostics.test.ts +0 -291
  362. package/src/executors/bounded-exec/progress.test.ts +0 -139
  363. package/src/executors/bounded-exec/ram-temp-held.test.ts +0 -264
  364. package/src/executors/bounded-exec/ram-temp-host.test.ts +0 -635
  365. package/src/executors/bounded-exec/ram-temp.test.ts +0 -750
  366. package/src/executors/bounded-exec/run-cpu-pool.test.ts +0 -79
  367. package/src/executors/bounded-exec/runner-hook.test.ts +0 -193
  368. package/src/executors/bounded-exec/runner-lifecycle.test.ts +0 -82
  369. package/src/executors/bounded-exec/verdict.test.ts +0 -545
  370. package/src/executors/cargo-zigbuild/executor.test.ts +0 -129
  371. package/src/executors/clean-outputs/executor.test.ts +0 -20
  372. package/src/executors/typescript-emit/executor.test.ts +0 -83
  373. package/src/failure-summary.ts +0 -119
  374. package/src/generators/bounded-test-targets/generator.test.ts +0 -138
  375. package/src/generators/bun-test-tracing/generator.test.ts +0 -250
  376. package/src/generators/create-package/generator.test.ts +0 -190
  377. package/src/generators/make-public/generator.test.ts +0 -137
  378. package/src/graph-input-contract.test.ts +0 -379
  379. package/src/host-controller-wiring.test.ts +0 -31
  380. package/src/index.test.ts +0 -3319
  381. package/src/linked-snapshots.nx.test.ts +0 -254
  382. package/src/managed-files/forgejo-artifact.test.ts +0 -395
  383. package/src/managed-files/generator.test.ts +0 -243
  384. package/src/managed-files/github-host-cache-isolation.test.ts +0 -86
  385. package/src/managed-files/json-edit.test.ts +0 -216
  386. package/src/managed-files/managed-content.test.ts +0 -166
  387. package/src/managed-files/managed-format-json.test.ts +0 -308
  388. package/src/managed-files/repo-path.test.ts +0 -172
  389. package/src/managed-files/setup-devenv-free-disk.test.ts +0 -95
  390. package/src/managed-files/trace-db-artifact.test.ts +0 -7
  391. package/src/managed-files/tree-permissions.test.ts +0 -109
  392. package/src/managed-files/tree.test.ts +0 -123
  393. package/src/manifest-hash.test.ts +0 -219
  394. package/src/nextest-code-bound.test.ts +0 -161
  395. package/src/nextest-extraction.test.ts +0 -216
  396. package/src/nextest-extraction.ts +0 -371
  397. package/src/nextest-partitions.test.ts +0 -501
  398. package/src/nx-cache-bound.test.ts +0 -109
  399. package/src/nx-cache-restore-mtime.test.ts +0 -170
  400. package/src/nx-daemon-claim.test.ts +0 -279
  401. package/src/nx-daemon-idle-cpu.test.ts +0 -80
  402. package/src/nx-daemon-idle-policy.test.ts +0 -111
  403. package/src/nx-daemon-ignore-files.test.ts +0 -210
  404. package/src/nx-daemon-root-normalization.test.ts +0 -105
  405. package/src/nx-daemon-start-never.test.ts +0 -292
  406. package/src/nx-daemon-validity.test.ts +0 -1055
  407. package/src/nx-dot-input-policy.test.ts +0 -353
  408. package/src/nx-failure-life-cycles.test.ts +0 -207
  409. package/src/nx-files-archive-racy.test.ts +0 -97
  410. package/src/nx-foreign-workspace-env.test.ts +0 -329
  411. package/src/nx-incomplete-run-summary.test.ts +0 -70
  412. package/src/nx-plugin-load-errors.test.ts +0 -120
  413. package/src/nx-project-graph-errors.test.ts +0 -70
  414. package/src/nx-project-resolution-cache.test.ts +0 -176
  415. package/src/nx-raw-inputs.test.ts +0 -166
  416. package/src/nx-resident-graph-workers.test.ts +0 -112
  417. package/src/nx-run-information.test.ts +0 -118
  418. package/src/nx-skipped-task-exit.test.ts +0 -180
  419. package/src/nx-state-location.test.ts +0 -63
  420. package/src/nx-store-resolution.test.ts +0 -81
  421. package/src/nx-task-graph-cycles.test.ts +0 -148
  422. package/src/nx-task-output-lease.test.ts +0 -550
  423. package/src/nx-use-local.test.ts +0 -105
  424. package/src/owned-installation.test.ts +0 -105
  425. package/src/package-target-policy.test.ts +0 -1014
  426. package/src/producer-receipts.test.ts +0 -285
  427. package/src/release-config-policy.test.ts +0 -311
  428. package/src/runtime-input.test.ts +0 -393
  429. package/src/serial-group-wiring.test.ts +0 -326
  430. package/src/task-history-namespace.test.ts +0 -181
  431. package/src/task-results.test.ts +0 -228
  432. package/src/test-clock-policy.test.ts +0 -338
  433. package/src/test-program.test.ts +0 -303
  434. package/src/test-timings.test.ts +0 -240
  435. package/src/test-walk-policy.test.ts +0 -620
  436. package/src/testing.test.ts +0 -509
  437. package/src/typecheck-test-policy.test.ts +0 -1468
  438. package/src/typescript-resolution.test.ts +0 -76
  439. package/src/version-actions.test.ts +0 -80
  440. package/src/workspace-config-policy.test.ts +0 -737
@@ -3,12 +3,16 @@ import { randomUUID } from 'node:crypto';
3
3
  import { constants } from 'node:fs';
4
4
  import { lstat, mkdir, mkdtemp, open, readdir, readFile, rename, rm, rmdir, stat, statfs, writeFile, } from 'node:fs/promises';
5
5
  import { Socket } from 'node:net';
6
- import { basename, join } from 'node:path';
6
+ import { basename, dirname, join } from 'node:path';
7
7
  import { setTimeout as sleep } from 'node:timers/promises';
8
- import { awaitExit, pidsWithTempIn, pidsWorkingIn, processTable, terminate, withDescendants, } from '../../testing.js';
8
+ import { O_EXLOCK } from '@smoothbricks/cargo-retain/open-flags';
9
+ import { DEADLINE_PATIENCE, describeMembersLeft, killProcessGroup } from '../../process-group.js';
9
10
  import { isRecord } from '../../type-guards.js';
10
11
  import { diskClassOf, recordedShare, takeDiskLease } from './disk-lease.js';
11
12
  import { GATEWAY_SOCKET } from './gateway-lease.js';
13
+ import { COWSHED_EXECUTABLE_ENV, parseHandle, } from './owned-subtree.js';
14
+ import { attachRamDisk } from './ram-attach.js';
15
+ import { detachGatewayRamDisk } from './ram-detach.js';
12
16
  import { captureHeldVerdict, parseHeldVerdict, validateHeldVerdict, } from './ram-temp-held.js';
13
17
  /**
14
18
  * One RAM-backed APFS volume per host user, shared by every test task that runs
@@ -27,13 +31,26 @@ import { captureHeldVerdict, parseHeldVerdict, validateHeldVerdict, } from './ra
27
31
  * no `diskimagesiod`, so it spends none of the AppleDiskImages2 attach budget
28
32
  * that cowshed's images and tests draw on (specs/cowshed/01a_apfs.md, "How
29
33
  * the APFS host degrades"; measured 2026-10-05).
34
+ * - The disk lives as long as that helper, and a helper forked inside a job is
35
+ * the job's member, which the job's end retires under every other lease. So
36
+ * the helper belongs to the cowshed gateway, which no job contains and which
37
+ * attaches the disk under the creating task's lease (`ram-lease`,
38
+ * specs/cowshed/05_gateway.md, "RAM disks"); a task never does.
30
39
  * - Attach + format + mount costs ~2 s and is DiskArbitration traffic, so the
31
40
  * volume is created once, lazily, and every task takes a subdirectory.
32
- * - Only DiskArbitration's own mountpoint (`/Volumes/<volume name>`) is safe to
33
- * ask for: `diskutil mount -mountPoint <dir>` was refused as not privileged
34
- * (0xf8da0009), and storagekitd escalated it to an administrator dialog whose
35
- * wait blocked every diskutil on the host. A default mount raised no authd
36
- * request (log show, 2026-10-04).
41
+ * - Spotlight's mds keeps one IOKit right for every APFS volume it admits, for
42
+ * the life of the mds process, and admits no volume whose kernel-resolved
43
+ * mount path contains `/var/folders/` (specs/cowshed/01a_apfs.md, "Spotlight
44
+ * media references"). Measured 2026-10-22: a RAM volume mounted at /Volumes
45
+ * or /private/tmp left mds one right; the same mount under
46
+ * /private/var/folders left none. So the volume mounts below the per-user root
47
+ * `cowshed setup` makes, `/private/var/folders/cowshed/<uid>`, and a task
48
+ * refuses to create it while that root is missing or not the user's 0700
49
+ * directory.
50
+ * - The kernel mounts it there: `mount_apfs` needs no authorization, where
51
+ * `diskutil mount -mountPoint <dir>` was refused as not privileged
52
+ * (0xf8da0009) and storagekitd escalated it to an administrator dialog whose
53
+ * wait blocked every diskutil on the host (log show, 2026-10-04).
37
54
  * - Without authorization the volume mounts only `noowners`: launchd refuses a
38
55
  * plist from it ("Caller specified a plist with bad ownership/permissions"),
39
56
  * so a test that bootstraps a launchd job keeps the plist outside TMPDIR.
@@ -46,7 +63,7 @@ import { captureHeldVerdict, parseHeldVerdict, validateHeldVerdict, } from './ra
46
63
  * One caller creates or detaches the volume at a time, and a caller that finds
47
64
  * either in flight yields and looks again; each dead lease is settled by the
48
65
  * one caller that claimed it, and every other caller passes it by. A claim
49
- * names its owner's pid, so a claim whose owner died is void. Before it
66
+ * names its owner's pid; death voids it only with no pending detach. Before it
50
67
  * removes a lease or detaches the volume, a caller takes the lock again and
51
68
  * checks that the volume, the lease directory and its own claim are still as
52
69
  * it claimed them. A lease is a directory named after the task process's pid;
@@ -58,20 +75,29 @@ import { captureHeldVerdict, parseHeldVerdict, validateHeldVerdict, } from './ra
58
75
  * working in it, by working directory or by `TMPDIR`, has been stopped.
59
76
  *
60
77
  * The volume is created under its final name and never renamed. It is mounted by `mount_apfs` at a
61
- * private staging directory and marked there; the kernel then unmounts it (`umount`) and `diskutil mount`, the
62
- * only call that places it at its mountpoint, so it reaches `/Volumes` already marked. A Disk
63
- * Arbitration rename names whatever volume holds the path it recorded, and a force-unmounted volume
64
- * leaves a bare directory there on the host's Data volume, so no rename is made. `noowners` lets the
65
- * marker be written, since a fresh volume's root is owned by root (measured 2026-10-15). A creator that
66
- * dies part way leaves debris at the staging directory or as an unmounted volume, never an unmarked
67
- * volume at the mountpoint, which DiskArbitration would make every later volume dodge as "<name> 1".
68
- * The host's own image list is the only record of what was
69
- * attached: before creating, a task detaches every RAM disk of this user and
70
- * this volume's exact size that is mounted nowhere but this volume's names,
71
- * because a creator killed or deadlined mid-step leaves one behind — measured
72
- * 2026-10-06: a deadlined `hdiutil attach` whose diskimages-helper finished the
73
- * attach after `hdiutil` was killed, and a volume mounted with no marker. A
74
- * disk with a lease directory on it is never detached; its error names it.
78
+ * private staging directory and marked there, unmounted (`umount`), and mounted by `mount_apfs` again at its
79
+ * mountpoint, so it reaches the mountpoint already marked. A Disk Arbitration rename names whatever volume
80
+ * holds the path it recorded, and a force-unmounted volume leaves a bare directory there on the host's Data
81
+ * volume, so no rename is made. `noowners` lets the marker be written, since a fresh volume's root is owned
82
+ * by root (measured 2026-10-15). A creator that dies part way leaves debris at the staging directory or as an
83
+ * unmounted volume, never an unmarked volume at the mountpoint. No Disk Arbitration call made either
84
+ * directory, so none removes it: this module removes both once the volume is gone.
85
+ * The I/O Registry is the only record of what was attached, and it names every disk's volume. A task inventories the
86
+ * RAM disks that are this volume's and no other (`volumeDisks`): of this user and this volume's exact size, mounting
87
+ * nowhere but at its mountpoint or staging directory, and either carrying a volume called exactly its name, which a
88
+ * volume is made under and keeps, or recorded by the exact registry entry its owner holds a receipt or its ledger holds
89
+ * custody for, which covers an attach whose format never finished, or records as the disk a creator kept, which covers
90
+ * a volume unmounted from under it. A RAM disk of that size that is neither, another volume's, a test's, or an
91
+ * unformatted one nothing recorded, is ignored, however it is mounted. The gateway holds
92
+ * each disk it attaches under its creator's lease until the creator keeps it, its volume mounted and marked at the
93
+ * mountpoint, and detaches it when the creator releases it or goes away first: a creator killed or deadlined mid-step
94
+ * leaves no disk behind, where one did before the lease (measured 2026-10-06: a deadlined `hdiutil attach` whose
95
+ * diskimages-helper finished the attach after `hdiutil` was killed). A gateway restart leaves an unended lease's disk
96
+ * to the next gateway's startup scan. A creator records its disk's registry entry in the ledger before it keeps it: the
97
+ * volume's marker names the entry only while the volume is mounted, and a volume an operator's unmount took from its
98
+ * mountpoint leaves its disk attached, mounted nowhere, with nothing else to name it. Before creating, a task detaches
99
+ * each disk of that inventory its owner holds a receipt for or its ledger records as kept. Any other disk, one with a
100
+ * lease directory on it, or one with something attached below it stops the creation instead; its error names it.
75
101
  *
76
102
  * An image attached from a file below a lease belongs to whoever attached it:
77
103
  * cowshed's real-APFS fixtures release theirs under the production per-image
@@ -82,20 +108,20 @@ import { captureHeldVerdict, parseHeldVerdict, validateHeldVerdict, } from './ra
82
108
  * holder has an identity a cheap `lstat` re-proves (a mount below the lease),
83
109
  * the ledger keeps that proof (`ram-temp-held.ts`) and later tasks check it
84
110
  * instead of probing the host; any change sends the lease back to a probe.
85
- * Every disk child runs under a deadline, in its own process group so the
86
- * deadline also reaches the helper it spawned, so a wedged DiskArbitration
87
- * fails the task instead of every task waiting on the volume. A detach is the
88
- * exception: never killed at its deadline, because an interrupted detach can
89
- * wedge DiskArbitration itself; its wait is bounded and reported by name, and
90
- * a stray's detach gets the short stray bound, so one wedged stray cannot
91
- * hold the create claim while a chain of tasks queues behind it.
111
+ * SAFE disk children delegate their execution budget and reap to cowshed. Protected
112
+ * image commands are never killed at the caller's deadline. A detach publishes its
113
+ * exact custody before it spawns. While its live caller still waits on the facade the
114
+ * custody is `waiting`, and other callers queue behind it as behind any claim. Once
115
+ * that caller stops waiting, or its run throws without an answer, the custody is
116
+ * `reported`: no lease is admitted until a normal terminal answer or the bound registry
117
+ * entry's absence proves it safe. A dead caller alone proves neither; its death only
118
+ * turns queueing into reporting. The facade pid is a diagnostic, never authority.
92
119
  *
93
- * A cowshed sandbox denies writes to /private/tmp (EPERM on the lock), and
94
- * cannot attach disk images at all; there the task keeps the workspace's own
95
- * TMPDIR and says so once on stderr.
120
+ * A cowshed sandbox denies the volume's paths (EPERM reading its mountpoint or
121
+ * marker, or opening the lock in /private/tmp) and cannot attach disk images at
122
+ * all; whichever refusal comes first, the task keeps the workspace's own TMPDIR
123
+ * and says so once on stderr.
96
124
  */
97
- /** macOS `open(2)` flag: take an exclusive flock atomically with the open. Absent from `fs.constants`. */
98
- const O_EXLOCK = 0x20;
99
125
  /** Contended opens yield without occupying a filesystem worker needed by the lock holder. */
100
126
  const LOCK_RETRY_MS = 50;
101
127
  /**
@@ -109,177 +135,209 @@ const GIB = 1024 * MIB;
109
135
  /**
110
136
  * The revision of the volume's protocol. Checkouts at different revisions run on one host at
111
137
  * once, and each is safe only beside its own: revision 1 leases under the kernel lock alone,
112
- * revision 2 leases and detaches outside it, behind claims in a ledger revision 1 never reads.
113
- * So no revision shares a volume with another. It names the volume, its lock and its ledger, and
114
- * adds as many sectors to the RAM disk, whose size and user are what a creator's stray reclaim
115
- * matches: neither revision detaches the other's disk, mounted or still attaching.
138
+ * revision 2 leases and detaches outside it, behind claims in a ledger revision 1 never reads,
139
+ * and revision 3 mounts below the per-user cowshed root instead of at the `/Volumes` path
140
+ * DiskArbitration gave revisions 1 and 2. So no revision shares a volume with another. It names
141
+ * the volume, its mountpoint, its lock and its ledger, and adds as many sectors to the RAM disk,
142
+ * whose size and user are what a creator's stray reclaim matches: no revision detaches another's
143
+ * disk, mounted or still attaching. A volume of an earlier revision is detached by that
144
+ * revision's own last release.
116
145
  */
117
- const RAM_TEMP_REVISION = 2;
146
+ const RAM_TEMP_REVISION = 3;
118
147
  /**
119
148
  * The volume's ceiling, plus the revision's sectors. Pages are allocated as they are written and
120
149
  * returned when the volume detaches, so this bounds what a runaway suite can take, not what a gate
121
150
  * costs. Measured 2026-10-04: a full parallel smoothbricks `lint test build host-controller-test`
122
151
  * gate peaked at 1.61 GiB used with 18 concurrent leases; 8 GiB is five times that. That
123
- * gate also staged cowshed's real-APFS fixture images on the volume, which now stay under
124
- * /private/tmp, so the peak is an upper bound.
152
+ * gate also staged cowshed's real-APFS fixture images on the volume, which now stay outside it,
153
+ * so the peak is an upper bound.
125
154
  */
126
155
  export const RAM_TEMP_CAPACITY_BYTES = 8 * GIB + RAM_TEMP_REVISION * SECTOR_BYTES;
127
156
  /** A failed task with less than this free on the volume is reported as having run out of space. */
128
157
  const FULL_FREE_BYTES = 64 * MIB;
129
158
  /** `<pid>-<mkdtemp suffix>`: the pid says whether the lease's task is alive. */
130
159
  const LEASE_NAME = /^(\d+)-[A-Za-z0-9]{6}$/;
160
+ /** The random suffix `mkdtemp` gives a lease name. */
161
+ const LEASE_SUFFIX_BYTES = 6;
162
+ /** Darwin's `sockaddr_un.sun_path` holds 104 bytes, the last a NUL: a socket's path is at most 103. */
163
+ const SOCKET_PATH_BYTES = 103;
164
+ /**
165
+ * The one length rule of the RAM temp layout (specs/cowshed/01_storage.md, "RAM temp path budget"): a lease directory,
166
+ * the TMPDIR its task gets, is at most this many bytes. It is the layout's worst case, a test namespace's at the largest
167
+ * uid and pid: `/private/var/folders/cowshed/` (29), a u32 uid (10), `/<ns>` (8), `/ram3` (5), `/<pid ≤ 99999>-` (7)
168
+ * and the suffix (6). Production's worst case is 57.
169
+ */
170
+ export const RAM_TMPDIR_MAX_BYTES = 65;
171
+ /** What the rule leaves below a lease for a socket's `/<names>`: 38 bytes. */
172
+ export const RAM_TMPDIR_SOCKET_BUDGET_BYTES = SOCKET_PATH_BYTES - RAM_TMPDIR_MAX_BYTES;
173
+ /** The length in bytes of the lease directory process `pid` makes below `mountpoint`. */
174
+ export function leaseDirectoryBytes(mountpoint, pid) {
175
+ return Buffer.byteLength(`${mountpoint}/${pid}-`) + LEASE_SUFFIX_BYTES;
176
+ }
131
177
  const MARKER_FILE = '.smoo-ram';
132
178
  /**
133
- * How long a process a task left in its lease gets to exit on SIGTERM before it gets SIGKILL: the
134
- * time a daemon takes to stop its watcher and its plugin workers, and well under the grace a
135
- * bounded leg gives its own command.
179
+ * The scratch of a run that did not pass, moved out of its lease when the lease is reclaimed: a directory beside the
180
+ * leases on the same volume, so the move is one `rename(2)` and copies nothing. An entry is
181
+ * `<archived at, epoch ms, 13 digits>-<lease name>`, so the names sort oldest first.
136
182
  */
137
- const LEFTOVER_GRACE_MS = 5_000;
138
- /** A `ps` state in which a process starts nothing: stopped (`T`, `t` when traced) or exited (`Z`). */
139
- const STARTS_NOTHING = /^[TtZ]/;
183
+ const ARCHIVE_DIR = '.archive';
184
+ const ARCHIVE_NAME = /^\d{13}-\d+-[A-Za-z0-9]{6}$/;
140
185
  /**
141
- * The processes `host` reads. A lease belongs to one task and its command is gone by the time the
142
- * lease ends, so what still works in it is what the command left behind. Most of that works in the
143
- * lease only through `TMPDIR`, never by working directory: a test's ttsc plugin build copies the
144
- * typescript-go sources into `$TMPDIR` from a process working in its project, and a Bun or Node
145
- * process writes its compile cache there as it exits. Neither is known to the task's pid, and
146
- * whichever outlived that pid would write into a lease being removed (measured 2026-10-18: `rm`
147
- * failing ENOTEMPTY under a ttsc copy whose task had died). A fixture's Nx daemon is another: Nx
148
- * detaches it into a session of its own, so the process-group kill that ends a timed-out command
149
- * never reaches it, and a test process that is killed runs no teardown of its own. Deleting the
150
- * lease asks such a daemon to leave only by deleting its record, which it notices within a second
151
- * when it is idle and not at all while it is wedged; a signal does not depend on the daemon
152
- * noticing, and a process left on the volume is what keeps it from detaching.
153
- *
154
- * A leftover keeps running while it is looked for, and a child it starts after the process table
155
- * was read is in no table that was. So each one found is held with SIGSTOP and the table is read
156
- * again, until a read names nothing that the read before did not already show stopped: a stopped
157
- * process starts nothing, and whatever it started before it stopped is in every table read after.
158
- * Discovery waits for stopped-census readiness; the exit grace starts only after SIGTERM.
159
- * Only then does each get SIGTERM, and SIGCONT to act on it. A child whose parent exited before it
160
- * could be held has lost its ancestry, so once the stopped-table barrier holds, the lease is asked
161
- * again what works in it, including when that table names nothing, to recover reparented children.
186
+ * Archives on their way out, below the archive directory: each is renamed here as `<deleter pid>-<archive name>` and
187
+ * deleted by that process in the background. A dead deleter's entries are claimed by renaming them to the next one's pid.
162
188
  */
163
- export function leaseProcessesOn(host) {
164
- return {
165
- async stopWorkingIn(directory) {
166
- let working = (await host.workingIn(directory)).filter((pid) => pid !== process.pid);
167
- if (working.length === 0) {
168
- return [];
169
- }
170
- const known = new Map();
171
- let held = new Set();
172
- let failures;
173
- try {
174
- for (;;) {
175
- const roots = [...working, ...known.keys()];
176
- const current = withDescendants(await host.table(), roots).filter((entry) => entry.pid !== process.pid);
177
- for (const entry of current) {
178
- known.set(entry.pid, entry);
179
- }
180
- if (current.every((entry) => held.has(entry.pid) && STARTS_NOTHING.test(entry.stat))) {
181
- working = (await host.workingIn(directory)).filter((pid) => pid !== process.pid);
182
- if (working.every((pid) => held.has(pid))) {
183
- break;
184
- }
185
- }
186
- for (const entry of current) {
187
- host.signal(entry.pid, 'SIGSTOP');
188
- }
189
- held = new Set(current.filter((entry) => STARTS_NOTHING.test(entry.stat)).map((entry) => entry.pid));
190
- }
191
- for (const entry of known.values()) {
192
- host.signal(entry.pid, 'SIGTERM');
193
- }
194
- }
195
- catch (error) {
196
- failures = [error];
197
- }
198
- finally {
199
- // SIGTERM is pending while stopped. One failed resume must not strand the other holds.
200
- for (const entry of known.values()) {
201
- try {
202
- host.signal(entry.pid, 'SIGCONT');
203
- }
204
- catch (error) {
205
- failures ??= [];
206
- failures.push(new Error(`${entry.pid} (${entry.command}): SIGCONT failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error }));
207
- }
208
- }
209
- }
210
- if (failures !== undefined) {
211
- if (failures.length === 1) {
212
- throw failures[0];
213
- }
214
- throw new AggregateError(failures, `processes working in ${directory}: ${failures.map((error) => (error instanceof Error ? error.message : String(error))).join('; ')}`);
215
- }
216
- const leftovers = [...known.values()];
217
- try {
218
- await awaitExit(leftovers, `processes working in ${directory}`, LEFTOVER_GRACE_MS);
219
- }
220
- catch {
221
- for (const entry of leftovers) {
222
- host.signal(entry.pid, 'SIGKILL');
223
- }
224
- await awaitExit(leftovers, `processes working in ${directory} after SIGKILL`, LEFTOVER_GRACE_MS);
225
- }
226
- return leftovers.map((entry) => `${entry.pid} (${entry.command.slice(0, 160)})`);
227
- },
228
- };
189
+ const DELETING_DIR = '.deleting';
190
+ const DELETING_NAME = /^(\d+)-(\d{13}-\d+-[A-Za-z0-9]{6})$/;
191
+ /**
192
+ * How many archives the volume keeps: the failing run under triage and the one before it, the pair a triage compares to
193
+ * tell a flake from a regression. A stated reason, not a measurement.
194
+ */
195
+ export const ARCHIVES_KEPT = 2;
196
+ /**
197
+ * Below this share of the volume free, the volume keeps no archive: live leases need the space more than evidence does.
198
+ * Half of the 8 GiB volume is 4 GiB, 2.5 times the 1.61 GiB a full parallel gate peaked at (measured 2026-10-04, see
199
+ * `RAM_TEMP_CAPACITY_BYTES`).
200
+ */
201
+ const ARCHIVE_FLOOR_SHARE = 0.5;
202
+ /**
203
+ * How long a process a task left in its subtree gets to exit on SIGTERM before it gets SIGKILL:
204
+ * the time a daemon takes to stop its watcher and its plugin workers, and well under the grace a
205
+ * bounded leg gives its own command.
206
+ */
207
+ export const LEFTOVER_GRACE_MS = 5_000;
208
+ /** A lease's subtree handle file: beside the lease on the volume, never in it, so the command cannot remove it. */
209
+ function subtreeRecordPath(directory) {
210
+ return `${directory}.subtree`;
229
211
  }
230
- /** What works in `directory` on this host: by working directory, and by the `TMPDIR` it was started with. */
231
- export async function pidsInLease(directory) {
232
- const [working, temp] = await Promise.all([pidsWorkingIn(directory), pidsWithTempIn(directory)]);
233
- return [...new Set([...working, ...temp])];
212
+ /** One coverage gap the supervisor reported for a subtree it retired, as text. */
213
+ export function describeCoverageGap(gap) {
214
+ return gap.pid === null ? gap.kind : `${gap.kind} (pid ${gap.pid})`;
234
215
  }
235
- export const hostLeaseProcesses = leaseProcessesOn({
236
- workingIn: pidsInLease,
237
- table: processTable,
238
- signal: terminate,
239
- });
240
- export function ramTempPaths(user) {
241
- const volumeName = `smoo-ram${RAM_TEMP_REVISION}-${user.uid}`;
216
+ /** One process a retirement signalled, as `<pid> (<image>)`. */
217
+ export function describeSignalled(entry) {
218
+ return `${entry.pid} (${entry.image ?? 'unknown image'})`;
219
+ }
220
+ /** The namespace of the user's own volume, which no test leases, creates or detaches. */
221
+ export const PRODUCTION = { kind: 'production' };
222
+ const NAMESPACE_BASE = 36;
223
+ const NAMESPACE_PID_DIGITS = 5;
224
+ const NAMESPACE_ORDINAL_DIGITS = 2;
225
+ /** `value` as `digits` zero-padded lowercase base-36 digits; the refusal names it `what` when it does not fit them. */
226
+ function base36Digits(value, digits, what) {
227
+ if (!Number.isSafeInteger(value) || value < 0 || value >= NAMESPACE_BASE ** digits) {
228
+ throw new RangeError(`${what} ${value} does not fit a test namespace's ${digits} base-36 digits`);
229
+ }
230
+ return value.toString(NAMESPACE_BASE).padStart(digits, '0');
231
+ }
232
+ /**
233
+ * The namespace process `pid` mints as its `ordinal`th, encoded as `TestNamespace::of` encodes it:
234
+ * `testNamespace(94769, 3)` is `0214h03`. A pid or an ordinal that does not fit its digits throws.
235
+ */
236
+ export function testNamespace(pid, ordinal) {
237
+ const pidDigits = base36Digits(pid, NAMESPACE_PID_DIGITS, 'pid');
238
+ const ordinalDigits = base36Digits(ordinal, NAMESPACE_ORDINAL_DIGITS, 'ordinal');
239
+ return { kind: 'test', name: `${pidDigits}${ordinalDigits}` };
240
+ }
241
+ /**
242
+ * Where the volume of `user` in `namespace` lives and what it is called. Production's are the user's own: the per-user
243
+ * root `/private/var/folders/cowshed/<uid>`, the mountpoint `<root>/ram3` and staging directory `<root>/ram3-new` below
244
+ * it, the volume `smoo-ram3-<uid>` and its lock in `/private/tmp`. A test namespace's lie in the directory of its name
245
+ * below that root, `<root>/<ns>`: its mountpoint, staging directory and lock (`ram3.lock`) in it, and its name after
246
+ * the volume's (`smoo-ram3-<uid>-<ns>`), so none of its paths or names is production's.
247
+ */
248
+ export function ramTempPaths(user, namespace) {
249
+ const userRoot = `/private/var/folders/cowshed/${user.uid}`;
250
+ const leaf = `ram${RAM_TEMP_REVISION}`;
251
+ const own = `smoo-${leaf}-${user.uid}`;
252
+ const production = namespace.kind === 'production';
253
+ const root = production ? userRoot : `${userRoot}/${namespace.name}`;
254
+ const mountpoint = `${root}/${leaf}`;
242
255
  return {
243
- mountpoint: join('/Volumes', volumeName),
244
- lockFile: `/private/tmp/${volumeName}.lock`,
245
- volumeName,
246
- staging: `/private/tmp/${volumeName}-new`,
247
- user: user.username,
256
+ root,
257
+ uid: user.uid,
258
+ mountpoint,
259
+ lockFile: production ? `/private/tmp/${own}.lock` : `${mountpoint}.lock`,
260
+ volumeName: production ? own : `${own}-${namespace.name}`,
261
+ staging: `${mountpoint}-new`,
262
+ leaseBytesMax: RAM_TMPDIR_MAX_BYTES,
248
263
  };
249
264
  }
250
265
  export function describeRamTempError(error) {
251
266
  switch (error.kind) {
267
+ case 'ram-unavailable':
268
+ return `RAM acceleration unavailable (${error.reason}): ${error.detail}`;
252
269
  case 'provision-failed':
253
270
  return `RAM temp volume: ${error.step} failed: ${error.detail}`;
254
271
  case 'volume-full':
255
272
  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`;
273
+ case 'lease-lost':
274
+ return `RAM temp volume: lease ${error.lease} was lost while its task held it: ${error.detail}; what the task wrote to its TMPDIR went with it`;
275
+ case 'root-unready':
276
+ return `RAM temp volume: ${error.root} ${error.detail}; run "cowshed setup", which makes it a directory of yours with mode 0700`;
277
+ case 'lease-path-budget':
278
+ return `RAM temp volume: a lease below ${error.mountpoint} for pid ${error.pid} would be ${error.bytes} bytes, past the ${error.most} its layout admits, leaving ${SOCKET_PATH_BYTES - error.most} below it for a socket's names within sun_path (specs/cowshed/01_storage.md, "RAM temp path budget")`;
256
279
  }
257
280
  }
258
- const EMPTY_LEDGER = { lifecycle: null, claims: [], held: [] };
281
+ const EMPTY_LEDGER = { lifecycle: null, claims: [], held: [], kept: null };
282
+ /**
283
+ * This process's background deletions of archives, one at a time in order. Nothing that takes or releases a lease waits
284
+ * on it; the detach of the volume does, since a deletion still walking the volume would hold it busy.
285
+ */
286
+ let archiveDeletion = Promise.resolve();
287
+ /** Settles once every archive deletion this process has queued so far has finished; a test seam, and the detach's wait. */
288
+ export function archiveDeletions() {
289
+ return archiveDeletion;
290
+ }
259
291
  export class RamTempVolume {
260
292
  paths;
261
- capacityBytes;
262
293
  commands;
263
294
  pid;
264
295
  isAlive;
265
- processes;
296
+ policy;
266
297
  /** The RAM disk's size, which with the attaching user identifies this module's disks on the host. */
267
298
  sectors;
268
299
  /** The claims and held verdicts the lock admits changes to, beside the lock file. */
269
300
  ledgerPath;
270
- constructor(paths, capacityBytes, commands, pid = process.pid, isAlive = processIsAlive, processes = hostLeaseProcesses) {
301
+ /**
302
+ * Where optional RAM's ordinary fallback makes its owned scratch: the lock's own directory, which an unavailable answer
303
+ * has just written. For the user's volume that is `/private/tmp`, outside every checkout, so no Git or Cargo walk from
304
+ * the command's temp files finds the workspace it builds; the workspace's runtime alias resolves into
305
+ * `<mount>/.cowshed/run`, inside the checkout, and the inherited TMPDIR may be RAM. A test namespace's lock lies in
306
+ * its own root, so its ordinary scratch does too.
307
+ */
308
+ ordinaryParent;
309
+ constructor(paths, capacityBytes, commands, pid = process.pid, isAlive = processIsAlive, policy = 'required') {
271
310
  this.paths = paths;
272
- this.capacityBytes = capacityBytes;
273
311
  this.commands = commands;
274
312
  this.pid = pid;
275
313
  this.isAlive = isAlive;
276
- this.processes = processes;
314
+ this.policy = policy;
277
315
  this.sectors = Math.ceil(capacityBytes / SECTOR_BYTES);
278
316
  this.ledgerPath = `${paths.lockFile}.ledger`;
317
+ this.ordinaryParent = dirname(paths.lockFile);
279
318
  }
280
- /** Take a lease: create the volume if no task holds one, and a private directory on it. */
281
- async acquire() {
282
- const op = { owner: { pid: this.pid, token: randomUUID() }, claimed: false, made: null };
319
+ /**
320
+ * Take a lease: create the volume if no task holds one, and a private directory on it. A dead
321
+ * lease found on the way is settled through `subtrees`, the supervisor that owns the caller.
322
+ */
323
+ async acquire(subtrees) {
324
+ const bytes = leaseDirectoryBytes(this.paths.mountpoint, this.pid);
325
+ if (bytes > this.paths.leaseBytesMax) {
326
+ return {
327
+ ok: false,
328
+ error: {
329
+ kind: 'lease-path-budget',
330
+ mountpoint: this.paths.mountpoint,
331
+ pid: this.pid,
332
+ bytes,
333
+ most: this.paths.leaseBytesMax,
334
+ },
335
+ };
336
+ }
337
+ const readiness = await rootReadiness(this.paths);
338
+ if (!readiness.ok)
339
+ return readiness;
340
+ const op = { owner: { pid: this.pid, token: randomUUID() }, subtrees, claimed: false, made: null };
283
341
  let result;
284
342
  try {
285
343
  result = await this.lease(op);
@@ -298,6 +356,9 @@ export class RamTempVolume {
298
356
  }
299
357
  // The caller gets no lease, so the one made for it goes; a returned lease is never touched.
300
358
  const cleanup = [...(ended.ok ? [] : [ended.error]), ...(await this.undo(op))];
359
+ if (result.error.kind === 'ram-unavailable' && this.policy === 'optional' && cleanup.length === 0) {
360
+ return { ok: true, value: { kind: 'unavailable', reason: result.error.reason, detail: result.error.detail } };
361
+ }
301
362
  if (result.error.kind !== 'lock-denied') {
302
363
  return { ok: false, error: alsoFailed(result.error, cleanup) };
303
364
  }
@@ -381,7 +442,7 @@ export class RamTempVolume {
381
442
  }
382
443
  // The lease exists before the lock drops, so no release finds the volume empty under it.
383
444
  const directory = await this.make(op);
384
- const claimed = await this.claim(ledger, volume, op.owner, null);
445
+ const claimed = await this.claim(ledger, volume, op.owner, null, false);
385
446
  return {
386
447
  ledger: claimed.ledger,
387
448
  value: { kind: 'leased', volume, directory, held: claimed.held, candidates: claimed.candidates },
@@ -392,10 +453,14 @@ export class RamTempVolume {
392
453
  }
393
454
  const value = taken.value;
394
455
  switch (value.kind) {
395
- case 'wait':
456
+ case 'wait': {
396
457
  // Another caller is creating or detaching the volume: look again once it has.
397
- waited = await this.waitOut(value.claim, waited);
458
+ const yielded = await this.yieldTo(op, value.claim, waited);
459
+ if (!yielded.ok)
460
+ return yielded;
461
+ waited = yielded.value;
398
462
  continue;
463
+ }
399
464
  case 'create':
400
465
  return await this.create(op);
401
466
  case 'leased': {
@@ -419,10 +484,12 @@ export class RamTempVolume {
419
484
  lease: {
420
485
  directory: value.directory,
421
486
  mountpoint: this.paths.mountpoint,
422
- capacityBytes: value.volume.capacity,
487
+ attach: value.volume.attach,
423
488
  },
424
489
  held: [...value.held, ...settled.value.held].map((lease) => lease.text),
425
490
  reaped: [...settled.value.reaped],
491
+ retained: [...settled.value.retained],
492
+ gaps: [...settled.value.gaps],
426
493
  },
427
494
  };
428
495
  }
@@ -431,7 +498,7 @@ export class RamTempVolume {
431
498
  }
432
499
  /** With this caller's creation claim published: provision the volume, then take the first lease on it. */
433
500
  async create(op) {
434
- const provisioned = await this.provisionVolume();
501
+ const provisioned = await this.provisionVolume(op);
435
502
  if (!provisioned.ok) {
436
503
  return provisioned;
437
504
  }
@@ -449,7 +516,11 @@ export class RamTempVolume {
449
516
  value: failed('create', `${this.paths.mountpoint} is not the marked volume once provisioned`),
450
517
  };
451
518
  }
452
- return { ledger: next, value: { ok: true, value: await this.make(op) } };
519
+ const directory = await this.make(op);
520
+ return {
521
+ ledger: next,
522
+ value: { ok: true, value: { directory, mountpoint: this.paths.mountpoint, attach: volume.attach } },
523
+ };
453
524
  });
454
525
  if (!placed.ok) {
455
526
  return placed;
@@ -461,67 +532,68 @@ export class RamTempVolume {
461
532
  ok: true,
462
533
  value: {
463
534
  kind: 'leased',
464
- lease: { directory: placed.value.value, mountpoint: this.paths.mountpoint, capacityBytes: this.capacityBytes },
535
+ lease: placed.value.value,
465
536
  held: [],
466
537
  reaped: [],
538
+ retained: [],
539
+ gaps: [],
467
540
  },
468
541
  };
469
542
  }
470
543
  /**
471
- * Stop what the task left working in its lease, before the lease ends: the processes whose
472
- * working directory is in it and everything they started, answered as `<pid> (<command>)`.
473
- * Runs outside the volume's lock, which one lease's leftovers must not hold up the others
474
- * behind, and costs a scan of every process only when the lease still holds anything.
544
+ * Record the supervisor's handle on the subtree whose command uses `lease`, beside the lease, so
545
+ * that if this task dies before it retires that subtree, whoever settles the dead lease can hand
546
+ * the handle back to the supervisor instead of guessing from a census who worked there.
475
547
  */
476
- async reap(lease) {
548
+ async record(lease, handle) {
477
549
  try {
478
- const entries = await readdir(lease.directory).catch((error) => {
479
- if (errorCode(error) === 'ENOENT')
480
- return [];
481
- throw error;
482
- });
483
- if (entries.length === 0) {
484
- return { ok: true, value: [] };
485
- }
486
- return { ok: true, value: await this.processes.stopWorkingIn(lease.directory) };
550
+ await writeFile(subtreeRecordPath(lease.directory), `${JSON.stringify(handle)}\n`, { mode: 0o600 });
551
+ return { ok: true, value: undefined };
487
552
  }
488
553
  catch (error) {
489
- return failed('reap', errorText(error));
554
+ return failed('record subtree', errorText(error));
490
555
  }
491
556
  }
492
- /** End a lease; the last lease detaches the volume, returning its RAM. */
493
- async release(lease) {
494
- const op = { owner: { pid: this.pid, token: randomUUID() }, claimed: false, made: null };
557
+ /**
558
+ * End a lease; the last lease detaches the volume, returning its RAM. `keep` archives the lease's scratch instead of
559
+ * deleting it: its run did not pass. A dead lease found on the way is settled through `subtrees`. Answers what became
560
+ * of every scratch this release reclaimed, its own included.
561
+ */
562
+ async release(lease, keep, subtrees) {
563
+ const op = { owner: { pid: this.pid, token: randomUUID() }, subtrees, claimed: false, made: null };
495
564
  let result;
496
565
  try {
497
- result = await this.releaseLease(op, basename(lease.directory));
566
+ result = await this.releaseLease(op, lease, keep);
498
567
  }
499
568
  catch (error) {
500
569
  result = failed('release', errorText(error));
501
570
  }
502
571
  const ended = await this.end(op);
503
572
  if (result.ok) {
504
- return ended;
573
+ return ended.ok ? result : ended;
505
574
  }
506
575
  const primary = result.error.kind === 'lock-denied'
507
576
  ? { kind: 'provision-failed', step: 'lock', detail: result.error.detail }
508
577
  : result.error;
509
578
  return { ok: false, error: alsoFailed(primary, ended.ok ? [] : [ended.error]) };
510
579
  }
511
- async releaseLease(op, own) {
580
+ async releaseLease(op, lease, keep) {
581
+ const own = basename(lease.directory);
512
582
  let waited = null;
513
583
  for (;;) {
514
584
  const taken = await this.locked(op, 'release', async (ledger, volume) => {
515
- if (volume === null) {
516
- return { ledger, value: { kind: 'unmounted' } };
585
+ // A lease that went while its task held it is said, never released as though it were there.
586
+ const held = leaseOn(lease, volume);
587
+ if ('lost' in held) {
588
+ return { ledger, value: { kind: 'lost', detail: held.lost } };
517
589
  }
518
590
  if (ledger.lifecycle !== null) {
519
591
  return { ledger, value: { kind: 'wait', claim: ledger.lifecycle } };
520
592
  }
521
- const claimed = await this.claim(ledger, volume, op.owner, own);
593
+ const claimed = await this.claim(ledger, held.on, op.owner, own, keep);
522
594
  return {
523
595
  ledger: claimed.ledger,
524
- value: { kind: 'claimed', volume, held: claimed.held, candidates: claimed.candidates },
596
+ value: { kind: 'claimed', volume: held.on, held: claimed.held, candidates: claimed.candidates },
525
597
  };
526
598
  });
527
599
  if (!taken.ok) {
@@ -529,11 +601,18 @@ export class RamTempVolume {
529
601
  }
530
602
  const value = taken.value;
531
603
  switch (value.kind) {
532
- case 'unmounted':
533
- return { ok: true, value: undefined };
534
- case 'wait':
535
- waited = await this.waitOut(value.claim, waited);
604
+ case 'lost':
605
+ return {
606
+ ok: false,
607
+ error: { kind: 'lease-lost', lease: lease.directory, mountpoint: lease.mountpoint, detail: value.detail },
608
+ };
609
+ case 'wait': {
610
+ const yielded = await this.yieldTo(op, value.claim, waited);
611
+ if (!yielded.ok)
612
+ return yielded;
613
+ waited = yielded.value;
536
614
  continue;
615
+ }
537
616
  case 'claimed': {
538
617
  const settled = await this.settle(op, value.volume, value.candidates);
539
618
  if (!settled.ok) {
@@ -556,7 +635,23 @@ export class RamTempVolume {
556
635
  if (kept !== undefined) {
557
636
  return failed('release', kept.text);
558
637
  }
559
- return idle.value ? await this.detach(op, value.volume) : { ok: true, value: undefined };
638
+ if (!idle.value) {
639
+ return { ok: true, value: [...settled.value.retained] };
640
+ }
641
+ const detached = await this.detach(op, value.volume);
642
+ if (!detached.ok) {
643
+ return detached;
644
+ }
645
+ // The volume's pages go with it, its archives included: what the lines above kept lived until now.
646
+ return {
647
+ ok: true,
648
+ value: [
649
+ ...settled.value.retained,
650
+ ...(settled.value.retained.length > 0
651
+ ? [`${this.paths.mountpoint} detached with its last lease, and every archive on it went with it`]
652
+ : []),
653
+ ],
654
+ };
560
655
  }
561
656
  }
562
657
  }
@@ -572,33 +667,51 @@ export class RamTempVolume {
572
667
  const elapsed = now - wait.since;
573
668
  const due = Math.floor(elapsed / CLAIM_WAIT_NOTICE_MS);
574
669
  if (due > wait.notices) {
575
- process.stderr.write(`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`);
670
+ process.stderr.write(`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}${claim.pending === undefined ? `; if that pid is not ${claim.kind === 'create' ? 'creating' : 'detaching'} ${this.paths.mountpoint}, remove the ledger once no task uses the volume` : `; that caller still waits on its detach of ${claim.pending.physical}, whose custody the ledger keeps`}\n`);
576
671
  }
577
672
  await sleep(LOCK_RETRY_MS);
578
673
  return { ...wait, notices: Math.max(wait.notices, due) };
579
674
  }
580
- /** After a failed task: whether the volume ran out of space, which is then the error to report. */
675
+ /**
676
+ * After a failed task: whether the volume ran out of space, which is then the error to report. A lease no longer on
677
+ * its volume is said by its release, and a volume that cannot be read has no space to report.
678
+ */
581
679
  async fullness(lease) {
582
680
  const space = await this.space(lease);
583
- if (space === null || space.freeBytes >= FULL_FREE_BYTES) {
681
+ if (space.kind !== 'measured' || space.freeBytes >= FULL_FREE_BYTES) {
584
682
  return null;
585
683
  }
586
684
  const { mountpoint, capacityBytes, freeBytes } = space;
587
685
  return { kind: 'volume-full', mountpoint, capacityBytes, freeBytes };
588
686
  }
589
- /** The lease's volume and the space left on it now; `null` when the volume cannot be read. */
687
+ /**
688
+ * The lease's volume and the space left on it now, measured only while the mountpoint holds the attach the lease was
689
+ * taken on and the lease is still on it: a bare mountpoint's statfs reads the host's Data volume, whose free space is
690
+ * not the lease's. A lease that went with its volume, or from it, is `lost`; a read that failed is `unread`.
691
+ */
590
692
  async space(lease) {
693
+ const { directory, mountpoint } = lease;
591
694
  try {
592
- const fs = await statfs(lease.mountpoint);
695
+ const observed = await this.observe();
696
+ if (!observed.ok) {
697
+ const detail = observed.error.kind === 'lock-denied' ? observed.error.detail : describeRamTempError(observed.error);
698
+ return { kind: 'unread', lease: directory, mountpoint, detail };
699
+ }
700
+ const held = leaseOn(lease, observed.value);
701
+ if ('lost' in held) {
702
+ return { kind: 'lost', lease: directory, mountpoint, detail: held.lost };
703
+ }
704
+ const fs = await statfs(mountpoint);
593
705
  return {
594
- lease: lease.directory,
595
- mountpoint: lease.mountpoint,
596
- capacityBytes: lease.capacityBytes,
706
+ kind: 'measured',
707
+ lease: directory,
708
+ mountpoint,
709
+ capacityBytes: fs.blocks * fs.bsize,
597
710
  freeBytes: fs.bavail * fs.bsize,
598
711
  };
599
712
  }
600
- catch {
601
- return null;
713
+ catch (error) {
714
+ return { kind: 'unread', lease: directory, mountpoint, detail: errorText(error) };
602
715
  }
603
716
  }
604
717
  async lock() {
@@ -618,7 +731,121 @@ export class RamTempVolume {
618
731
  }
619
732
  }
620
733
  }
621
- /** Drop whatever claims `op` still holds: an operation that failed part way leaves none behind it. */
734
+ /**
735
+ * Yield to another caller's lifecycle claim. Every claim is queued behind, a detach whose live caller still waits on
736
+ * its facade included. Reported custody, or waiting custody whose caller died, admits nothing until its exact
737
+ * registry entry is gone: the caller's liveness only chooses between queueing and reporting, never clears custody.
738
+ */
739
+ async yieldTo(op, claim, waited) {
740
+ const pending = claim.pending;
741
+ if (pending === undefined || (pending.phase === 'waiting' && this.isAlive(claim.owner.pid))) {
742
+ return { ok: true, value: await this.waitOut(claim, waited) };
743
+ }
744
+ const reconciled = await this.reconcileDetach(op, claim);
745
+ return reconciled.ok ? { ok: true, value: waited } : reconciled;
746
+ }
747
+ /** A detach nobody waits on any more can be reconciled only against its exact registry identity, outside the lock. */
748
+ async reconcileDetach(op, claim) {
749
+ const pending = claim.pending;
750
+ if (pending === undefined)
751
+ return { ok: true, value: undefined };
752
+ if (pending.registryEntry !== null) {
753
+ const registry = await this.commands.run('/usr/sbin/ioreg', ['-r', '-c', 'IOHDIXHDDriveOutKernel', '-l', '-w0']);
754
+ if (registry.status !== 0)
755
+ return failed('detach custody', commandText(registry));
756
+ const disks = ramDisksIn(registry.stdout, '');
757
+ if (!disks.ok)
758
+ return failed('detach custody', disks.error);
759
+ if (!disks.value.some((disk) => disk.entry === pending.registryEntry)) {
760
+ return this.locked(op, 'detach custody', async (ledger) => ({
761
+ ledger: sameDetach(ledger.lifecycle, claim.owner, pending) ? { ...ledger, lifecycle: null } : ledger,
762
+ value: undefined,
763
+ }));
764
+ }
765
+ }
766
+ return failed('detach custody', `${pending.physical} (registry ${pending.registryEntry ?? 'unbound'}, ${pending.phase} by pid ${claim.owner.pid}, facade ${pending.facadePid ?? 'unrecorded'}) still has pending detach authority in ${this.ledgerPath}; no lease admitted until terminal completion${pending.registryEntry === null ? '' : ' or that registry entry disappears'}`);
767
+ }
768
+ /** Publish authority before spawn: a crash anywhere after this point must not admit a lease past the detach. */
769
+ async runDetach(op, physical, registryEntry) {
770
+ const custody = { physical, registryEntry, phase: 'waiting', facadePid: null };
771
+ const begun = await this.locked(op, 'detach custody', async (ledger) => {
772
+ const claim = ledger.lifecycle;
773
+ if (claim?.owner.token !== op.owner.token || claim.pending !== undefined)
774
+ return { ledger, value: false };
775
+ return { ledger: { ...ledger, lifecycle: { ...claim, pending: custody } }, value: true };
776
+ });
777
+ if (!begun.ok)
778
+ return begun.error.kind === 'lock-denied'
779
+ ? failed('lock', begun.error.detail)
780
+ : { ok: false, error: begun.error };
781
+ if (!begun.value)
782
+ return failed('detach custody', 'the operation no longer owns an idle lifecycle claim; nothing detached');
783
+ let output;
784
+ try {
785
+ if (registryEntry === null)
786
+ throw new Error('detach has no captured registry identity; retained without dispatch');
787
+ output = await this.commands.detachRam(physical, registryEntry);
788
+ }
789
+ catch (error) {
790
+ // Whether a child started is unknown, so its custody is reported, never dropped.
791
+ const reported = await this.reportDetach(op, custody, null);
792
+ const detail = `the detach of ${physical} gave no answer (${errorText(error)}); its custody stays reported in ${this.ledgerPath}`;
793
+ return failed('detach custody', reported.ok ? detail : `${detail}; ${describeRamTempError(reported.error)}`);
794
+ }
795
+ const pending = output.pending;
796
+ if (pending === undefined) {
797
+ const finished = await this.finishDetach(op, custody, false);
798
+ return finished.ok ? { ok: true, value: output } : finished;
799
+ }
800
+ const retained = await this.reportDetach(op, custody, pending.pid);
801
+ // The gateway owns the mutation. Only its authoritative terminal/not-started reply clears this request; a lost connection does not.
802
+ void pending.completion
803
+ .then(async (terminal) => {
804
+ if (terminal === null)
805
+ return;
806
+ const finished = await this.finishDetach(op, custody, true);
807
+ process.stderr.write(`RAM temp volume: detach of ${physical} completed after its caller stopped waiting (${commandText(terminal)}); ${finished.ok ? 'terminal receipt processed' : describeRamTempError(finished.error)}\n`);
808
+ })
809
+ .catch((error) => {
810
+ process.stderr.write(`RAM temp volume: detach completion for ${physical} could not publish: ${errorText(error)}\n`);
811
+ });
812
+ return retained.ok ? { ok: true, value: output } : retained;
813
+ }
814
+ /** Only this operation's exact terminal receipt can clear its pending authority; a late receipt cannot clear a successor. */
815
+ async finishDetach(op, custody, release) {
816
+ const finished = await this.locked(op, 'detach completion', async (ledger) => {
817
+ const claim = ledger.lifecycle;
818
+ if (claim === null || !sameDetach(claim, op.owner, custody))
819
+ return { ledger, value: undefined };
820
+ return {
821
+ ledger: { ...ledger, lifecycle: release ? null : { kind: claim.kind, owner: claim.owner } },
822
+ value: undefined,
823
+ };
824
+ });
825
+ if (finished.ok)
826
+ return finished;
827
+ return finished.error.kind === 'lock-denied'
828
+ ? failed('lock', finished.error.detail)
829
+ : { ok: false, error: finished.error };
830
+ }
831
+ /** Its caller stops waiting on the detach: the exact custody becomes reported, its facade pid kept for diagnosis. */
832
+ async reportDetach(op, custody, facadePid) {
833
+ const reported = await this.locked(op, 'detach custody', async (ledger) => {
834
+ const claim = ledger.lifecycle;
835
+ if (claim === null || !sameDetach(claim, op.owner, custody))
836
+ return { ledger, value: undefined };
837
+ return {
838
+ ledger: { ...ledger, lifecycle: { ...claim, pending: { ...custody, phase: 'reported', facadePid } } },
839
+ value: undefined,
840
+ };
841
+ });
842
+ if (reported.ok)
843
+ return reported;
844
+ return reported.error.kind === 'lock-denied'
845
+ ? failed('lock', reported.error.detail)
846
+ : { ok: false, error: reported.error };
847
+ }
848
+ /** Drop finished claims, never the authority of a detach whose caller merely stopped waiting. */
622
849
  async end(op) {
623
850
  if (!op.claimed) {
624
851
  return { ok: true, value: undefined };
@@ -640,33 +867,62 @@ export class RamTempVolume {
640
867
  * `change` reads metadata and takes or names directories; it runs no host command.
641
868
  */
642
869
  async locked(op, step, change) {
643
- const lock = await this.lock();
644
- if (!lock.ok) {
645
- return lock.error.code === 'EPERM'
646
- ? { ok: false, error: { kind: 'lock-denied', detail: `${this.paths.lockFile}: ${lock.error.message}` } }
647
- : failed('lock', lock.error.message);
648
- }
649
- try {
650
- const read = await this.readLedger();
651
- if (!read.ok) {
652
- return read;
870
+ for (;;) {
871
+ // Registry work stays outside the lock. A changed locked identity invalidates this
872
+ // snapshot; release the lock and prove the replacement afresh before any mutation.
873
+ const initialLedger = await this.readLedger();
874
+ if (!initialLedger.ok)
875
+ return initialLedger;
876
+ const before = await this.observe();
877
+ if (!before.ok)
878
+ return before;
879
+ if (before.value !== null && op.provenance !== before.value.key) {
880
+ const validated = await this.validateProvenance(before.value);
881
+ if (!validated.ok) {
882
+ // The last release detaches outside the lock, so the volume can go between its observation and this
883
+ // registry read: a volume no longer there is looked at again, and only the one still mounted is refused.
884
+ const again = await this.observe();
885
+ if (!again.ok)
886
+ return again;
887
+ if (again.value?.key !== before.value.key)
888
+ continue;
889
+ return validated;
890
+ }
891
+ op.provenance = before.value.key;
653
892
  }
654
- const volume = await this.observe();
655
- const next = await change(prune(read.value.ledger, volume, this.isAlive), volume);
656
- const text = ledgerText(next.ledger);
657
- if (text !== (read.value.text ?? ledgerText(EMPTY_LEDGER))) {
658
- await publishLedger(this.ledgerPath, text);
893
+ const lock = await this.lock();
894
+ if (!lock.ok) {
895
+ return lock.error.code === 'EPERM'
896
+ ? { ok: false, error: { kind: 'lock-denied', detail: `${this.paths.lockFile}: ${lock.error.message}` } }
897
+ : failed('lock', lock.error.message);
898
+ }
899
+ try {
900
+ const read = await this.readLedger();
901
+ if (!read.ok)
902
+ return read;
903
+ const observed = await this.observe();
904
+ if (!observed.ok)
905
+ return observed;
906
+ const volume = observed.value;
907
+ if (volume !== null && (volume.key !== before.value?.key || op.provenance !== volume.key)) {
908
+ op.provenance = undefined;
909
+ continue;
910
+ }
911
+ const next = await change(prune(read.value.ledger, volume, this.isAlive), volume);
912
+ const text = ledgerText(next.ledger);
913
+ if (text !== (read.value.text ?? ledgerText(EMPTY_LEDGER)))
914
+ await publishLedger(this.ledgerPath, text);
915
+ op.claimed =
916
+ next.ledger.lifecycle?.owner.token === op.owner.token ||
917
+ next.ledger.claims.some((claim) => claim.owner.token === op.owner.token);
918
+ return { ok: true, value: next.value };
919
+ }
920
+ catch (error) {
921
+ return failed(step, errorText(error));
922
+ }
923
+ finally {
924
+ await lock.value.close();
659
925
  }
660
- op.claimed =
661
- next.ledger.lifecycle?.owner.token === op.owner.token ||
662
- next.ledger.claims.some((claim) => claim.owner.token === op.owner.token);
663
- return { ok: true, value: next.value };
664
- }
665
- catch (error) {
666
- return failed(step, errorText(error));
667
- }
668
- finally {
669
- await lock.value.close();
670
926
  }
671
927
  }
672
928
  /** The ledger as published, and its text; none yet is an empty one. Only this module writes it, whole. */
@@ -687,9 +943,9 @@ export class RamTempVolume {
687
943
  }
688
944
  return failed('ledger', `${this.ledgerPath}: ${errorText(error)}`);
689
945
  }
690
- // Claims that cannot be read cannot be honoured, so no lease or volume change is safe until it is
691
- // removed; only this module writes it, in one rename, so a malformed one is not its own.
692
- const refused = (detail) => failed('ledger', `${this.ledgerPath} ${detail}; remove it once no task uses the volume`);
946
+ // An unreadable ledger may hold detached-child authority even after every caller died.
947
+ // Preserve it and refuse admission rather than suggesting pid death authorizes its removal.
948
+ const refused = (detail) => failed('ledger', `${this.ledgerPath} ${detail}; retained; no lease or detach admitted while its authority is unreadable`);
693
949
  let wire;
694
950
  try {
695
951
  wire = JSON.parse(text);
@@ -697,6 +953,9 @@ export class RamTempVolume {
697
953
  catch (error) {
698
954
  return refused(`is not JSON: ${errorText(error)}`);
699
955
  }
956
+ if (isRecord(wire) && wire.version !== 1 && wire.version !== 2) {
957
+ return refused(`has unsupported version ${JSON.stringify(wire.version)}`);
958
+ }
700
959
  const ledger = parseLedger(wire);
701
960
  return ledger === undefined ? refused("is not this module's ledger") : { ok: true, value: { ledger, text } };
702
961
  }
@@ -707,35 +966,124 @@ export class RamTempVolume {
707
966
  */
708
967
  async observe() {
709
968
  const markerPath = join(this.paths.mountpoint, MARKER_FILE);
710
- const marker = await readFile(markerPath, 'utf8').catch(() => null);
711
- if (marker?.trim() !== this.paths.volumeName) {
712
- return null;
969
+ let markerText;
970
+ try {
971
+ const handle = await open(markerPath, constants.O_RDONLY | constants.O_NOFOLLOW);
972
+ try {
973
+ markerText = await handle.readFile('utf8');
974
+ }
975
+ finally {
976
+ await handle.close();
977
+ }
713
978
  }
714
- const [root, parent, mark] = await Promise.all([
715
- stat(this.paths.mountpoint, { bigint: true }),
716
- stat(join(this.paths.mountpoint, '..'), { bigint: true }),
717
- lstat(markerPath, { bigint: true }),
718
- ]);
719
- if (root.dev === parent.dev) {
720
- return null;
979
+ catch (error) {
980
+ if (errorCode(error) === 'ENOENT')
981
+ return { ok: true, value: null };
982
+ return errorCode(error) === 'EPERM' ? denied(markerPath, error) : failed('provenance', errorText(error));
721
983
  }
722
- const [fs, names] = await Promise.all([statfs(this.paths.mountpoint), readdir(this.paths.mountpoint)]);
984
+ if (markerText.trim() === this.paths.volumeName) {
985
+ return {
986
+ ok: false,
987
+ error: {
988
+ kind: 'ram-unavailable',
989
+ reason: 'unproven-owner',
990
+ detail: `${this.paths.mountpoint} has a legacy name-only marker; no lease, reclaim or detach admitted`,
991
+ },
992
+ };
993
+ }
994
+ let marker;
995
+ try {
996
+ marker = JSON.parse(markerText);
997
+ }
998
+ catch (error) {
999
+ return failed('provenance', `malformed volume marker: ${errorText(error)}`);
1000
+ }
1001
+ if (!isRecord(marker) ||
1002
+ marker.version !== 1 ||
1003
+ marker.volumeName !== this.paths.volumeName ||
1004
+ marker.owner !== 'gateway' ||
1005
+ typeof marker.registryEntry !== 'string' ||
1006
+ !/^0x[0-9a-f]+$/.test(marker.registryEntry)) {
1007
+ return failed('provenance', 'the marker is not version-1 gateway provenance for this volume');
1008
+ }
1009
+ let root;
1010
+ let parent;
1011
+ let mark;
1012
+ let names;
1013
+ try {
1014
+ [root, parent, mark] = await Promise.all([
1015
+ stat(this.paths.mountpoint, { bigint: true }),
1016
+ stat(join(this.paths.mountpoint, '..'), { bigint: true }),
1017
+ lstat(markerPath, { bigint: true }),
1018
+ ]);
1019
+ names = await readdir(this.paths.mountpoint);
1020
+ }
1021
+ catch (error) {
1022
+ if (errorCode(error) === 'EPERM')
1023
+ return denied(this.paths.mountpoint, error);
1024
+ // The marker was read, then the volume went: the last release detaches it outside the lock, and its mountpoint
1025
+ // with it. What is mounted now is nothing, as when the marker is not there to read.
1026
+ if (errorCode(error) === 'ENOENT')
1027
+ return { ok: true, value: null };
1028
+ throw error;
1029
+ }
1030
+ if (root.dev === parent.dev || !mark.isFile())
1031
+ return failed('provenance', 'gateway marker is not on a separately mounted RAM volume');
1032
+ const rootIdentity = `root ${root.dev}:${root.ino}:${root.birthtimeNs}`;
1033
+ const registry = `registry ${marker.registryEntry}`;
723
1034
  return {
724
- capacity: fs.blocks * fs.bsize,
725
- key: [
726
- `root ${root.dev}:${root.ino}:${root.birthtimeNs}`,
727
- `marker ${mark.dev}:${mark.ino}:${mark.birthtimeNs}:${mark.ctimeNs}`,
728
- ].join(' '),
729
- device: Number(root.dev),
730
- leases: names.filter((name) => LEASE_NAME.test(name)),
1035
+ ok: true,
1036
+ value: {
1037
+ registryEntry: marker.registryEntry,
1038
+ key: [rootIdentity, `marker ${mark.dev}:${mark.ino}:${mark.birthtimeNs}:${mark.ctimeNs}`, registry].join(' '),
1039
+ attach: `${rootIdentity} ${registry}`,
1040
+ device: Number(root.dev),
1041
+ leases: names.filter((name) => LEASE_NAME.test(name)),
1042
+ },
731
1043
  };
732
1044
  }
1045
+ /** Prove this immutable marker belongs to the exact live attachment, outside the lock. */
1046
+ async validateProvenance(volume) {
1047
+ const registry = await this.commands.run('/usr/sbin/ioreg', ['-r', '-c', 'IOHDIXHDDriveOutKernel', '-l', '-w0']);
1048
+ const mounts = await this.commands.run('/sbin/mount', []);
1049
+ if (registry.status !== 0 || mounts.status !== 0)
1050
+ return failed('provenance', commandText(registry.status !== 0 ? registry : mounts));
1051
+ const parsed = ramDisksIn(registry.stdout, mounts.stdout);
1052
+ if (!parsed.ok)
1053
+ return failed('provenance', parsed.error);
1054
+ const disk = parsed.value.find((candidate) => candidate.entry === volume.registryEntry);
1055
+ return disk !== undefined &&
1056
+ disk.physical !== null &&
1057
+ disk.uid === this.paths.uid &&
1058
+ disk.sectors === this.sectors &&
1059
+ disk.mountpoints.includes(this.paths.mountpoint)
1060
+ ? { ok: true, value: undefined }
1061
+ : failed('provenance', `recorded registry entry ${volume.registryEntry} no longer names this mounted volume; no lease or detach admitted`);
1062
+ }
1063
+ /** Capture only the exact whole disk this attach answered, before any filesystem mutation. */
1064
+ async attachedIdentity(physical) {
1065
+ const registry = await this.commands.run('/usr/sbin/ioreg', ['-r', '-c', 'IOHDIXHDDriveOutKernel', '-l', '-w0']);
1066
+ if (registry.status !== 0)
1067
+ return failed('attach identity', commandText(registry));
1068
+ const parsed = ramDisksIn(registry.stdout, '');
1069
+ if (!parsed.ok)
1070
+ return failed('attach identity', parsed.error);
1071
+ const matches = parsed.value.filter((disk) => disk.physical === physical);
1072
+ const [disk] = matches;
1073
+ return matches.length === 1 &&
1074
+ disk !== undefined &&
1075
+ disk.physical !== null &&
1076
+ disk.uid === this.paths.uid &&
1077
+ disk.sectors === this.sectors
1078
+ ? { ok: true, value: { ...disk, physical: disk.physical } }
1079
+ : failed('attach identity', `${physical} is not the unique registry identity of this gateway attach; no provisioning or guessed detach`);
1080
+ }
733
1081
  /**
734
1082
  * Under the lock: claim `own`, the caller's ending lease if any, and every dead lease no other
735
1083
  * caller is settling. A dead lease whose cached verdict still validates is named held and left
736
1084
  * unclaimed: that proof costs `lstat` calls, not a host-wide probe, so no caller waits on it.
737
1085
  */
738
- async claim(ledger, volume, owner, own) {
1086
+ async claim(ledger, volume, owner, own, keepOwn) {
739
1087
  const held = [];
740
1088
  const candidates = [];
741
1089
  const claims = [...ledger.claims];
@@ -763,42 +1111,78 @@ export class RamTempVolume {
763
1111
  verdicts = verdicts.filter((entry) => entry !== cached);
764
1112
  }
765
1113
  claims.push({ name, identity, owner });
766
- candidates.push({ name, directory, identity, own: name === own });
1114
+ candidates.push({ name, directory, identity, own: name === own, keep: name !== own || keepOwn });
767
1115
  }
768
1116
  return { ledger: { ...ledger, claims, held: verdicts }, held, candidates };
769
1117
  }
770
1118
  /**
771
- * Outside the lock: settle the leases this caller claimed. The processes every dead one still
772
- * runs are stopped first, and only then is the pass's one inventory read, so no inventory older
773
- * than a lease's settled census approves its removal. Anything attached from below a lease keeps
774
- * it: an image backed by a file there would be left pinned to a deleted file, and detaching it
775
- * here would race the owner that releases it under its own lease; a mount there is backed
776
- * elsewhere — a cowshed workspace adopted from a fixture checkout, say — and `rm -r` would
1119
+ * Outside the lock: settle the leases this caller claimed. Every dead one's recorded subtree is
1120
+ * handed back to the supervisor first, and only then is the pass's one inventory read, so no
1121
+ * inventory older than a lease's retirement approves its removal. Anything attached from below a
1122
+ * lease keeps it: an image backed by a file there would be left pinned to a deleted file, and
1123
+ * detaching it here would race the owner that releases it under its own lease; a mount there is
1124
+ * backed elsewhere — a cowshed workspace adopted from a fixture checkout, say — and `rm -r` would
777
1125
  * delete its contents through the mount. A kept lease gets a verdict to publish, when its
778
- * holders have cheap lifetime keys. A lease nothing holds is removed once the lock confirms it
779
- * is as claimed.
1126
+ * holders have cheap lifetime keys. A lease nothing holds is reclaimed once the lock confirms it
1127
+ * is as claimed: a kept one's scratch is renamed into the archive (`retain`), any other deleted.
780
1128
  */
781
1129
  async settle(op, volume, candidates) {
782
1130
  if (candidates.length === 0) {
783
- return { ok: true, value: { held: [], reaped: [], verdicts: [] } };
1131
+ return { ok: true, value: { held: [], reaped: [], gaps: [], retained: [], verdicts: [] } };
784
1132
  }
785
1133
  const reaped = [];
1134
+ const gaps = [];
1135
+ const held = [];
786
1136
  for (const candidate of candidates) {
787
- // Its task is gone, so what works in it is what that task left: stopped before the lease is
788
- // removed, even where the removal is refused below. An empty lease is asked too: a leftover
789
- // that has not written yet writes once it runs again. A task reaps its own (`reap`).
790
- if (!candidate.own) {
791
- reaped.push(...(await this.processes.stopWorkingIn(candidate.directory)));
1137
+ // A task retires its own subtree before it releases; a dead one could not. Its subtree is the
1138
+ // supervisor's to end, named by the handle the task recorded — never by who works in the lease
1139
+ // (specs/cowshed/07_api.md, `JobSubtreeHandle`). A lease with no readable handle recorded none
1140
+ // to retire: its task died before its command was admitted, or that admission was refused.
1141
+ if (candidate.own) {
1142
+ continue;
1143
+ }
1144
+ const recorded = await readFile(subtreeRecordPath(candidate.directory), 'utf8').catch((error) => {
1145
+ if (errorCode(error) === 'ENOENT')
1146
+ return null;
1147
+ throw error;
1148
+ });
1149
+ const handle = recorded === null ? null : parseHandle(recorded);
1150
+ if (handle === null) {
1151
+ continue;
1152
+ }
1153
+ const retired = await op.subtrees.retire(handle, LEFTOVER_GRACE_MS);
1154
+ switch (retired.kind) {
1155
+ case 'retired':
1156
+ reaped.push(...retired.signalled.map(describeSignalled));
1157
+ if (retired.signalledIncomplete) {
1158
+ gaps.push(`${candidate.directory}: the supervisor may have ended processes it could not name`);
1159
+ }
1160
+ gaps.push(...retired.gaps.map((gap) => `${candidate.directory}: ${describeCoverageGap(gap)}`));
1161
+ break;
1162
+ case 'refused':
1163
+ // An ended job's supervisor retired its whole tree as it ended, and a spent handle was
1164
+ // already retired: either way nothing of that subtree is left to end.
1165
+ if (retired.reason !== 'jobEnded' && retired.reason !== 'spentHandle') {
1166
+ held.push({
1167
+ name: candidate.name,
1168
+ text: `${candidate.directory} is kept: its subtree is not this task's to retire (supervisor: ${retired.reason}); it goes once that subtree's job ends`,
1169
+ });
1170
+ }
1171
+ break;
1172
+ case 'failed':
1173
+ return failed('retire', `${candidate.directory}: ${retired.detail}`);
792
1174
  }
793
1175
  }
794
1176
  const inventory = await this.readInventory();
795
1177
  if (!inventory.ok) {
796
1178
  return inventory;
797
1179
  }
798
- const held = [];
799
1180
  const verdicts = [];
800
1181
  const removable = [];
801
1182
  for (const candidate of candidates) {
1183
+ if (held.some((lease) => lease.name === candidate.name)) {
1184
+ continue;
1185
+ }
802
1186
  const below = candidatesBelow(inventory.value, `${candidate.directory}/`);
803
1187
  if (below.length === 0) {
804
1188
  removable.push(candidate);
@@ -812,6 +1196,7 @@ export class RamTempVolume {
812
1196
  verdicts.push({ lease: candidate.name, verdict: captured.value });
813
1197
  }
814
1198
  }
1199
+ const archived = [];
815
1200
  if (removable.length > 0) {
816
1201
  const confirmed = await this.locked(op, 'reclaim', async (ledger, current) => ({
817
1202
  ledger,
@@ -821,13 +1206,93 @@ export class RamTempVolume {
821
1206
  return confirmed;
822
1207
  }
823
1208
  for (const candidate of confirmed.value) {
1209
+ // Its subtree was retired above, or had ended: the handle beside the lease is spent either way.
1210
+ await rm(subtreeRecordPath(candidate.directory), { force: true });
1211
+ if (candidate.keep) {
1212
+ // One rename on the volume: the scratch stays whole and readable, and nothing waits on a deletion.
1213
+ const archive = `${String(Date.now()).padStart(13, '0')}-${candidate.name}`;
1214
+ await mkdir(join(this.paths.mountpoint, ARCHIVE_DIR), { recursive: true, mode: 0o700 });
1215
+ await rename(candidate.directory, join(this.paths.mountpoint, ARCHIVE_DIR, archive));
1216
+ archived.push({ directory: candidate.directory, archive });
1217
+ continue;
1218
+ }
824
1219
  // Nothing holds the lease, so its directories may be made removable first: `rm -r` cannot
825
1220
  // empty a readonly one. Only this volume's device is changed (see prepareForRemoval).
826
1221
  await prepareForRemoval(candidate.directory, volume.device);
827
1222
  await rm(candidate.directory, { recursive: true, force: true });
828
1223
  }
829
1224
  }
830
- return { ok: true, value: { held, reaped, verdicts } };
1225
+ const retained = archived.length === 0 ? [] : await this.retain(volume, archived);
1226
+ return { ok: true, value: { held, reaped, gaps, retained, verdicts } };
1227
+ }
1228
+ /**
1229
+ * Keep the newest {@link ARCHIVES_KEPT} archives while at least {@link ARCHIVE_FLOOR_SHARE} of the volume is free, and
1230
+ * none below that; rename every other one out of the archive and delete it in the background. Answers, for each lease
1231
+ * just archived, where its scratch is kept or why it was not. The floor is read once, here, as an archive arrives.
1232
+ */
1233
+ async retain(volume, archived) {
1234
+ const root = join(this.paths.mountpoint, ARCHIVE_DIR);
1235
+ const [fs, names] = await Promise.all([statfs(this.paths.mountpoint), readdir(root)]);
1236
+ const freeBytes = fs.bavail * fs.bsize;
1237
+ const floorBytes = Math.ceil(fs.blocks * fs.bsize * ARCHIVE_FLOOR_SHARE);
1238
+ const archives = names.filter((name) => ARCHIVE_NAME.test(name)).sort();
1239
+ const kept = freeBytes < floorBytes ? [] : archives.slice(-ARCHIVES_KEPT);
1240
+ await mkdir(join(root, DELETING_DIR), { recursive: true, mode: 0o700 });
1241
+ for (const name of archives.filter((candidate) => !kept.includes(candidate))) {
1242
+ await rename(join(root, name), join(root, DELETING_DIR, `${this.pid}-${name}`)).catch((error) => {
1243
+ // Another caller's retention renamed it first, and deletes it.
1244
+ if (errorCode(error) !== 'ENOENT')
1245
+ throw error;
1246
+ });
1247
+ }
1248
+ this.deleteArchives(volume.device);
1249
+ return archived.map(({ directory, archive }) => kept.includes(archive)
1250
+ ? `${directory} archived at ${join(root, archive)}: kept until ${ARCHIVES_KEPT} newer archives replace it, less than ${Math.round(floorBytes / MIB)} MiB of the volume is free when one arrives, or the volume detaches with its last lease`
1251
+ : freeBytes < floorBytes
1252
+ ? `${directory} deleted: the volume has ${Math.round(freeBytes / MIB)} MiB free, below the ${Math.round(floorBytes / MIB)} MiB under which it keeps no archive`
1253
+ : `${directory} deleted: ${ARCHIVES_KEPT} newer archives are kept`);
1254
+ }
1255
+ /**
1256
+ * Queue the deletion of the archives this process renamed out, and of any a dead deleter left, behind this process's
1257
+ * earlier ones. Nothing waits for it. A failure is said on stderr and leaves its entry for the next deleter.
1258
+ */
1259
+ deleteArchives(device) {
1260
+ archiveDeletion = archiveDeletion.then(() => this.emptyDeleting(device).catch((error) => {
1261
+ process.stderr.write(`RAM temp volume: could not delete an archive in ${join(this.paths.mountpoint, ARCHIVE_DIR, DELETING_DIR)}: ${errorText(error)}; the next archive's retention retries it\n`);
1262
+ }));
1263
+ }
1264
+ async emptyDeleting(device) {
1265
+ const root = join(this.paths.mountpoint, ARCHIVE_DIR, DELETING_DIR);
1266
+ const names = await readdir(root).catch((error) => {
1267
+ if (errorCode(error) === 'ENOENT')
1268
+ return [];
1269
+ throw error;
1270
+ });
1271
+ for (const name of names) {
1272
+ const claim = DELETING_NAME.exec(name);
1273
+ if (claim === null) {
1274
+ process.stderr.write(`RAM temp volume: ${join(root, name)} is no archive being deleted; left as it is\n`);
1275
+ continue;
1276
+ }
1277
+ let entry = join(root, name);
1278
+ const deleter = Number(claim[1]);
1279
+ if (deleter !== this.pid) {
1280
+ if (this.isAlive(deleter))
1281
+ continue;
1282
+ const mine = join(root, `${this.pid}-${claim[2]}`);
1283
+ const taken = await rename(entry, mine).then(() => true, (error) => {
1284
+ if (errorCode(error) === 'ENOENT')
1285
+ return false;
1286
+ throw error;
1287
+ });
1288
+ if (!taken)
1289
+ continue;
1290
+ entry = mine;
1291
+ }
1292
+ // An archive keeps its lease's modes, so a readonly directory in it is made removable first (see prepareForRemoval).
1293
+ await prepareForRemoval(entry, device);
1294
+ await rm(entry, { recursive: true, force: true });
1295
+ }
831
1296
  }
832
1297
  /**
833
1298
  * Under the lock: the claimed leases still as claimed — this caller's claim on the same
@@ -845,50 +1310,104 @@ export class RamTempVolume {
845
1310
  }
846
1311
  return confirmed;
847
1312
  }
848
- /** Detach what earlier creators left, then attach and provision the volume. */
849
- async provisionVolume() {
850
- const strays = await this.reclaimStrays(this.holdersPass());
851
- if (!strays.ok) {
852
- return strays;
1313
+ /** Check the root the volume mounts below, detach what earlier creators left, then attach and provision the volume. */
1314
+ async provisionVolume(op) {
1315
+ try {
1316
+ const [root, parent] = await Promise.all([stat(this.paths.mountpoint), stat(join(this.paths.mountpoint, '..'))]);
1317
+ if (root.dev === parent.dev && (await readdir(this.paths.mountpoint)).length !== 0) {
1318
+ return {
1319
+ ok: false,
1320
+ error: {
1321
+ kind: 'ram-unavailable',
1322
+ reason: 'unproven-owner',
1323
+ detail: `${this.paths.mountpoint} is an unmounted directory with unowned contents; nothing removed or hidden by a new mount`,
1324
+ },
1325
+ };
1326
+ }
1327
+ }
1328
+ catch (error) {
1329
+ if (errorCode(error) !== 'ENOENT')
1330
+ return failed('provenance', errorText(error));
853
1331
  }
854
- const attached = await this.commands.run('/usr/bin/hdiutil', ['attach', '-nomount', `ram://${this.sectors}`]);
855
- if (attached.status !== 0) {
856
- // A deadlined attach took its helper's process group down with it; one that attached
857
- // regardless is a stray the next creator detaches.
858
- return failed('hdiutil attach', commandText(attached));
1332
+ const root = await rootReadiness(this.paths);
1333
+ if (!root.ok) {
1334
+ return root;
859
1335
  }
860
- const physical = /^(\/dev\/disk\d+)\b/.exec(attached.stdout)?.[1];
861
- if (!physical) {
862
- return failed('hdiutil attach', `no device in: ${attached.stdout.trim()}`);
1336
+ const strays = await this.reclaimStrays(op, this.holdersPass());
1337
+ if (!strays.ok) {
1338
+ return strays;
863
1339
  }
864
- const provisioned = await this.provision(physical);
865
- if (provisioned.ok) {
1340
+ const attached = await this.commands.attachRam(this.sectors);
1341
+ if (!attached.ok) {
1342
+ // An attach whose answer never came may still finish; this caller closed its lease, so the gateway detaches it.
1343
+ return typeof attached.error === 'string'
1344
+ ? failed('ram-lease', attached.error)
1345
+ : { ok: false, error: attached.error };
1346
+ }
1347
+ // Every path from here ends the lease: kept once the volume is mounted and marked at its mountpoint, released on
1348
+ // any failure or throw before that.
1349
+ const lease = attached.value;
1350
+ const kept = await this.provisionAndKeep(op, lease).catch((error) => failed('provision', errorText(error)));
1351
+ return kept.ok ? kept : this.rollBack(op, lease, kept.error);
1352
+ }
1353
+ /**
1354
+ * Provision the leased disk, record it in the ledger as the kept volume's disk, and keep it once its volume is mounted
1355
+ * and marked at its mountpoint. A record whose keep then fails names a disk the rollback detaches.
1356
+ */
1357
+ async provisionAndKeep(op, lease) {
1358
+ const identity = await this.attachedIdentity(lease.device);
1359
+ if (!identity.ok)
1360
+ return identity;
1361
+ const entry = identity.value.entry;
1362
+ const provisioned = await this.provision(lease.device, entry);
1363
+ if (!provisioned.ok)
866
1364
  return provisioned;
1365
+ const recorded = await this.locked(op, 'ram-lease keep', async (ledger) => ({
1366
+ ledger: { ...ledger, kept: entry },
1367
+ value: undefined,
1368
+ }));
1369
+ if (!recorded.ok) {
1370
+ return failed('ram-lease keep', recorded.error.kind === 'lock-denied' ? recorded.error.detail : describeRamTempError(recorded.error));
867
1371
  }
868
- const detached = await this.commands.run('/usr/bin/hdiutil', ['detach', '-force', physical]);
869
- // The detach takes every volume of the disk with it. What it leaves at the staging path is a bare
870
- // directory on the host's Data volume: removed here, and already absent is done.
1372
+ const kept = await lease.keep();
1373
+ return kept.ok ? kept : failed('ram-lease keep', kept.error);
1374
+ }
1375
+ /**
1376
+ * End the lease of a volume that failed. The gateway detaches the disk on release, by its registry entry and without
1377
+ * force, so a busy owned staging volume is retained. A lease lost to a gateway restart answers no release: this caller
1378
+ * then detaches the exact disk itself, under its ledger's custody, so no later lease is admitted on a disk the next
1379
+ * gateway's startup scan removes.
1380
+ */
1381
+ async rollBack(op, lease, failure) {
1382
+ const released = await lease.release();
1383
+ const lost = released.ok ? [] : [released.error];
1384
+ const command = released.ok ? released : await this.runDetach(op, lease.device, lease.registryEntry);
1385
+ if (!command.ok)
1386
+ return failed(failure.step, [failure.detail, ...lost, describeRamTempError(command.error)].join('; '));
1387
+ const detached = command.value;
1388
+ if (detached.pending !== undefined) {
1389
+ return failed(failure.step, [failure.detail, ...lost, commandText(detached)].join('; '));
1390
+ }
1391
+ // The detach takes every volume of the disk with it. What it leaves at the staging directory and the
1392
+ // mountpoint is a bare directory on the host's Data volume each: removed here, and already absent is done.
871
1393
  const detachFailure = detached.status === 0
872
- ? null
873
- : `hdiutil detach -force ${physical} then failed (${commandText(detached)}), so it stays attached until the next creator reclaims it`;
874
- const stagingFailure = await rmdir(this.paths.staging).then(() => null, (error) => errorCode(error) === 'ENOENT' ? null : `rmdir ${this.paths.staging} then failed (${errorText(error)})`);
875
- const failures = [detachFailure, stagingFailure].filter((failure) => failure !== null);
876
- return failures.length === 0
877
- ? provisioned
878
- : failed(provisioned.error.step, [provisioned.error.detail, ...failures].join('; '));
1394
+ ? []
1395
+ : [`gateway detach ${lease.device} then failed (${commandText(detached)}); owned staging is retained`];
1396
+ const directoryFailures = detached.status === 0 ? await removeMountDirectories([this.paths.staging, this.paths.mountpoint]) : [];
1397
+ return failed(failure.step, [failure.detail, ...lost, ...detachFailure, ...directoryFailures].join('; '));
879
1398
  }
880
1399
  /**
881
1400
  * Create the volume under its final name, mount it with `mount_apfs` at the private staging
882
- * directory, and mark it there. Then `umount` that private mount and let `diskutil mount` place
883
- * the volume at the mountpoint: the only call that does, and it runs after the marker, so the
884
- * volume never reaches `/Volumes` unmarked. Nothing is renamed (see the module comment). The
885
- * staging mount is the kernel's, so the kernel releases it: a Disk Arbitration unmount waits in
886
- * its one queue behind its own probe of the fresh RAM disk (5.1 s for the `zfs` probe alone in
887
- * `log stream`; 6.5–6.7 s per unmount against 64–69 ms for `umount`, measured 2026-10-15). A
888
- * crash before the final mount leaves the volume attached at the staging directory or
889
- * unmounted; the next creator's reclaim detaches either.
1401
+ * directory, and mark it there. Then `umount` that private mount and mount the volume with
1402
+ * `mount_apfs` again at the mountpoint, after the marker, so the volume never reaches the
1403
+ * mountpoint unmarked. Nothing is renamed (see the module comment). The staging mount is the
1404
+ * kernel's, so the kernel releases it: a Disk Arbitration unmount waits in its one queue behind
1405
+ * its own probe of the fresh RAM disk (5.1 s for the `zfs` probe alone in `log stream`;
1406
+ * 6.5–6.7 s per unmount against 64–69 ms for `umount`, measured 2026-10-15). A crash before
1407
+ * the final mount leaves the volume attached at the staging directory or unmounted; the next
1408
+ * creator's reclaim detaches either.
890
1409
  */
891
- async provision(physical) {
1410
+ async provision(physical, registryEntry) {
892
1411
  const container = await this.commands.run('/usr/sbin/diskutil', ['apfs', 'createContainer', physical]);
893
1412
  const containerDisk = operationDisk(container.stdout);
894
1413
  if (container.status !== 0 || !containerDisk) {
@@ -923,7 +1442,13 @@ export class RamTempVolume {
923
1442
  return atStaging;
924
1443
  }
925
1444
  try {
926
- await writeFile(join(staging, MARKER_FILE), `${this.paths.volumeName}\n`);
1445
+ const marker = {
1446
+ version: 1,
1447
+ volumeName: this.paths.volumeName,
1448
+ owner: 'gateway',
1449
+ registryEntry,
1450
+ };
1451
+ await writeFile(join(staging, MARKER_FILE), `${JSON.stringify(marker)}\n`);
927
1452
  }
928
1453
  catch (error) {
929
1454
  return failed('marker', errorText(error));
@@ -932,13 +1457,24 @@ export class RamTempVolume {
932
1457
  if (unmounted.status !== 0) {
933
1458
  return failed('umount (staging)', commandText(unmounted));
934
1459
  }
935
- // No -mountPoint: DiskArbitration names the mountpoint after the volume, and appends " 1" when a
936
- // /Volumes entry already holds the name.
937
- const placing = await this.commands.run('/usr/sbin/diskutil', ['mount', '-mountOptions', 'nobrowse', volume]);
1460
+ // `mount_apfs` mounts at a directory of this module's choosing without authorization; `diskutil mount
1461
+ // -mountPoint` raised an administrator dialog (see the module comment).
1462
+ try {
1463
+ await mkdir(this.paths.mountpoint, { recursive: true, mode: 0o700 });
1464
+ }
1465
+ catch (error) {
1466
+ return failed('mountpoint directory', errorText(error));
1467
+ }
1468
+ const placing = await this.commands.run('/sbin/mount_apfs', [
1469
+ '-o',
1470
+ 'nobrowse,noowners',
1471
+ `/dev/${volume}`,
1472
+ this.paths.mountpoint,
1473
+ ]);
938
1474
  if (placing.status !== 0) {
939
- return failed('diskutil mount', commandText(placing));
1475
+ return failed('mount_apfs (mountpoint)', commandText(placing));
940
1476
  }
941
- const placed = await this.expectMounted(volume, this.paths.mountpoint, 'diskutil mount');
1477
+ const placed = await this.expectMounted(volume, this.paths.mountpoint, 'mount_apfs (mountpoint)');
942
1478
  if (!placed.ok) {
943
1479
  return placed;
944
1480
  }
@@ -960,29 +1496,70 @@ export class RamTempVolume {
960
1496
  ? { ok: true, value: undefined }
961
1497
  : failed(step, `${volume} mounted at ${point ?? 'nowhere'}, expected ${expected}`);
962
1498
  }
963
- /** This module's RAM disks attached on the host: this user's, of this volume's exact size, mounted nowhere else. */
1499
+ /**
1500
+ * This volume's RAM disks attached on the host, read from the I/O Registry, which omits no attached disk: the ones
1501
+ * `volumeDisks` names. A RAM disk of this user and size that is not this volume's, another volume's, a test's, or an
1502
+ * unformatted one nothing recorded, is not its to inventory or detach, and is ignored. One of its own still
1503
+ * publishing its media is named, never passed over.
1504
+ */
964
1505
  async attached() {
965
- const info = await this.commands.run('/usr/bin/hdiutil', ['info']);
966
- if (info.status !== 0) {
967
- return failed('hdiutil info', commandText(info));
968
- }
969
- const ours = (point) => {
970
- // DiskArbitration's " 1" suffix: a volume that found its name taken.
971
- const name = point.replace(/ \d+$/, '');
972
- // hdiutil lists a mount by the kernel's path; `staging` is written as that path, so it compares exactly.
973
- return name === this.paths.mountpoint || name === this.paths.staging;
974
- };
1506
+ const registry = await this.commands.run('/usr/sbin/ioreg', ['-r', '-c', 'IOHDIXHDDriveOutKernel', '-l', '-w0']);
1507
+ if (registry.status !== 0) {
1508
+ return failed('ioreg (RAM disks)', commandText(registry));
1509
+ }
1510
+ const table = await this.commands.run('/sbin/mount', []);
1511
+ if (table.status !== 0) {
1512
+ return failed('mount (mount table)', commandText(table));
1513
+ }
1514
+ const disks = ramDisksIn(registry.stdout, table.stdout);
1515
+ if (!disks.ok) {
1516
+ return failed('ioreg (RAM disks)', disks.error);
1517
+ }
1518
+ const custody = await this.custody();
1519
+ if (!custody.ok) {
1520
+ return custody;
1521
+ }
1522
+ const attached = [];
1523
+ for (const disk of volumeDisks(disks.value, this.paths, this.sectors, (candidate) => custody.value.has(candidate.entry) ||
1524
+ (candidate.physical !== null &&
1525
+ this.commands.ownsRamDisk?.({ ...candidate, physical: candidate.physical }) === true))) {
1526
+ const { physical } = disk;
1527
+ if (physical === null) {
1528
+ return failed('ioreg (RAM disks)', `a RAM disk of uid ${disk.uid} with ${disk.sectors} sectors has published no media yet; look again once its attach settles`);
1529
+ }
1530
+ attached.push({ ...disk, physical });
1531
+ }
1532
+ return { ok: true, value: attached };
1533
+ }
1534
+ /**
1535
+ * The registry entries the ledger records: the one it keeps pending detach custody of, exact and published before the
1536
+ * spawn, and the disk whose volume a creator last kept.
1537
+ */
1538
+ async custody() {
1539
+ const read = await this.readLedger();
1540
+ if (!read.ok) {
1541
+ return read;
1542
+ }
1543
+ const { lifecycle, kept } = read.value.ledger;
1544
+ const entry = lifecycle?.pending?.registryEntry;
975
1545
  return {
976
1546
  ok: true,
977
- value: ramDisksIn(info.stdout).filter((disk) => disk.user === this.paths.user && disk.sectors === this.sectors && disk.mountpoints.every(ours)),
1547
+ value: new Set([...(entry === undefined || entry === null ? [] : [entry]), ...(kept === null ? [] : [kept])]),
978
1548
  };
979
1549
  }
980
1550
  /**
981
- * Detach what earlier creators left attached: no marked volume is mounted, so every RAM disk of
982
- * this volume is debris — unformatted, staged, or mounted without its marker. One carrying a
983
- * lease, or with anything attached below it, is still in use and stops the creation instead.
1551
+ * Detach what earlier creators left attached: no marked volume is mounted, so every RAM disk of this volume
1552
+ * (`attached`: by its exact name or its exact record) is debris — unformatted and recorded, staged, mounted
1553
+ * without its marker, or the kept volume's disk an operator's unmount left mounted nowhere. One carrying a lease, or
1554
+ * with anything attached below it, is still in use and stops the creation instead, and so does one its owner holds no
1555
+ * receipt for and its ledger does not record as kept: it is named, never detached.
984
1556
  */
985
- async reclaimStrays(holders) {
1557
+ async reclaimStrays(op, holders) {
1558
+ const read = await this.readLedger();
1559
+ if (!read.ok) {
1560
+ return read;
1561
+ }
1562
+ const { kept } = read.value.ledger;
986
1563
  const strays = await this.attached();
987
1564
  if (!strays.ok) {
988
1565
  return strays;
@@ -1004,9 +1581,22 @@ export class RamTempVolume {
1004
1581
  return failed('reclaim', holdingText(point, held.value));
1005
1582
  }
1006
1583
  }
1007
- const detached = await this.commands.run('/usr/bin/hdiutil', ['detach', '-force', disk.physical], STRAY_DETACH_DEADLINE_MS);
1008
- if (detached.status !== 0) {
1009
- return failed(`hdiutil detach (stray ${disk.physical})`, commandText(detached));
1584
+ if (disk.entry !== kept && this.commands.ownsRamDisk?.(disk) !== true) {
1585
+ return {
1586
+ ok: false,
1587
+ error: {
1588
+ kind: 'ram-unavailable',
1589
+ reason: 'unproven-owner',
1590
+ detail: `${disk.physical} has no exact gateway creation receipt; no reclaim or detach admitted`,
1591
+ },
1592
+ };
1593
+ }
1594
+ const command = await this.runDetach(op, disk.physical, disk.entry);
1595
+ if (!command.ok)
1596
+ return command;
1597
+ const detached = detachOutcome(command.value, disk, `hdiutil detach (stray ${disk.physical})`);
1598
+ if (!detached.ok) {
1599
+ return detached;
1010
1600
  }
1011
1601
  }
1012
1602
  return { ok: true, value: undefined };
@@ -1031,7 +1621,7 @@ export class RamTempVolume {
1031
1621
  }
1032
1622
  const disk = disks.value.find((candidate) => candidate.mountpoints.includes(this.paths.mountpoint));
1033
1623
  if (!disk) {
1034
- return failed('detach', `hdiutil info lists no RAM disk of ${this.paths.user} with ${this.sectors} sectors mounted at ${this.paths.mountpoint}`);
1624
+ return failed('detach', `the I/O Registry lists no RAM disk of uid ${this.paths.uid} with ${this.sectors} sectors mounted at ${this.paths.mountpoint} as volume ${this.paths.volumeName}`);
1035
1625
  }
1036
1626
  const unchanged = await this.locked(op, 'detach', async (ledger, current) => ({
1037
1627
  ledger,
@@ -1046,15 +1636,18 @@ export class RamTempVolume {
1046
1636
  // A lease or another attach arrived despite the claim: the volume stays for it.
1047
1637
  return { ok: true, value: undefined };
1048
1638
  }
1049
- let detached = await this.commands.run('/usr/bin/hdiutil', ['detach', disk.physical]);
1050
- if (detached.status !== 0) {
1051
- detached = await this.commands.run('/usr/bin/hdiutil', ['detach', '-force', disk.physical]);
1052
- }
1053
- if (detached.status !== 0) {
1054
- return failed('hdiutil detach', commandText(detached));
1639
+ // Detaching frees the archives' pages anyway, but a deletion of this process's still walking the volume holds it busy.
1640
+ await archiveDeletions();
1641
+ const command = await this.runDetach(op, disk.physical, disk.entry);
1642
+ if (!command.ok)
1643
+ return command;
1644
+ const detached = detachOutcome(command.value, disk, 'hdiutil detach');
1645
+ if (!detached.ok) {
1646
+ return detached;
1055
1647
  }
1056
- // DiskArbitration removes the /Volumes directory it created when the volume goes.
1057
- return { ok: true, value: undefined };
1648
+ // No Disk Arbitration call made the mountpoint, so none removes it: this module does, now its volume is gone.
1649
+ const left = await removeMountDirectories([this.paths.mountpoint]);
1650
+ return left.length === 0 ? { ok: true, value: undefined } : failed('detach', left.join('; '));
1058
1651
  }
1059
1652
  /** The host's attachments as one pass reads them: one `ioreg` run and one `mount` run. */
1060
1653
  async readInventory() {
@@ -1102,6 +1695,70 @@ function candidatesBelow(inventory, prefix) {
1102
1695
  .map((point) => ({ kind: 'mount', mountpoint: point, description: `${point} (mounted)` })),
1103
1696
  ];
1104
1697
  }
1698
+ /**
1699
+ * Whether the root is a directory its volume may mount below: the per-user root `cowshed setup` makes, or a test
1700
+ * namespace's directory its fixture made, each a directory, not a link, the user's, mode 0700. A link could place the
1701
+ * mount outside `/var/folders/`, where mds admits it, and another owner or mode exposes the volume.
1702
+ */
1703
+ async function rootReadiness(paths) {
1704
+ const unready = (detail) => ({
1705
+ ok: false,
1706
+ error: { kind: 'root-unready', root: paths.root, detail },
1707
+ });
1708
+ let info;
1709
+ try {
1710
+ info = await lstat(paths.root);
1711
+ }
1712
+ catch (error) {
1713
+ return unready(errorCode(error) === 'ENOENT' ? 'is missing' : `cannot be read (${errorText(error)})`);
1714
+ }
1715
+ if (!info.isDirectory()) {
1716
+ return unready('is not a directory');
1717
+ }
1718
+ if (info.uid !== paths.uid) {
1719
+ return unready(`is owned by uid ${info.uid}, not ${paths.uid}`);
1720
+ }
1721
+ const mode = info.mode & 0o777;
1722
+ return mode === 0o700 ? { ok: true, value: undefined } : unready(`has mode ${mode.toString(8)}, not 700`);
1723
+ }
1724
+ /**
1725
+ * Remove directories a volume was mounted on, once it is gone. `rmdir` removes only an empty directory, follows no
1726
+ * link and refuses one with a mount on it; already absent is done. Answers each failure.
1727
+ */
1728
+ async function removeMountDirectories(directories) {
1729
+ const failures = [];
1730
+ for (const directory of directories) {
1731
+ try {
1732
+ await rmdir(directory);
1733
+ }
1734
+ catch (error) {
1735
+ if (errorCode(error) !== 'ENOENT') {
1736
+ failures.push(`rmdir ${directory} then failed (${errorText(error)})`);
1737
+ }
1738
+ }
1739
+ }
1740
+ return failures;
1741
+ }
1742
+ /**
1743
+ * The volume one read found at the lease's mountpoint, while the lease is still on that attach of it; else why it is
1744
+ * not. Every lease's `TMPDIR` is a directory on one attach: once that attach is gone, the path is a bare directory on
1745
+ * the host's Data volume, or on a later attach, which a write through `TMPDIR` can make again.
1746
+ */
1747
+ function leaseOn(lease, volume) {
1748
+ if (volume === null) {
1749
+ return {
1750
+ lost: `no marked volume is mounted at ${lease.mountpoint} any more: it was detached while the task held its lease`,
1751
+ };
1752
+ }
1753
+ if (volume.attach !== lease.attach) {
1754
+ return {
1755
+ lost: `${lease.mountpoint} holds another attach of the volume than the one the lease was taken on: it was detached and made again while the task held its lease`,
1756
+ };
1757
+ }
1758
+ return volume.leases.includes(basename(lease.directory))
1759
+ ? { on: volume }
1760
+ : { lost: `${lease.directory} is gone from the volume while the task held it` };
1761
+ }
1105
1762
  /** The pid a lease directory is named after: whether its task is alive. */
1106
1763
  function leasePid(name) {
1107
1764
  return Number(LEASE_NAME.exec(name)?.[1]);
@@ -1124,23 +1781,33 @@ function heldContext(volume, name, identity) {
1124
1781
  return { volumeKey: volume.key, leaseKey: `${name} ${identity}`, ramDevice: String(volume.device) };
1125
1782
  }
1126
1783
  /**
1127
- * The ledger with the claims of dead owners voided, and the verdicts kept only for leases still on
1128
- * this attach of the volume. A claim's owner is judged as a lease's is, by its pid.
1784
+ * Dead callers void only claims without pending detach custody. A pending command's authority
1785
+ * survives every pid observation; verdicts still belong only to this attach of the volume.
1129
1786
  */
1130
1787
  function prune(ledger, volume, isAlive) {
1131
1788
  return {
1132
- lifecycle: ledger.lifecycle !== null && isAlive(ledger.lifecycle.owner.pid) ? ledger.lifecycle : null,
1789
+ lifecycle: ledger.lifecycle !== null && (ledger.lifecycle.pending !== undefined || isAlive(ledger.lifecycle.owner.pid))
1790
+ ? ledger.lifecycle
1791
+ : null,
1133
1792
  claims: ledger.claims.filter((claim) => isAlive(claim.owner.pid)),
1134
1793
  held: volume === null
1135
1794
  ? []
1136
1795
  : ledger.held.filter((entry) => entry.verdict.context.volumeKey === volume.key && volume.leases.includes(entry.lease)),
1796
+ kept: ledger.kept,
1137
1797
  };
1138
1798
  }
1799
+ /** The operation token and registry incarnation, never a pid or reusable BSD name alone, identify a pending detach. */
1800
+ function sameDetach(claim, owner, custody) {
1801
+ return (claim?.owner.token === owner.token &&
1802
+ claim.pending?.physical === custody.physical &&
1803
+ claim.pending.registryEntry === custody.registryEntry);
1804
+ }
1139
1805
  function withoutClaimsOf(ledger, owner) {
1140
1806
  return {
1141
- lifecycle: ledger.lifecycle?.owner.token === owner.token ? null : ledger.lifecycle,
1807
+ lifecycle: ledger.lifecycle?.owner.token === owner.token && ledger.lifecycle.pending === undefined ? null : ledger.lifecycle,
1142
1808
  claims: ledger.claims.filter((claim) => claim.owner.token !== owner.token),
1143
1809
  held: ledger.held,
1810
+ kept: ledger.kept,
1144
1811
  };
1145
1812
  }
1146
1813
  /** The ledger once a caller has settled its claims: they are dropped, and its verdicts replace older ones. */
@@ -1154,7 +1821,8 @@ function settledLedger(ledger, volume, owner, verdicts) {
1154
1821
  }
1155
1822
  /** The ledger's wire form, version 1. */
1156
1823
  function ledgerText(ledger) {
1157
- return `${JSON.stringify({ version: 1, lifecycle: ledger.lifecycle, claims: ledger.claims, held: ledger.held })}\n`;
1824
+ // Older readers reject version 2 instead of pruning the pending authority by the caller's pid.
1825
+ return `${JSON.stringify({ version: ledger.lifecycle?.pending === undefined ? 1 : 2, lifecycle: ledger.lifecycle, claims: ledger.claims, held: ledger.held, ...(ledger.kept === null ? {} : { kept: ledger.kept }) })}\n`;
1158
1826
  }
1159
1827
  /** Publish the ledger in one rename, so no reader, and no crash, ever leaves half of it. */
1160
1828
  async function publishLedger(path, text) {
@@ -1175,7 +1843,7 @@ async function publishLedger(path, text) {
1175
1843
  * so its lease is probed afresh; it never stands for a lease nothing holds.
1176
1844
  */
1177
1845
  function parseLedger(value) {
1178
- if (!isRecord(value) || value.version !== 1) {
1846
+ if (!isRecord(value) || (value.version !== 1 && value.version !== 2)) {
1179
1847
  return undefined;
1180
1848
  }
1181
1849
  const { lifecycle: lifecycleWire, claims: claimsWire, held: heldWire } = value;
@@ -1192,8 +1860,16 @@ function parseLedger(value) {
1192
1860
  if ((kind !== 'create' && kind !== 'detach') || owner === undefined) {
1193
1861
  return undefined;
1194
1862
  }
1195
- lifecycle = { kind, owner };
1863
+ const pending = lifecycleWire.pending === undefined ? undefined : parseDetachCustody(lifecycleWire.pending);
1864
+ if (lifecycleWire.pending !== undefined && pending === undefined)
1865
+ return undefined;
1866
+ lifecycle = pending === undefined ? { kind, owner } : { kind, owner, pending };
1196
1867
  }
1868
+ if ((value.version === 2) !== (lifecycle?.pending !== undefined))
1869
+ return undefined;
1870
+ const keptWire = value.kept;
1871
+ if (keptWire !== undefined && (typeof keptWire !== 'string' || !/^0x[0-9a-f]+$/.test(keptWire)))
1872
+ return undefined;
1197
1873
  const claims = [];
1198
1874
  for (const entry of claimsWire) {
1199
1875
  if (!isRecord(entry)) {
@@ -1217,7 +1893,19 @@ function parseLedger(value) {
1217
1893
  held.push({ lease, verdict });
1218
1894
  }
1219
1895
  }
1220
- return { lifecycle, claims, held };
1896
+ return { lifecycle, claims, held, kept: keptWire ?? null };
1897
+ }
1898
+ function parseDetachCustody(value) {
1899
+ if (!isRecord(value))
1900
+ return undefined;
1901
+ const { physical, registryEntry, phase, facadePid } = value;
1902
+ if ((phase !== 'waiting' && phase !== 'reported') ||
1903
+ typeof physical !== 'string' ||
1904
+ !/^\/dev\/disk\d+$/.test(physical) ||
1905
+ (registryEntry !== null && (typeof registryEntry !== 'string' || !/^0x[0-9a-f]+$/.test(registryEntry))) ||
1906
+ (facadePid !== null && (typeof facadePid !== 'number' || !Number.isSafeInteger(facadePid) || facadePid <= 0)))
1907
+ return undefined;
1908
+ return { physical, registryEntry, phase, facadePid };
1221
1909
  }
1222
1910
  function parseOwner(value) {
1223
1911
  if (!isRecord(value)) {
@@ -1240,8 +1928,12 @@ function alsoFailed(primary, cleanup) {
1240
1928
  const after = `cleanup then failed: ${cleanup.map(describeRamTempError).join('; ')}`;
1241
1929
  switch (primary.kind) {
1242
1930
  case 'provision-failed':
1931
+ case 'ram-unavailable':
1932
+ case 'root-unready':
1243
1933
  return { ...primary, detail: `${primary.detail}; ${after}` };
1244
1934
  case 'volume-full':
1935
+ case 'lease-lost':
1936
+ case 'lease-path-budget':
1245
1937
  return { kind: 'provision-failed', step: 'cleanup', detail: `${describeRamTempError(primary)}; ${after}` };
1246
1938
  }
1247
1939
  }
@@ -1334,27 +2026,114 @@ export function operationDisk(stdout) {
1334
2026
  return /^Disk from APFS operation: (disk\d+(?:s\d+)?)$/m.exec(stdout)?.[1] ?? null;
1335
2027
  }
1336
2028
  /**
1337
- * The RAM disks in `hdiutil info` output. Images are separated by a row of `=`; a RAM disk's
1338
- * `image-path` is `ram://<sectors>`, and its entity rows are `<dev>\t<content hint>\t<mountpoint>`,
1339
- * the whole disk first.
2029
+ * The RAM disks in `ioreg -r -c IOHDIXHDDriveOutKernel -l -w0` output, with the mounts `mount` output gives them. A RAM
2030
+ * disk is a legacy DiskImages device served by a diskimages-helper: each starts a `+-o IOHDIXHDDriveOutKernel` entry
2031
+ * whose own properties carry `image-path` <"ram://<sectors>"> and `owner-uid`, and the `BSD Name`s below it are its
2032
+ * whole disk first, then its APFS container and volumes; each volume node carries its `FullName` beside its `BSD Name`,
2033
+ * which is how a volume's name reaches its mounts. The registry is the kernel's record, and unlike `hdiutil info`,
2034
+ * which drops images while another attaches or detaches, it leaves out no attached disk. So an entry this cannot read
2035
+ * is an error, never a disk left out: a partial read must not stand for an absent disk.
1340
2036
  */
1341
- export function ramDisksIn(info) {
2037
+ export function ramDisksIn(registry, table) {
2038
+ const mounted = new Map();
2039
+ for (const [, device, point] of table.matchAll(/^\/dev\/(disk\d+(?:s\d+)*) on (.+) \([^)]*\)$/gm)) {
2040
+ if (device !== undefined && point !== undefined) {
2041
+ mounted.set(device, [...(mounted.get(device) ?? []), point]);
2042
+ }
2043
+ }
1342
2044
  const disks = [];
1343
- for (const block of info.split(/^=+$/m)) {
1344
- const sectors = /^image-path\s*:\s*ram:\/\/(\d+)\s*$/m.exec(block)?.[1];
1345
- const user = /^mounting user\s*:\s*(\S+)\s*$/m.exec(block)?.[1];
1346
- const entities = [...block.matchAll(/^(\/dev\/disk\d+(?:s\d+)*)\t[^\t\n]*(?:\t([^\n]*))?$/gm)];
1347
- const physical = entities[0]?.[1];
1348
- if (sectors === undefined || user === undefined || physical === undefined) {
2045
+ for (const entry of registry.split(/^(?=\+-o )/m)) {
2046
+ if (entry.trim() === '') {
2047
+ continue;
2048
+ }
2049
+ const header = entry.slice(0, entry.indexOf('\n') === -1 ? undefined : entry.indexOf('\n'));
2050
+ const entryId = /<class IOHDIXHDDriveOutKernel, id (0x[0-9a-f]+),/.exec(header)?.[1];
2051
+ if (!header.startsWith('+-o ') || entryId === undefined) {
2052
+ return { ok: false, error: `not an IOHDIXHDDriveOutKernel entry: ${header.slice(0, 160)}` };
2053
+ }
2054
+ // The entry's own properties end at its first child; only they name its image and owner.
2055
+ const firstChild = entry.indexOf('+-o ', header.length);
2056
+ const own = entry.slice(header.length, firstChild === -1 ? undefined : firstChild);
2057
+ const imagePath = /"image-path" = <"([^"]*)">/.exec(own)?.[1];
2058
+ const owner = /"owner-uid" = (\d+)/.exec(own)?.[1];
2059
+ // Every node's property list closes before the next node: a read cut short leaves one open.
2060
+ const opened = entry.match(/^[| ]*\{\s*$/gm)?.length ?? 0;
2061
+ const closed = entry.match(/^[| ]*\}\s*$/gm)?.length ?? 0;
2062
+ if (opened === 0 || opened !== closed || imagePath === undefined || owner === undefined) {
2063
+ return {
2064
+ ok: false,
2065
+ error: `an incomplete entry (${opened} property lists opened, ${closed} closed${imagePath === undefined ? ', no image-path' : ''}${owner === undefined ? ', no owner-uid' : ''}): ${header.slice(0, 160)}`,
2066
+ };
2067
+ }
2068
+ const sectors = /^ram:\/\/(\d+)$/.exec(imagePath)?.[1];
2069
+ if (sectors === undefined) {
2070
+ // A file-backed legacy image, not a RAM disk.
1349
2071
  continue;
1350
2072
  }
1351
- const mountpoints = entities.flatMap((entity) => {
1352
- const point = entity[2]?.trimEnd();
1353
- return point ? [point] : [];
2073
+ const names = [...entry.matchAll(/"BSD Name" = "(disk\d+(?:s\d+)*)"/g)].flatMap((match) => match[1] === undefined ? [] : [match[1]]);
2074
+ const volumes = [];
2075
+ for (const node of entry.split(/^(?=[| ]*\+-o )/m)) {
2076
+ if (!/^[| ]*\+-o [^\n]*<class AppleAPFSVolume,/.test(node)) {
2077
+ continue;
2078
+ }
2079
+ const name = /^[| ]*"FullName" = "(.*)"[ \t]*$/m.exec(node)?.[1];
2080
+ const device = /"BSD Name" = "(disk\d+(?:s\d+)*)"/.exec(node)?.[1];
2081
+ if (name !== undefined) {
2082
+ volumes.push({ name, mountpoints: device === undefined ? [] : (mounted.get(device) ?? []) });
2083
+ }
2084
+ }
2085
+ disks.push({
2086
+ entry: entryId,
2087
+ physical: names[0] === undefined ? null : `/dev/${names[0]}`,
2088
+ sectors: Number(sectors),
2089
+ uid: Number(owner),
2090
+ mountpoints: names.flatMap((name) => mounted.get(name) ?? []),
2091
+ volumes,
1354
2092
  });
1355
- disks.push({ physical, sectors: Number(sectors), user, mountpoints });
1356
2093
  }
1357
- return disks;
2094
+ return { ok: true, value: disks };
2095
+ }
2096
+ /**
2097
+ * The RAM disks of `disks` that are this volume's, and no others. A disk is the volume's only when it has its user and
2098
+ * its exact size, mounts nowhere but at its mountpoint or staging directory, and either carries a volume called exactly
2099
+ * its name that is mounted, or is recorded: `recorded` says the disk's exact registry entry is one this volume's owner
2100
+ * holds a receipt or its ledger holds custody for, which covers an attach whose format never finished, or records as
2101
+ * the disk a creator kept, which covers a volume unmounted from under it. A disk's size and owner establish nothing, so
2102
+ * an unmounted disk of the same size that nothing recorded is not the volume's.
2103
+ */
2104
+ export function volumeDisks(disks, paths, sectors, recorded) {
2105
+ // The mount table lists a mount by the kernel's path; both paths are written as that path, so they compare exactly.
2106
+ const ours = (point) => point === paths.mountpoint || point === paths.staging;
2107
+ return disks.filter((disk) => disk.uid === paths.uid &&
2108
+ disk.sectors === sectors &&
2109
+ disk.mountpoints.every(ours) &&
2110
+ (disk.volumes.some((volume) => volume.name === paths.volumeName && volume.mountpoints.length > 0) ||
2111
+ recorded(disk)));
2112
+ }
2113
+ /**
2114
+ * Detach a RAM disk an inventory found, by its whole-disk name, bound to the registry entry the inventory read it as.
2115
+ * A BSD name passes to the next disk once its disk goes, and a detach can queue for the disk admission meanwhile, so
2116
+ * the gateway reads the entry again inside its own admission, immediately before it spawns `hdiutil`, and
2117
+ * refuses, detaching nothing, unless the entry still names this whole disk (specs/cowshed/06_cli.md, `--registry-entry`).
2118
+ * That refusal is this detach's failure, named, and never retried with `-force`: this process did not just attach the
2119
+ * disk. The window that remains is cowshed's, from its read to hdiutil's own open of the name.
2120
+ */
2121
+ export async function detachRamDisk(commands, disk, step) {
2122
+ const detached = await commands.detachRam(disk.physical, disk.entry);
2123
+ return detachOutcome(detached, disk, step);
2124
+ }
2125
+ function detachOutcome(detached, disk, step) {
2126
+ if (detached.status === 0) {
2127
+ return { ok: true, value: undefined };
2128
+ }
2129
+ // A cowshed wrapper exit (100–106) whose stderr says it refused: the entry no longer names the disk.
2130
+ const refused = detached.status >= 100 &&
2131
+ detached.status <= 106 &&
2132
+ detached.stderr.includes('refused') &&
2133
+ detached.stderr.includes('nothing was detached');
2134
+ return failed(step, refused
2135
+ ? `${disk.physical} not detached: its registry entry ${disk.entry} no longer names it (${commandText(detached)})`
2136
+ : commandText(detached));
1358
2137
  }
1359
2138
  /**
1360
2139
  * A disk child that DiskArbitration never answers would wedge the task, and every task queued
@@ -1362,35 +2141,23 @@ export function ramDisksIn(info) {
1362
2141
  * DiskArbitration was saturated. Cowshed bounds its disk children the same way.
1363
2142
  */
1364
2143
  const HOST_COMMAND_DEADLINE_MS = 120_000;
1365
- /**
1366
- * How long one creator waits on a stray's detach before it reports the stray by name and
1367
- * gives the create claim back. A stray detach that makes no progress is DiskArbitration's
1368
- * wedge, not this volume's: at 120 s a chain of creators each waited the full bound on the
1369
- * same stray and the claim never moved. The detach itself is never killed (below); the
1370
- * bound is on the wait, and the next creator finds the stray gone or names it again.
1371
- */
1372
- const STRAY_DETACH_DEADLINE_MS = 30_000;
1373
2144
  /** Disk tools delegate their lease and process lifetime to cowshed, with one image policy. */
1374
- export function diskCommand(file, args, deadlineMs) {
2145
+ export function diskCommand(file, args, deadlineMs, binding, gatewaySocket) {
1375
2146
  const program = basename(file);
1376
2147
  if (program !== 'hdiutil' && program !== 'diskutil') {
1377
2148
  return null;
1378
2149
  }
1379
2150
  // Match SystemCommandRunner's protected-image policy, including its case-sensitive verbs.
1380
2151
  const image = program === 'hdiutil' || args[0] === 'image' || args[0] === 'eject';
2152
+ const bound = binding === undefined ? [] : ['--registry-entry', binding.registryEntry];
2153
+ const gateway = gatewaySocket === undefined ? [] : ['--gateway-socket', gatewaySocket];
1381
2154
  return {
1382
2155
  args: image
1383
- ? ['disk-command', program, '--', ...args]
1384
- : ['disk-command', program, '--deadline-ms', String(deadlineMs), '--', ...args],
2156
+ ? ['disk-command', program, ...gateway, ...bound, '--', ...args]
2157
+ : ['disk-command', program, ...gateway, '--deadline-ms', String(deadlineMs), '--', ...args],
1385
2158
  lifetime: image ? 'stop-wait' : 'facade-owned',
1386
2159
  };
1387
2160
  }
1388
- /**
1389
- * The variable naming the cowshed executable that runs `cowshed disk-command`. Unset, it is the installed `cowshed`
1390
- * on PATH. A repository that tests its own cowshed sets it, on the targets that test it, to that checkout's build:
1391
- * an installed cowshed that predates a command its own checkout added would fail the very code under test.
1392
- */
1393
- export const COWSHED_EXECUTABLE_ENV = 'COWSHED_EXECUTABLE';
1394
2161
  /** Whether this process already said the cowshed gateway is not there to lease disk commands. */
1395
2162
  let gatewayAbsenceSaid = false;
1396
2163
  /**
@@ -1408,12 +2175,17 @@ const predatesSeen = new Map();
1408
2175
  * device until reboot. Never acquire a second lease around the facade. Other leased helpers
1409
2176
  * take their lease here. Recorded lease waits ask for `alone`; an older gateway is asked
1410
2177
  * shared at once, and for a minute after.
2178
+ *
2179
+ * `gatewaySocket` is the gateway every disk lease, facade admission and RAM attach and detach goes through. It has no
2180
+ * default: the caller names it. The Nx executor names the host's own, `GATEWAY_SOCKET`, which `disk-command` defaults
2181
+ * to, so the facade is not told of it and a cowshed that predates `--gateway-socket` still serves it. A host proof
2182
+ * names its fixture's, which the facade is told of.
1411
2183
  */
1412
- export function createHostCommands(defaultDeadlineMs = HOST_COMMAND_DEADLINE_MS, gatewaySocket = GATEWAY_SOCKET, wantedShare = recordedShare(), cowshed = process.env[COWSHED_EXECUTABLE_ENV] ?? 'cowshed') {
2184
+ export function createHostCommands(gatewaySocket, defaultDeadlineMs = HOST_COMMAND_DEADLINE_MS, wantedShare = recordedShare(), cowshed = process.env[COWSHED_EXECUTABLE_ENV] ?? 'cowshed') {
1413
2185
  return {
1414
- async run(file, args, callDeadlineMs) {
2186
+ async run(file, args, callDeadlineMs, binding) {
1415
2187
  const deadlineMs = callDeadlineMs ?? defaultDeadlineMs;
1416
- const disk = diskCommand(file, args, deadlineMs);
2188
+ const disk = diskCommand(file, args, deadlineMs, binding, gatewaySocket === GATEWAY_SOCKET ? undefined : gatewaySocket);
1417
2189
  if (disk !== null) {
1418
2190
  return runBounded(cowshed, disk.args, deadlineMs, disk.lifetime);
1419
2191
  }
@@ -1449,6 +2221,12 @@ export function createHostCommands(defaultDeadlineMs = HOST_COMMAND_DEADLINE_MS,
1449
2221
  }
1450
2222
  }
1451
2223
  },
2224
+ detachRam(device, registryEntry) {
2225
+ return detachGatewayRamDisk(gatewaySocket, device, registryEntry);
2226
+ },
2227
+ attachRam(sectors) {
2228
+ return attachRamDisk(gatewaySocket, sectors, defaultDeadlineMs);
2229
+ },
1452
2230
  };
1453
2231
  }
1454
2232
  function runBounded(file, args, deadlineMs, lifetime = 'kill') {
@@ -1462,19 +2240,27 @@ function runBounded(file, args, deadlineMs, lifetime = 'kill') {
1462
2240
  // reap and lease custody; a wrapper's exit or signal is not the disk child's exit or signal.
1463
2241
  const child = spawn(file, [...args], { detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
1464
2242
  const stdout = [];
2243
+ let complete;
2244
+ const completion = lifetime === 'stop-wait'
2245
+ ? new Promise((settled) => {
2246
+ complete = settled;
2247
+ })
2248
+ : null;
1465
2249
  const stderr = [];
1466
2250
  child.stdout.on('data', (chunk) => stdout.push(chunk));
1467
2251
  child.stderr.on('data', (chunk) => stderr.push(chunk));
1468
2252
  const text = (chunks) => Buffer.concat(chunks).toString('utf8');
1469
- // Safe disk commands have no Node timer: the CLI owns the total admission + child budget,
1470
- // kills only its owned safe child, and returns after reap. Protected image output is already
1471
- // file-backed in cowshed, so only that caller may close its pipes and stop waiting.
2253
+ // Set once the deadline has fired and is killing the group: from then on it owns the result.
2254
+ let timedOut = false;
2255
+ let stoppedWaiting = false;
2256
+ // Safe disk commands have no Node timer: the CLI owns admission, execution and reap.
2257
+ // Protected commands keep draining their pipes after stop-wait: closing a live facade's
2258
+ // output is not proof its native child ended, and must not manufacture an early exit.
1472
2259
  const timer = lifetime === 'facade-owned'
1473
2260
  ? undefined
1474
2261
  : setTimeout(() => {
1475
- if (lifetime === 'stop-wait') {
1476
- child.stdout.destroy();
1477
- child.stderr.destroy();
2262
+ if (completion !== null) {
2263
+ stoppedWaiting = true;
1478
2264
  child.unref();
1479
2265
  // A piped child's streams are sockets; only a socket can be unref'd.
1480
2266
  if (child.stdout instanceof Socket)
@@ -1483,6 +2269,7 @@ function runBounded(file, args, deadlineMs, lifetime = 'kill') {
1483
2269
  child.stderr.unref();
1484
2270
  resolve({
1485
2271
  status: 1,
2272
+ pending: { pid: child.pid ?? null, completion },
1486
2273
  stdout: text(stdout),
1487
2274
  stderr: [
1488
2275
  text(stderr),
@@ -1493,35 +2280,54 @@ function runBounded(file, args, deadlineMs, lifetime = 'kill') {
1493
2280
  });
1494
2281
  return;
1495
2282
  }
1496
- resolve({
1497
- status: 1,
1498
- stdout: text(stdout),
1499
- stderr: `no answer within ${deadlineMs} ms; ${killGroup(child)}`,
2283
+ // A `close` that comes while the group is being killed must not end the call with an ordinary completion
2284
+ // before the kill is done: the deadline answers.
2285
+ timedOut = true;
2286
+ void killGroup(child).then((killed) => {
2287
+ resolve({ status: 1, stdout: text(stdout), stderr: `no answer within ${deadlineMs} ms; ${killed}` });
1500
2288
  });
1501
2289
  }, deadlineMs);
1502
2290
  child.on('error', (error) => {
1503
2291
  clearTimeout(timer);
1504
- resolve({ status: 1, stdout: text(stdout), stderr: error.message });
2292
+ if (timedOut)
2293
+ return;
2294
+ const output = { status: 1, stdout: text(stdout), stderr: error.message };
2295
+ complete?.(child.pid === undefined ? output : null);
2296
+ resolve(child.pid !== undefined && completion !== null ? { ...output, pending: { pid: child.pid, completion } } : output);
1505
2297
  });
1506
2298
  child.on('close', (code, signal) => {
1507
2299
  clearTimeout(timer);
2300
+ if (timedOut)
2301
+ return;
1508
2302
  const error = text(stderr);
1509
- resolve({
2303
+ const output = {
1510
2304
  status: code ?? 1,
1511
2305
  stdout: text(stdout),
1512
2306
  stderr: signal === null ? error : [error, `killed by ${signal}`].filter(Boolean).join('\n'),
1513
- });
2307
+ };
2308
+ // Wrapper errors can report wait/reap failure with a native child still alive (06_cli.md).
2309
+ const terminal = code !== null && (code < 100 || code > 106);
2310
+ complete?.(terminal ? output : null);
2311
+ if (!terminal && completion !== null && stoppedWaiting) {
2312
+ process.stderr.write(`RAM temp volume: cowshed command ${child.pid ?? 'unknown'} ended without a native terminal receipt: ${commandText(output)}\n`);
2313
+ }
2314
+ resolve(!terminal && completion !== null ? { ...output, pending: { pid: child.pid ?? null, completion } } : output);
1514
2315
  });
1515
2316
  return promise;
1516
2317
  }
1517
- /** SIGKILL the child's whole process group; what happened, for the error. */
1518
- function killGroup(child) {
2318
+ /**
2319
+ * SIGKILL the child's whole process group, again while it lists members; what happened, for the error. A group that
2320
+ * is still listed when the kill gives up is not called killed.
2321
+ */
2322
+ async function killGroup(child) {
1519
2323
  if (child.pid === undefined) {
1520
2324
  return 'never started';
1521
2325
  }
1522
2326
  try {
1523
- process.kill(-child.pid, 'SIGKILL');
1524
- return `killed process group ${child.pid}`;
2327
+ const left = await killProcessGroup(child.pid, DEADLINE_PATIENCE);
2328
+ return left
2329
+ ? `signalled its process group, but ${describeMembersLeft(child.pid)}`
2330
+ : `killed process group ${child.pid}`;
1525
2331
  }
1526
2332
  catch (error) {
1527
2333
  return `killing process group ${child.pid} failed: ${errorText(error)}`;
@@ -1537,6 +2343,14 @@ function processIsAlive(pid) {
1537
2343
  return errorCode(error) === 'EPERM';
1538
2344
  }
1539
2345
  }
2346
+ /**
2347
+ * A cowshed sandbox's refusal of one of the volume's own paths: the same answer as its refusal of the lock, so the task
2348
+ * keeps its workspace TMPDIR (`sandboxed`) whichever path the sandbox refuses first. A job's sandbox admits no part of
2349
+ * the RAM volume it cannot use, and this module reads that refusal rather than a second rule saying where it runs.
2350
+ */
2351
+ function denied(path, error) {
2352
+ return { ok: false, error: { kind: 'lock-denied', detail: `${path}: ${errorText(error)}` } };
2353
+ }
1540
2354
  function failed(step, detail) {
1541
2355
  return { ok: false, error: { kind: 'provision-failed', step, detail } };
1542
2356
  }