@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
@@ -1,6 +1,6 @@
1
1
  import { type ChildProcess, spawn } from 'node:child_process';
2
2
  import { randomUUID } from 'node:crypto';
3
- import { constants } from 'node:fs';
3
+ import { type BigIntStats, constants, type Stats } from 'node:fs';
4
4
  import {
5
5
  type FileHandle,
6
6
  lstat,
@@ -17,20 +17,23 @@ import {
17
17
  writeFile,
18
18
  } from 'node:fs/promises';
19
19
  import { Socket } from 'node:net';
20
- import { basename, join } from 'node:path';
20
+ import { basename, dirname, join } from 'node:path';
21
21
  import { setTimeout as sleep } from 'node:timers/promises';
22
- import {
23
- awaitExit,
24
- type ProcessEntry,
25
- pidsWithTempIn,
26
- pidsWorkingIn,
27
- processTable,
28
- terminate,
29
- withDescendants,
30
- } from '../../testing.js';
22
+ import { O_EXLOCK } from '@smoothbricks/cargo-retain/open-flags';
23
+ import { DEADLINE_PATIENCE, describeMembersLeft, killProcessGroup } from '../../process-group.js';
31
24
  import { isRecord } from '../../type-guards.js';
32
25
  import { diskClassOf, type PhaseShare, recordedShare, takeDiskLease } from './disk-lease.js';
33
26
  import { GATEWAY_SOCKET } from './gateway-lease.js';
27
+ import {
28
+ COWSHED_EXECUTABLE_ENV,
29
+ type CoverageGap,
30
+ parseHandle,
31
+ type SignalledProcess,
32
+ type SubtreeHandle,
33
+ type SubtreeOwner,
34
+ } from './owned-subtree.js';
35
+ import { attachRamDisk } from './ram-attach.js';
36
+ import { detachGatewayRamDisk } from './ram-detach.js';
34
37
  import {
35
38
  captureHeldVerdict,
36
39
  type HeldCandidate,
@@ -58,13 +61,26 @@ import type { TempVolumeSpace } from './verdict.js';
58
61
  * no `diskimagesiod`, so it spends none of the AppleDiskImages2 attach budget
59
62
  * that cowshed's images and tests draw on (specs/cowshed/01a_apfs.md, "How
60
63
  * the APFS host degrades"; measured 2026-10-05).
64
+ * - The disk lives as long as that helper, and a helper forked inside a job is
65
+ * the job's member, which the job's end retires under every other lease. So
66
+ * the helper belongs to the cowshed gateway, which no job contains and which
67
+ * attaches the disk under the creating task's lease (`ram-lease`,
68
+ * specs/cowshed/05_gateway.md, "RAM disks"); a task never does.
61
69
  * - Attach + format + mount costs ~2 s and is DiskArbitration traffic, so the
62
70
  * volume is created once, lazily, and every task takes a subdirectory.
63
- * - Only DiskArbitration's own mountpoint (`/Volumes/<volume name>`) is safe to
64
- * ask for: `diskutil mount -mountPoint <dir>` was refused as not privileged
65
- * (0xf8da0009), and storagekitd escalated it to an administrator dialog whose
66
- * wait blocked every diskutil on the host. A default mount raised no authd
67
- * request (log show, 2026-10-04).
71
+ * - Spotlight's mds keeps one IOKit right for every APFS volume it admits, for
72
+ * the life of the mds process, and admits no volume whose kernel-resolved
73
+ * mount path contains `/var/folders/` (specs/cowshed/01a_apfs.md, "Spotlight
74
+ * media references"). Measured 2026-10-22: a RAM volume mounted at /Volumes
75
+ * or /private/tmp left mds one right; the same mount under
76
+ * /private/var/folders left none. So the volume mounts below the per-user root
77
+ * `cowshed setup` makes, `/private/var/folders/cowshed/<uid>`, and a task
78
+ * refuses to create it while that root is missing or not the user's 0700
79
+ * directory.
80
+ * - The kernel mounts it there: `mount_apfs` needs no authorization, where
81
+ * `diskutil mount -mountPoint <dir>` was refused as not privileged
82
+ * (0xf8da0009) and storagekitd escalated it to an administrator dialog whose
83
+ * wait blocked every diskutil on the host (log show, 2026-10-04).
68
84
  * - Without authorization the volume mounts only `noowners`: launchd refuses a
69
85
  * plist from it ("Caller specified a plist with bad ownership/permissions"),
70
86
  * so a test that bootstraps a launchd job keeps the plist outside TMPDIR.
@@ -77,7 +93,7 @@ import type { TempVolumeSpace } from './verdict.js';
77
93
  * One caller creates or detaches the volume at a time, and a caller that finds
78
94
  * either in flight yields and looks again; each dead lease is settled by the
79
95
  * one caller that claimed it, and every other caller passes it by. A claim
80
- * names its owner's pid, so a claim whose owner died is void. Before it
96
+ * names its owner's pid; death voids it only with no pending detach. Before it
81
97
  * removes a lease or detaches the volume, a caller takes the lock again and
82
98
  * checks that the volume, the lease directory and its own claim are still as
83
99
  * it claimed them. A lease is a directory named after the task process's pid;
@@ -89,20 +105,29 @@ import type { TempVolumeSpace } from './verdict.js';
89
105
  * working in it, by working directory or by `TMPDIR`, has been stopped.
90
106
  *
91
107
  * The volume is created under its final name and never renamed. It is mounted by `mount_apfs` at a
92
- * private staging directory and marked there; the kernel then unmounts it (`umount`) and `diskutil mount`, the
93
- * only call that places it at its mountpoint, so it reaches `/Volumes` already marked. A Disk
94
- * Arbitration rename names whatever volume holds the path it recorded, and a force-unmounted volume
95
- * leaves a bare directory there on the host's Data volume, so no rename is made. `noowners` lets the
96
- * marker be written, since a fresh volume's root is owned by root (measured 2026-10-15). A creator that
97
- * dies part way leaves debris at the staging directory or as an unmounted volume, never an unmarked
98
- * volume at the mountpoint, which DiskArbitration would make every later volume dodge as "<name> 1".
99
- * The host's own image list is the only record of what was
100
- * attached: before creating, a task detaches every RAM disk of this user and
101
- * this volume's exact size that is mounted nowhere but this volume's names,
102
- * because a creator killed or deadlined mid-step leaves one behind — measured
103
- * 2026-10-06: a deadlined `hdiutil attach` whose diskimages-helper finished the
104
- * attach after `hdiutil` was killed, and a volume mounted with no marker. A
105
- * disk with a lease directory on it is never detached; its error names it.
108
+ * private staging directory and marked there, unmounted (`umount`), and mounted by `mount_apfs` again at its
109
+ * mountpoint, so it reaches the mountpoint already marked. A Disk Arbitration rename names whatever volume
110
+ * holds the path it recorded, and a force-unmounted volume leaves a bare directory there on the host's Data
111
+ * volume, so no rename is made. `noowners` lets the marker be written, since a fresh volume's root is owned
112
+ * by root (measured 2026-10-15). A creator that dies part way leaves debris at the staging directory or as an
113
+ * unmounted volume, never an unmarked volume at the mountpoint. No Disk Arbitration call made either
114
+ * directory, so none removes it: this module removes both once the volume is gone.
115
+ * The I/O Registry is the only record of what was attached, and it names every disk's volume. A task inventories the
116
+ * RAM disks that are this volume's and no other (`volumeDisks`): of this user and this volume's exact size, mounting
117
+ * nowhere but at its mountpoint or staging directory, and either carrying a volume called exactly its name, which a
118
+ * volume is made under and keeps, or recorded by the exact registry entry its owner holds a receipt or its ledger holds
119
+ * custody for, which covers an attach whose format never finished, or records as the disk a creator kept, which covers
120
+ * a volume unmounted from under it. A RAM disk of that size that is neither, another volume's, a test's, or an
121
+ * unformatted one nothing recorded, is ignored, however it is mounted. The gateway holds
122
+ * each disk it attaches under its creator's lease until the creator keeps it, its volume mounted and marked at the
123
+ * mountpoint, and detaches it when the creator releases it or goes away first: a creator killed or deadlined mid-step
124
+ * leaves no disk behind, where one did before the lease (measured 2026-10-06: a deadlined `hdiutil attach` whose
125
+ * diskimages-helper finished the attach after `hdiutil` was killed). A gateway restart leaves an unended lease's disk
126
+ * to the next gateway's startup scan. A creator records its disk's registry entry in the ledger before it keeps it: the
127
+ * volume's marker names the entry only while the volume is mounted, and a volume an operator's unmount took from its
128
+ * mountpoint leaves its disk attached, mounted nowhere, with nothing else to name it. Before creating, a task detaches
129
+ * each disk of that inventory its owner holds a receipt for or its ledger records as kept. Any other disk, one with a
130
+ * lease directory on it, or one with something attached below it stops the creation instead; its error names it.
106
131
  *
107
132
  * An image attached from a file below a lease belongs to whoever attached it:
108
133
  * cowshed's real-APFS fixtures release theirs under the production per-image
@@ -113,21 +138,21 @@ import type { TempVolumeSpace } from './verdict.js';
113
138
  * holder has an identity a cheap `lstat` re-proves (a mount below the lease),
114
139
  * the ledger keeps that proof (`ram-temp-held.ts`) and later tasks check it
115
140
  * instead of probing the host; any change sends the lease back to a probe.
116
- * Every disk child runs under a deadline, in its own process group so the
117
- * deadline also reaches the helper it spawned, so a wedged DiskArbitration
118
- * fails the task instead of every task waiting on the volume. A detach is the
119
- * exception: never killed at its deadline, because an interrupted detach can
120
- * wedge DiskArbitration itself; its wait is bounded and reported by name, and
121
- * a stray's detach gets the short stray bound, so one wedged stray cannot
122
- * hold the create claim while a chain of tasks queues behind it.
141
+ * SAFE disk children delegate their execution budget and reap to cowshed. Protected
142
+ * image commands are never killed at the caller's deadline. A detach publishes its
143
+ * exact custody before it spawns. While its live caller still waits on the facade the
144
+ * custody is `waiting`, and other callers queue behind it as behind any claim. Once
145
+ * that caller stops waiting, or its run throws without an answer, the custody is
146
+ * `reported`: no lease is admitted until a normal terminal answer or the bound registry
147
+ * entry's absence proves it safe. A dead caller alone proves neither; its death only
148
+ * turns queueing into reporting. The facade pid is a diagnostic, never authority.
123
149
  *
124
- * A cowshed sandbox denies writes to /private/tmp (EPERM on the lock), and
125
- * cannot attach disk images at all; there the task keeps the workspace's own
126
- * TMPDIR and says so once on stderr.
150
+ * A cowshed sandbox denies the volume's paths (EPERM reading its mountpoint or
151
+ * marker, or opening the lock in /private/tmp) and cannot attach disk images at
152
+ * all; whichever refusal comes first, the task keeps the workspace's own TMPDIR
153
+ * and says so once on stderr.
127
154
  */
128
155
 
129
- /** macOS `open(2)` flag: take an exclusive flock atomically with the open. Absent from `fs.constants`. */
130
- const O_EXLOCK = 0x20;
131
156
  /** Contended opens yield without occupying a filesystem worker needed by the lock holder. */
132
157
  const LOCK_RETRY_MS = 50;
133
158
  /**
@@ -141,243 +166,353 @@ const GIB = 1024 * MIB;
141
166
  /**
142
167
  * The revision of the volume's protocol. Checkouts at different revisions run on one host at
143
168
  * once, and each is safe only beside its own: revision 1 leases under the kernel lock alone,
144
- * revision 2 leases and detaches outside it, behind claims in a ledger revision 1 never reads.
145
- * So no revision shares a volume with another. It names the volume, its lock and its ledger, and
146
- * adds as many sectors to the RAM disk, whose size and user are what a creator's stray reclaim
147
- * matches: neither revision detaches the other's disk, mounted or still attaching.
169
+ * revision 2 leases and detaches outside it, behind claims in a ledger revision 1 never reads,
170
+ * and revision 3 mounts below the per-user cowshed root instead of at the `/Volumes` path
171
+ * DiskArbitration gave revisions 1 and 2. So no revision shares a volume with another. It names
172
+ * the volume, its mountpoint, its lock and its ledger, and adds as many sectors to the RAM disk,
173
+ * whose size and user are what a creator's stray reclaim matches: no revision detaches another's
174
+ * disk, mounted or still attaching. A volume of an earlier revision is detached by that
175
+ * revision's own last release.
148
176
  */
149
- const RAM_TEMP_REVISION = 2;
177
+ const RAM_TEMP_REVISION = 3;
150
178
  /**
151
179
  * The volume's ceiling, plus the revision's sectors. Pages are allocated as they are written and
152
180
  * returned when the volume detaches, so this bounds what a runaway suite can take, not what a gate
153
181
  * costs. Measured 2026-10-04: a full parallel smoothbricks `lint test build host-controller-test`
154
182
  * gate peaked at 1.61 GiB used with 18 concurrent leases; 8 GiB is five times that. That
155
- * gate also staged cowshed's real-APFS fixture images on the volume, which now stay under
156
- * /private/tmp, so the peak is an upper bound.
183
+ * gate also staged cowshed's real-APFS fixture images on the volume, which now stay outside it,
184
+ * so the peak is an upper bound.
157
185
  */
158
186
  export const RAM_TEMP_CAPACITY_BYTES = 8 * GIB + RAM_TEMP_REVISION * SECTOR_BYTES;
159
187
  /** A failed task with less than this free on the volume is reported as having run out of space. */
160
188
  const FULL_FREE_BYTES = 64 * MIB;
161
189
  /** `<pid>-<mkdtemp suffix>`: the pid says whether the lease's task is alive. */
162
190
  const LEASE_NAME = /^(\d+)-[A-Za-z0-9]{6}$/;
191
+ /** The random suffix `mkdtemp` gives a lease name. */
192
+ const LEASE_SUFFIX_BYTES = 6;
193
+ /** Darwin's `sockaddr_un.sun_path` holds 104 bytes, the last a NUL: a socket's path is at most 103. */
194
+ const SOCKET_PATH_BYTES = 103;
195
+ /**
196
+ * The one length rule of the RAM temp layout (specs/cowshed/01_storage.md, "RAM temp path budget"): a lease directory,
197
+ * 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
198
+ * uid and pid: `/private/var/folders/cowshed/` (29), a u32 uid (10), `/<ns>` (8), `/ram3` (5), `/<pid ≤ 99999>-` (7)
199
+ * and the suffix (6). Production's worst case is 57.
200
+ */
201
+ export const RAM_TMPDIR_MAX_BYTES = 65;
202
+ /** What the rule leaves below a lease for a socket's `/<names>`: 38 bytes. */
203
+ export const RAM_TMPDIR_SOCKET_BUDGET_BYTES = SOCKET_PATH_BYTES - RAM_TMPDIR_MAX_BYTES;
204
+
205
+ /** The length in bytes of the lease directory process `pid` makes below `mountpoint`. */
206
+ export function leaseDirectoryBytes(mountpoint: string, pid: number): number {
207
+ return Buffer.byteLength(`${mountpoint}/${pid}-`) + LEASE_SUFFIX_BYTES;
208
+ }
163
209
  const MARKER_FILE = '.smoo-ram';
210
+ /**
211
+ * The scratch of a run that did not pass, moved out of its lease when the lease is reclaimed: a directory beside the
212
+ * leases on the same volume, so the move is one `rename(2)` and copies nothing. An entry is
213
+ * `<archived at, epoch ms, 13 digits>-<lease name>`, so the names sort oldest first.
214
+ */
215
+ const ARCHIVE_DIR = '.archive';
216
+ const ARCHIVE_NAME = /^\d{13}-\d+-[A-Za-z0-9]{6}$/;
217
+ /**
218
+ * Archives on their way out, below the archive directory: each is renamed here as `<deleter pid>-<archive name>` and
219
+ * deleted by that process in the background. A dead deleter's entries are claimed by renaming them to the next one's pid.
220
+ */
221
+ const DELETING_DIR = '.deleting';
222
+ const DELETING_NAME = /^(\d+)-(\d{13}-\d+-[A-Za-z0-9]{6})$/;
223
+ /**
224
+ * How many archives the volume keeps: the failing run under triage and the one before it, the pair a triage compares to
225
+ * tell a flake from a regression. A stated reason, not a measurement.
226
+ */
227
+ export const ARCHIVES_KEPT = 2;
228
+ /**
229
+ * Below this share of the volume free, the volume keeps no archive: live leases need the space more than evidence does.
230
+ * 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
231
+ * `RAM_TEMP_CAPACITY_BYTES`).
232
+ */
233
+ const ARCHIVE_FLOOR_SHARE = 0.5;
164
234
 
165
235
  export interface CommandOutput {
166
236
  status: number;
167
237
  stdout: string;
168
238
  stderr: string;
239
+ /** A bounded wait or a signalled facade is not a terminal disk-child receipt. */
240
+ readonly pending?: {
241
+ /** Diagnostic only: neither this pid's death nor reuse releases detach authority. */
242
+ readonly pid: number | null;
243
+ /** This exact child object's normal exit; null means native completion could not be proved. */
244
+ readonly completion: Promise<CommandOutput | null>;
245
+ };
169
246
  }
170
247
 
171
248
  /** The host programs the volume lifecycle runs. A seam so the state machine is testable without DiskArbitration. */
249
+ /**
250
+ * Binds an `hdiutil detach <device>` to the I/O Registry entry the caller inventoried the device as: cowshed reads the
251
+ * entry again inside the disk admission and detaches only while it still has the device as its whole disk.
252
+ */
253
+ export interface DetachBinding {
254
+ readonly registryEntry: string;
255
+ }
256
+
257
+ /** A RAM disk the gateway attached and holds until this caller keeps or releases it; the gateway detaches it if the caller goes away first. */
258
+ export interface RamDiskLease {
259
+ /** Its whole disk, `/dev/diskN`. */
260
+ readonly device: string;
261
+ /** Its I/O Registry entry, `0x…`, as the gateway read it right after its attach. */
262
+ readonly registryEntry: string;
263
+ /**
264
+ * The caller owns the disk from here. Err: the gateway refused, or no answer came, and then nothing is known: the
265
+ * gateway may have handed the disk over or left it to its next startup scan, so the caller detaches it by its entry.
266
+ */
267
+ keep(): Promise<Result<void, string>>;
268
+ /** The gateway detaches the disk now. Ok: its detach answer; Err: the lease was lost (no answer), so nothing is known of a detach. */
269
+ release(): Promise<Result<CommandOutput, string>>;
270
+ }
271
+
172
272
  export interface HostCommands {
173
- run(file: string, args: readonly string[], deadlineMs?: number): Promise<CommandOutput>;
273
+ run(file: string, args: readonly string[], deadlineMs?: number, binding?: DetachBinding): Promise<CommandOutput>;
274
+ /**
275
+ * Attach a RAM disk of `sectors` 512-byte sectors through its owner, answering its lease. The owner is the cowshed
276
+ * gateway (`ram-lease`), never this task: a helper the task's own job forked would end with it. The gateway holds the
277
+ * disk until the lease is kept or released, and detaches it if this caller goes away first.
278
+ */
279
+ attachRam(sectors: number): Promise<Result<RamDiskLease, string | RamUnavailable>>;
280
+ /**
281
+ * Exact attach receipts owned by this caller; names and capacity never establish this authority. A disk it owns
282
+ * counts as the volume's even with nothing mounted, which covers an attach whose format never finished; one it holds
283
+ * no receipt for counts only as the volume of its exact name.
284
+ */
285
+ ownsRamDisk?(disk: AttachedRamDisk): boolean;
286
+ detachRam(device: string, registryEntry: string): Promise<CommandOutput>;
174
287
  }
175
288
 
176
289
  /**
177
- * How long a process a task left in its lease gets to exit on SIGTERM before it gets SIGKILL: the
178
- * time a daemon takes to stop its watcher and its plugin workers, and well under the grace a
290
+ * How long a process a task left in its subtree gets to exit on SIGTERM before it gets SIGKILL:
291
+ * the time a daemon takes to stop its watcher and its plugin workers, and well under the grace a
179
292
  * bounded leg gives its own command.
180
293
  */
181
- const LEFTOVER_GRACE_MS = 5_000;
294
+ export const LEFTOVER_GRACE_MS = 5_000;
182
295
 
183
- /**
184
- * The processes still working in a lease directory once its task is over, and how they end. A
185
- * seam so the volume's state machine is testable without any.
186
- */
187
- export interface LeaseProcesses {
188
- /**
189
- * End every process that works in `directory` — its working directory or the `TMPDIR` it was
190
- * started with is there — and everything those started, and answer each as `<pid> (<command>)`.
191
- * Every one has exited when this settles; one that would not rejects with its name.
192
- */
193
- stopWorkingIn(directory: string): Promise<string[]>;
296
+ /** A lease's subtree handle file: beside the lease on the volume, never in it, so the command cannot remove it. */
297
+ function subtreeRecordPath(directory: string): string {
298
+ return `${directory}.subtree`;
194
299
  }
195
300
 
196
- /** The host reads and signals cleanup uses; a seam for process ordering and signal failures. */
197
- export interface ProcessHost {
198
- /** The processes whose working directory, or the `TMPDIR` they were started with, is `directory` or lies beneath it. */
199
- workingIn(directory: string): Promise<number[]>;
200
- /** Every process on the host. */
201
- table(): Promise<ProcessEntry[]>;
202
- signal(pid: number, signal: NodeJS.Signals): void;
301
+ /** One coverage gap the supervisor reported for a subtree it retired, as text. */
302
+ export function describeCoverageGap(gap: CoverageGap): string {
303
+ return gap.pid === null ? gap.kind : `${gap.kind} (pid ${gap.pid})`;
203
304
  }
204
305
 
205
- /** A `ps` state in which a process starts nothing: stopped (`T`, `t` when traced) or exited (`Z`). */
206
- const STARTS_NOTHING = /^[TtZ]/;
306
+ /** One process a retirement signalled, as `<pid> (<image>)`. */
307
+ export function describeSignalled(entry: SignalledProcess): string {
308
+ return `${entry.pid} (${entry.image ?? 'unknown image'})`;
309
+ }
207
310
 
208
311
  /**
209
- * The processes `host` reads. A lease belongs to one task and its command is gone by the time the
210
- * lease ends, so what still works in it is what the command left behind. Most of that works in the
211
- * lease only through `TMPDIR`, never by working directory: a test's ttsc plugin build copies the
212
- * typescript-go sources into `$TMPDIR` from a process working in its project, and a Bun or Node
213
- * process writes its compile cache there as it exits. Neither is known to the task's pid, and
214
- * whichever outlived that pid would write into a lease being removed (measured 2026-10-18: `rm`
215
- * failing ENOTEMPTY under a ttsc copy whose task had died). A fixture's Nx daemon is another: Nx
216
- * detaches it into a session of its own, so the process-group kill that ends a timed-out command
217
- * never reaches it, and a test process that is killed runs no teardown of its own. Deleting the
218
- * lease asks such a daemon to leave only by deleting its record, which it notices within a second
219
- * when it is idle and not at all while it is wedged; a signal does not depend on the daemon
220
- * noticing, and a process left on the volume is what keeps it from detaching.
221
- *
222
- * A leftover keeps running while it is looked for, and a child it starts after the process table
223
- * was read is in no table that was. So each one found is held with SIGSTOP and the table is read
224
- * again, until a read names nothing that the read before did not already show stopped: a stopped
225
- * process starts nothing, and whatever it started before it stopped is in every table read after.
226
- * Discovery waits for stopped-census readiness; the exit grace starts only after SIGTERM.
227
- * Only then does each get SIGTERM, and SIGCONT to act on it. A child whose parent exited before it
228
- * could be held has lost its ancestry, so once the stopped-table barrier holds, the lease is asked
229
- * again what works in it, including when that table names nothing, to recover reparented children.
312
+ * A test run's host namespace: seven lowercase base-36 characters, the pid of the process that minted it in the first
313
+ * five (zero-padded, so the first is a digit, which begins no production name) and that process's ordinal in the last
314
+ * two. The pid tells a later run whether the namespace's owner is gone. Mirrors `cowshed_os::namespace::TestNamespace`.
230
315
  */
231
- export function leaseProcessesOn(host: ProcessHost): LeaseProcesses {
232
- return {
233
- async stopWorkingIn(directory) {
234
- let working = (await host.workingIn(directory)).filter((pid) => pid !== process.pid);
235
- if (working.length === 0) {
236
- return [];
237
- }
238
- const known = new Map<number, ProcessEntry>();
239
- let held = new Set<number>();
240
- let failures: unknown[] | undefined;
241
- try {
242
- for (;;) {
243
- const roots = [...working, ...known.keys()];
244
- const current = withDescendants(await host.table(), roots).filter((entry) => entry.pid !== process.pid);
245
- for (const entry of current) {
246
- known.set(entry.pid, entry);
247
- }
248
- if (current.every((entry) => held.has(entry.pid) && STARTS_NOTHING.test(entry.stat))) {
249
- working = (await host.workingIn(directory)).filter((pid) => pid !== process.pid);
250
- if (working.every((pid) => held.has(pid))) {
251
- break;
252
- }
253
- }
254
- for (const entry of current) {
255
- host.signal(entry.pid, 'SIGSTOP');
256
- }
257
- held = new Set(current.filter((entry) => STARTS_NOTHING.test(entry.stat)).map((entry) => entry.pid));
258
- }
259
- for (const entry of known.values()) {
260
- host.signal(entry.pid, 'SIGTERM');
261
- }
262
- } catch (error) {
263
- failures = [error];
264
- } finally {
265
- // SIGTERM is pending while stopped. One failed resume must not strand the other holds.
266
- for (const entry of known.values()) {
267
- try {
268
- host.signal(entry.pid, 'SIGCONT');
269
- } catch (error) {
270
- failures ??= [];
271
- failures.push(
272
- new Error(
273
- `${entry.pid} (${entry.command}): SIGCONT failed: ${error instanceof Error ? error.message : String(error)}`,
274
- { cause: error },
275
- ),
276
- );
277
- }
278
- }
279
- }
280
- if (failures !== undefined) {
281
- if (failures.length === 1) {
282
- throw failures[0];
283
- }
284
- throw new AggregateError(
285
- failures,
286
- `processes working in ${directory}: ${failures.map((error) => (error instanceof Error ? error.message : String(error))).join('; ')}`,
287
- );
288
- }
289
- const leftovers = [...known.values()];
290
- try {
291
- await awaitExit(leftovers, `processes working in ${directory}`, LEFTOVER_GRACE_MS);
292
- } catch {
293
- for (const entry of leftovers) {
294
- host.signal(entry.pid, 'SIGKILL');
295
- }
296
- await awaitExit(leftovers, `processes working in ${directory} after SIGKILL`, LEFTOVER_GRACE_MS);
297
- }
298
- return leftovers.map((entry) => `${entry.pid} (${entry.command.slice(0, 160)})`);
299
- },
300
- };
301
- }
316
+ export type TestNamespace = { readonly kind: 'test'; readonly name: string };
302
317
 
303
- /** What works in `directory` on this host: by working directory, and by the `TMPDIR` it was started with. */
304
- export async function pidsInLease(directory: string): Promise<number[]> {
305
- const [working, temp] = await Promise.all([pidsWorkingIn(directory), pidsWithTempIn(directory)]);
306
- return [...new Set([...working, ...temp])];
318
+ /**
319
+ * Whose names a host's RAM temp volume carries: production's, or one test run's own (specs/cowshed/01_storage.md,
320
+ * "Host namespace"). Every path and name the volume takes derives from it (`ramTempPaths`), so no name a test makes can
321
+ * be one production reads, sweeps or reclaims, and no guard compares them. Mirrors
322
+ * `cowshed_os::namespace::HostNamespace`.
323
+ */
324
+ export type HostNamespace = { readonly kind: 'production' } | TestNamespace;
325
+
326
+ /** The namespace of the user's own volume, which no test leases, creates or detaches. */
327
+ export const PRODUCTION: HostNamespace = { kind: 'production' };
328
+
329
+ const NAMESPACE_BASE = 36;
330
+ const NAMESPACE_PID_DIGITS = 5;
331
+ const NAMESPACE_ORDINAL_DIGITS = 2;
332
+
333
+ /** `value` as `digits` zero-padded lowercase base-36 digits; the refusal names it `what` when it does not fit them. */
334
+ function base36Digits(value: number, digits: number, what: string): string {
335
+ if (!Number.isSafeInteger(value) || value < 0 || value >= NAMESPACE_BASE ** digits) {
336
+ throw new RangeError(`${what} ${value} does not fit a test namespace's ${digits} base-36 digits`);
337
+ }
338
+ return value.toString(NAMESPACE_BASE).padStart(digits, '0');
307
339
  }
308
340
 
309
- export const hostLeaseProcesses: LeaseProcesses = leaseProcessesOn({
310
- workingIn: pidsInLease,
311
- table: processTable,
312
- signal: terminate,
313
- });
341
+ /**
342
+ * The namespace process `pid` mints as its `ordinal`th, encoded as `TestNamespace::of` encodes it:
343
+ * `testNamespace(94769, 3)` is `0214h03`. A pid or an ordinal that does not fit its digits throws.
344
+ */
345
+ export function testNamespace(pid: number, ordinal: number): TestNamespace {
346
+ const pidDigits = base36Digits(pid, NAMESPACE_PID_DIGITS, 'pid');
347
+ const ordinalDigits = base36Digits(ordinal, NAMESPACE_ORDINAL_DIGITS, 'ordinal');
348
+ return { kind: 'test', name: `${pidDigits}${ordinalDigits}` };
349
+ }
314
350
 
315
351
  export interface RamTempPaths {
316
- /** Where DiskArbitration mounts the volume: `/Volumes/<volumeName>`. Short for sun_path (104 bytes). */
352
+ /**
353
+ * The root the volume mounts below: a directory of `uid`'s with mode 0700, holding the mountpoint and the staging
354
+ * directory. Production's is the per-user root `cowshed setup` makes, `/private/var/folders/cowshed/<uid>`; a test
355
+ * namespace's is the directory of its name below that root, which its fixture makes. mds admits no volume mounted
356
+ * below `/var/folders/`.
357
+ */
358
+ root: string;
359
+ /** The user that must own `root`. */
360
+ uid: number;
361
+ /**
362
+ * Where the kernel mounts the volume: `<root>/ram<revision>`, so no two revisions stack on one directory. Its length
363
+ * bounds every lease's, which {@link RAM_TMPDIR_MAX_BYTES} caps.
364
+ */
317
365
  mountpoint: string;
366
+ /**
367
+ * The kernel lock, and the ledger beside it: `/private/tmp/<volumeName>.lock` for production,
368
+ * `<root>/ram<revision>.lock` for a test namespace, which keeps its ordinary scratch beside the lock in its own root.
369
+ */
318
370
  lockFile: string;
319
- /** APFS volume name; names the mountpoint. */
371
+ /** APFS volume name; its marker holds it. `smoo-ram<revision>-<uid>`, with `-<ns>` after it for a test namespace. */
320
372
  volumeName: string;
321
- /** Where the volume is mounted to be marked before Disk Arbitration places it at `mountpoint`. */
373
+ /** Where the volume is mounted to be marked before it is mounted at `mountpoint`. */
322
374
  staging: string;
323
- /** Login name `hdiutil info` reports as the attaching user of this module's RAM disks. */
324
- user: string;
375
+ /**
376
+ * The longest lease directory, a task's TMPDIR, this layout admits: {@link RAM_TMPDIR_MAX_BYTES} for every layout
377
+ * `ramTempPaths` makes. A unit fixture that moves the volume into its own scratch makes no TMPDIR and states
378
+ * `Number.MAX_SAFE_INTEGER`, which survives JSON as Infinity does not.
379
+ */
380
+ leaseBytesMax: number;
325
381
  }
326
382
 
327
- export function ramTempPaths(user: { uid: number; username: string }): RamTempPaths {
328
- const volumeName = `smoo-ram${RAM_TEMP_REVISION}-${user.uid}`;
383
+ /**
384
+ * Where the volume of `user` in `namespace` lives and what it is called. Production's are the user's own: the per-user
385
+ * root `/private/var/folders/cowshed/<uid>`, the mountpoint `<root>/ram3` and staging directory `<root>/ram3-new` below
386
+ * it, the volume `smoo-ram3-<uid>` and its lock in `/private/tmp`. A test namespace's lie in the directory of its name
387
+ * below that root, `<root>/<ns>`: its mountpoint, staging directory and lock (`ram3.lock`) in it, and its name after
388
+ * the volume's (`smoo-ram3-<uid>-<ns>`), so none of its paths or names is production's.
389
+ */
390
+ export function ramTempPaths(user: { uid: number }, namespace: HostNamespace): RamTempPaths {
391
+ const userRoot = `/private/var/folders/cowshed/${user.uid}`;
392
+ const leaf = `ram${RAM_TEMP_REVISION}`;
393
+ const own = `smoo-${leaf}-${user.uid}`;
394
+ const production = namespace.kind === 'production';
395
+ const root = production ? userRoot : `${userRoot}/${namespace.name}`;
396
+ const mountpoint = `${root}/${leaf}`;
329
397
  return {
330
- mountpoint: join('/Volumes', volumeName),
331
- lockFile: `/private/tmp/${volumeName}.lock`,
332
- volumeName,
333
- staging: `/private/tmp/${volumeName}-new`,
334
- user: user.username,
398
+ root,
399
+ uid: user.uid,
400
+ mountpoint,
401
+ lockFile: production ? `/private/tmp/${own}.lock` : `${mountpoint}.lock`,
402
+ volumeName: production ? own : `${own}-${namespace.name}`,
403
+ staging: `${mountpoint}-new`,
404
+ leaseBytesMax: RAM_TMPDIR_MAX_BYTES,
335
405
  };
336
406
  }
337
407
 
338
- /** An attached RAM disk, as `hdiutil info` lists it. */
408
+ /** An APFS volume of a RAM disk, as the I/O Registry names it and the mount table places it. */
409
+ export interface RamVolume {
410
+ /** Its `FullName`. A volume is made under its final name and never renamed, so the name says whose it is. */
411
+ name: string;
412
+ /** Where it is mounted, if anywhere. */
413
+ mountpoints: string[];
414
+ }
415
+
416
+ /** An attached RAM disk, as the I/O Registry and the mount table show it. */
339
417
  export interface RamDisk {
340
- /** The whole disk (`/dev/diskN`): detaching it removes its container and volumes. */
341
- physical: string;
418
+ /** Its `IOHDIXHDDriveOutKernel` node's registry entry ID: no later disk has it, where a BSD name passes to the next. */
419
+ entry: string;
420
+ /**
421
+ * The whole disk (`/dev/diskN`): detaching it removes its container and volumes. Null while the disk has published
422
+ * no media yet, part way through its attach.
423
+ */
424
+ physical: string | null;
342
425
  sectors: number;
343
- /** Login name of the user that attached it. */
344
- user: string;
426
+ /** The uid that attached it. */
427
+ uid: number;
345
428
  /** Where its volumes are mounted, if anywhere. */
346
429
  mountpoints: string[];
430
+ /** Its APFS volumes, by the exact names the I/O Registry gives them: none before it is formatted. */
431
+ volumes: RamVolume[];
432
+ }
433
+
434
+ /** A RAM disk with its whole disk published, which a detach can name. */
435
+ export interface AttachedRamDisk extends RamDisk {
436
+ physical: string;
347
437
  }
348
438
 
349
439
  export interface RamTempLease {
350
440
  /** The task's TMPDIR: a directory on the volume that only this task uses. */
351
441
  directory: string;
352
442
  mountpoint: string;
353
- capacityBytes: number;
443
+ /**
444
+ * The attach of the volume the lease was taken on ({@link MountedVolume.attach}). A read of the mountpoint that finds
445
+ * another attach, or none, is not this lease's volume: its free space is some other filesystem's.
446
+ */
447
+ attach: string;
448
+ }
449
+
450
+ export interface RamUnavailable {
451
+ readonly kind: 'ram-unavailable';
452
+ readonly reason: 'gateway-unsupported' | 'gateway-absent' | 'unproven-owner';
453
+ readonly detail: string;
454
+ }
455
+
456
+ interface GatewayVolumeMarker {
457
+ readonly version: 1;
458
+ readonly volumeName: string;
459
+ readonly owner: 'gateway';
460
+ readonly registryEntry: string;
354
461
  }
355
462
 
356
463
  export type RamTempAcquisition =
357
464
  /**
358
465
  * `held`: dead leases that could not be reclaimed, each with what still holds it. `reaped`: the
359
- * processes of dead leases that were still working there and were stopped before the lease went.
466
+ * processes the supervisor retired from dead leases' recorded subtrees before those leases went,
467
+ * as `<pid> (<image>)`. `gaps`: where the supervisor's view of those subtrees may have missed one.
360
468
  */
361
- | { kind: 'leased'; lease: RamTempLease; held: string[]; reaped: string[] }
469
+ | {
470
+ kind: 'leased';
471
+ lease: RamTempLease;
472
+ held: string[];
473
+ reaped: string[];
474
+ gaps: string[];
475
+ /** What became of each dead lease's scratch this acquire reclaimed: archived and kept, or deleted and why. */
476
+ retained: string[];
477
+ }
362
478
  /** Inside a cowshed sandbox: /private/tmp is not writable and no image can attach. */
363
- | { kind: 'sandboxed'; detail: string };
479
+ | { kind: 'sandboxed'; detail: string }
480
+ | { kind: 'unavailable'; reason: RamUnavailable['reason']; detail: string };
364
481
 
365
482
  /** A host command or filesystem step failed while the volume was being created, mounted or detached. */
366
483
  type ProvisionFailed = { kind: 'provision-failed'; step: string; detail: string };
367
484
 
368
485
  export type RamTempError =
486
+ | RamUnavailable
369
487
  | ProvisionFailed
370
488
  /** A failed task left the volume (nearly) full: the likely cause of its failure. */
371
- | { kind: 'volume-full'; mountpoint: string; capacityBytes: number; freeBytes: number };
489
+ | { kind: 'volume-full'; mountpoint: string; capacityBytes: number; freeBytes: number }
490
+ /** The lease went while its task held it: its volume was detached or replaced, or its directory removed. */
491
+ | { kind: 'lease-lost'; lease: string; mountpoint: string; detail: string }
492
+ /**
493
+ * The root the volume mounts below, the per-user root or a test namespace's directory, is missing or is not the
494
+ * user's 0700 directory.
495
+ */
496
+ | { kind: 'root-unready'; root: string; detail: string }
497
+ /** The lease this caller would make is longer than its layout admits: refused before anything is made. */
498
+ | { kind: 'lease-path-budget'; mountpoint: string; pid: number; bytes: number; most: number };
372
499
 
373
500
  export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
374
501
 
375
502
  export function describeRamTempError(error: RamTempError): string {
376
503
  switch (error.kind) {
504
+ case 'ram-unavailable':
505
+ return `RAM acceleration unavailable (${error.reason}): ${error.detail}`;
377
506
  case 'provision-failed':
378
507
  return `RAM temp volume: ${error.step} failed: ${error.detail}`;
379
508
  case 'volume-full':
380
509
  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`;
510
+ case 'lease-lost':
511
+ 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`;
512
+ case 'root-unready':
513
+ return `RAM temp volume: ${error.root} ${error.detail}; run "cowshed setup", which makes it a directory of yours with mode 0700`;
514
+ case 'lease-path-budget':
515
+ 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")`;
381
516
  }
382
517
  }
383
518
 
@@ -401,10 +536,24 @@ interface ClaimOwner {
401
536
  readonly token: string;
402
537
  }
403
538
 
539
+ /** Published before spawn, retained across caller death. Null registry identity means only a terminal receipt suffices. */
540
+ interface DetachCustody {
541
+ readonly physical: string;
542
+ readonly registryEntry: string | null;
543
+ /**
544
+ * `waiting` while its caller still awaits the facade, so other callers queue; `reported` once that caller stopped
545
+ * waiting or its run threw, so other callers reconcile against the registry or refuse.
546
+ */
547
+ readonly phase: 'waiting' | 'reported';
548
+ /** Diagnostic only: the facade its caller stopped waiting on, when one was spawned. */
549
+ readonly facadePid: number | null;
550
+ }
551
+
404
552
  /** The volume is being created or detached: no other caller takes a lease or detaches meanwhile. */
405
553
  interface LifecycleClaim {
406
554
  readonly kind: 'create' | 'detach';
407
555
  readonly owner: ClaimOwner;
556
+ readonly pending?: DetachCustody;
408
557
  }
409
558
 
410
559
  /** One caller is settling the lease `name`, as it was when claimed: stopping, probing and removing it. */
@@ -420,20 +569,30 @@ interface HeldEntry {
420
569
  readonly verdict: HeldVerdict;
421
570
  }
422
571
 
423
- /** What the lock admits changes to, published beside the lock file. Claims of dead owners are void. */
572
+ /** What the lock admits changes to. Dead callers void only claims with no pending detach authority. */
424
573
  interface Ledger {
425
574
  readonly lifecycle: LifecycleClaim | null;
426
575
  readonly claims: readonly LeaseClaim[];
427
576
  readonly held: readonly HeldEntry[];
577
+ /**
578
+ * The registry entry of the disk whose volume a creator last kept, recorded before the keep. A registry entry id is
579
+ * never reused, so a record whose disk is gone names nothing and is replaced by the next keep.
580
+ */
581
+ readonly kept: string | null;
428
582
  }
429
583
 
430
- const EMPTY_LEDGER: Ledger = { lifecycle: null, claims: [], held: [] };
584
+ const EMPTY_LEDGER: Ledger = { lifecycle: null, claims: [], held: [], kept: null };
431
585
 
432
586
  /** The volume as one locked step finds it mounted. */
433
587
  interface MountedVolume {
434
- readonly capacity: number;
588
+ readonly registryEntry: string;
435
589
  /** This attach of the volume: its root's and its marker's identity, never times that change while it is in use. */
436
590
  readonly key: string;
591
+ /**
592
+ * The attach alone: its root's identity and its I/O Registry entry. A rewrite of the marker changes {@link key}, which
593
+ * provenance then proves again, while the leases on the attach stay where they are.
594
+ */
595
+ readonly attach: string;
437
596
  readonly device: number;
438
597
  /** The lease directories on it. */
439
598
  readonly leases: readonly string[];
@@ -442,9 +601,12 @@ interface MountedVolume {
442
601
  /**
443
602
  * One acquire or release. `claimed`: the ledger as it last published holds one of its claims.
444
603
  * `made`: the lease directory an acquire made, with its identity, until the caller has it.
604
+ * `subtrees`: the supervisor this caller asks to retire a dead lease's recorded subtree.
445
605
  */
446
606
  interface Operation {
607
+ provenance?: string;
447
608
  readonly owner: ClaimOwner;
609
+ readonly subtrees: SubtreeOwner;
448
610
  claimed: boolean;
449
611
  made: { readonly directory: string; readonly identity: string } | null;
450
612
  }
@@ -462,6 +624,8 @@ interface Candidate {
462
624
  readonly identity: string;
463
625
  /** The caller's own ending lease, whose task reaped it, rather than a dead one. */
464
626
  readonly own: boolean;
627
+ /** Its scratch is archived, not deleted: its task died, or its own run did not pass. */
628
+ readonly keep: boolean;
465
629
  }
466
630
 
467
631
  /** A lease kept because something is attached below it, described for the task's output. */
@@ -477,13 +641,32 @@ interface Claimed {
477
641
  readonly candidates: readonly Candidate[];
478
642
  }
479
643
 
480
- /** What settling claimed leases found: those kept, the processes stopped, and the verdicts to publish. */
644
+ /** What settling claimed leases found: those kept, the processes retired, the gaps, and the verdicts to publish. */
481
645
  interface Settled {
482
646
  readonly held: readonly HeldLease[];
483
647
  readonly reaped: readonly string[];
648
+ readonly retained: readonly string[];
649
+ readonly gaps: readonly string[];
484
650
  readonly verdicts: readonly HeldEntry[];
485
651
  }
486
652
 
653
+ /** A reclaimed lease whose scratch was renamed into the archive, and the name it has there. */
654
+ interface Archived {
655
+ readonly directory: string;
656
+ readonly archive: string;
657
+ }
658
+
659
+ /**
660
+ * This process's background deletions of archives, one at a time in order. Nothing that takes or releases a lease waits
661
+ * on it; the detach of the volume does, since a deletion still walking the volume would hold it busy.
662
+ */
663
+ let archiveDeletion: Promise<void> = Promise.resolve();
664
+
665
+ /** Settles once every archive deletion this process has queued so far has finished; a test seam, and the detach's wait. */
666
+ export function archiveDeletions(): Promise<void> {
667
+ return archiveDeletion;
668
+ }
669
+
487
670
  /** How long a caller has waited on one lifecycle claim, and how many notices it has printed. */
488
671
  interface ClaimWait {
489
672
  readonly token: string;
@@ -503,7 +686,7 @@ type Taken =
503
686
  };
504
687
 
505
688
  type Releasing =
506
- | { readonly kind: 'unmounted' }
689
+ | { readonly kind: 'lost'; readonly detail: string }
507
690
  | { readonly kind: 'wait'; readonly claim: LifecycleClaim }
508
691
  | {
509
692
  readonly kind: 'claimed';
@@ -520,22 +703,49 @@ export class RamTempVolume {
520
703
  private readonly sectors: number;
521
704
  /** The claims and held verdicts the lock admits changes to, beside the lock file. */
522
705
  private readonly ledgerPath: string;
706
+ /**
707
+ * Where optional RAM's ordinary fallback makes its owned scratch: the lock's own directory, which an unavailable answer
708
+ * has just written. For the user's volume that is `/private/tmp`, outside every checkout, so no Git or Cargo walk from
709
+ * the command's temp files finds the workspace it builds; the workspace's runtime alias resolves into
710
+ * `<mount>/.cowshed/run`, inside the checkout, and the inherited TMPDIR may be RAM. A test namespace's lock lies in
711
+ * its own root, so its ordinary scratch does too.
712
+ */
713
+ readonly ordinaryParent: string;
523
714
 
524
715
  constructor(
525
716
  private readonly paths: RamTempPaths,
526
- private readonly capacityBytes: number,
717
+ capacityBytes: number,
527
718
  private readonly commands: HostCommands,
528
719
  private readonly pid: number = process.pid,
529
720
  private readonly isAlive: (pid: number) => boolean = processIsAlive,
530
- private readonly processes: LeaseProcesses = hostLeaseProcesses,
721
+ private readonly policy: 'required' | 'optional' = 'required',
531
722
  ) {
532
723
  this.sectors = Math.ceil(capacityBytes / SECTOR_BYTES);
533
724
  this.ledgerPath = `${paths.lockFile}.ledger`;
725
+ this.ordinaryParent = dirname(paths.lockFile);
534
726
  }
535
727
 
536
- /** Take a lease: create the volume if no task holds one, and a private directory on it. */
537
- async acquire(): Promise<Result<RamTempAcquisition, RamTempError>> {
538
- const op: Operation = { owner: { pid: this.pid, token: randomUUID() }, claimed: false, made: null };
728
+ /**
729
+ * Take a lease: create the volume if no task holds one, and a private directory on it. A dead
730
+ * lease found on the way is settled through `subtrees`, the supervisor that owns the caller.
731
+ */
732
+ async acquire(subtrees: SubtreeOwner): Promise<Result<RamTempAcquisition, RamTempError>> {
733
+ const bytes = leaseDirectoryBytes(this.paths.mountpoint, this.pid);
734
+ if (bytes > this.paths.leaseBytesMax) {
735
+ return {
736
+ ok: false,
737
+ error: {
738
+ kind: 'lease-path-budget',
739
+ mountpoint: this.paths.mountpoint,
740
+ pid: this.pid,
741
+ bytes,
742
+ most: this.paths.leaseBytesMax,
743
+ },
744
+ };
745
+ }
746
+ const readiness = await rootReadiness(this.paths);
747
+ if (!readiness.ok) return readiness;
748
+ const op: Operation = { owner: { pid: this.pid, token: randomUUID() }, subtrees, claimed: false, made: null };
539
749
  let result: Result<RamTempAcquisition, LockedError>;
540
750
  try {
541
751
  result = await this.lease(op);
@@ -553,6 +763,9 @@ export class RamTempVolume {
553
763
  }
554
764
  // The caller gets no lease, so the one made for it goes; a returned lease is never touched.
555
765
  const cleanup = [...(ended.ok ? [] : [ended.error]), ...(await this.undo(op))];
766
+ if (result.error.kind === 'ram-unavailable' && this.policy === 'optional' && cleanup.length === 0) {
767
+ return { ok: true, value: { kind: 'unavailable', reason: result.error.reason, detail: result.error.detail } };
768
+ }
556
769
  if (result.error.kind !== 'lock-denied') {
557
770
  return { ok: false, error: alsoFailed(result.error, cleanup) };
558
771
  }
@@ -646,7 +859,7 @@ export class RamTempVolume {
646
859
  }
647
860
  // The lease exists before the lock drops, so no release finds the volume empty under it.
648
861
  const directory = await this.make(op);
649
- const claimed = await this.claim(ledger, volume, op.owner, null);
862
+ const claimed = await this.claim(ledger, volume, op.owner, null, false);
650
863
  return {
651
864
  ledger: claimed.ledger,
652
865
  value: { kind: 'leased', volume, directory, held: claimed.held, candidates: claimed.candidates },
@@ -657,10 +870,13 @@ export class RamTempVolume {
657
870
  }
658
871
  const value = taken.value;
659
872
  switch (value.kind) {
660
- case 'wait':
873
+ case 'wait': {
661
874
  // Another caller is creating or detaching the volume: look again once it has.
662
- waited = await this.waitOut(value.claim, waited);
875
+ const yielded = await this.yieldTo(op, value.claim, waited);
876
+ if (!yielded.ok) return yielded;
877
+ waited = yielded.value;
663
878
  continue;
879
+ }
664
880
  case 'create':
665
881
  return await this.create(op);
666
882
  case 'leased': {
@@ -684,10 +900,12 @@ export class RamTempVolume {
684
900
  lease: {
685
901
  directory: value.directory,
686
902
  mountpoint: this.paths.mountpoint,
687
- capacityBytes: value.volume.capacity,
903
+ attach: value.volume.attach,
688
904
  },
689
905
  held: [...value.held, ...settled.value.held].map((lease) => lease.text),
690
906
  reaped: [...settled.value.reaped],
907
+ retained: [...settled.value.retained],
908
+ gaps: [...settled.value.gaps],
691
909
  },
692
910
  };
693
911
  }
@@ -697,14 +915,14 @@ export class RamTempVolume {
697
915
 
698
916
  /** With this caller's creation claim published: provision the volume, then take the first lease on it. */
699
917
  private async create(op: Operation): Promise<Result<RamTempAcquisition, LockedError>> {
700
- const provisioned = await this.provisionVolume();
918
+ const provisioned = await this.provisionVolume(op);
701
919
  if (!provisioned.ok) {
702
920
  return provisioned;
703
921
  }
704
922
  const placed = await this.locked(
705
923
  op,
706
924
  'lease',
707
- async (ledger, volume): Promise<Step<Result<string, RamTempError>>> => {
925
+ async (ledger, volume): Promise<Step<Result<RamTempLease, RamTempError>>> => {
708
926
  const next = withoutClaimsOf(ledger, op.owner);
709
927
  if (ledger.lifecycle?.owner.token !== op.owner.token) {
710
928
  return {
@@ -721,7 +939,11 @@ export class RamTempVolume {
721
939
  value: failed('create', `${this.paths.mountpoint} is not the marked volume once provisioned`),
722
940
  };
723
941
  }
724
- return { ledger: next, value: { ok: true, value: await this.make(op) } };
942
+ const directory = await this.make(op);
943
+ return {
944
+ ledger: next,
945
+ value: { ok: true, value: { directory, mountpoint: this.paths.mountpoint, attach: volume.attach } },
946
+ };
725
947
  },
726
948
  );
727
949
  if (!placed.ok) {
@@ -734,46 +956,45 @@ export class RamTempVolume {
734
956
  ok: true,
735
957
  value: {
736
958
  kind: 'leased',
737
- lease: { directory: placed.value.value, mountpoint: this.paths.mountpoint, capacityBytes: this.capacityBytes },
959
+ lease: placed.value.value,
738
960
  held: [],
739
961
  reaped: [],
962
+ retained: [],
963
+ gaps: [],
740
964
  },
741
965
  };
742
966
  }
743
967
 
744
968
  /**
745
- * Stop what the task left working in its lease, before the lease ends: the processes whose
746
- * working directory is in it and everything they started, answered as `<pid> (<command>)`.
747
- * Runs outside the volume's lock, which one lease's leftovers must not hold up the others
748
- * behind, and costs a scan of every process only when the lease still holds anything.
969
+ * Record the supervisor's handle on the subtree whose command uses `lease`, beside the lease, so
970
+ * that if this task dies before it retires that subtree, whoever settles the dead lease can hand
971
+ * the handle back to the supervisor instead of guessing from a census who worked there.
749
972
  */
750
- async reap(lease: RamTempLease): Promise<Result<string[], RamTempError>> {
973
+ async record(lease: RamTempLease, handle: SubtreeHandle): Promise<Result<void, RamTempError>> {
751
974
  try {
752
- const entries = await readdir(lease.directory).catch((error: unknown) => {
753
- if (errorCode(error) === 'ENOENT') return [];
754
- throw error;
755
- });
756
- if (entries.length === 0) {
757
- return { ok: true, value: [] };
758
- }
759
- return { ok: true, value: await this.processes.stopWorkingIn(lease.directory) };
975
+ await writeFile(subtreeRecordPath(lease.directory), `${JSON.stringify(handle)}\n`, { mode: 0o600 });
976
+ return { ok: true, value: undefined };
760
977
  } catch (error) {
761
- return failed('reap', errorText(error));
978
+ return failed('record subtree', errorText(error));
762
979
  }
763
980
  }
764
981
 
765
- /** End a lease; the last lease detaches the volume, returning its RAM. */
766
- async release(lease: RamTempLease): Promise<Result<void, RamTempError>> {
767
- const op: Operation = { owner: { pid: this.pid, token: randomUUID() }, claimed: false, made: null };
768
- let result: Result<void, LockedError>;
982
+ /**
983
+ * End a lease; the last lease detaches the volume, returning its RAM. `keep` archives the lease's scratch instead of
984
+ * deleting it: its run did not pass. A dead lease found on the way is settled through `subtrees`. Answers what became
985
+ * of every scratch this release reclaimed, its own included.
986
+ */
987
+ async release(lease: RamTempLease, keep: boolean, subtrees: SubtreeOwner): Promise<Result<string[], RamTempError>> {
988
+ const op: Operation = { owner: { pid: this.pid, token: randomUUID() }, subtrees, claimed: false, made: null };
989
+ let result: Result<string[], LockedError>;
769
990
  try {
770
- result = await this.releaseLease(op, basename(lease.directory));
991
+ result = await this.releaseLease(op, lease, keep);
771
992
  } catch (error) {
772
993
  result = failed('release', errorText(error));
773
994
  }
774
995
  const ended = await this.end(op);
775
996
  if (result.ok) {
776
- return ended;
997
+ return ended.ok ? result : ended;
777
998
  }
778
999
  const primary: RamTempError =
779
1000
  result.error.kind === 'lock-denied'
@@ -782,20 +1003,27 @@ export class RamTempVolume {
782
1003
  return { ok: false, error: alsoFailed(primary, ended.ok ? [] : [ended.error]) };
783
1004
  }
784
1005
 
785
- private async releaseLease(op: Operation, own: string): Promise<Result<void, LockedError>> {
1006
+ private async releaseLease(
1007
+ op: Operation,
1008
+ lease: RamTempLease,
1009
+ keep: boolean,
1010
+ ): Promise<Result<string[], LockedError>> {
1011
+ const own = basename(lease.directory);
786
1012
  let waited: ClaimWait | null = null;
787
1013
  for (;;) {
788
1014
  const taken = await this.locked(op, 'release', async (ledger, volume): Promise<Step<Releasing>> => {
789
- if (volume === null) {
790
- return { ledger, value: { kind: 'unmounted' } };
1015
+ // A lease that went while its task held it is said, never released as though it were there.
1016
+ const held = leaseOn(lease, volume);
1017
+ if ('lost' in held) {
1018
+ return { ledger, value: { kind: 'lost', detail: held.lost } };
791
1019
  }
792
1020
  if (ledger.lifecycle !== null) {
793
1021
  return { ledger, value: { kind: 'wait', claim: ledger.lifecycle } };
794
1022
  }
795
- const claimed = await this.claim(ledger, volume, op.owner, own);
1023
+ const claimed = await this.claim(ledger, held.on, op.owner, own, keep);
796
1024
  return {
797
1025
  ledger: claimed.ledger,
798
- value: { kind: 'claimed', volume, held: claimed.held, candidates: claimed.candidates },
1026
+ value: { kind: 'claimed', volume: held.on, held: claimed.held, candidates: claimed.candidates },
799
1027
  };
800
1028
  });
801
1029
  if (!taken.ok) {
@@ -803,11 +1031,17 @@ export class RamTempVolume {
803
1031
  }
804
1032
  const value = taken.value;
805
1033
  switch (value.kind) {
806
- case 'unmounted':
807
- return { ok: true, value: undefined };
808
- case 'wait':
809
- waited = await this.waitOut(value.claim, waited);
1034
+ case 'lost':
1035
+ return {
1036
+ ok: false,
1037
+ error: { kind: 'lease-lost', lease: lease.directory, mountpoint: lease.mountpoint, detail: value.detail },
1038
+ };
1039
+ case 'wait': {
1040
+ const yielded = await this.yieldTo(op, value.claim, waited);
1041
+ if (!yielded.ok) return yielded;
1042
+ waited = yielded.value;
810
1043
  continue;
1044
+ }
811
1045
  case 'claimed': {
812
1046
  const settled = await this.settle(op, value.volume, value.candidates);
813
1047
  if (!settled.ok) {
@@ -830,7 +1064,23 @@ export class RamTempVolume {
830
1064
  if (kept !== undefined) {
831
1065
  return failed('release', kept.text);
832
1066
  }
833
- return idle.value ? await this.detach(op, value.volume) : { ok: true, value: undefined };
1067
+ if (!idle.value) {
1068
+ return { ok: true, value: [...settled.value.retained] };
1069
+ }
1070
+ const detached = await this.detach(op, value.volume);
1071
+ if (!detached.ok) {
1072
+ return detached;
1073
+ }
1074
+ // The volume's pages go with it, its archives included: what the lines above kept lived until now.
1075
+ return {
1076
+ ok: true,
1077
+ value: [
1078
+ ...settled.value.retained,
1079
+ ...(settled.value.retained.length > 0
1080
+ ? [`${this.paths.mountpoint} detached with its last lease, and every archive on it went with it`]
1081
+ : []),
1082
+ ],
1083
+ };
834
1084
  }
835
1085
  }
836
1086
  }
@@ -848,35 +1098,54 @@ export class RamTempVolume {
848
1098
  const due = Math.floor(elapsed / CLAIM_WAIT_NOTICE_MS);
849
1099
  if (due > wait.notices) {
850
1100
  process.stderr.write(
851
- `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`,
1101
+ `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`,
852
1102
  );
853
1103
  }
854
1104
  await sleep(LOCK_RETRY_MS);
855
1105
  return { ...wait, notices: Math.max(wait.notices, due) };
856
1106
  }
857
1107
 
858
- /** After a failed task: whether the volume ran out of space, which is then the error to report. */
1108
+ /**
1109
+ * After a failed task: whether the volume ran out of space, which is then the error to report. A lease no longer on
1110
+ * its volume is said by its release, and a volume that cannot be read has no space to report.
1111
+ */
859
1112
  async fullness(lease: RamTempLease): Promise<RamTempError | null> {
860
1113
  const space = await this.space(lease);
861
- if (space === null || space.freeBytes >= FULL_FREE_BYTES) {
1114
+ if (space.kind !== 'measured' || space.freeBytes >= FULL_FREE_BYTES) {
862
1115
  return null;
863
1116
  }
864
1117
  const { mountpoint, capacityBytes, freeBytes } = space;
865
1118
  return { kind: 'volume-full', mountpoint, capacityBytes, freeBytes };
866
1119
  }
867
1120
 
868
- /** The lease's volume and the space left on it now; `null` when the volume cannot be read. */
869
- async space(lease: RamTempLease): Promise<TempVolumeSpace | null> {
1121
+ /**
1122
+ * The lease's volume and the space left on it now, measured only while the mountpoint holds the attach the lease was
1123
+ * taken on and the lease is still on it: a bare mountpoint's statfs reads the host's Data volume, whose free space is
1124
+ * not the lease's. A lease that went with its volume, or from it, is `lost`; a read that failed is `unread`.
1125
+ */
1126
+ async space(lease: RamTempLease): Promise<TempVolumeSpace> {
1127
+ const { directory, mountpoint } = lease;
870
1128
  try {
871
- const fs = await statfs(lease.mountpoint);
1129
+ const observed = await this.observe();
1130
+ if (!observed.ok) {
1131
+ const detail =
1132
+ observed.error.kind === 'lock-denied' ? observed.error.detail : describeRamTempError(observed.error);
1133
+ return { kind: 'unread', lease: directory, mountpoint, detail };
1134
+ }
1135
+ const held = leaseOn(lease, observed.value);
1136
+ if ('lost' in held) {
1137
+ return { kind: 'lost', lease: directory, mountpoint, detail: held.lost };
1138
+ }
1139
+ const fs = await statfs(mountpoint);
872
1140
  return {
873
- lease: lease.directory,
874
- mountpoint: lease.mountpoint,
875
- capacityBytes: lease.capacityBytes,
1141
+ kind: 'measured',
1142
+ lease: directory,
1143
+ mountpoint,
1144
+ capacityBytes: fs.blocks * fs.bsize,
876
1145
  freeBytes: fs.bavail * fs.bsize,
877
1146
  };
878
- } catch {
879
- return null;
1147
+ } catch (error) {
1148
+ return { kind: 'unread', lease: directory, mountpoint, detail: errorText(error) };
880
1149
  }
881
1150
  }
882
1151
 
@@ -901,7 +1170,139 @@ export class RamTempVolume {
901
1170
  }
902
1171
  }
903
1172
 
904
- /** Drop whatever claims `op` still holds: an operation that failed part way leaves none behind it. */
1173
+ /**
1174
+ * Yield to another caller's lifecycle claim. Every claim is queued behind, a detach whose live caller still waits on
1175
+ * its facade included. Reported custody, or waiting custody whose caller died, admits nothing until its exact
1176
+ * registry entry is gone: the caller's liveness only chooses between queueing and reporting, never clears custody.
1177
+ */
1178
+ private async yieldTo(
1179
+ op: Operation,
1180
+ claim: LifecycleClaim,
1181
+ waited: ClaimWait | null,
1182
+ ): Promise<Result<ClaimWait | null, LockedError>> {
1183
+ const pending = claim.pending;
1184
+ if (pending === undefined || (pending.phase === 'waiting' && this.isAlive(claim.owner.pid))) {
1185
+ return { ok: true, value: await this.waitOut(claim, waited) };
1186
+ }
1187
+ const reconciled = await this.reconcileDetach(op, claim);
1188
+ return reconciled.ok ? { ok: true, value: waited } : reconciled;
1189
+ }
1190
+
1191
+ /** A detach nobody waits on any more can be reconciled only against its exact registry identity, outside the lock. */
1192
+ private async reconcileDetach(op: Operation, claim: LifecycleClaim): Promise<Result<void, LockedError>> {
1193
+ const pending = claim.pending;
1194
+ if (pending === undefined) return { ok: true, value: undefined };
1195
+ if (pending.registryEntry !== null) {
1196
+ const registry = await this.commands.run('/usr/sbin/ioreg', ['-r', '-c', 'IOHDIXHDDriveOutKernel', '-l', '-w0']);
1197
+ if (registry.status !== 0) return failed('detach custody', commandText(registry));
1198
+ const disks = ramDisksIn(registry.stdout, '');
1199
+ if (!disks.ok) return failed('detach custody', disks.error);
1200
+ if (!disks.value.some((disk) => disk.entry === pending.registryEntry)) {
1201
+ return this.locked(op, 'detach custody', async (ledger) => ({
1202
+ ledger: sameDetach(ledger.lifecycle, claim.owner, pending) ? { ...ledger, lifecycle: null } : ledger,
1203
+ value: undefined,
1204
+ }));
1205
+ }
1206
+ }
1207
+ return failed(
1208
+ 'detach custody',
1209
+ `${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'}`,
1210
+ );
1211
+ }
1212
+
1213
+ /** Publish authority before spawn: a crash anywhere after this point must not admit a lease past the detach. */
1214
+ private async runDetach(
1215
+ op: Operation,
1216
+ physical: string,
1217
+ registryEntry: string | null,
1218
+ ): Promise<Result<CommandOutput, RamTempError>> {
1219
+ const custody: DetachCustody = { physical, registryEntry, phase: 'waiting', facadePid: null };
1220
+ const begun = await this.locked(op, 'detach custody', async (ledger): Promise<Step<boolean>> => {
1221
+ const claim = ledger.lifecycle;
1222
+ if (claim?.owner.token !== op.owner.token || claim.pending !== undefined) return { ledger, value: false };
1223
+ return { ledger: { ...ledger, lifecycle: { ...claim, pending: custody } }, value: true };
1224
+ });
1225
+ if (!begun.ok)
1226
+ return begun.error.kind === 'lock-denied'
1227
+ ? failed('lock', begun.error.detail)
1228
+ : { ok: false, error: begun.error };
1229
+ if (!begun.value)
1230
+ return failed('detach custody', 'the operation no longer owns an idle lifecycle claim; nothing detached');
1231
+ let output: CommandOutput;
1232
+ try {
1233
+ if (registryEntry === null)
1234
+ throw new Error('detach has no captured registry identity; retained without dispatch');
1235
+ output = await this.commands.detachRam(physical, registryEntry);
1236
+ } catch (error) {
1237
+ // Whether a child started is unknown, so its custody is reported, never dropped.
1238
+ const reported = await this.reportDetach(op, custody, null);
1239
+ const detail = `the detach of ${physical} gave no answer (${errorText(error)}); its custody stays reported in ${this.ledgerPath}`;
1240
+ return failed('detach custody', reported.ok ? detail : `${detail}; ${describeRamTempError(reported.error)}`);
1241
+ }
1242
+ const pending = output.pending;
1243
+ if (pending === undefined) {
1244
+ const finished = await this.finishDetach(op, custody, false);
1245
+ return finished.ok ? { ok: true, value: output } : finished;
1246
+ }
1247
+ const retained = await this.reportDetach(op, custody, pending.pid);
1248
+ // The gateway owns the mutation. Only its authoritative terminal/not-started reply clears this request; a lost connection does not.
1249
+ void pending.completion
1250
+ .then(async (terminal) => {
1251
+ if (terminal === null) return;
1252
+ const finished = await this.finishDetach(op, custody, true);
1253
+ process.stderr.write(
1254
+ `RAM temp volume: detach of ${physical} completed after its caller stopped waiting (${commandText(terminal)}); ${finished.ok ? 'terminal receipt processed' : describeRamTempError(finished.error)}\n`,
1255
+ );
1256
+ })
1257
+ .catch((error: unknown) => {
1258
+ process.stderr.write(
1259
+ `RAM temp volume: detach completion for ${physical} could not publish: ${errorText(error)}\n`,
1260
+ );
1261
+ });
1262
+ return retained.ok ? { ok: true, value: output } : retained;
1263
+ }
1264
+
1265
+ /** Only this operation's exact terminal receipt can clear its pending authority; a late receipt cannot clear a successor. */
1266
+ private async finishDetach(
1267
+ op: Operation,
1268
+ custody: DetachCustody,
1269
+ release: boolean,
1270
+ ): Promise<Result<void, RamTempError>> {
1271
+ const finished = await this.locked(op, 'detach completion', async (ledger) => {
1272
+ const claim = ledger.lifecycle;
1273
+ if (claim === null || !sameDetach(claim, op.owner, custody)) return { ledger, value: undefined };
1274
+ return {
1275
+ ledger: { ...ledger, lifecycle: release ? null : { kind: claim.kind, owner: claim.owner } },
1276
+ value: undefined,
1277
+ };
1278
+ });
1279
+ if (finished.ok) return finished;
1280
+ return finished.error.kind === 'lock-denied'
1281
+ ? failed('lock', finished.error.detail)
1282
+ : { ok: false, error: finished.error };
1283
+ }
1284
+
1285
+ /** Its caller stops waiting on the detach: the exact custody becomes reported, its facade pid kept for diagnosis. */
1286
+ private async reportDetach(
1287
+ op: Operation,
1288
+ custody: DetachCustody,
1289
+ facadePid: number | null,
1290
+ ): Promise<Result<void, RamTempError>> {
1291
+ const reported = await this.locked(op, 'detach custody', async (ledger): Promise<Step<undefined>> => {
1292
+ const claim = ledger.lifecycle;
1293
+ if (claim === null || !sameDetach(claim, op.owner, custody)) return { ledger, value: undefined };
1294
+ return {
1295
+ ledger: { ...ledger, lifecycle: { ...claim, pending: { ...custody, phase: 'reported', facadePid } } },
1296
+ value: undefined,
1297
+ };
1298
+ });
1299
+ if (reported.ok) return reported;
1300
+ return reported.error.kind === 'lock-denied'
1301
+ ? failed('lock', reported.error.detail)
1302
+ : { ok: false, error: reported.error };
1303
+ }
1304
+
1305
+ /** Drop finished claims, never the authority of a detach whose caller merely stopped waiting. */
905
1306
  private async end(op: Operation): Promise<Result<void, RamTempError>> {
906
1307
  if (!op.claimed) {
907
1308
  return { ok: true, value: undefined };
@@ -928,31 +1329,53 @@ export class RamTempVolume {
928
1329
  step: string,
929
1330
  change: (ledger: Ledger, volume: MountedVolume | null) => Promise<Step<T>>,
930
1331
  ): Promise<Result<T, LockedError>> {
931
- const lock = await this.lock();
932
- if (!lock.ok) {
933
- return lock.error.code === 'EPERM'
934
- ? { ok: false, error: { kind: 'lock-denied', detail: `${this.paths.lockFile}: ${lock.error.message}` } }
935
- : failed('lock', lock.error.message);
936
- }
937
- try {
938
- const read = await this.readLedger();
939
- if (!read.ok) {
940
- return read;
1332
+ for (;;) {
1333
+ // Registry work stays outside the lock. A changed locked identity invalidates this
1334
+ // snapshot; release the lock and prove the replacement afresh before any mutation.
1335
+ const initialLedger = await this.readLedger();
1336
+ if (!initialLedger.ok) return initialLedger;
1337
+ const before = await this.observe();
1338
+ if (!before.ok) return before;
1339
+ if (before.value !== null && op.provenance !== before.value.key) {
1340
+ const validated = await this.validateProvenance(before.value);
1341
+ if (!validated.ok) {
1342
+ // The last release detaches outside the lock, so the volume can go between its observation and this
1343
+ // registry read: a volume no longer there is looked at again, and only the one still mounted is refused.
1344
+ const again = await this.observe();
1345
+ if (!again.ok) return again;
1346
+ if (again.value?.key !== before.value.key) continue;
1347
+ return validated;
1348
+ }
1349
+ op.provenance = before.value.key;
941
1350
  }
942
- const volume = await this.observe();
943
- const next = await change(prune(read.value.ledger, volume, this.isAlive), volume);
944
- const text = ledgerText(next.ledger);
945
- if (text !== (read.value.text ?? ledgerText(EMPTY_LEDGER))) {
946
- await publishLedger(this.ledgerPath, text);
1351
+ const lock = await this.lock();
1352
+ if (!lock.ok) {
1353
+ return lock.error.code === 'EPERM'
1354
+ ? { ok: false, error: { kind: 'lock-denied', detail: `${this.paths.lockFile}: ${lock.error.message}` } }
1355
+ : failed('lock', lock.error.message);
1356
+ }
1357
+ try {
1358
+ const read = await this.readLedger();
1359
+ if (!read.ok) return read;
1360
+ const observed = await this.observe();
1361
+ if (!observed.ok) return observed;
1362
+ const volume = observed.value;
1363
+ if (volume !== null && (volume.key !== before.value?.key || op.provenance !== volume.key)) {
1364
+ op.provenance = undefined;
1365
+ continue;
1366
+ }
1367
+ const next = await change(prune(read.value.ledger, volume, this.isAlive), volume);
1368
+ const text = ledgerText(next.ledger);
1369
+ if (text !== (read.value.text ?? ledgerText(EMPTY_LEDGER))) await publishLedger(this.ledgerPath, text);
1370
+ op.claimed =
1371
+ next.ledger.lifecycle?.owner.token === op.owner.token ||
1372
+ next.ledger.claims.some((claim) => claim.owner.token === op.owner.token);
1373
+ return { ok: true, value: next.value };
1374
+ } catch (error) {
1375
+ return failed(step, errorText(error));
1376
+ } finally {
1377
+ await lock.value.close();
947
1378
  }
948
- op.claimed =
949
- next.ledger.lifecycle?.owner.token === op.owner.token ||
950
- next.ledger.claims.some((claim) => claim.owner.token === op.owner.token);
951
- return { ok: true, value: next.value };
952
- } catch (error) {
953
- return failed(step, errorText(error));
954
- } finally {
955
- await lock.value.close();
956
1379
  }
957
1380
  }
958
1381
 
@@ -972,12 +1395,12 @@ export class RamTempVolume {
972
1395
  }
973
1396
  return failed('ledger', `${this.ledgerPath}: ${errorText(error)}`);
974
1397
  }
975
- // Claims that cannot be read cannot be honoured, so no lease or volume change is safe until it is
976
- // removed; only this module writes it, in one rename, so a malformed one is not its own.
1398
+ // An unreadable ledger may hold detached-child authority even after every caller died.
1399
+ // Preserve it and refuse admission rather than suggesting pid death authorizes its removal.
977
1400
  const refused = (detail: string) =>
978
1401
  failed<{ ledger: Ledger; text: string | null }>(
979
1402
  'ledger',
980
- `${this.ledgerPath} ${detail}; remove it once no task uses the volume`,
1403
+ `${this.ledgerPath} ${detail}; retained; no lease or detach admitted while its authority is unreadable`,
981
1404
  );
982
1405
  let wire: unknown;
983
1406
  try {
@@ -985,6 +1408,9 @@ export class RamTempVolume {
985
1408
  } catch (error) {
986
1409
  return refused(`is not JSON: ${errorText(error)}`);
987
1410
  }
1411
+ if (isRecord(wire) && wire.version !== 1 && wire.version !== 2) {
1412
+ return refused(`has unsupported version ${JSON.stringify(wire.version)}`);
1413
+ }
988
1414
  const ledger = parseLedger(wire);
989
1415
  return ledger === undefined ? refused("is not this module's ledger") : { ok: true, value: { ledger, text } };
990
1416
  }
@@ -994,38 +1420,133 @@ export class RamTempVolume {
994
1420
  * names this attach: the root's and the marker's identity and birth, and the marker's change
995
1421
  * time, which nothing changes once it is written. The root's own times change with every lease.
996
1422
  */
997
- private async observe(): Promise<MountedVolume | null> {
1423
+ private async observe(): Promise<Result<MountedVolume | null, LockedError>> {
998
1424
  const markerPath = join(this.paths.mountpoint, MARKER_FILE);
999
- const marker = await readFile(markerPath, 'utf8').catch(() => null);
1000
- if (marker?.trim() !== this.paths.volumeName) {
1001
- return null;
1425
+ let markerText: string;
1426
+ try {
1427
+ const handle = await open(markerPath, constants.O_RDONLY | constants.O_NOFOLLOW);
1428
+ try {
1429
+ markerText = await handle.readFile('utf8');
1430
+ } finally {
1431
+ await handle.close();
1432
+ }
1433
+ } catch (error) {
1434
+ if (errorCode(error) === 'ENOENT') return { ok: true, value: null };
1435
+ return errorCode(error) === 'EPERM' ? denied(markerPath, error) : failed('provenance', errorText(error));
1002
1436
  }
1003
- const [root, parent, mark] = await Promise.all([
1004
- stat(this.paths.mountpoint, { bigint: true }),
1005
- stat(join(this.paths.mountpoint, '..'), { bigint: true }),
1006
- lstat(markerPath, { bigint: true }),
1007
- ]);
1008
- if (root.dev === parent.dev) {
1009
- return null;
1437
+ if (markerText.trim() === this.paths.volumeName) {
1438
+ return {
1439
+ ok: false,
1440
+ error: {
1441
+ kind: 'ram-unavailable',
1442
+ reason: 'unproven-owner',
1443
+ detail: `${this.paths.mountpoint} has a legacy name-only marker; no lease, reclaim or detach admitted`,
1444
+ },
1445
+ };
1010
1446
  }
1011
- const [fs, names] = await Promise.all([statfs(this.paths.mountpoint), readdir(this.paths.mountpoint)]);
1447
+ let marker: unknown;
1448
+ try {
1449
+ marker = JSON.parse(markerText);
1450
+ } catch (error) {
1451
+ return failed('provenance', `malformed volume marker: ${errorText(error)}`);
1452
+ }
1453
+ if (
1454
+ !isRecord(marker) ||
1455
+ marker.version !== 1 ||
1456
+ marker.volumeName !== this.paths.volumeName ||
1457
+ marker.owner !== 'gateway' ||
1458
+ typeof marker.registryEntry !== 'string' ||
1459
+ !/^0x[0-9a-f]+$/.test(marker.registryEntry)
1460
+ ) {
1461
+ return failed('provenance', 'the marker is not version-1 gateway provenance for this volume');
1462
+ }
1463
+ let root: BigIntStats;
1464
+ let parent: BigIntStats;
1465
+ let mark: BigIntStats;
1466
+ let names: string[];
1467
+ try {
1468
+ [root, parent, mark] = await Promise.all([
1469
+ stat(this.paths.mountpoint, { bigint: true }),
1470
+ stat(join(this.paths.mountpoint, '..'), { bigint: true }),
1471
+ lstat(markerPath, { bigint: true }),
1472
+ ]);
1473
+ names = await readdir(this.paths.mountpoint);
1474
+ } catch (error) {
1475
+ if (errorCode(error) === 'EPERM') return denied(this.paths.mountpoint, error);
1476
+ // The marker was read, then the volume went: the last release detaches it outside the lock, and its mountpoint
1477
+ // with it. What is mounted now is nothing, as when the marker is not there to read.
1478
+ if (errorCode(error) === 'ENOENT') return { ok: true, value: null };
1479
+ throw error;
1480
+ }
1481
+ if (root.dev === parent.dev || !mark.isFile())
1482
+ return failed('provenance', 'gateway marker is not on a separately mounted RAM volume');
1483
+ const rootIdentity = `root ${root.dev}:${root.ino}:${root.birthtimeNs}`;
1484
+ const registry = `registry ${marker.registryEntry}`;
1012
1485
  return {
1013
- capacity: fs.blocks * fs.bsize,
1014
- key: [
1015
- `root ${root.dev}:${root.ino}:${root.birthtimeNs}`,
1016
- `marker ${mark.dev}:${mark.ino}:${mark.birthtimeNs}:${mark.ctimeNs}`,
1017
- ].join(' '),
1018
- device: Number(root.dev),
1019
- leases: names.filter((name) => LEASE_NAME.test(name)),
1486
+ ok: true,
1487
+ value: {
1488
+ registryEntry: marker.registryEntry,
1489
+ key: [rootIdentity, `marker ${mark.dev}:${mark.ino}:${mark.birthtimeNs}:${mark.ctimeNs}`, registry].join(' '),
1490
+ attach: `${rootIdentity} ${registry}`,
1491
+ device: Number(root.dev),
1492
+ leases: names.filter((name) => LEASE_NAME.test(name)),
1493
+ },
1020
1494
  };
1021
1495
  }
1022
1496
 
1497
+ /** Prove this immutable marker belongs to the exact live attachment, outside the lock. */
1498
+ private async validateProvenance(volume: MountedVolume): Promise<Result<void, RamTempError>> {
1499
+ const registry = await this.commands.run('/usr/sbin/ioreg', ['-r', '-c', 'IOHDIXHDDriveOutKernel', '-l', '-w0']);
1500
+ const mounts = await this.commands.run('/sbin/mount', []);
1501
+ if (registry.status !== 0 || mounts.status !== 0)
1502
+ return failed('provenance', commandText(registry.status !== 0 ? registry : mounts));
1503
+ const parsed = ramDisksIn(registry.stdout, mounts.stdout);
1504
+ if (!parsed.ok) return failed('provenance', parsed.error);
1505
+ const disk = parsed.value.find((candidate) => candidate.entry === volume.registryEntry);
1506
+ return disk !== undefined &&
1507
+ disk.physical !== null &&
1508
+ disk.uid === this.paths.uid &&
1509
+ disk.sectors === this.sectors &&
1510
+ disk.mountpoints.includes(this.paths.mountpoint)
1511
+ ? { ok: true, value: undefined }
1512
+ : failed(
1513
+ 'provenance',
1514
+ `recorded registry entry ${volume.registryEntry} no longer names this mounted volume; no lease or detach admitted`,
1515
+ );
1516
+ }
1517
+
1518
+ /** Capture only the exact whole disk this attach answered, before any filesystem mutation. */
1519
+ private async attachedIdentity(physical: string): Promise<Result<AttachedRamDisk, ProvisionFailed>> {
1520
+ const registry = await this.commands.run('/usr/sbin/ioreg', ['-r', '-c', 'IOHDIXHDDriveOutKernel', '-l', '-w0']);
1521
+ if (registry.status !== 0) return failed('attach identity', commandText(registry));
1522
+ const parsed = ramDisksIn(registry.stdout, '');
1523
+ if (!parsed.ok) return failed('attach identity', parsed.error);
1524
+ const matches = parsed.value.filter((disk) => disk.physical === physical);
1525
+ const [disk] = matches;
1526
+ return matches.length === 1 &&
1527
+ disk !== undefined &&
1528
+ disk.physical !== null &&
1529
+ disk.uid === this.paths.uid &&
1530
+ disk.sectors === this.sectors
1531
+ ? { ok: true, value: { ...disk, physical: disk.physical } }
1532
+ : failed(
1533
+ 'attach identity',
1534
+ `${physical} is not the unique registry identity of this gateway attach; no provisioning or guessed detach`,
1535
+ );
1536
+ }
1537
+
1023
1538
  /**
1024
1539
  * Under the lock: claim `own`, the caller's ending lease if any, and every dead lease no other
1025
1540
  * caller is settling. A dead lease whose cached verdict still validates is named held and left
1026
1541
  * unclaimed: that proof costs `lstat` calls, not a host-wide probe, so no caller waits on it.
1027
1542
  */
1028
- private async claim(ledger: Ledger, volume: MountedVolume, owner: ClaimOwner, own: string | null): Promise<Claimed> {
1543
+ private async claim(
1544
+ ledger: Ledger,
1545
+ volume: MountedVolume,
1546
+ owner: ClaimOwner,
1547
+ own: string | null,
1548
+ keepOwn: boolean,
1549
+ ): Promise<Claimed> {
1029
1550
  const held: HeldLease[] = [];
1030
1551
  const candidates: Candidate[] = [];
1031
1552
  const claims = [...ledger.claims];
@@ -1056,21 +1577,21 @@ export class RamTempVolume {
1056
1577
  verdicts = verdicts.filter((entry) => entry !== cached);
1057
1578
  }
1058
1579
  claims.push({ name, identity, owner });
1059
- candidates.push({ name, directory, identity, own: name === own });
1580
+ candidates.push({ name, directory, identity, own: name === own, keep: name !== own || keepOwn });
1060
1581
  }
1061
1582
  return { ledger: { ...ledger, claims, held: verdicts }, held, candidates };
1062
1583
  }
1063
1584
 
1064
1585
  /**
1065
- * Outside the lock: settle the leases this caller claimed. The processes every dead one still
1066
- * runs are stopped first, and only then is the pass's one inventory read, so no inventory older
1067
- * than a lease's settled census approves its removal. Anything attached from below a lease keeps
1068
- * it: an image backed by a file there would be left pinned to a deleted file, and detaching it
1069
- * here would race the owner that releases it under its own lease; a mount there is backed
1070
- * elsewhere — a cowshed workspace adopted from a fixture checkout, say — and `rm -r` would
1586
+ * Outside the lock: settle the leases this caller claimed. Every dead one's recorded subtree is
1587
+ * handed back to the supervisor first, and only then is the pass's one inventory read, so no
1588
+ * inventory older than a lease's retirement approves its removal. Anything attached from below a
1589
+ * lease keeps it: an image backed by a file there would be left pinned to a deleted file, and
1590
+ * detaching it here would race the owner that releases it under its own lease; a mount there is
1591
+ * backed elsewhere — a cowshed workspace adopted from a fixture checkout, say — and `rm -r` would
1071
1592
  * delete its contents through the mount. A kept lease gets a verdict to publish, when its
1072
- * holders have cheap lifetime keys. A lease nothing holds is removed once the lock confirms it
1073
- * is as claimed.
1593
+ * holders have cheap lifetime keys. A lease nothing holds is reclaimed once the lock confirms it
1594
+ * is as claimed: a kept one's scratch is renamed into the archive (`retain`), any other deleted.
1074
1595
  */
1075
1596
  private async settle(
1076
1597
  op: Operation,
@@ -1078,25 +1599,60 @@ export class RamTempVolume {
1078
1599
  candidates: readonly Candidate[],
1079
1600
  ): Promise<Result<Settled, LockedError>> {
1080
1601
  if (candidates.length === 0) {
1081
- return { ok: true, value: { held: [], reaped: [], verdicts: [] } };
1602
+ return { ok: true, value: { held: [], reaped: [], gaps: [], retained: [], verdicts: [] } };
1082
1603
  }
1083
1604
  const reaped: string[] = [];
1605
+ const gaps: string[] = [];
1606
+ const held: HeldLease[] = [];
1084
1607
  for (const candidate of candidates) {
1085
- // Its task is gone, so what works in it is what that task left: stopped before the lease is
1086
- // removed, even where the removal is refused below. An empty lease is asked too: a leftover
1087
- // that has not written yet writes once it runs again. A task reaps its own (`reap`).
1088
- if (!candidate.own) {
1089
- reaped.push(...(await this.processes.stopWorkingIn(candidate.directory)));
1608
+ // A task retires its own subtree before it releases; a dead one could not. Its subtree is the
1609
+ // supervisor's to end, named by the handle the task recorded — never by who works in the lease
1610
+ // (specs/cowshed/07_api.md, `JobSubtreeHandle`). A lease with no readable handle recorded none
1611
+ // to retire: its task died before its command was admitted, or that admission was refused.
1612
+ if (candidate.own) {
1613
+ continue;
1614
+ }
1615
+ const recorded = await readFile(subtreeRecordPath(candidate.directory), 'utf8').catch((error: unknown) => {
1616
+ if (errorCode(error) === 'ENOENT') return null;
1617
+ throw error;
1618
+ });
1619
+ const handle = recorded === null ? null : parseHandle(recorded);
1620
+ if (handle === null) {
1621
+ continue;
1622
+ }
1623
+ const retired = await op.subtrees.retire(handle, LEFTOVER_GRACE_MS);
1624
+ switch (retired.kind) {
1625
+ case 'retired':
1626
+ reaped.push(...retired.signalled.map(describeSignalled));
1627
+ if (retired.signalledIncomplete) {
1628
+ gaps.push(`${candidate.directory}: the supervisor may have ended processes it could not name`);
1629
+ }
1630
+ gaps.push(...retired.gaps.map((gap) => `${candidate.directory}: ${describeCoverageGap(gap)}`));
1631
+ break;
1632
+ case 'refused':
1633
+ // An ended job's supervisor retired its whole tree as it ended, and a spent handle was
1634
+ // already retired: either way nothing of that subtree is left to end.
1635
+ if (retired.reason !== 'jobEnded' && retired.reason !== 'spentHandle') {
1636
+ held.push({
1637
+ name: candidate.name,
1638
+ 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`,
1639
+ });
1640
+ }
1641
+ break;
1642
+ case 'failed':
1643
+ return failed('retire', `${candidate.directory}: ${retired.detail}`);
1090
1644
  }
1091
1645
  }
1092
1646
  const inventory = await this.readInventory();
1093
1647
  if (!inventory.ok) {
1094
1648
  return inventory;
1095
1649
  }
1096
- const held: HeldLease[] = [];
1097
1650
  const verdicts: HeldEntry[] = [];
1098
1651
  const removable: Candidate[] = [];
1099
1652
  for (const candidate of candidates) {
1653
+ if (held.some((lease) => lease.name === candidate.name)) {
1654
+ continue;
1655
+ }
1100
1656
  const below = candidatesBelow(inventory.value, `${candidate.directory}/`);
1101
1657
  if (below.length === 0) {
1102
1658
  removable.push(candidate);
@@ -1110,6 +1666,7 @@ export class RamTempVolume {
1110
1666
  verdicts.push({ lease: candidate.name, verdict: captured.value });
1111
1667
  }
1112
1668
  }
1669
+ const archived: Archived[] = [];
1113
1670
  if (removable.length > 0) {
1114
1671
  const confirmed = await this.locked(
1115
1672
  op,
@@ -1123,13 +1680,100 @@ export class RamTempVolume {
1123
1680
  return confirmed;
1124
1681
  }
1125
1682
  for (const candidate of confirmed.value) {
1683
+ // Its subtree was retired above, or had ended: the handle beside the lease is spent either way.
1684
+ await rm(subtreeRecordPath(candidate.directory), { force: true });
1685
+ if (candidate.keep) {
1686
+ // One rename on the volume: the scratch stays whole and readable, and nothing waits on a deletion.
1687
+ const archive = `${String(Date.now()).padStart(13, '0')}-${candidate.name}`;
1688
+ await mkdir(join(this.paths.mountpoint, ARCHIVE_DIR), { recursive: true, mode: 0o700 });
1689
+ await rename(candidate.directory, join(this.paths.mountpoint, ARCHIVE_DIR, archive));
1690
+ archived.push({ directory: candidate.directory, archive });
1691
+ continue;
1692
+ }
1126
1693
  // Nothing holds the lease, so its directories may be made removable first: `rm -r` cannot
1127
1694
  // empty a readonly one. Only this volume's device is changed (see prepareForRemoval).
1128
1695
  await prepareForRemoval(candidate.directory, volume.device);
1129
1696
  await rm(candidate.directory, { recursive: true, force: true });
1130
1697
  }
1131
1698
  }
1132
- return { ok: true, value: { held, reaped, verdicts } };
1699
+ const retained = archived.length === 0 ? [] : await this.retain(volume, archived);
1700
+ return { ok: true, value: { held, reaped, gaps, retained, verdicts } };
1701
+ }
1702
+
1703
+ /**
1704
+ * Keep the newest {@link ARCHIVES_KEPT} archives while at least {@link ARCHIVE_FLOOR_SHARE} of the volume is free, and
1705
+ * none below that; rename every other one out of the archive and delete it in the background. Answers, for each lease
1706
+ * just archived, where its scratch is kept or why it was not. The floor is read once, here, as an archive arrives.
1707
+ */
1708
+ private async retain(volume: MountedVolume, archived: readonly Archived[]): Promise<string[]> {
1709
+ const root = join(this.paths.mountpoint, ARCHIVE_DIR);
1710
+ const [fs, names] = await Promise.all([statfs(this.paths.mountpoint), readdir(root)]);
1711
+ const freeBytes = fs.bavail * fs.bsize;
1712
+ const floorBytes = Math.ceil(fs.blocks * fs.bsize * ARCHIVE_FLOOR_SHARE);
1713
+ const archives = names.filter((name) => ARCHIVE_NAME.test(name)).sort();
1714
+ const kept = freeBytes < floorBytes ? [] : archives.slice(-ARCHIVES_KEPT);
1715
+ await mkdir(join(root, DELETING_DIR), { recursive: true, mode: 0o700 });
1716
+ for (const name of archives.filter((candidate) => !kept.includes(candidate))) {
1717
+ await rename(join(root, name), join(root, DELETING_DIR, `${this.pid}-${name}`)).catch((error: unknown) => {
1718
+ // Another caller's retention renamed it first, and deletes it.
1719
+ if (errorCode(error) !== 'ENOENT') throw error;
1720
+ });
1721
+ }
1722
+ this.deleteArchives(volume.device);
1723
+ return archived.map(({ directory, archive }) =>
1724
+ kept.includes(archive)
1725
+ ? `${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`
1726
+ : freeBytes < floorBytes
1727
+ ? `${directory} deleted: the volume has ${Math.round(freeBytes / MIB)} MiB free, below the ${Math.round(floorBytes / MIB)} MiB under which it keeps no archive`
1728
+ : `${directory} deleted: ${ARCHIVES_KEPT} newer archives are kept`,
1729
+ );
1730
+ }
1731
+
1732
+ /**
1733
+ * Queue the deletion of the archives this process renamed out, and of any a dead deleter left, behind this process's
1734
+ * earlier ones. Nothing waits for it. A failure is said on stderr and leaves its entry for the next deleter.
1735
+ */
1736
+ private deleteArchives(device: number): void {
1737
+ archiveDeletion = archiveDeletion.then(() =>
1738
+ this.emptyDeleting(device).catch((error: unknown) => {
1739
+ process.stderr.write(
1740
+ `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`,
1741
+ );
1742
+ }),
1743
+ );
1744
+ }
1745
+
1746
+ private async emptyDeleting(device: number): Promise<void> {
1747
+ const root = join(this.paths.mountpoint, ARCHIVE_DIR, DELETING_DIR);
1748
+ const names = await readdir(root).catch((error: unknown) => {
1749
+ if (errorCode(error) === 'ENOENT') return [];
1750
+ throw error;
1751
+ });
1752
+ for (const name of names) {
1753
+ const claim = DELETING_NAME.exec(name);
1754
+ if (claim === null) {
1755
+ process.stderr.write(`RAM temp volume: ${join(root, name)} is no archive being deleted; left as it is\n`);
1756
+ continue;
1757
+ }
1758
+ let entry = join(root, name);
1759
+ const deleter = Number(claim[1]);
1760
+ if (deleter !== this.pid) {
1761
+ if (this.isAlive(deleter)) continue;
1762
+ const mine = join(root, `${this.pid}-${claim[2]}`);
1763
+ const taken = await rename(entry, mine).then(
1764
+ () => true,
1765
+ (error: unknown) => {
1766
+ if (errorCode(error) === 'ENOENT') return false;
1767
+ throw error;
1768
+ },
1769
+ );
1770
+ if (!taken) continue;
1771
+ entry = mine;
1772
+ }
1773
+ // An archive keeps its lease's modes, so a readonly directory in it is made removable first (see prepareForRemoval).
1774
+ await prepareForRemoval(entry, device);
1775
+ await rm(entry, { recursive: true, force: true });
1776
+ }
1133
1777
  }
1134
1778
 
1135
1779
  /**
@@ -1154,56 +1798,114 @@ export class RamTempVolume {
1154
1798
  return confirmed;
1155
1799
  }
1156
1800
 
1157
- /** Detach what earlier creators left, then attach and provision the volume. */
1158
- private async provisionVolume(): Promise<Result<void, RamTempError>> {
1159
- const strays = await this.reclaimStrays(this.holdersPass());
1160
- if (!strays.ok) {
1161
- return strays;
1801
+ /** Check the root the volume mounts below, detach what earlier creators left, then attach and provision the volume. */
1802
+ private async provisionVolume(op: Operation): Promise<Result<void, RamTempError>> {
1803
+ try {
1804
+ const [root, parent] = await Promise.all([stat(this.paths.mountpoint), stat(join(this.paths.mountpoint, '..'))]);
1805
+ if (root.dev === parent.dev && (await readdir(this.paths.mountpoint)).length !== 0) {
1806
+ return {
1807
+ ok: false,
1808
+ error: {
1809
+ kind: 'ram-unavailable',
1810
+ reason: 'unproven-owner',
1811
+ detail: `${this.paths.mountpoint} is an unmounted directory with unowned contents; nothing removed or hidden by a new mount`,
1812
+ },
1813
+ };
1814
+ }
1815
+ } catch (error) {
1816
+ if (errorCode(error) !== 'ENOENT') return failed('provenance', errorText(error));
1162
1817
  }
1163
- const attached = await this.commands.run('/usr/bin/hdiutil', ['attach', '-nomount', `ram://${this.sectors}`]);
1164
- if (attached.status !== 0) {
1165
- // A deadlined attach took its helper's process group down with it; one that attached
1166
- // regardless is a stray the next creator detaches.
1167
- return failed('hdiutil attach', commandText(attached));
1818
+ const root = await rootReadiness(this.paths);
1819
+ if (!root.ok) {
1820
+ return root;
1168
1821
  }
1169
- const physical = /^(\/dev\/disk\d+)\b/.exec(attached.stdout)?.[1];
1170
- if (!physical) {
1171
- return failed('hdiutil attach', `no device in: ${attached.stdout.trim()}`);
1822
+ const strays = await this.reclaimStrays(op, this.holdersPass());
1823
+ if (!strays.ok) {
1824
+ return strays;
1172
1825
  }
1173
- const provisioned = await this.provision(physical);
1174
- if (provisioned.ok) {
1175
- return provisioned;
1826
+ const attached = await this.commands.attachRam(this.sectors);
1827
+ if (!attached.ok) {
1828
+ // An attach whose answer never came may still finish; this caller closed its lease, so the gateway detaches it.
1829
+ return typeof attached.error === 'string'
1830
+ ? failed('ram-lease', attached.error)
1831
+ : { ok: false, error: attached.error };
1832
+ }
1833
+ // Every path from here ends the lease: kept once the volume is mounted and marked at its mountpoint, released on
1834
+ // any failure or throw before that.
1835
+ const lease = attached.value;
1836
+ const kept = await this.provisionAndKeep(op, lease).catch((error: unknown) =>
1837
+ failed<void>('provision', errorText(error)),
1838
+ );
1839
+ return kept.ok ? kept : this.rollBack(op, lease, kept.error);
1840
+ }
1841
+
1842
+ /**
1843
+ * Provision the leased disk, record it in the ledger as the kept volume's disk, and keep it once its volume is mounted
1844
+ * and marked at its mountpoint. A record whose keep then fails names a disk the rollback detaches.
1845
+ */
1846
+ private async provisionAndKeep(op: Operation, lease: RamDiskLease): Promise<Result<void, ProvisionFailed>> {
1847
+ const identity = await this.attachedIdentity(lease.device);
1848
+ if (!identity.ok) return identity;
1849
+ const entry = identity.value.entry;
1850
+ const provisioned = await this.provision(lease.device, entry);
1851
+ if (!provisioned.ok) return provisioned;
1852
+ const recorded = await this.locked(op, 'ram-lease keep', async (ledger) => ({
1853
+ ledger: { ...ledger, kept: entry },
1854
+ value: undefined,
1855
+ }));
1856
+ if (!recorded.ok) {
1857
+ return failed(
1858
+ 'ram-lease keep',
1859
+ recorded.error.kind === 'lock-denied' ? recorded.error.detail : describeRamTempError(recorded.error),
1860
+ );
1176
1861
  }
1177
- const detached = await this.commands.run('/usr/bin/hdiutil', ['detach', '-force', physical]);
1178
- // The detach takes every volume of the disk with it. What it leaves at the staging path is a bare
1179
- // directory on the host's Data volume: removed here, and already absent is done.
1862
+ const kept = await lease.keep();
1863
+ return kept.ok ? kept : failed('ram-lease keep', kept.error);
1864
+ }
1865
+
1866
+ /**
1867
+ * End the lease of a volume that failed. The gateway detaches the disk on release, by its registry entry and without
1868
+ * force, so a busy owned staging volume is retained. A lease lost to a gateway restart answers no release: this caller
1869
+ * then detaches the exact disk itself, under its ledger's custody, so no later lease is admitted on a disk the next
1870
+ * gateway's startup scan removes.
1871
+ */
1872
+ private async rollBack(
1873
+ op: Operation,
1874
+ lease: RamDiskLease,
1875
+ failure: ProvisionFailed,
1876
+ ): Promise<Result<never, ProvisionFailed>> {
1877
+ const released = await lease.release();
1878
+ const lost = released.ok ? [] : [released.error];
1879
+ const command = released.ok ? released : await this.runDetach(op, lease.device, lease.registryEntry);
1880
+ if (!command.ok)
1881
+ return failed(failure.step, [failure.detail, ...lost, describeRamTempError(command.error)].join('; '));
1882
+ const detached = command.value;
1883
+ if (detached.pending !== undefined) {
1884
+ return failed(failure.step, [failure.detail, ...lost, commandText(detached)].join('; '));
1885
+ }
1886
+ // The detach takes every volume of the disk with it. What it leaves at the staging directory and the
1887
+ // mountpoint is a bare directory on the host's Data volume each: removed here, and already absent is done.
1180
1888
  const detachFailure =
1181
1889
  detached.status === 0
1182
- ? null
1183
- : `hdiutil detach -force ${physical} then failed (${commandText(detached)}), so it stays attached until the next creator reclaims it`;
1184
- const stagingFailure = await rmdir(this.paths.staging).then(
1185
- () => null,
1186
- (error: unknown) =>
1187
- errorCode(error) === 'ENOENT' ? null : `rmdir ${this.paths.staging} then failed (${errorText(error)})`,
1188
- );
1189
- const failures = [detachFailure, stagingFailure].filter((failure): failure is string => failure !== null);
1190
- return failures.length === 0
1191
- ? provisioned
1192
- : failed(provisioned.error.step, [provisioned.error.detail, ...failures].join('; '));
1890
+ ? []
1891
+ : [`gateway detach ${lease.device} then failed (${commandText(detached)}); owned staging is retained`];
1892
+ const directoryFailures =
1893
+ detached.status === 0 ? await removeMountDirectories([this.paths.staging, this.paths.mountpoint]) : [];
1894
+ return failed(failure.step, [failure.detail, ...lost, ...detachFailure, ...directoryFailures].join('; '));
1193
1895
  }
1194
1896
 
1195
1897
  /**
1196
1898
  * Create the volume under its final name, mount it with `mount_apfs` at the private staging
1197
- * directory, and mark it there. Then `umount` that private mount and let `diskutil mount` place
1198
- * the volume at the mountpoint: the only call that does, and it runs after the marker, so the
1199
- * volume never reaches `/Volumes` unmarked. Nothing is renamed (see the module comment). The
1200
- * staging mount is the kernel's, so the kernel releases it: a Disk Arbitration unmount waits in
1201
- * its one queue behind its own probe of the fresh RAM disk (5.1 s for the `zfs` probe alone in
1202
- * `log stream`; 6.5–6.7 s per unmount against 64–69 ms for `umount`, measured 2026-10-15). A
1203
- * crash before the final mount leaves the volume attached at the staging directory or
1204
- * unmounted; the next creator's reclaim detaches either.
1899
+ * directory, and mark it there. Then `umount` that private mount and mount the volume with
1900
+ * `mount_apfs` again at the mountpoint, after the marker, so the volume never reaches the
1901
+ * mountpoint unmarked. Nothing is renamed (see the module comment). The staging mount is the
1902
+ * kernel's, so the kernel releases it: a Disk Arbitration unmount waits in its one queue behind
1903
+ * its own probe of the fresh RAM disk (5.1 s for the `zfs` probe alone in `log stream`;
1904
+ * 6.5–6.7 s per unmount against 64–69 ms for `umount`, measured 2026-10-15). A crash before
1905
+ * the final mount leaves the volume attached at the staging directory or unmounted; the next
1906
+ * creator's reclaim detaches either.
1205
1907
  */
1206
- private async provision(physical: string): Promise<Result<void, ProvisionFailed>> {
1908
+ private async provision(physical: string, registryEntry: string): Promise<Result<void, ProvisionFailed>> {
1207
1909
  const container = await this.commands.run('/usr/sbin/diskutil', ['apfs', 'createContainer', physical]);
1208
1910
  const containerDisk = operationDisk(container.stdout);
1209
1911
  if (container.status !== 0 || !containerDisk) {
@@ -1237,7 +1939,13 @@ export class RamTempVolume {
1237
1939
  return atStaging;
1238
1940
  }
1239
1941
  try {
1240
- await writeFile(join(staging, MARKER_FILE), `${this.paths.volumeName}\n`);
1942
+ const marker: GatewayVolumeMarker = {
1943
+ version: 1,
1944
+ volumeName: this.paths.volumeName,
1945
+ owner: 'gateway',
1946
+ registryEntry,
1947
+ };
1948
+ await writeFile(join(staging, MARKER_FILE), `${JSON.stringify(marker)}\n`);
1241
1949
  } catch (error) {
1242
1950
  return failed('marker', errorText(error));
1243
1951
  }
@@ -1245,13 +1953,23 @@ export class RamTempVolume {
1245
1953
  if (unmounted.status !== 0) {
1246
1954
  return failed('umount (staging)', commandText(unmounted));
1247
1955
  }
1248
- // No -mountPoint: DiskArbitration names the mountpoint after the volume, and appends " 1" when a
1249
- // /Volumes entry already holds the name.
1250
- const placing = await this.commands.run('/usr/sbin/diskutil', ['mount', '-mountOptions', 'nobrowse', volume]);
1956
+ // `mount_apfs` mounts at a directory of this module's choosing without authorization; `diskutil mount
1957
+ // -mountPoint` raised an administrator dialog (see the module comment).
1958
+ try {
1959
+ await mkdir(this.paths.mountpoint, { recursive: true, mode: 0o700 });
1960
+ } catch (error) {
1961
+ return failed('mountpoint directory', errorText(error));
1962
+ }
1963
+ const placing = await this.commands.run('/sbin/mount_apfs', [
1964
+ '-o',
1965
+ 'nobrowse,noowners',
1966
+ `/dev/${volume}`,
1967
+ this.paths.mountpoint,
1968
+ ]);
1251
1969
  if (placing.status !== 0) {
1252
- return failed('diskutil mount', commandText(placing));
1970
+ return failed('mount_apfs (mountpoint)', commandText(placing));
1253
1971
  }
1254
- const placed = await this.expectMounted(volume, this.paths.mountpoint, 'diskutil mount');
1972
+ const placed = await this.expectMounted(volume, this.paths.mountpoint, 'mount_apfs (mountpoint)');
1255
1973
  if (!placed.ok) {
1256
1974
  return placed;
1257
1975
  }
@@ -1274,32 +1992,81 @@ export class RamTempVolume {
1274
1992
  : failed(step, `${volume} mounted at ${point ?? 'nowhere'}, expected ${expected}`);
1275
1993
  }
1276
1994
 
1277
- /** This module's RAM disks attached on the host: this user's, of this volume's exact size, mounted nowhere else. */
1278
- private async attached(): Promise<Result<RamDisk[], ProvisionFailed>> {
1279
- const info = await this.commands.run('/usr/bin/hdiutil', ['info']);
1280
- if (info.status !== 0) {
1281
- return failed('hdiutil info', commandText(info));
1995
+ /**
1996
+ * This volume's RAM disks attached on the host, read from the I/O Registry, which omits no attached disk: the ones
1997
+ * `volumeDisks` names. A RAM disk of this user and size that is not this volume's, another volume's, a test's, or an
1998
+ * unformatted one nothing recorded, is not its to inventory or detach, and is ignored. One of its own still
1999
+ * publishing its media is named, never passed over.
2000
+ */
2001
+ private async attached(): Promise<Result<AttachedRamDisk[], RamTempError>> {
2002
+ const registry = await this.commands.run('/usr/sbin/ioreg', ['-r', '-c', 'IOHDIXHDDriveOutKernel', '-l', '-w0']);
2003
+ if (registry.status !== 0) {
2004
+ return failed('ioreg (RAM disks)', commandText(registry));
1282
2005
  }
1283
- const ours = (point: string) => {
1284
- // DiskArbitration's " 1" suffix: a volume that found its name taken.
1285
- const name = point.replace(/ \d+$/, '');
1286
- // hdiutil lists a mount by the kernel's path; `staging` is written as that path, so it compares exactly.
1287
- return name === this.paths.mountpoint || name === this.paths.staging;
1288
- };
2006
+ const table = await this.commands.run('/sbin/mount', []);
2007
+ if (table.status !== 0) {
2008
+ return failed('mount (mount table)', commandText(table));
2009
+ }
2010
+ const disks = ramDisksIn(registry.stdout, table.stdout);
2011
+ if (!disks.ok) {
2012
+ return failed('ioreg (RAM disks)', disks.error);
2013
+ }
2014
+ const custody = await this.custody();
2015
+ if (!custody.ok) {
2016
+ return custody;
2017
+ }
2018
+ const attached: AttachedRamDisk[] = [];
2019
+ for (const disk of volumeDisks(
2020
+ disks.value,
2021
+ this.paths,
2022
+ this.sectors,
2023
+ (candidate) =>
2024
+ custody.value.has(candidate.entry) ||
2025
+ (candidate.physical !== null &&
2026
+ this.commands.ownsRamDisk?.({ ...candidate, physical: candidate.physical }) === true),
2027
+ )) {
2028
+ const { physical } = disk;
2029
+ if (physical === null) {
2030
+ return failed(
2031
+ 'ioreg (RAM disks)',
2032
+ `a RAM disk of uid ${disk.uid} with ${disk.sectors} sectors has published no media yet; look again once its attach settles`,
2033
+ );
2034
+ }
2035
+ attached.push({ ...disk, physical });
2036
+ }
2037
+ return { ok: true, value: attached };
2038
+ }
2039
+
2040
+ /**
2041
+ * The registry entries the ledger records: the one it keeps pending detach custody of, exact and published before the
2042
+ * spawn, and the disk whose volume a creator last kept.
2043
+ */
2044
+ private async custody(): Promise<Result<ReadonlySet<string>, RamTempError>> {
2045
+ const read = await this.readLedger();
2046
+ if (!read.ok) {
2047
+ return read;
2048
+ }
2049
+ const { lifecycle, kept } = read.value.ledger;
2050
+ const entry = lifecycle?.pending?.registryEntry;
1289
2051
  return {
1290
2052
  ok: true,
1291
- value: ramDisksIn(info.stdout).filter(
1292
- (disk) => disk.user === this.paths.user && disk.sectors === this.sectors && disk.mountpoints.every(ours),
1293
- ),
2053
+ value: new Set([...(entry === undefined || entry === null ? [] : [entry]), ...(kept === null ? [] : [kept])]),
1294
2054
  };
1295
2055
  }
1296
2056
 
1297
2057
  /**
1298
- * Detach what earlier creators left attached: no marked volume is mounted, so every RAM disk of
1299
- * this volume is debris — unformatted, staged, or mounted without its marker. One carrying a
1300
- * lease, or with anything attached below it, is still in use and stops the creation instead.
2058
+ * Detach what earlier creators left attached: no marked volume is mounted, so every RAM disk of this volume
2059
+ * (`attached`: by its exact name or its exact record) is debris — unformatted and recorded, staged, mounted
2060
+ * without its marker, or the kept volume's disk an operator's unmount left mounted nowhere. One carrying a lease, or
2061
+ * with anything attached below it, is still in use and stops the creation instead, and so does one its owner holds no
2062
+ * receipt for and its ledger does not record as kept: it is named, never detached.
1301
2063
  */
1302
- private async reclaimStrays(holders: Holders): Promise<Result<void, RamTempError>> {
2064
+ private async reclaimStrays(op: Operation, holders: Holders): Promise<Result<void, RamTempError>> {
2065
+ const read = await this.readLedger();
2066
+ if (!read.ok) {
2067
+ return read;
2068
+ }
2069
+ const { kept } = read.value.ledger;
1303
2070
  const strays = await this.attached();
1304
2071
  if (!strays.ok) {
1305
2072
  return strays;
@@ -1327,13 +2094,21 @@ export class RamTempVolume {
1327
2094
  return failed('reclaim', holdingText(point, held.value));
1328
2095
  }
1329
2096
  }
1330
- const detached = await this.commands.run(
1331
- '/usr/bin/hdiutil',
1332
- ['detach', '-force', disk.physical],
1333
- STRAY_DETACH_DEADLINE_MS,
1334
- );
1335
- if (detached.status !== 0) {
1336
- return failed(`hdiutil detach (stray ${disk.physical})`, commandText(detached));
2097
+ if (disk.entry !== kept && this.commands.ownsRamDisk?.(disk) !== true) {
2098
+ return {
2099
+ ok: false,
2100
+ error: {
2101
+ kind: 'ram-unavailable',
2102
+ reason: 'unproven-owner',
2103
+ detail: `${disk.physical} has no exact gateway creation receipt; no reclaim or detach admitted`,
2104
+ },
2105
+ };
2106
+ }
2107
+ const command = await this.runDetach(op, disk.physical, disk.entry);
2108
+ if (!command.ok) return command;
2109
+ const detached = detachOutcome(command.value, disk, `hdiutil detach (stray ${disk.physical})`);
2110
+ if (!detached.ok) {
2111
+ return detached;
1337
2112
  }
1338
2113
  }
1339
2114
  return { ok: true, value: undefined };
@@ -1361,7 +2136,7 @@ export class RamTempVolume {
1361
2136
  if (!disk) {
1362
2137
  return failed(
1363
2138
  'detach',
1364
- `hdiutil info lists no RAM disk of ${this.paths.user} with ${this.sectors} sectors mounted at ${this.paths.mountpoint}`,
2139
+ `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}`,
1365
2140
  );
1366
2141
  }
1367
2142
  const unchanged = await this.locked(
@@ -1382,15 +2157,17 @@ export class RamTempVolume {
1382
2157
  // A lease or another attach arrived despite the claim: the volume stays for it.
1383
2158
  return { ok: true, value: undefined };
1384
2159
  }
1385
- let detached = await this.commands.run('/usr/bin/hdiutil', ['detach', disk.physical]);
1386
- if (detached.status !== 0) {
1387
- detached = await this.commands.run('/usr/bin/hdiutil', ['detach', '-force', disk.physical]);
1388
- }
1389
- if (detached.status !== 0) {
1390
- return failed('hdiutil detach', commandText(detached));
2160
+ // Detaching frees the archives' pages anyway, but a deletion of this process's still walking the volume holds it busy.
2161
+ await archiveDeletions();
2162
+ const command = await this.runDetach(op, disk.physical, disk.entry);
2163
+ if (!command.ok) return command;
2164
+ const detached = detachOutcome(command.value, disk, 'hdiutil detach');
2165
+ if (!detached.ok) {
2166
+ return detached;
1391
2167
  }
1392
- // DiskArbitration removes the /Volumes directory it created when the volume goes.
1393
- return { ok: true, value: undefined };
2168
+ // No Disk Arbitration call made the mountpoint, so none removes it: this module does, now its volume is gone.
2169
+ const left = await removeMountDirectories([this.paths.mountpoint]);
2170
+ return left.length === 0 ? { ok: true, value: undefined } : failed('detach', left.join('; '));
1394
2171
  }
1395
2172
 
1396
2173
  /** The host's attachments as one pass reads them: one `ioreg` run and one `mount` run. */
@@ -1444,6 +2221,74 @@ function candidatesBelow(inventory: Inventory, prefix: string): HeldCandidate[]
1444
2221
  ];
1445
2222
  }
1446
2223
 
2224
+ /**
2225
+ * Whether the root is a directory its volume may mount below: the per-user root `cowshed setup` makes, or a test
2226
+ * namespace's directory its fixture made, each a directory, not a link, the user's, mode 0700. A link could place the
2227
+ * mount outside `/var/folders/`, where mds admits it, and another owner or mode exposes the volume.
2228
+ */
2229
+ async function rootReadiness(paths: RamTempPaths): Promise<Result<void, RamTempError>> {
2230
+ const unready = (detail: string): Result<void, RamTempError> => ({
2231
+ ok: false,
2232
+ error: { kind: 'root-unready', root: paths.root, detail },
2233
+ });
2234
+ let info: Stats;
2235
+ try {
2236
+ info = await lstat(paths.root);
2237
+ } catch (error) {
2238
+ return unready(errorCode(error) === 'ENOENT' ? 'is missing' : `cannot be read (${errorText(error)})`);
2239
+ }
2240
+ if (!info.isDirectory()) {
2241
+ return unready('is not a directory');
2242
+ }
2243
+ if (info.uid !== paths.uid) {
2244
+ return unready(`is owned by uid ${info.uid}, not ${paths.uid}`);
2245
+ }
2246
+ const mode = info.mode & 0o777;
2247
+ return mode === 0o700 ? { ok: true, value: undefined } : unready(`has mode ${mode.toString(8)}, not 700`);
2248
+ }
2249
+
2250
+ /**
2251
+ * Remove directories a volume was mounted on, once it is gone. `rmdir` removes only an empty directory, follows no
2252
+ * link and refuses one with a mount on it; already absent is done. Answers each failure.
2253
+ */
2254
+ async function removeMountDirectories(directories: readonly string[]): Promise<string[]> {
2255
+ const failures: string[] = [];
2256
+ for (const directory of directories) {
2257
+ try {
2258
+ await rmdir(directory);
2259
+ } catch (error) {
2260
+ if (errorCode(error) !== 'ENOENT') {
2261
+ failures.push(`rmdir ${directory} then failed (${errorText(error)})`);
2262
+ }
2263
+ }
2264
+ }
2265
+ return failures;
2266
+ }
2267
+
2268
+ /**
2269
+ * The volume one read found at the lease's mountpoint, while the lease is still on that attach of it; else why it is
2270
+ * not. Every lease's `TMPDIR` is a directory on one attach: once that attach is gone, the path is a bare directory on
2271
+ * the host's Data volume, or on a later attach, which a write through `TMPDIR` can make again.
2272
+ */
2273
+ function leaseOn(
2274
+ lease: RamTempLease,
2275
+ volume: MountedVolume | null,
2276
+ ): { readonly on: MountedVolume } | { readonly lost: string } {
2277
+ if (volume === null) {
2278
+ return {
2279
+ lost: `no marked volume is mounted at ${lease.mountpoint} any more: it was detached while the task held its lease`,
2280
+ };
2281
+ }
2282
+ if (volume.attach !== lease.attach) {
2283
+ return {
2284
+ 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`,
2285
+ };
2286
+ }
2287
+ return volume.leases.includes(basename(lease.directory))
2288
+ ? { on: volume }
2289
+ : { lost: `${lease.directory} is gone from the volume while the task held it` };
2290
+ }
2291
+
1447
2292
  /** The pid a lease directory is named after: whether its task is alive. */
1448
2293
  function leasePid(name: string): number {
1449
2294
  return Number(LEASE_NAME.exec(name)?.[1]);
@@ -1468,12 +2313,15 @@ function heldContext(volume: MountedVolume, name: string, identity: string): Hel
1468
2313
  }
1469
2314
 
1470
2315
  /**
1471
- * The ledger with the claims of dead owners voided, and the verdicts kept only for leases still on
1472
- * this attach of the volume. A claim's owner is judged as a lease's is, by its pid.
2316
+ * Dead callers void only claims without pending detach custody. A pending command's authority
2317
+ * survives every pid observation; verdicts still belong only to this attach of the volume.
1473
2318
  */
1474
2319
  function prune(ledger: Ledger, volume: MountedVolume | null, isAlive: (pid: number) => boolean): Ledger {
1475
2320
  return {
1476
- lifecycle: ledger.lifecycle !== null && isAlive(ledger.lifecycle.owner.pid) ? ledger.lifecycle : null,
2321
+ lifecycle:
2322
+ ledger.lifecycle !== null && (ledger.lifecycle.pending !== undefined || isAlive(ledger.lifecycle.owner.pid))
2323
+ ? ledger.lifecycle
2324
+ : null,
1477
2325
  claims: ledger.claims.filter((claim) => isAlive(claim.owner.pid)),
1478
2326
  held:
1479
2327
  volume === null
@@ -1481,14 +2329,26 @@ function prune(ledger: Ledger, volume: MountedVolume | null, isAlive: (pid: numb
1481
2329
  : ledger.held.filter(
1482
2330
  (entry) => entry.verdict.context.volumeKey === volume.key && volume.leases.includes(entry.lease),
1483
2331
  ),
2332
+ kept: ledger.kept,
1484
2333
  };
1485
2334
  }
1486
2335
 
2336
+ /** The operation token and registry incarnation, never a pid or reusable BSD name alone, identify a pending detach. */
2337
+ function sameDetach(claim: LifecycleClaim | null, owner: ClaimOwner, custody: DetachCustody): boolean {
2338
+ return (
2339
+ claim?.owner.token === owner.token &&
2340
+ claim.pending?.physical === custody.physical &&
2341
+ claim.pending.registryEntry === custody.registryEntry
2342
+ );
2343
+ }
2344
+
1487
2345
  function withoutClaimsOf(ledger: Ledger, owner: ClaimOwner): Ledger {
1488
2346
  return {
1489
- lifecycle: ledger.lifecycle?.owner.token === owner.token ? null : ledger.lifecycle,
2347
+ lifecycle:
2348
+ ledger.lifecycle?.owner.token === owner.token && ledger.lifecycle.pending === undefined ? null : ledger.lifecycle,
1490
2349
  claims: ledger.claims.filter((claim) => claim.owner.token !== owner.token),
1491
2350
  held: ledger.held,
2351
+ kept: ledger.kept,
1492
2352
  };
1493
2353
  }
1494
2354
 
@@ -1511,7 +2371,8 @@ function settledLedger(
1511
2371
 
1512
2372
  /** The ledger's wire form, version 1. */
1513
2373
  function ledgerText(ledger: Ledger): string {
1514
- return `${JSON.stringify({ version: 1, lifecycle: ledger.lifecycle, claims: ledger.claims, held: ledger.held })}\n`;
2374
+ // Older readers reject version 2 instead of pruning the pending authority by the caller's pid.
2375
+ 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`;
1515
2376
  }
1516
2377
 
1517
2378
  /** Publish the ledger in one rename, so no reader, and no crash, ever leaves half of it. */
@@ -1536,7 +2397,7 @@ async function publishLedger(path: string, text: string): Promise<void> {
1536
2397
  * so its lease is probed afresh; it never stands for a lease nothing holds.
1537
2398
  */
1538
2399
  function parseLedger(value: unknown): Ledger | undefined {
1539
- if (!isRecord(value) || value.version !== 1) {
2400
+ if (!isRecord(value) || (value.version !== 1 && value.version !== 2)) {
1540
2401
  return undefined;
1541
2402
  }
1542
2403
  const { lifecycle: lifecycleWire, claims: claimsWire, held: heldWire } = value;
@@ -1553,8 +2414,13 @@ function parseLedger(value: unknown): Ledger | undefined {
1553
2414
  if ((kind !== 'create' && kind !== 'detach') || owner === undefined) {
1554
2415
  return undefined;
1555
2416
  }
1556
- lifecycle = { kind, owner };
2417
+ const pending = lifecycleWire.pending === undefined ? undefined : parseDetachCustody(lifecycleWire.pending);
2418
+ if (lifecycleWire.pending !== undefined && pending === undefined) return undefined;
2419
+ lifecycle = pending === undefined ? { kind, owner } : { kind, owner, pending };
1557
2420
  }
2421
+ if ((value.version === 2) !== (lifecycle?.pending !== undefined)) return undefined;
2422
+ const keptWire = value.kept;
2423
+ if (keptWire !== undefined && (typeof keptWire !== 'string' || !/^0x[0-9a-f]+$/.test(keptWire))) return undefined;
1558
2424
  const claims: LeaseClaim[] = [];
1559
2425
  for (const entry of claimsWire) {
1560
2426
  if (!isRecord(entry)) {
@@ -1578,7 +2444,21 @@ function parseLedger(value: unknown): Ledger | undefined {
1578
2444
  held.push({ lease, verdict });
1579
2445
  }
1580
2446
  }
1581
- return { lifecycle, claims, held };
2447
+ return { lifecycle, claims, held, kept: keptWire ?? null };
2448
+ }
2449
+
2450
+ function parseDetachCustody(value: unknown): DetachCustody | undefined {
2451
+ if (!isRecord(value)) return undefined;
2452
+ const { physical, registryEntry, phase, facadePid } = value;
2453
+ if (
2454
+ (phase !== 'waiting' && phase !== 'reported') ||
2455
+ typeof physical !== 'string' ||
2456
+ !/^\/dev\/disk\d+$/.test(physical) ||
2457
+ (registryEntry !== null && (typeof registryEntry !== 'string' || !/^0x[0-9a-f]+$/.test(registryEntry))) ||
2458
+ (facadePid !== null && (typeof facadePid !== 'number' || !Number.isSafeInteger(facadePid) || facadePid <= 0))
2459
+ )
2460
+ return undefined;
2461
+ return { physical, registryEntry, phase, facadePid };
1582
2462
  }
1583
2463
 
1584
2464
  function parseOwner(value: unknown): ClaimOwner | undefined {
@@ -1604,8 +2484,12 @@ function alsoFailed(primary: RamTempError, cleanup: readonly RamTempError[]): Ra
1604
2484
  const after = `cleanup then failed: ${cleanup.map(describeRamTempError).join('; ')}`;
1605
2485
  switch (primary.kind) {
1606
2486
  case 'provision-failed':
2487
+ case 'ram-unavailable':
2488
+ case 'root-unready':
1607
2489
  return { ...primary, detail: `${primary.detail}; ${after}` };
1608
2490
  case 'volume-full':
2491
+ case 'lease-lost':
2492
+ case 'lease-path-budget':
1609
2493
  return { kind: 'provision-failed', step: 'cleanup', detail: `${describeRamTempError(primary)}; ${after}` };
1610
2494
  }
1611
2495
  }
@@ -1703,27 +2587,135 @@ export function operationDisk(stdout: string): string | null {
1703
2587
  }
1704
2588
 
1705
2589
  /**
1706
- * The RAM disks in `hdiutil info` output. Images are separated by a row of `=`; a RAM disk's
1707
- * `image-path` is `ram://<sectors>`, and its entity rows are `<dev>\t<content hint>\t<mountpoint>`,
1708
- * the whole disk first.
2590
+ * The RAM disks in `ioreg -r -c IOHDIXHDDriveOutKernel -l -w0` output, with the mounts `mount` output gives them. A RAM
2591
+ * disk is a legacy DiskImages device served by a diskimages-helper: each starts a `+-o IOHDIXHDDriveOutKernel` entry
2592
+ * whose own properties carry `image-path` <"ram://<sectors>"> and `owner-uid`, and the `BSD Name`s below it are its
2593
+ * whole disk first, then its APFS container and volumes; each volume node carries its `FullName` beside its `BSD Name`,
2594
+ * which is how a volume's name reaches its mounts. The registry is the kernel's record, and unlike `hdiutil info`,
2595
+ * which drops images while another attaches or detaches, it leaves out no attached disk. So an entry this cannot read
2596
+ * is an error, never a disk left out: a partial read must not stand for an absent disk.
1709
2597
  */
1710
- export function ramDisksIn(info: string): RamDisk[] {
2598
+ export function ramDisksIn(registry: string, table: string): Result<RamDisk[], string> {
2599
+ const mounted = new Map<string, string[]>();
2600
+ for (const [, device, point] of table.matchAll(/^\/dev\/(disk\d+(?:s\d+)*) on (.+) \([^)]*\)$/gm)) {
2601
+ if (device !== undefined && point !== undefined) {
2602
+ mounted.set(device, [...(mounted.get(device) ?? []), point]);
2603
+ }
2604
+ }
1711
2605
  const disks: RamDisk[] = [];
1712
- for (const block of info.split(/^=+$/m)) {
1713
- const sectors = /^image-path\s*:\s*ram:\/\/(\d+)\s*$/m.exec(block)?.[1];
1714
- const user = /^mounting user\s*:\s*(\S+)\s*$/m.exec(block)?.[1];
1715
- const entities = [...block.matchAll(/^(\/dev\/disk\d+(?:s\d+)*)\t[^\t\n]*(?:\t([^\n]*))?$/gm)];
1716
- const physical = entities[0]?.[1];
1717
- if (sectors === undefined || user === undefined || physical === undefined) {
2606
+ for (const entry of registry.split(/^(?=\+-o )/m)) {
2607
+ if (entry.trim() === '') {
1718
2608
  continue;
1719
2609
  }
1720
- const mountpoints = entities.flatMap((entity) => {
1721
- const point = entity[2]?.trimEnd();
1722
- return point ? [point] : [];
2610
+ const header = entry.slice(0, entry.indexOf('\n') === -1 ? undefined : entry.indexOf('\n'));
2611
+ const entryId = /<class IOHDIXHDDriveOutKernel, id (0x[0-9a-f]+),/.exec(header)?.[1];
2612
+ if (!header.startsWith('+-o ') || entryId === undefined) {
2613
+ return { ok: false, error: `not an IOHDIXHDDriveOutKernel entry: ${header.slice(0, 160)}` };
2614
+ }
2615
+ // The entry's own properties end at its first child; only they name its image and owner.
2616
+ const firstChild = entry.indexOf('+-o ', header.length);
2617
+ const own = entry.slice(header.length, firstChild === -1 ? undefined : firstChild);
2618
+ const imagePath = /"image-path" = <"([^"]*)">/.exec(own)?.[1];
2619
+ const owner = /"owner-uid" = (\d+)/.exec(own)?.[1];
2620
+ // Every node's property list closes before the next node: a read cut short leaves one open.
2621
+ const opened = entry.match(/^[| ]*\{\s*$/gm)?.length ?? 0;
2622
+ const closed = entry.match(/^[| ]*\}\s*$/gm)?.length ?? 0;
2623
+ if (opened === 0 || opened !== closed || imagePath === undefined || owner === undefined) {
2624
+ return {
2625
+ ok: false,
2626
+ error: `an incomplete entry (${opened} property lists opened, ${closed} closed${imagePath === undefined ? ', no image-path' : ''}${owner === undefined ? ', no owner-uid' : ''}): ${header.slice(0, 160)}`,
2627
+ };
2628
+ }
2629
+ const sectors = /^ram:\/\/(\d+)$/.exec(imagePath)?.[1];
2630
+ if (sectors === undefined) {
2631
+ // A file-backed legacy image, not a RAM disk.
2632
+ continue;
2633
+ }
2634
+ const names = [...entry.matchAll(/"BSD Name" = "(disk\d+(?:s\d+)*)"/g)].flatMap((match) =>
2635
+ match[1] === undefined ? [] : [match[1]],
2636
+ );
2637
+ const volumes: RamVolume[] = [];
2638
+ for (const node of entry.split(/^(?=[| ]*\+-o )/m)) {
2639
+ if (!/^[| ]*\+-o [^\n]*<class AppleAPFSVolume,/.test(node)) {
2640
+ continue;
2641
+ }
2642
+ const name = /^[| ]*"FullName" = "(.*)"[ \t]*$/m.exec(node)?.[1];
2643
+ const device = /"BSD Name" = "(disk\d+(?:s\d+)*)"/.exec(node)?.[1];
2644
+ if (name !== undefined) {
2645
+ volumes.push({ name, mountpoints: device === undefined ? [] : (mounted.get(device) ?? []) });
2646
+ }
2647
+ }
2648
+ disks.push({
2649
+ entry: entryId,
2650
+ physical: names[0] === undefined ? null : `/dev/${names[0]}`,
2651
+ sectors: Number(sectors),
2652
+ uid: Number(owner),
2653
+ mountpoints: names.flatMap((name) => mounted.get(name) ?? []),
2654
+ volumes,
1723
2655
  });
1724
- disks.push({ physical, sectors: Number(sectors), user, mountpoints });
1725
2656
  }
1726
- return disks;
2657
+ return { ok: true, value: disks };
2658
+ }
2659
+
2660
+ /**
2661
+ * 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
2662
+ * its exact size, mounts nowhere but at its mountpoint or staging directory, and either carries a volume called exactly
2663
+ * its name that is mounted, or is recorded: `recorded` says the disk's exact registry entry is one this volume's owner
2664
+ * holds a receipt or its ledger holds custody for, which covers an attach whose format never finished, or records as
2665
+ * the disk a creator kept, which covers a volume unmounted from under it. A disk's size and owner establish nothing, so
2666
+ * an unmounted disk of the same size that nothing recorded is not the volume's.
2667
+ */
2668
+ export function volumeDisks(
2669
+ disks: readonly RamDisk[],
2670
+ paths: Pick<RamTempPaths, 'uid' | 'mountpoint' | 'staging' | 'volumeName'>,
2671
+ sectors: number,
2672
+ recorded: (disk: RamDisk) => boolean,
2673
+ ): RamDisk[] {
2674
+ // The mount table lists a mount by the kernel's path; both paths are written as that path, so they compare exactly.
2675
+ const ours = (point: string) => point === paths.mountpoint || point === paths.staging;
2676
+ return disks.filter(
2677
+ (disk) =>
2678
+ disk.uid === paths.uid &&
2679
+ disk.sectors === sectors &&
2680
+ disk.mountpoints.every(ours) &&
2681
+ (disk.volumes.some((volume) => volume.name === paths.volumeName && volume.mountpoints.length > 0) ||
2682
+ recorded(disk)),
2683
+ );
2684
+ }
2685
+
2686
+ /**
2687
+ * Detach a RAM disk an inventory found, by its whole-disk name, bound to the registry entry the inventory read it as.
2688
+ * A BSD name passes to the next disk once its disk goes, and a detach can queue for the disk admission meanwhile, so
2689
+ * the gateway reads the entry again inside its own admission, immediately before it spawns `hdiutil`, and
2690
+ * refuses, detaching nothing, unless the entry still names this whole disk (specs/cowshed/06_cli.md, `--registry-entry`).
2691
+ * That refusal is this detach's failure, named, and never retried with `-force`: this process did not just attach the
2692
+ * disk. The window that remains is cowshed's, from its read to hdiutil's own open of the name.
2693
+ */
2694
+ export async function detachRamDisk(
2695
+ commands: Pick<HostCommands, 'detachRam'>,
2696
+ disk: AttachedRamDisk,
2697
+ step: string,
2698
+ ): Promise<Result<void, ProvisionFailed>> {
2699
+ const detached = await commands.detachRam(disk.physical, disk.entry);
2700
+ return detachOutcome(detached, disk, step);
2701
+ }
2702
+
2703
+ function detachOutcome(detached: CommandOutput, disk: AttachedRamDisk, step: string): Result<void, ProvisionFailed> {
2704
+ if (detached.status === 0) {
2705
+ return { ok: true, value: undefined };
2706
+ }
2707
+ // A cowshed wrapper exit (100–106) whose stderr says it refused: the entry no longer names the disk.
2708
+ const refused =
2709
+ detached.status >= 100 &&
2710
+ detached.status <= 106 &&
2711
+ detached.stderr.includes('refused') &&
2712
+ detached.stderr.includes('nothing was detached');
2713
+ return failed(
2714
+ step,
2715
+ refused
2716
+ ? `${disk.physical} not detached: its registry entry ${disk.entry} no longer names it (${commandText(detached)})`
2717
+ : commandText(detached),
2718
+ );
1727
2719
  }
1728
2720
 
1729
2721
  /**
@@ -1733,20 +2725,13 @@ export function ramDisksIn(info: string): RamDisk[] {
1733
2725
  */
1734
2726
  const HOST_COMMAND_DEADLINE_MS = 120_000;
1735
2727
 
1736
- /**
1737
- * How long one creator waits on a stray's detach before it reports the stray by name and
1738
- * gives the create claim back. A stray detach that makes no progress is DiskArbitration's
1739
- * wedge, not this volume's: at 120 s a chain of creators each waited the full bound on the
1740
- * same stray and the claim never moved. The detach itself is never killed (below); the
1741
- * bound is on the wait, and the next creator finds the stray gone or names it again.
1742
- */
1743
- const STRAY_DETACH_DEADLINE_MS = 30_000;
1744
-
1745
2728
  /** Disk tools delegate their lease and process lifetime to cowshed, with one image policy. */
1746
2729
  export function diskCommand(
1747
2730
  file: string,
1748
2731
  args: readonly string[],
1749
2732
  deadlineMs: number,
2733
+ binding?: DetachBinding,
2734
+ gatewaySocket?: string,
1750
2735
  ): { args: string[]; lifetime: 'stop-wait' | 'facade-owned' } | null {
1751
2736
  const program = basename(file);
1752
2737
  if (program !== 'hdiutil' && program !== 'diskutil') {
@@ -1754,21 +2739,16 @@ export function diskCommand(
1754
2739
  }
1755
2740
  // Match SystemCommandRunner's protected-image policy, including its case-sensitive verbs.
1756
2741
  const image = program === 'hdiutil' || args[0] === 'image' || args[0] === 'eject';
2742
+ const bound = binding === undefined ? [] : ['--registry-entry', binding.registryEntry];
2743
+ const gateway = gatewaySocket === undefined ? [] : ['--gateway-socket', gatewaySocket];
1757
2744
  return {
1758
2745
  args: image
1759
- ? ['disk-command', program, '--', ...args]
1760
- : ['disk-command', program, '--deadline-ms', String(deadlineMs), '--', ...args],
2746
+ ? ['disk-command', program, ...gateway, ...bound, '--', ...args]
2747
+ : ['disk-command', program, ...gateway, '--deadline-ms', String(deadlineMs), '--', ...args],
1761
2748
  lifetime: image ? 'stop-wait' : 'facade-owned',
1762
2749
  };
1763
2750
  }
1764
2751
 
1765
- /**
1766
- * The variable naming the cowshed executable that runs `cowshed disk-command`. Unset, it is the installed `cowshed`
1767
- * on PATH. A repository that tests its own cowshed sets it, on the targets that test it, to that checkout's build:
1768
- * an installed cowshed that predates a command its own checkout added would fail the very code under test.
1769
- */
1770
- export const COWSHED_EXECUTABLE_ENV = 'COWSHED_EXECUTABLE';
1771
-
1772
2752
  /** Whether this process already said the cowshed gateway is not there to lease disk commands. */
1773
2753
  let gatewayAbsenceSaid = false;
1774
2754
 
@@ -1789,17 +2769,28 @@ const predatesSeen = new Map<string, { at: number; what: 'leases' | 'alone' }>()
1789
2769
  * device until reboot. Never acquire a second lease around the facade. Other leased helpers
1790
2770
  * take their lease here. Recorded lease waits ask for `alone`; an older gateway is asked
1791
2771
  * shared at once, and for a minute after.
2772
+ *
2773
+ * `gatewaySocket` is the gateway every disk lease, facade admission and RAM attach and detach goes through. It has no
2774
+ * default: the caller names it. The Nx executor names the host's own, `GATEWAY_SOCKET`, which `disk-command` defaults
2775
+ * to, so the facade is not told of it and a cowshed that predates `--gateway-socket` still serves it. A host proof
2776
+ * names its fixture's, which the facade is told of.
1792
2777
  */
1793
2778
  export function createHostCommands(
2779
+ gatewaySocket: string,
1794
2780
  defaultDeadlineMs: number = HOST_COMMAND_DEADLINE_MS,
1795
- gatewaySocket: string = GATEWAY_SOCKET,
1796
2781
  wantedShare: PhaseShare = recordedShare(),
1797
2782
  cowshed = process.env[COWSHED_EXECUTABLE_ENV] ?? 'cowshed',
1798
2783
  ): HostCommands {
1799
2784
  return {
1800
- async run(file, args, callDeadlineMs) {
2785
+ async run(file, args, callDeadlineMs, binding) {
1801
2786
  const deadlineMs = callDeadlineMs ?? defaultDeadlineMs;
1802
- const disk = diskCommand(file, args, deadlineMs);
2787
+ const disk = diskCommand(
2788
+ file,
2789
+ args,
2790
+ deadlineMs,
2791
+ binding,
2792
+ gatewaySocket === GATEWAY_SOCKET ? undefined : gatewaySocket,
2793
+ );
1803
2794
  if (disk !== null) {
1804
2795
  return runBounded(cowshed, disk.args, deadlineMs, disk.lifetime);
1805
2796
  }
@@ -1834,6 +2825,12 @@ export function createHostCommands(
1834
2825
  }
1835
2826
  }
1836
2827
  },
2828
+ detachRam(device, registryEntry) {
2829
+ return detachGatewayRamDisk(gatewaySocket, device, registryEntry);
2830
+ },
2831
+ attachRam(sectors) {
2832
+ return attachRamDisk(gatewaySocket, sectors, defaultDeadlineMs);
2833
+ },
1837
2834
  };
1838
2835
  }
1839
2836
 
@@ -1853,26 +2850,36 @@ function runBounded(
1853
2850
  // reap and lease custody; a wrapper's exit or signal is not the disk child's exit or signal.
1854
2851
  const child = spawn(file, [...args], { detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
1855
2852
  const stdout: Buffer[] = [];
2853
+ let complete: ((output: CommandOutput | null) => void) | undefined;
2854
+ const completion =
2855
+ lifetime === 'stop-wait'
2856
+ ? new Promise<CommandOutput | null>((settled) => {
2857
+ complete = settled;
2858
+ })
2859
+ : null;
1856
2860
  const stderr: Buffer[] = [];
1857
2861
  child.stdout.on('data', (chunk: Buffer) => stdout.push(chunk));
1858
2862
  child.stderr.on('data', (chunk: Buffer) => stderr.push(chunk));
1859
2863
  const text = (chunks: Buffer[]) => Buffer.concat(chunks).toString('utf8');
1860
- // Safe disk commands have no Node timer: the CLI owns the total admission + child budget,
1861
- // kills only its owned safe child, and returns after reap. Protected image output is already
1862
- // file-backed in cowshed, so only that caller may close its pipes and stop waiting.
2864
+ // Set once the deadline has fired and is killing the group: from then on it owns the result.
2865
+ let timedOut = false;
2866
+ let stoppedWaiting = false;
2867
+ // Safe disk commands have no Node timer: the CLI owns admission, execution and reap.
2868
+ // Protected commands keep draining their pipes after stop-wait: closing a live facade's
2869
+ // output is not proof its native child ended, and must not manufacture an early exit.
1863
2870
  const timer =
1864
2871
  lifetime === 'facade-owned'
1865
2872
  ? undefined
1866
2873
  : setTimeout(() => {
1867
- if (lifetime === 'stop-wait') {
1868
- child.stdout.destroy();
1869
- child.stderr.destroy();
2874
+ if (completion !== null) {
2875
+ stoppedWaiting = true;
1870
2876
  child.unref();
1871
2877
  // A piped child's streams are sockets; only a socket can be unref'd.
1872
2878
  if (child.stdout instanceof Socket) child.stdout.unref();
1873
2879
  if (child.stderr instanceof Socket) child.stderr.unref();
1874
2880
  resolve({
1875
2881
  status: 1,
2882
+ pending: { pid: child.pid ?? null, completion },
1876
2883
  stdout: text(stdout),
1877
2884
  stderr: [
1878
2885
  text(stderr),
@@ -1883,36 +2890,57 @@ function runBounded(
1883
2890
  });
1884
2891
  return;
1885
2892
  }
1886
- resolve({
1887
- status: 1,
1888
- stdout: text(stdout),
1889
- stderr: `no answer within ${deadlineMs} ms; ${killGroup(child)}`,
2893
+ // A `close` that comes while the group is being killed must not end the call with an ordinary completion
2894
+ // before the kill is done: the deadline answers.
2895
+ timedOut = true;
2896
+ void killGroup(child).then((killed) => {
2897
+ resolve({ status: 1, stdout: text(stdout), stderr: `no answer within ${deadlineMs} ms; ${killed}` });
1890
2898
  });
1891
2899
  }, deadlineMs);
1892
2900
  child.on('error', (error) => {
1893
2901
  clearTimeout(timer);
1894
- resolve({ status: 1, stdout: text(stdout), stderr: error.message });
2902
+ if (timedOut) return;
2903
+ const output = { status: 1, stdout: text(stdout), stderr: error.message };
2904
+ complete?.(child.pid === undefined ? output : null);
2905
+ resolve(
2906
+ child.pid !== undefined && completion !== null ? { ...output, pending: { pid: child.pid, completion } } : output,
2907
+ );
1895
2908
  });
1896
2909
  child.on('close', (code, signal) => {
1897
2910
  clearTimeout(timer);
2911
+ if (timedOut) return;
1898
2912
  const error = text(stderr);
1899
- resolve({
2913
+ const output = {
1900
2914
  status: code ?? 1,
1901
2915
  stdout: text(stdout),
1902
2916
  stderr: signal === null ? error : [error, `killed by ${signal}`].filter(Boolean).join('\n'),
1903
- });
2917
+ };
2918
+ // Wrapper errors can report wait/reap failure with a native child still alive (06_cli.md).
2919
+ const terminal = code !== null && (code < 100 || code > 106);
2920
+ complete?.(terminal ? output : null);
2921
+ if (!terminal && completion !== null && stoppedWaiting) {
2922
+ process.stderr.write(
2923
+ `RAM temp volume: cowshed command ${child.pid ?? 'unknown'} ended without a native terminal receipt: ${commandText(output)}\n`,
2924
+ );
2925
+ }
2926
+ resolve(!terminal && completion !== null ? { ...output, pending: { pid: child.pid ?? null, completion } } : output);
1904
2927
  });
1905
2928
  return promise;
1906
2929
  }
1907
2930
 
1908
- /** SIGKILL the child's whole process group; what happened, for the error. */
1909
- function killGroup(child: ChildProcess): string {
2931
+ /**
2932
+ * SIGKILL the child's whole process group, again while it lists members; what happened, for the error. A group that
2933
+ * is still listed when the kill gives up is not called killed.
2934
+ */
2935
+ async function killGroup(child: ChildProcess): Promise<string> {
1910
2936
  if (child.pid === undefined) {
1911
2937
  return 'never started';
1912
2938
  }
1913
2939
  try {
1914
- process.kill(-child.pid, 'SIGKILL');
1915
- return `killed process group ${child.pid}`;
2940
+ const left = await killProcessGroup(child.pid, DEADLINE_PATIENCE);
2941
+ return left
2942
+ ? `signalled its process group, but ${describeMembersLeft(child.pid)}`
2943
+ : `killed process group ${child.pid}`;
1916
2944
  } catch (error) {
1917
2945
  return `killing process group ${child.pid} failed: ${errorText(error)}`;
1918
2946
  }
@@ -1928,6 +2956,15 @@ function processIsAlive(pid: number): boolean {
1928
2956
  }
1929
2957
  }
1930
2958
 
2959
+ /**
2960
+ * 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
2961
+ * keeps its workspace TMPDIR (`sandboxed`) whichever path the sandbox refuses first. A job's sandbox admits no part of
2962
+ * the RAM volume it cannot use, and this module reads that refusal rather than a second rule saying where it runs.
2963
+ */
2964
+ function denied<T>(path: string, error: unknown): Result<T, LockedError> {
2965
+ return { ok: false, error: { kind: 'lock-denied', detail: `${path}: ${errorText(error)}` } };
2966
+ }
2967
+
1931
2968
  function failed<T>(step: string, detail: string): Result<T, ProvisionFailed> {
1932
2969
  return { ok: false, error: { kind: 'provision-failed', step, detail } };
1933
2970
  }