pi-crew 0.9.50 → 0.9.52

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 (609) hide show
  1. package/CHANGELOG.md +150 -0
  2. package/README.md +216 -20
  3. package/dist/build-meta.json +2222 -1761
  4. package/dist/index.mjs +18636 -17603
  5. package/docs/actions-reference.md +431 -1
  6. package/package.json +19 -9
  7. package/schema.json +41 -0
  8. package/scripts/check-bundle-size.mjs +38 -0
  9. package/scripts/test-runner.mjs +11 -1
  10. package/skills/distill-software/SKILL.md +24 -1
  11. package/dist/index.mjs.map +0 -7
  12. package/docs/FEATURE_INTAKE.md +0 -126
  13. package/docs/HARNESS.md +0 -87
  14. package/docs/HARNESS_BACKLOG.md +0 -89
  15. package/docs/PROJECT_REVIEW.md +0 -270
  16. package/docs/PROJECT_REVIEW_FIXES.md +0 -342
  17. package/docs/PROJECT_REVIEW_ROUND4.md +0 -156
  18. package/docs/PROJECT_REVIEW_ROUND5.md +0 -86
  19. package/docs/REVIEW-FINDINGS-2026-06 +0 -357
  20. package/docs/REVIEW-FINDINGS-2026-07-CORE.md +0 -139
  21. package/docs/REVIEW-FINDINGS-2026-07.md +0 -125
  22. package/docs/TEST_MATRIX.md +0 -51
  23. package/docs/archive/README.md +0 -91
  24. package/docs/archive/followup-review-round3-2026-05-12.md +0 -342
  25. package/docs/archive/followup-review-round4-2026-05-13.md +0 -107
  26. package/docs/archive/pi-crew-bugs.md +0 -961
  27. package/docs/archive/pi-crew-test-final.md +0 -120
  28. package/docs/archive/pi-crew-test-results.md +0 -260
  29. package/docs/archive/pi-crew-test-round2.md +0 -136
  30. package/docs/archive/pi-crew-test-round4.md +0 -100
  31. package/docs/archive/pi-crew-test-round5.md +0 -70
  32. package/docs/archive/pi-crew-test-round6.md +0 -110
  33. package/docs/archive/pi-crew-v0.5.10-audit-fix-plan.md +0 -60
  34. package/docs/archive/pi-crew-v0.5.11-audit-fix-plan.md +0 -92
  35. package/docs/archive/pi-crew-v0.5.12-audit-fix-plan.md +0 -76
  36. package/docs/archive/pi-crew-v0.5.13-audit-fix-plan.md +0 -75
  37. package/docs/archive/pi-crew-v0.5.14-audit-fix-plan.md +0 -75
  38. package/docs/archive/pi-crew-v0.5.16-audit-fix-plan.md +0 -35
  39. package/docs/archive/pi-crew-v0.5.17-audit-fix-plan.md +0 -80
  40. package/docs/archive/pi-crew-v0.5.5-audit-fix-plan.md +0 -133
  41. package/docs/archive/pi-crew-v0.5.9-audit-fix-plan.md +0 -88
  42. package/docs/archive/pi-mono-opportunities.md +0 -969
  43. package/docs/archive/pi-mono-review.md +0 -291
  44. package/docs/archive/pi-subagent4-comparison.md +0 -261
  45. package/docs/archive/pi-subagents3-deep-analysis.md +0 -508
  46. package/docs/bugs/bug-021-notification-badge-counter-misleading.md +0 -293
  47. package/docs/bugs/bug-023-chain-windows-path-resolution.md +0 -106
  48. package/docs/bugs/bug-quota-display-truncation.md +0 -223
  49. package/docs/bugs/cross-session-notification-leakage.md +0 -82
  50. package/docs/code-review-2026-05-11.md +0 -592
  51. package/docs/coding-agent-optimization.md +0 -268
  52. package/docs/comparison-pi-subagents-vs-pi-crew.md +0 -303
  53. package/docs/decisions/0001-durable-state.md +0 -41
  54. package/docs/decisions/0002-child-process-for-async.md +0 -42
  55. package/docs/decisions/0003-depth-guard.md +0 -36
  56. package/docs/decisions/0004-execfile-over-exec.md +0 -34
  57. package/docs/decisions/0005-no-parameter-properties.md +0 -49
  58. package/docs/decisions/0006-publish-bundled-esm.md +0 -63
  59. package/docs/decisions/0007-active-run-binary-index.md +0 -54
  60. package/docs/decisions/0008-child-pi-warm-pool.md +0 -61
  61. package/docs/decisions/2026-07-21-broker-phase4-default-on.md +0 -77
  62. package/docs/decisions/2026-07-21-broker-windows-perms.md +0 -91
  63. package/docs/decisions/2026-07-22-broker-phase4-gated-on.md +0 -99
  64. package/docs/decisions/2026-07-24-oidc-trusted-publishing.md +0 -112
  65. package/docs/decisions/README.md +0 -26
  66. package/docs/deep-review-report.md +0 -384
  67. package/docs/distillation/cybersecurity-patterns.md +0 -294
  68. package/docs/feature-analysis-subagent4.md +0 -305
  69. package/docs/fix-plan-disabletools-exit-null.md +0 -219
  70. package/docs/fixes/BATCH_A_H1_H2.md +0 -86
  71. package/docs/fixes/bug-006-foreground-cancel-concurrent.md +0 -78
  72. package/docs/fixes/bug-007-async-notifier-stale-ctx.md +0 -112
  73. package/docs/fixes/bug-008-child-process-silent-timeout.md +0 -100
  74. package/docs/fixes/bug-009-executor-yield-limit-needs-attention.md +0 -75
  75. package/docs/fixes/bug-010-child-process-api-key-filtered.md +0 -109
  76. package/docs/fixes/bug-011-spawn-pi-enoent.md +0 -92
  77. package/docs/fixes/bug-012-essential-env-stripped.md +0 -89
  78. package/docs/fixes/bug-013-background-runner-death.md +0 -84
  79. package/docs/fixes/bug-014-infinite-retry-loop-needs-attention.md +0 -82
  80. package/docs/fixes/bug-015-background-runner-sigterm.md +0 -65
  81. package/docs/fixes/bug-017-background-runner-session-shutdown.md +0 -66
  82. package/docs/fixes/bug-017-background-runner-sigkill-double-fork.md +0 -28
  83. package/docs/fixes/bug-018-child-pi-worker-stdin-hang.md +0 -61
  84. package/docs/fixes/bug-019-phantom-runs-temp-workspace.md +0 -52
  85. package/docs/fixes/bug-020-infinite-retry-loop-needs-attention.md +0 -47
  86. package/docs/fixes/v0.9.10/locks-fix-verify.md +0 -3
  87. package/docs/fixes/v0.9.10/smoke-test.md +0 -12
  88. package/docs/followup-plan-2026-05-12.md +0 -463
  89. package/docs/followup-review-2026-05-12.md +0 -297
  90. package/docs/goals.md +0 -59
  91. package/docs/implementation-plan-top3.md +0 -333
  92. package/docs/issue-29-analysis.md +0 -189
  93. package/docs/live-mailbox-runtime.md +0 -36
  94. package/docs/migration/atomic-write-v2-migration.md +0 -299
  95. package/docs/next-upgrade-roadmap.md +0 -808
  96. package/docs/oh-my-pi-research.md +0 -509
  97. package/docs/optimization-plan-2026-07.md +0 -366
  98. package/docs/optimization-plan.md +0 -644
  99. package/docs/patterns/command-agent-skill.md +0 -71
  100. package/docs/perf/baseline-2026-05.md +0 -113
  101. package/docs/perf/final-report-2026-05.md +0 -206
  102. package/docs/perf/optimization-plan-2026-07-verified.md +0 -396
  103. package/docs/perf/performance-audit-report-2026-07.md +0 -948
  104. package/docs/perf/performance-review-2026-07.md +0 -287
  105. package/docs/perf/sprint-1-report.md +0 -71
  106. package/docs/perf/sprint-2-report.md +0 -81
  107. package/docs/perf/sprint-2.5-report.md +0 -53
  108. package/docs/perf/sprint-3-report.md +0 -36
  109. package/docs/perf/sprint-4-report.md +0 -47
  110. package/docs/perf/sprint-5-report.md +0 -51
  111. package/docs/perf/sprint-6-report.md +0 -94
  112. package/docs/perf/sprint-7-report.md +0 -74
  113. package/docs/perf/upgrade-plan-2026-05.md +0 -147
  114. package/docs/performance-optimization-execution-plan.md +0 -520
  115. package/docs/phase4-triage.md +0 -58
  116. package/docs/pi-crew-investigation-report.md +0 -411
  117. package/docs/product/README.md +0 -31
  118. package/docs/product/platform.md +0 -27
  119. package/docs/product/runtime-safety.md +0 -37
  120. package/docs/product/team-run.md +0 -39
  121. package/docs/product/team-tool.md +0 -37
  122. package/docs/runtime-analysis-child-vs-live.md +0 -171
  123. package/docs/runtime-migration-in-process-analysis.md +0 -250
  124. package/docs/skills/REFERENCE.md +0 -138
  125. package/docs/stories/README.md +0 -32
  126. package/docs/stories/US-DEPS-major-upgrade.md +0 -62
  127. package/docs/stories/backlog.md +0 -36
  128. package/docs/superpowers/plans/2026-06-09-fallow-patterns-adoption.md +0 -1270
  129. package/docs/templates/decision.md +0 -27
  130. package/docs/templates/story.md +0 -44
  131. package/docs/templates/validation-report.md +0 -32
  132. package/docs/ui-optimization-plan.md +0 -447
  133. package/src/adapters/claude-adapter.ts +0 -23
  134. package/src/adapters/codex-adapter.ts +0 -21
  135. package/src/adapters/cursor-adapter.ts +0 -17
  136. package/src/adapters/export-util.ts +0 -143
  137. package/src/adapters/index.ts +0 -15
  138. package/src/adapters/registry.ts +0 -18
  139. package/src/adapters/types.ts +0 -23
  140. package/src/agents/agent-config.ts +0 -194
  141. package/src/agents/agent-search.ts +0 -98
  142. package/src/agents/agent-serializer.ts +0 -38
  143. package/src/agents/discover-agents.ts +0 -623
  144. package/src/benchmark/benchmark-runner.ts +0 -313
  145. package/src/benchmark/feedback-loop.ts +0 -73
  146. package/src/config/config.ts +0 -1269
  147. package/src/config/defaults.ts +0 -193
  148. package/src/config/drift-detector.ts +0 -290
  149. package/src/config/markers.ts +0 -330
  150. package/src/config/resilient-parser.ts +0 -117
  151. package/src/config/role-tools.ts +0 -118
  152. package/src/config/suggestions.ts +0 -75
  153. package/src/config/types.ts +0 -278
  154. package/src/errors.ts +0 -194
  155. package/src/extension/action-suggestions.ts +0 -117
  156. package/src/extension/async-notifier.ts +0 -179
  157. package/src/extension/autonomous-policy.ts +0 -209
  158. package/src/extension/command-completions.ts +0 -120
  159. package/src/extension/context-status-injection.ts +0 -185
  160. package/src/extension/crew-autocomplete.ts +0 -131
  161. package/src/extension/crew-cleanup.ts +0 -168
  162. package/src/extension/crew-input-router.ts +0 -93
  163. package/src/extension/crew-shortcuts.ts +0 -87
  164. package/src/extension/crew-vibes/cat-frames.ts +0 -18
  165. package/src/extension/crew-vibes/config.ts +0 -195
  166. package/src/extension/crew-vibes/figures.ts +0 -101
  167. package/src/extension/crew-vibes/font-detect.ts +0 -71
  168. package/src/extension/crew-vibes/footer.ts +0 -292
  169. package/src/extension/crew-vibes/index.ts +0 -432
  170. package/src/extension/crew-vibes/provider-usage.ts +0 -396
  171. package/src/extension/crew-vibes/render.ts +0 -206
  172. package/src/extension/crew-vibes/speed.ts +0 -286
  173. package/src/extension/cross-extension-rpc.ts +0 -350
  174. package/src/extension/help.ts +0 -62
  175. package/src/extension/import-index.ts +0 -74
  176. package/src/extension/knowledge-injection.ts +0 -402
  177. package/src/extension/management.ts +0 -571
  178. package/src/extension/message-renderers.ts +0 -108
  179. package/src/extension/notification-router.ts +0 -152
  180. package/src/extension/notification-sink.ts +0 -54
  181. package/src/extension/pi-api.ts +0 -56
  182. package/src/extension/plan-orchestrate.ts +0 -302
  183. package/src/extension/project-init.ts +0 -170
  184. package/src/extension/register.ts +0 -113
  185. package/src/extension/registration/artifact-cleanup.ts +0 -20
  186. package/src/extension/registration/command-registration.ts +0 -58
  187. package/src/extension/registration/command-utils.ts +0 -58
  188. package/src/extension/registration/commands.ts +0 -1228
  189. package/src/extension/registration/compaction-guard.ts +0 -333
  190. package/src/extension/registration/context-builder.ts +0 -135
  191. package/src/extension/registration/crash-recovery-cache.ts +0 -54
  192. package/src/extension/registration/foreground-run-controller.ts +0 -238
  193. package/src/extension/registration/hook-registration.ts +0 -119
  194. package/src/extension/registration/lazy-configurers.ts +0 -124
  195. package/src/extension/registration/lifecycle-handlers.ts +0 -923
  196. package/src/extension/registration/lifecycle.ts +0 -259
  197. package/src/extension/registration/observability.ts +0 -322
  198. package/src/extension/registration/registration-types.ts +0 -158
  199. package/src/extension/registration/runtime-cleanup.ts +0 -230
  200. package/src/extension/registration/subagent-helpers.ts +0 -125
  201. package/src/extension/registration/subagent-manager-setup.ts +0 -330
  202. package/src/extension/registration/subagent-tools.ts +0 -456
  203. package/src/extension/registration/team-tool.ts +0 -220
  204. package/src/extension/registration/tool-registration.ts +0 -50
  205. package/src/extension/registration/ui.ts +0 -172
  206. package/src/extension/registration/viewers.ts +0 -121
  207. package/src/extension/registration/wire-cross-extension.ts +0 -37
  208. package/src/extension/result-watcher.ts +0 -139
  209. package/src/extension/rpc-hmac.ts +0 -256
  210. package/src/extension/run-bundle-schema.ts +0 -104
  211. package/src/extension/run-export.ts +0 -97
  212. package/src/extension/run-import.ts +0 -168
  213. package/src/extension/run-index.ts +0 -131
  214. package/src/extension/run-maintenance.ts +0 -190
  215. package/src/extension/session-summary.ts +0 -18
  216. package/src/extension/team-manager-command.ts +0 -153
  217. package/src/extension/team-onboard.ts +0 -177
  218. package/src/extension/team-recommendation.ts +0 -288
  219. package/src/extension/team-tool/anchor.ts +0 -172
  220. package/src/extension/team-tool/api.ts +0 -1244
  221. package/src/extension/team-tool/auto-summarize.ts +0 -142
  222. package/src/extension/team-tool/cache-control.ts +0 -19
  223. package/src/extension/team-tool/cancel.ts +0 -337
  224. package/src/extension/team-tool/chain-dispatch.ts +0 -95
  225. package/src/extension/team-tool/chain-executor.ts +0 -379
  226. package/src/extension/team-tool/config-patch.ts +0 -50
  227. package/src/extension/team-tool/context.ts +0 -149
  228. package/src/extension/team-tool/destructive-gate.ts +0 -52
  229. package/src/extension/team-tool/doctor.ts +0 -431
  230. package/src/extension/team-tool/explain.ts +0 -282
  231. package/src/extension/team-tool/failure-patterns.ts +0 -118
  232. package/src/extension/team-tool/goal-wrap.ts +0 -330
  233. package/src/extension/team-tool/goal.ts +0 -556
  234. package/src/extension/team-tool/handle-schedule.ts +0 -332
  235. package/src/extension/team-tool/handle-settings.ts +0 -520
  236. package/src/extension/team-tool/health-monitor.ts +0 -481
  237. package/src/extension/team-tool/inspect.ts +0 -88
  238. package/src/extension/team-tool/intent-policy.ts +0 -45
  239. package/src/extension/team-tool/lifecycle-actions.ts +0 -615
  240. package/src/extension/team-tool/orchestrate.ts +0 -98
  241. package/src/extension/team-tool/parallel-dispatch.ts +0 -183
  242. package/src/extension/team-tool/plan.ts +0 -50
  243. package/src/extension/team-tool/respond.ts +0 -150
  244. package/src/extension/team-tool/run-not-found.ts +0 -49
  245. package/src/extension/team-tool/run.ts +0 -1035
  246. package/src/extension/team-tool/status.ts +0 -260
  247. package/src/extension/team-tool/workflow-manage.ts +0 -261
  248. package/src/extension/team-tool-types.ts +0 -26
  249. package/src/extension/team-tool.ts +0 -1116
  250. package/src/extension/tool-result.ts +0 -16
  251. package/src/extension/validate-resources.ts +0 -108
  252. package/src/hooks/registry.ts +0 -200
  253. package/src/hooks/types.ts +0 -69
  254. package/src/i18n.ts +0 -212
  255. package/src/observability/correlation.ts +0 -50
  256. package/src/observability/event-bus.ts +0 -86
  257. package/src/observability/event-to-metric.ts +0 -170
  258. package/src/observability/exporters/adapter.ts +0 -27
  259. package/src/observability/exporters/otlp-exporter.ts +0 -356
  260. package/src/observability/exporters/prometheus-exporter.ts +0 -54
  261. package/src/observability/metric-registry.ts +0 -100
  262. package/src/observability/metric-retention.ts +0 -64
  263. package/src/observability/metric-sink.ts +0 -99
  264. package/src/observability/metrics-primitives.ts +0 -219
  265. package/src/plugins/plugin-define.ts +0 -6
  266. package/src/plugins/plugin-registry.ts +0 -32
  267. package/src/plugins/plugins/index.ts +0 -3
  268. package/src/plugins/plugins/nextjs.ts +0 -19
  269. package/src/plugins/plugins/vite.ts +0 -10
  270. package/src/plugins/plugins/vitest.ts +0 -9
  271. package/src/prompt/prompt-runtime.ts +0 -380
  272. package/src/runtime/adaptive-plan.ts +0 -563
  273. package/src/runtime/agent-control.ts +0 -215
  274. package/src/runtime/agent-memory.ts +0 -81
  275. package/src/runtime/agent-observability.ts +0 -122
  276. package/src/runtime/anchor-manager.ts +0 -475
  277. package/src/runtime/async-marker.ts +0 -32
  278. package/src/runtime/async-runner.ts +0 -381
  279. package/src/runtime/attention-events.ts +0 -28
  280. package/src/runtime/auto-summarize.ts +0 -344
  281. package/src/runtime/background-runner.ts +0 -837
  282. package/src/runtime/batch-barrier.ts +0 -147
  283. package/src/runtime/broker-issuer.ts +0 -37
  284. package/src/runtime/cancellation-token.ts +0 -99
  285. package/src/runtime/cancellation.ts +0 -99
  286. package/src/runtime/capability-inventory.ts +0 -137
  287. package/src/runtime/chain-parser.ts +0 -237
  288. package/src/runtime/chain-runner.ts +0 -606
  289. package/src/runtime/checkpoint.ts +0 -291
  290. package/src/runtime/child-pi-constants.ts +0 -42
  291. package/src/runtime/child-pi-kill.ts +0 -180
  292. package/src/runtime/child-pi-pool.ts +0 -68
  293. package/src/runtime/child-pi-spawn.ts +0 -287
  294. package/src/runtime/child-pi-steering.ts +0 -128
  295. package/src/runtime/child-pi-streams.ts +0 -296
  296. package/src/runtime/child-pi-transcript.ts +0 -169
  297. package/src/runtime/child-pi.ts +0 -1105
  298. package/src/runtime/coalesce-tasks.ts +0 -268
  299. package/src/runtime/code-summary.ts +0 -292
  300. package/src/runtime/command-trace.ts +0 -105
  301. package/src/runtime/compact-pipeline.ts +0 -56
  302. package/src/runtime/compact-stages/ansi-strip-stage.ts +0 -25
  303. package/src/runtime/compact-stages/blank-collapse-stage.ts +0 -31
  304. package/src/runtime/compact-stages/deduplicate-stage.ts +0 -34
  305. package/src/runtime/compact-stages/head-snap-stage.ts +0 -57
  306. package/src/runtime/compact-stages/index.ts +0 -23
  307. package/src/runtime/compact-stages/tail-capture-stage.ts +0 -77
  308. package/src/runtime/compact-stages/truncation-stage.ts +0 -74
  309. package/src/runtime/compaction-summary.ts +0 -278
  310. package/src/runtime/completion-guard.ts +0 -207
  311. package/src/runtime/concurrency.ts +0 -58
  312. package/src/runtime/crash-classification.ts +0 -229
  313. package/src/runtime/crash-recovery.ts +0 -577
  314. package/src/runtime/crew-agent-records.ts +0 -593
  315. package/src/runtime/crew-agent-runtime.ts +0 -62
  316. package/src/runtime/crew-broker-child.ts +0 -88
  317. package/src/runtime/crew-broker-client.ts +0 -673
  318. package/src/runtime/crew-broker-tokens.ts +0 -84
  319. package/src/runtime/crew-broker.ts +0 -1276
  320. package/src/runtime/crew-hooks.ts +0 -227
  321. package/src/runtime/cross-extension-rpc.ts +0 -143
  322. package/src/runtime/custom-tools/irc-tool.ts +0 -282
  323. package/src/runtime/custom-tools/submit-result-tool.ts +0 -102
  324. package/src/runtime/deadletter.ts +0 -47
  325. package/src/runtime/delivery-coordinator.ts +0 -211
  326. package/src/runtime/delta-conflict.ts +0 -348
  327. package/src/runtime/deterministic-ast.ts +0 -161
  328. package/src/runtime/diagnostic-export.ts +0 -171
  329. package/src/runtime/direct-run.ts +0 -45
  330. package/src/runtime/dwf-state-store.ts +0 -102
  331. package/src/runtime/dynamic-workflow-context.ts +0 -1016
  332. package/src/runtime/dynamic-workflow-runner.ts +0 -310
  333. package/src/runtime/effectiveness.ts +0 -90
  334. package/src/runtime/errors/crew-errors.ts +0 -162
  335. package/src/runtime/event-stream-bridge.ts +0 -98
  336. package/src/runtime/foreground-control.ts +0 -193
  337. package/src/runtime/foreground-watchdog.ts +0 -132
  338. package/src/runtime/global-worker-cap.ts +0 -96
  339. package/src/runtime/goal-achievement.ts +0 -148
  340. package/src/runtime/goal-evaluator.ts +0 -361
  341. package/src/runtime/goal-loop-runner.ts +0 -828
  342. package/src/runtime/goal-state-store.ts +0 -219
  343. package/src/runtime/green-contract.ts +0 -55
  344. package/src/runtime/group-join.ts +0 -267
  345. package/src/runtime/handoff-manager.ts +0 -598
  346. package/src/runtime/heartbeat-gradient.ts +0 -36
  347. package/src/runtime/heartbeat-watcher.ts +0 -239
  348. package/src/runtime/hidden-handoff.ts +0 -407
  349. package/src/runtime/important-line-classifier.ts +0 -140
  350. package/src/runtime/intercom-bridge.ts +0 -187
  351. package/src/runtime/iteration-hooks.ts +0 -305
  352. package/src/runtime/live-agent-control.ts +0 -136
  353. package/src/runtime/live-agent-manager.ts +0 -704
  354. package/src/runtime/live-control-realtime.ts +0 -56
  355. package/src/runtime/live-extension-bridge.ts +0 -148
  356. package/src/runtime/live-irc.ts +0 -97
  357. package/src/runtime/live-session-health.ts +0 -108
  358. package/src/runtime/live-session-runtime.ts +0 -1139
  359. package/src/runtime/loop-gates.ts +0 -128
  360. package/src/runtime/manifest-cache.ts +0 -375
  361. package/src/runtime/mcp-proxy.ts +0 -105
  362. package/src/runtime/metric-parser.ts +0 -36
  363. package/src/runtime/model-fallback.ts +0 -409
  364. package/src/runtime/model-resolver.ts +0 -126
  365. package/src/runtime/model-scope.ts +0 -158
  366. package/src/runtime/orphan-worker-registry.ts +0 -465
  367. package/src/runtime/output-validator.ts +0 -202
  368. package/src/runtime/overflow-recovery.ts +0 -206
  369. package/src/runtime/parallel-research.ts +0 -68
  370. package/src/runtime/parallel-utils.ts +0 -160
  371. package/src/runtime/parent-guard.ts +0 -134
  372. package/src/runtime/path-overlap.ts +0 -150
  373. package/src/runtime/peer-dep.ts +0 -292
  374. package/src/runtime/per-write-validator.ts +0 -181
  375. package/src/runtime/phase-progress.ts +0 -217
  376. package/src/runtime/phase-tracker.ts +0 -385
  377. package/src/runtime/pi-args.ts +0 -655
  378. package/src/runtime/pi-json-output.ts +0 -170
  379. package/src/runtime/pi-spawn.ts +0 -273
  380. package/src/runtime/pipeline-runner.ts +0 -523
  381. package/src/runtime/plan-templates.ts +0 -201
  382. package/src/runtime/policy-engine.ts +0 -115
  383. package/src/runtime/post-checks.ts +0 -142
  384. package/src/runtime/post-exit-stdio-guard.ts +0 -104
  385. package/src/runtime/process-lifecycle.ts +0 -491
  386. package/src/runtime/process-status.ts +0 -154
  387. package/src/runtime/progress-event-coalescer.ts +0 -44
  388. package/src/runtime/progress-tracker.ts +0 -124
  389. package/src/runtime/prose-compressor.ts +0 -162
  390. package/src/runtime/recovery-recipes.ts +0 -203
  391. package/src/runtime/replace.ts +0 -570
  392. package/src/runtime/resilient-edit.ts +0 -153
  393. package/src/runtime/result-extractor.ts +0 -213
  394. package/src/runtime/retry-executor.ts +0 -100
  395. package/src/runtime/retry-runner.ts +0 -336
  396. package/src/runtime/role-permission.ts +0 -59
  397. package/src/runtime/run-coalesced-task-group.ts +0 -308
  398. package/src/runtime/run-drift.ts +0 -219
  399. package/src/runtime/run-tracker.ts +0 -116
  400. package/src/runtime/runtime-policy.ts +0 -29
  401. package/src/runtime/runtime-resolver.ts +0 -172
  402. package/src/runtime/runtime-warmup.ts +0 -160
  403. package/src/runtime/scheduler.ts +0 -353
  404. package/src/runtime/semaphore.ts +0 -141
  405. package/src/runtime/sensitive-paths.ts +0 -93
  406. package/src/runtime/session-resources.ts +0 -25
  407. package/src/runtime/session-snapshot.ts +0 -59
  408. package/src/runtime/session-usage.ts +0 -79
  409. package/src/runtime/settings-store.ts +0 -155
  410. package/src/runtime/sidechain-output.ts +0 -35
  411. package/src/runtime/single-agent-compose.ts +0 -84
  412. package/src/runtime/skill-effectiveness.ts +0 -524
  413. package/src/runtime/skill-instructions.ts +0 -391
  414. package/src/runtime/stale-reconciler.ts +0 -680
  415. package/src/runtime/stream-preview.ts +0 -184
  416. package/src/runtime/streaming-output.ts +0 -50
  417. package/src/runtime/subagent-manager.ts +0 -561
  418. package/src/runtime/subprocess-tool-registry.ts +0 -70
  419. package/src/runtime/supervisor-contact.ts +0 -64
  420. package/src/runtime/task-display.ts +0 -52
  421. package/src/runtime/task-graph-scheduler.ts +0 -227
  422. package/src/runtime/task-graph.ts +0 -290
  423. package/src/runtime/task-health.ts +0 -83
  424. package/src/runtime/task-id.ts +0 -161
  425. package/src/runtime/task-output-context.ts +0 -602
  426. package/src/runtime/task-packet.ts +0 -268
  427. package/src/runtime/task-quality.ts +0 -199
  428. package/src/runtime/task-runner/capabilities.ts +0 -78
  429. package/src/runtime/task-runner/context-retrieval.ts +0 -163
  430. package/src/runtime/task-runner/live-executor.ts +0 -227
  431. package/src/runtime/task-runner/output-splitter.ts +0 -152
  432. package/src/runtime/task-runner/progress.ts +0 -157
  433. package/src/runtime/task-runner/prompt-builder.ts +0 -278
  434. package/src/runtime/task-runner/prompt-pipeline.ts +0 -88
  435. package/src/runtime/task-runner/result-utils.ts +0 -16
  436. package/src/runtime/task-runner/retrieval-orchestrator.ts +0 -310
  437. package/src/runtime/task-runner/run-projection.ts +0 -125
  438. package/src/runtime/task-runner/state-helpers.ts +0 -176
  439. package/src/runtime/task-runner/tail-read.ts +0 -34
  440. package/src/runtime/task-runner.ts +0 -1420
  441. package/src/runtime/team-runner-artifacts.ts +0 -13
  442. package/src/runtime/team-runner.ts +0 -1993
  443. package/src/runtime/tool-output-pruner.ts +0 -333
  444. package/src/runtime/tool-progress.ts +0 -278
  445. package/src/runtime/usage-tracker.ts +0 -73
  446. package/src/runtime/verification-gates.ts +0 -571
  447. package/src/runtime/verification-integrity.ts +0 -105
  448. package/src/runtime/verification-worktree.ts +0 -186
  449. package/src/runtime/worker-heartbeat.ts +0 -25
  450. package/src/runtime/worker-startup.ts +0 -83
  451. package/src/runtime/workflow-state.ts +0 -195
  452. package/src/runtime/workspace-lock.ts +0 -443
  453. package/src/runtime/workspace-tree.ts +0 -312
  454. package/src/runtime/yield-handler.ts +0 -224
  455. package/src/runtime/zombie-scanner.ts +0 -298
  456. package/src/schema/config-schema.ts +0 -327
  457. package/src/schema/team-tool-schema.ts +0 -415
  458. package/src/schema/validation-types.ts +0 -159
  459. package/src/skills/discover-skills.ts +0 -197
  460. package/src/skills/skill-templates.ts +0 -456
  461. package/src/skills/validate.ts +0 -285
  462. package/src/state/active-run-registry.ts +0 -439
  463. package/src/state/artifact-store.ts +0 -176
  464. package/src/state/atomic-write.ts +0 -903
  465. package/src/state/blob-store.ts +0 -308
  466. package/src/state/contracts.ts +0 -158
  467. package/src/state/crew-init.ts +0 -269
  468. package/src/state/decision-ledger.ts +0 -345
  469. package/src/state/event-log-rotation.ts +0 -342
  470. package/src/state/event-log.ts +0 -1311
  471. package/src/state/event-reconstructor.ts +0 -229
  472. package/src/state/gitignore-manager.ts +0 -46
  473. package/src/state/health-store.ts +0 -79
  474. package/src/state/hook-instinct-bridge.ts +0 -94
  475. package/src/state/hook-integrations.ts +0 -51
  476. package/src/state/instinct-store.ts +0 -275
  477. package/src/state/jsonl-writer.ts +0 -107
  478. package/src/state/locks.ts +0 -562
  479. package/src/state/mailbox.ts +0 -916
  480. package/src/state/observation-store.ts +0 -176
  481. package/src/state/run-cache.ts +0 -193
  482. package/src/state/run-graph.ts +0 -183
  483. package/src/state/run-metrics.ts +0 -165
  484. package/src/state/schedule.ts +0 -166
  485. package/src/state/session-state-map.ts +0 -51
  486. package/src/state/state-store.ts +0 -958
  487. package/src/state/task-claims.ts +0 -61
  488. package/src/state/tiered-eval.ts +0 -480
  489. package/src/state/types-eval.ts +0 -58
  490. package/src/state/types.ts +0 -440
  491. package/src/state/usage.ts +0 -138
  492. package/src/state/worker-atomic-writer.ts +0 -194
  493. package/src/subagents/async-entry.ts +0 -1
  494. package/src/subagents/index.ts +0 -3
  495. package/src/subagents/live/control.ts +0 -1
  496. package/src/subagents/live/manager.ts +0 -1
  497. package/src/subagents/live/realtime.ts +0 -1
  498. package/src/subagents/live/session-runtime.ts +0 -1
  499. package/src/subagents/manager.ts +0 -1
  500. package/src/subagents/spawn.ts +0 -1
  501. package/src/teams/discover-teams.ts +0 -187
  502. package/src/teams/team-config.ts +0 -27
  503. package/src/teams/team-serializer.ts +0 -38
  504. package/src/tools/safe-bash-extension.ts +0 -54
  505. package/src/tools/safe-bash.ts +0 -505
  506. package/src/types/diff.d.ts +0 -18
  507. package/src/types/new-api-types.ts +0 -35
  508. package/src/ui/agent-management-overlay.ts +0 -160
  509. package/src/ui/card-colors.ts +0 -139
  510. package/src/ui/crew-footer.ts +0 -102
  511. package/src/ui/crew-select-list.ts +0 -111
  512. package/src/ui/dashboard-panes/agents-pane.ts +0 -164
  513. package/src/ui/dashboard-panes/cancellation-pane.ts +0 -66
  514. package/src/ui/dashboard-panes/capability-pane.ts +0 -77
  515. package/src/ui/dashboard-panes/health-pane.ts +0 -31
  516. package/src/ui/dashboard-panes/mailbox-pane.ts +0 -35
  517. package/src/ui/dashboard-panes/metrics-pane.ts +0 -37
  518. package/src/ui/dashboard-panes/progress-pane.ts +0 -38
  519. package/src/ui/dashboard-panes/transcript-pane.ts +0 -10
  520. package/src/ui/deploy-bundled-themes.ts +0 -71
  521. package/src/ui/dwf-phase-display.ts +0 -151
  522. package/src/ui/dynamic-border.ts +0 -35
  523. package/src/ui/heartbeat-aggregator.ts +0 -74
  524. package/src/ui/key-utils.ts +0 -42
  525. package/src/ui/keybinding-map.ts +0 -248
  526. package/src/ui/layout-primitives.ts +0 -106
  527. package/src/ui/live-conversation-overlay.ts +0 -183
  528. package/src/ui/live-duration.ts +0 -55
  529. package/src/ui/live-run-sidebar.ts +0 -301
  530. package/src/ui/loaders.ts +0 -176
  531. package/src/ui/mascot.ts +0 -436
  532. package/src/ui/overlays/agent-picker-overlay.ts +0 -65
  533. package/src/ui/overlays/confirm-overlay.ts +0 -60
  534. package/src/ui/overlays/help-overlay.ts +0 -177
  535. package/src/ui/overlays/mailbox-compose-overlay.ts +0 -181
  536. package/src/ui/overlays/mailbox-compose-preview.ts +0 -78
  537. package/src/ui/overlays/mailbox-detail-overlay.ts +0 -154
  538. package/src/ui/pi-ui-compat.ts +0 -68
  539. package/src/ui/powerbar-publisher.ts +0 -459
  540. package/src/ui/render-coalescer.ts +0 -101
  541. package/src/ui/render-diff.ts +0 -160
  542. package/src/ui/render-scheduler.ts +0 -224
  543. package/src/ui/run-action-dispatcher.ts +0 -182
  544. package/src/ui/run-dashboard.ts +0 -913
  545. package/src/ui/run-event-bus.ts +0 -381
  546. package/src/ui/run-snapshot-cache.ts +0 -1057
  547. package/src/ui/settings-overlay.ts +0 -1067
  548. package/src/ui/snapshot-types.ts +0 -90
  549. package/src/ui/spinner.ts +0 -17
  550. package/src/ui/status-colors.ts +0 -143
  551. package/src/ui/syntax-highlight.ts +0 -136
  552. package/src/ui/terminal-status.ts +0 -269
  553. package/src/ui/theme-adapter.ts +0 -271
  554. package/src/ui/theme-discovery.ts +0 -199
  555. package/src/ui/tool-progress-formatter.ts +0 -93
  556. package/src/ui/tool-render.ts +0 -453
  557. package/src/ui/tool-renderers/brief-mode.ts +0 -225
  558. package/src/ui/tool-renderers/index.ts +0 -726
  559. package/src/ui/transcript-cache.ts +0 -128
  560. package/src/ui/transcript-entries.ts +0 -256
  561. package/src/ui/transcript-viewer.ts +0 -424
  562. package/src/ui/widget/index.ts +0 -357
  563. package/src/ui/widget/widget-formatters.ts +0 -182
  564. package/src/ui/widget/widget-model.ts +0 -110
  565. package/src/ui/widget/widget-renderer.ts +0 -182
  566. package/src/ui/widget/widget-types.ts +0 -36
  567. package/src/utils/bm25-search.ts +0 -235
  568. package/src/utils/completion-dedupe.ts +0 -63
  569. package/src/utils/conflict-detect.ts +0 -668
  570. package/src/utils/env-allowlist.ts +0 -30
  571. package/src/utils/env-filter.ts +0 -155
  572. package/src/utils/file-coalescer.ts +0 -98
  573. package/src/utils/fingerprint.ts +0 -180
  574. package/src/utils/frontmatter.ts +0 -70
  575. package/src/utils/fs-watch.ts +0 -37
  576. package/src/utils/gh-protocol.ts +0 -556
  577. package/src/utils/git.ts +0 -260
  578. package/src/utils/guards.ts +0 -107
  579. package/src/utils/ids.ts +0 -24
  580. package/src/utils/incremental-reader.ts +0 -220
  581. package/src/utils/internal-error.ts +0 -10
  582. package/src/utils/names.ts +0 -36
  583. package/src/utils/ndjson.ts +0 -115
  584. package/src/utils/paths.ts +0 -227
  585. package/src/utils/project-detector.ts +0 -160
  586. package/src/utils/redaction.ts +0 -347
  587. package/src/utils/resolve-shell.ts +0 -36
  588. package/src/utils/run-watcher-registry.ts +0 -152
  589. package/src/utils/safe-paths.ts +0 -383
  590. package/src/utils/scan-cache.ts +0 -144
  591. package/src/utils/session-utils.ts +0 -110
  592. package/src/utils/sleep.ts +0 -54
  593. package/src/utils/socket-path.ts +0 -127
  594. package/src/utils/sse-parser.ts +0 -129
  595. package/src/utils/task-name-generator.ts +0 -337
  596. package/src/utils/timings.ts +0 -33
  597. package/src/utils/token-counter.ts +0 -200
  598. package/src/utils/visual.ts +0 -207
  599. package/src/workflows/cost-estimator.ts +0 -34
  600. package/src/workflows/discover-workflows.ts +0 -290
  601. package/src/workflows/intermediate-store.ts +0 -166
  602. package/src/workflows/preflight-validator.ts +0 -168
  603. package/src/workflows/topology-analyzer.ts +0 -203
  604. package/src/workflows/validate-workflow.ts +0 -50
  605. package/src/workflows/workflow-config.ts +0 -70
  606. package/src/workflows/workflow-serializer.ts +0 -32
  607. package/src/worktree/branch-freshness.ts +0 -112
  608. package/src/worktree/cleanup.ts +0 -341
  609. package/src/worktree/worktree-manager.ts +0 -1200
@@ -1,903 +0,0 @@
1
- import * as crypto from "node:crypto";
2
- import * as fs from "node:fs";
3
- import * as os from "node:os";
4
- import * as path from "node:path";
5
- import { logInternalError } from "../utils/internal-error.ts";
6
- import { sleepSync } from "../utils/sleep.ts";
7
- import { atomicWriteFileViaWorker, isWorkerAtomicWriterEnabled } from "./worker-atomic-writer.ts";
8
-
9
- function hashContent(content: string): string {
10
- return crypto.createHash("sha256").update(content, "utf-8").digest("hex");
11
- }
12
-
13
- const RETRYABLE_RENAME_CODES = new Set(["EPERM", "EBUSY", "EACCES"]);
14
- // EEXIST is retryable: two concurrent async saves (OPT-02 async saveRunManifest)
15
- // can race on unlink+link — the second link() hits EEXIST because the first
16
- // already created the destination. The retry loop unlinks and re-links,
17
- // resolving the race. Exponential backoff + jitter prevents starvation.
18
- const RETRYABLE_LINK_CODES = new Set(["EPERM", "EBUSY", "EACCES", "ENOENT", "EEXIST"]);
19
-
20
- /**
21
- * Symlink-safe file write guard (caveman-inspired).
22
- * Returns true if the path is safe to write, false if it's a symlink or
23
- * inside a symlinked directory owned by another user.
24
- *
25
- * This walks the full ancestor chain to detect any symlinks in the path,
26
- * preventing attacks where an intermediate ancestor is a symlink.
27
- *
28
- * Platform note: The ownership verification (via process.getuid) is only
29
- * available on Unix-like platforms (Linux, macOS). On Windows or other
30
- * platforms where getuid is unavailable, the ownership check is skipped
31
- * and only symlink detection is performed. This means symlink safety
32
- * verification is weaker on non-Unix platforms. Consider using
33
- * platform-specific ownership verification (e.g., icacls on Windows)
34
- * for stronger guarantees on those platforms.
35
- *
36
- * Design note: Ownership verification (getuid/getgid) is only performed
37
- * when a path component is itself a symlink. For paths where all
38
- * components are regular directories, no ownership verification occurs.
39
- * This is intentional: an attacker who can create directories within
40
- * baseDir could exploit this, but this is mitigated by the boundary
41
- * check (realDir.startsWith(baseDir + path.sep)). In the pi-crew
42
- * context, baseDir is always within the user's own pi-crew state
43
- * directory tree (userPiRoot), so this is a low-risk design choice.
44
- * Callers must ensure baseDir is always inside a protected user
45
- * directory and never in a shared or world-writable location.
46
- */
47
- export function isSymlinkSafePath(filePath: string): boolean {
48
- try {
49
- // Note: baseDir is intentionally NOT resolved here with realpathSync.
50
- // The while loop below walks the full ancestor chain and the explicit
51
- // check at lines 94-101 verifies baseDir itself is not a symlink.
52
- // This redundant early resolution was removed per Issue 1.
53
- const baseDir = path.dirname(filePath);
54
- // Walk the full ancestor chain to detect any symlinks
55
- let currentPath = filePath;
56
- while (currentPath !== path.dirname(currentPath)) {
57
- const dir = path.dirname(currentPath);
58
- try {
59
- const dirStat = fs.lstatSync(dir);
60
- if (dirStat.isSymbolicLink()) {
61
- // Resolve and verify ownership on Unix
62
- const realDir = fs.realpathSync(dir);
63
- // Issue 1 fix: use resolved baseDir for boundary verification.
64
- // Accept if realDir is inside baseDir, equals baseDir, or is an
65
- // ancestor of baseDir. On macOS, /var/folders is a symlink to
66
- // /private/var/folders — resolve baseDir too for comparison.
67
- // Walk up ancestors to find the deepest existing one and resolve it.
68
- let realBase = baseDir;
69
- for (let walk = baseDir; walk !== path.dirname(walk); walk = path.dirname(walk)) {
70
- try {
71
- const resolved = fs.realpathSync(walk);
72
- // Found existing ancestor — join with remaining non-existent parts
73
- realBase = path.join(resolved, path.relative(walk, baseDir));
74
- break;
75
- } catch {
76
- /* not found yet, keep walking */
77
- }
78
- }
79
- const realDirNorm = realDir.endsWith(path.sep) ? realDir : realDir + path.sep;
80
- const realBaseNorm = realBase.endsWith(path.sep) ? realBase : realBase + path.sep;
81
- const isAncestor = realBaseNorm.startsWith(realDirNorm) || realBase === realDir;
82
- if (!isAncestor && !realDirNorm.startsWith(realBaseNorm)) return false;
83
- const realStat = fs.statSync(realDir);
84
- if (!realStat.isDirectory()) return false;
85
- // Only check ownership for user-controlled directories.
86
- // System directories like /private/var/folders on macOS are owned
87
- // by root but are safe to use (the OS manages them). Skip uid check
88
- // for directories not owned by the current user only when the real
89
- // path is inside or is an ancestor of a known system temp directory.
90
- if (typeof process.getuid === "function" && realStat.uid !== process.getuid()) {
91
- const systemTmp = (typeof os.tmpdir === "function" ? os.tmpdir() : "/tmp").toLowerCase();
92
- let realSystemTmp = systemTmp;
93
- try {
94
- realSystemTmp = fs.realpathSync(systemTmp).toLowerCase();
95
- } catch {
96
- /* ok */
97
- }
98
- const realDirLower = realDir.toLowerCase();
99
- const dirNorm = realDirLower.endsWith(path.sep) ? realDirLower : realDirLower + path.sep;
100
- const tmpNorm = realSystemTmp.endsWith(path.sep) ? realSystemTmp : realSystemTmp + path.sep;
101
- // Accept if realDir is inside tmpdir OR is an ancestor of tmpdir
102
- // (e.g. /private/var/folders is an ancestor of /private/var/folders/.../T/)
103
- const isInsideTmp = dirNorm.startsWith(tmpNorm) || realDirLower.startsWith(systemTmp);
104
- const isAncestorOfTmp = tmpNorm.startsWith(dirNorm) || realSystemTmp.startsWith(realDirLower);
105
- // Also accept canonical system temp paths:
106
- // - /tmp → /private/tmp (macOS)
107
- // - /var/folders → /private/var/folders (macOS)
108
- const isSystemTmp =
109
- process.platform === "darwin" &&
110
- (realDirLower === "/tmp" ||
111
- realDirLower === "/private/tmp" ||
112
- realDirLower === "/var/folders" ||
113
- realDirLower === "/private/var/folders" ||
114
- realDirLower.startsWith("/var/folders/") ||
115
- realDirLower.startsWith("/private/var/folders/"));
116
- if (!isInsideTmp && !isAncestorOfTmp && !isSystemTmp) {
117
- return false;
118
- }
119
- }
120
- }
121
- } catch (err) {
122
- // Directory doesn't exist yet — that's OK, mkdirSync will create it.
123
- // For permission errors (EACCES, EPERM), we cannot verify the path
124
- // is safe, so treat it as unsafe rather than returning true.
125
- const code = (err as NodeJS.ErrnoException).code;
126
- if (code === "ENOENT") {
127
- // OK - directory doesn't exist yet
128
- } else if (code === "EACCES" || code === "EPERM") {
129
- // Permission error - cannot verify path is safe
130
- logInternalError("isSymlinkSafePath.lstat.permission", err, `dir=${dir}`);
131
- return false;
132
- } else {
133
- // Other errors - log but continue (better to be conservative)
134
- logInternalError("isSymlinkSafePath.lstat", err, `dir=${dir}`);
135
- }
136
- }
137
- currentPath = dir;
138
- }
139
-
140
- // Issue 1 fix: verify baseDir itself is not a symlink.
141
- // The while loop above walks ancestors but stops when currentPath reaches
142
- // root (currentPath === path.dirname(currentPath)). If baseDir is a symlink
143
- // and is also the root of the path, it would not be checked. This explicit
144
- // check ensures baseDir is verified regardless of where the loop terminates.
145
- if (baseDir !== path.dirname(filePath)) {
146
- try {
147
- const baseDirStat = fs.lstatSync(baseDir);
148
- if (baseDirStat.isSymbolicLink()) return false;
149
- } catch {
150
- // baseDir does not exist yet — that is OK
151
- }
152
- }
153
- // Check if target file itself is a symlink
154
- try {
155
- const fileStat = fs.lstatSync(filePath);
156
- if (fileStat.isSymbolicLink()) return false;
157
- } catch {
158
- // File doesn't exist yet — that's OK
159
- }
160
-
161
- return true;
162
- } catch {
163
- return false;
164
- }
165
- }
166
-
167
- // ─── F5: Symlink-safe ancestor chain cache ─────────────────────────────────
168
- // `isSymlinkSafePath` walks the full ancestor chain with `lstatSync` per level
169
- // and is called twice per atomic write (initial + pre-rename re-check). The
170
- // parent dirs of `.crew/state/runs/{runId}/` are stable within a run, so we
171
- // cache the ancestor-walk verdict keyed by `dirname(filePath)`.
172
- //
173
- // SECURITY: TTL-only invalidation. The `.crew/` state directory is trusted
174
- // (single-user, non-shared). Symlink attacks require write access to the state
175
- // dir, which would already compromise the system. The short TTL provides
176
- // defense-in-depth. The target file itself is still checked every call (no
177
- // cache) — when in doubt the next call's statSync re-verifies.
178
- const SYMLINK_SAFE_TTL_MS = 10_000;
179
- const SYMLINK_SAFE_MAX_ENTRIES = 128;
180
- // P5 (perf): short-TTL cache for the target-file symlink check. Even though the
181
- // guard re-runs on every call by design, the common-case write path
182
- // (manifest.json, tasks.json, events.jsonl inside .crew/state/) repeatedly
183
- // re-stats the same known-regular files. A 1s TTL bounds the TOCTOU window
184
- // (same upper bound as isSymlinkSafeDirCached) and lets us skip the lstatSync
185
- // on burst writes. Invalidated whenever the directory itself is invalidated,
186
- // so the two caches stay coherent. Disable by setting TTL=0; the original
187
- // always-recheck behavior is preserved in that case.
188
- const TARGET_NOT_SYMLINK_TTL_MS = 1_000;
189
- const TARGET_NOT_SYMLINK_MAX_ENTRIES = 256;
190
- const targetNotSymlinkCache = new Map<string, { safe: boolean; at: number }>();
191
- // NOTE: This cache is process-local and assumes single-threaded access.
192
- // If worker-thread usage expands (e.g., worker-atomic-writer.ts), this cache
193
- // would need synchronization (e.g., a Mutex or WeakRef pattern).
194
- const symlinkSafeCache = new Map<string, { safe: boolean; at: number }>();
195
-
196
- /** Drop one or all cached entries. When a directory is invalidated, also
197
- * clear the target-file cache entries that live under that directory so the
198
- * two caches stay coherent — a swap at the dir level (e.g. directory
199
- * replaced) means per-file verdicts from before the swap may no longer
200
- * be trustworthy. */
201
- export function invalidateSymlinkSafeCache(dir?: string): void {
202
- if (dir) {
203
- symlinkSafeCache.delete(dir);
204
- // Drop all target-file entries whose path is inside `dir`.
205
- const dirPrefix = dir.endsWith(path.sep) ? dir : `${dir}${path.sep}`;
206
- for (const filePath of targetNotSymlinkCache.keys()) {
207
- if (filePath === dir || filePath.startsWith(dirPrefix)) {
208
- targetNotSymlinkCache.delete(filePath);
209
- }
210
- }
211
- } else {
212
- symlinkSafeCache.clear();
213
- targetNotSymlinkCache.clear();
214
- }
215
- }
216
-
217
- /** Target-file-only symlink check. Cheap single lstat. Cached for
218
- * TARGET_NOT_SYMLINK_TTL_MS (1s) on a per-file basis because the common-case
219
- * write path repeatedly stats the same known-regular files (manifest.json,
220
- * tasks.json, events.jsonl inside .crew/state/). A 1s TTL bounds the TOCTOU
221
- * window to a worst-case swap-then-write window of ~1s, which is the same
222
- * order as `isSymlinkSafeDirCached` (10s) and well within the existing
223
- * attack-prevention model. When TTL is 0 the cache is disabled and every
224
- * call re-stats (pre-P5 behavior preserved). Set TTL=0 if you need
225
- * exact-time TOCTOU semantics for an untrusted write target.
226
- * Always evicts the entry when the cached verdict goes false so a symlink
227
- * swap is picked up on the very next call. */
228
- function isTargetNotSymlink(filePath: string): boolean {
229
- if (TARGET_NOT_SYMLINK_TTL_MS <= 0) {
230
- try {
231
- if (fs.lstatSync(filePath).isSymbolicLink()) return false;
232
- } catch {
233
- // File doesn't exist yet — that's OK, atomicWriteFile will create it.
234
- }
235
- return true;
236
- }
237
- const now = Date.now();
238
- const hit = targetNotSymlinkCache.get(filePath);
239
- if (hit && now - hit.at < TARGET_NOT_SYMLINK_TTL_MS) return hit.safe;
240
- let safe = true;
241
- try {
242
- if (fs.lstatSync(filePath).isSymbolicLink()) safe = false;
243
- } catch {
244
- // File doesn't exist yet — that's OK, atomicWriteFile will create it.
245
- }
246
- // Cache the verdict. On a negative verdict (target IS a symlink) we still
247
- // cache briefly so a burst of rejected writes doesn't keep stat'ing — the
248
- // TTL is short enough that a cleanup will be visible within 1s.
249
- targetNotSymlinkCache.set(filePath, { safe, at: now });
250
- // Bound the cache to avoid unbounded growth across many file paths.
251
- while (targetNotSymlinkCache.size > TARGET_NOT_SYMLINK_MAX_ENTRIES) {
252
- const oldest = targetNotSymlinkCache.keys().next().value;
253
- if (oldest === undefined) break;
254
- targetNotSymlinkCache.delete(oldest);
255
- }
256
- return safe;
257
- }
258
-
259
- /**
260
- * Cached wrapper used by `atomicWriteFile` on the hot path. Only the ancestor-
261
- * chain walk (the slow part) is cached, keyed by `dirname(filePath)`; the
262
- * target-file symlink check ALWAYS re-runs so a mid-window symlink swap at the
263
- * target path is still caught (preserving the pre-rename TOCTOU guard).
264
- *
265
- * The cached verdict is computed from `isSymlinkSafePath(dir)` — i.e. the safety
266
- * of the *directory* itself, independent of any specific target file — so the
267
- * entry is correctly reusable for every file written into that dir (no
268
- * cross-file cache poisoning).
269
- */
270
- function isSymlinkSafeDirCached(filePath: string): boolean {
271
- const now = Date.now();
272
- const dir = path.dirname(filePath);
273
- // Always re-check the target file (uncached) before trusting the dir verdict.
274
- if (!isTargetNotSymlink(filePath)) return false;
275
- const hit = symlinkSafeCache.get(dir);
276
- if (hit && now - hit.at < SYMLINK_SAFE_TTL_MS) return hit.safe;
277
- // Cache miss: evaluate the ancestor-chain safety of the DIRECTORY itself.
278
- // Pass a synthetic file path (dir + sentinel) so `dir` is checked as an
279
- // ANCESTOR rather than a target file. When `dir` itself is a symlink
280
- // (e.g. macOS /tmp → /private/tmp), the ancestor-walk logic resolves it
281
- // and verifies ownership — accepting known system temp dirs. Passing `dir`
282
- // bare would hit the target-file symlink check at the bottom of
283
- // isSymlinkSafePath, which rejects ALL symlinks without ownership
284
- // resolution, causing false rejections for legitimate system dirs.
285
- const verdict = isSymlinkSafePath(path.join(dir, ".symlink-safe-check"));
286
- symlinkSafeCache.set(dir, { safe: verdict, at: now });
287
- // Bound the cache to avoid unbounded growth across many cwds.
288
- while (symlinkSafeCache.size > SYMLINK_SAFE_MAX_ENTRIES) {
289
- const oldest = symlinkSafeCache.keys().next().value;
290
- if (oldest === undefined) break;
291
- symlinkSafeCache.delete(oldest);
292
- }
293
- return verdict;
294
- }
295
-
296
- function sleep(ms: number): Promise<void> {
297
- return new Promise((resolve) => setTimeout(resolve, ms));
298
- }
299
-
300
- function isRetryableRenameError(error: unknown): boolean {
301
- return Boolean(
302
- error && typeof error === "object" && "code" in error && RETRYABLE_RENAME_CODES.has(String((error as NodeJS.ErrnoException).code)),
303
- );
304
- }
305
-
306
- function isRetryableLinkError(error: unknown): boolean {
307
- return Boolean(
308
- error && typeof error === "object" && "code" in error && RETRYABLE_LINK_CODES.has(String((error as NodeJS.ErrnoException).code)),
309
- );
310
- }
311
-
312
- /**
313
- * Issue 1 fix: rename via link+unlink instead of rename.
314
- * Unlike rename, link() does NOT follow symlinks at the destination path.
315
- * It atomically creates a hard link to the source. We then unlink the source.
316
- * This prevents TOCTOU attacks where an attacker plants a symlink at the
317
- * destination between the check and the rename operation.
318
- *
319
- * ST-8: this is the canonical symlink-safe rename helper used by both
320
- * `atomicWriteFile` (sync) and `atomicWriteFileAsync` (async) paths. The
321
- * helper is exported so any future caller can share the same symlink-safe
322
- * rename semantics; keep this signature stable.
323
- */
324
- export function renameWithLinkSync(tempPath: string, filePath: string, retries = 8): void {
325
- let lastError: unknown;
326
- for (let attempt = 0; attempt <= retries; attempt++) {
327
- try {
328
- if (process.platform === "win32") {
329
- // B9: MoveFileEx (Node's renameSync on Windows) replaces the destination atomically
330
- // with MOVEFILE_REPLACE_EXISTING, so no prior unlink is needed. Unlinking first
331
- // opened a window where concurrent readers saw ENOENT between the unlink and
332
- // the rename. Try rename directly; only fall back to unlink-then-rename for
333
- // edge cases (read-only dest / type mismatch / short-long-name alias).
334
- try {
335
- fs.renameSync(tempPath, filePath);
336
- return;
337
- } catch (renameError) {
338
- lastError = renameError;
339
- if (isRetryableLinkError(renameError) && attempt !== retries) {
340
- // retryable — loop again after sleep
341
- } else {
342
- try {
343
- fs.unlinkSync(filePath);
344
- } catch {
345
- /* destination may not exist */
346
- }
347
- try {
348
- fs.renameSync(tempPath, filePath);
349
- return;
350
- } catch (renameError2) {
351
- lastError = renameError2;
352
- if (!isRetryableLinkError(renameError2) || attempt === retries) break;
353
- }
354
- }
355
- }
356
- } else {
357
- try {
358
- fs.unlinkSync(filePath);
359
- } catch {
360
- /* destination may not exist */
361
- }
362
- // Create hard link — does NOT follow symlinks at filePath
363
- fs.linkSync(tempPath, filePath);
364
- // Successfully linked — now unlink the temp file
365
- fs.unlinkSync(tempPath);
366
- return;
367
- }
368
- } catch (error) {
369
- lastError = error;
370
- if (!isRetryableLinkError(error) || attempt === retries) break;
371
- }
372
- const base = Math.min(500, 10 * 2 ** attempt);
373
- const jitter = base * 0.2 * (Math.random() * 2 - 1);
374
- sleepSync(Math.max(1, Math.round(base + jitter)));
375
- }
376
- throw lastError;
377
- }
378
-
379
- /**
380
- * ST-8: async twin of `renameWithLinkSync`. Exported so any future caller
381
- * can share the same symlink-safe rename semantics as the primary
382
- * `atomicWriteFileAsync` path.
383
- */
384
- export async function renameWithLinkAsync(tempPath: string, filePath: string, retries = 8): Promise<void> {
385
- let lastError: unknown;
386
- for (let attempt = 0; attempt <= retries; attempt++) {
387
- try {
388
- if (process.platform === "win32") {
389
- // B9: MoveFileEx (Node's rename on Windows) replaces the destination atomically
390
- // with MOVEFILE_REPLACE_EXISTING, so no prior unlink is needed. Unlinking first
391
- // opened a window where concurrent readers saw ENOENT between the unlink and
392
- // the rename. Try rename directly; only fall back to unlink-then-rename for
393
- // edge cases (read-only dest / type mismatch / short-long-name alias).
394
- try {
395
- await fs.promises.rename(tempPath, filePath);
396
- return;
397
- } catch (renameError) {
398
- lastError = renameError;
399
- if (isRetryableLinkError(renameError) && attempt !== retries) {
400
- // retryable — loop again after sleep
401
- } else {
402
- try {
403
- await fs.promises.unlink(filePath);
404
- } catch {
405
- /* destination may not exist */
406
- }
407
- try {
408
- await fs.promises.rename(tempPath, filePath);
409
- return;
410
- } catch (renameError2) {
411
- lastError = renameError2;
412
- if (!isRetryableLinkError(renameError2) || attempt === retries) break;
413
- }
414
- }
415
- }
416
- } else {
417
- try {
418
- await fs.promises.unlink(filePath);
419
- } catch {
420
- /* destination may not exist */
421
- }
422
- // Create hard link — does NOT follow symlinks at filePath
423
- await fs.promises.link(tempPath, filePath);
424
- // Successfully linked — now unlink the temp file
425
- await fs.promises.unlink(tempPath);
426
- return;
427
- }
428
- } catch (error) {
429
- lastError = error;
430
- if (!isRetryableLinkError(error) || attempt === retries) break;
431
- }
432
- const base = Math.min(500, 10 * 2 ** attempt);
433
- const jitter = base * 0.2 * (Math.random() * 2 - 1);
434
- await sleep(Math.max(1, Math.round(base + jitter)));
435
- }
436
- throw lastError;
437
- }
438
- export function renameWithRetry(
439
- tempPath: string,
440
- filePath: string,
441
- retries = 8,
442
- rename: (oldPath: string, newPath: string) => void = fs.renameSync,
443
- ): void {
444
- let lastError: unknown;
445
- for (let attempt = 0; attempt <= retries; attempt++) {
446
- try {
447
- rename(tempPath, filePath);
448
- return;
449
- } catch (error) {
450
- lastError = error;
451
- if (!isRetryableRenameError(error) || attempt === retries) break;
452
- // 3.4: exponential backoff with ±20% jitter, capped at 500ms.
453
- // Without jitter, multiple processes contending on the same file
454
- // retry in lockstep and starve each other.
455
- const base = Math.min(500, 10 * 2 ** attempt);
456
- const jitter = base * 0.2 * (Math.random() * 2 - 1);
457
- sleepSync(Math.max(1, Math.round(base + jitter)));
458
- }
459
- }
460
- throw lastError;
461
- }
462
-
463
- /** Test alias for renameWithRetry. */
464
- export const __test__renameWithRetry = renameWithRetry;
465
-
466
- export async function renameWithRetryAsync(
467
- tempPath: string,
468
- filePath: string,
469
- retries = 8,
470
- rename: (oldPath: string, newPath: string) => Promise<void> = (source, destination) => fs.promises.rename(source, destination),
471
- ): Promise<void> {
472
- let lastError: unknown;
473
- for (let attempt = 0; attempt <= retries; attempt++) {
474
- try {
475
- await rename(tempPath, filePath);
476
- return;
477
- } catch (error) {
478
- lastError = error;
479
- if (!isRetryableRenameError(error) || attempt === retries) break;
480
- // 3.4: same jitter as renameWithRetry.
481
- const base = Math.min(500, 10 * 2 ** attempt);
482
- const jitter = base * 0.2 * (Math.random() * 2 - 1);
483
- await sleep(Math.max(1, Math.round(base + jitter)));
484
- }
485
- }
486
- throw lastError;
487
- }
488
-
489
- /** Test alias for renameWithRetryAsync. */
490
- export const __test__renameWithRetryAsync = renameWithRetryAsync;
491
-
492
- /**
493
- * F4: per-write durability knob.
494
- * - "full" (default): fsync the data file AND the parent directory after rename.
495
- * Cost is ms-scale on Windows; safe against crash + power-loss.
496
- * - "best-effort": skip both fsyncs. We still get atomic rename from temp file,
497
- * so a concurrent reader sees either the prior content or the full new
498
- * content — never a torn write. The trade-off is: a hard crash between
499
- * rename and a later `flush` may leave a few bytes stale on disk, which is
500
- * acceptable for informational writes (mailbox delivery, agent progress,
501
- * .seq sidecar) that the event-log reconstructor / crash-recovery can
502
- * reconcile without.
503
- */
504
- export type WriteDurability = "full" | "best-effort";
505
-
506
- /** Options accepted by atomicWriteFile (forward-compatible string | object form). */
507
- export type AtomicWriteOptions =
508
- | string // legacy: expectedHash
509
- | { expectedHash?: string; durability?: WriteDurability; mode?: number };
510
-
511
- function normalizeOptions(arg: unknown): { expectedHash?: string; durability: WriteDurability; mode?: number } {
512
- if (typeof arg === "string") return { expectedHash: arg, durability: "full", mode: undefined };
513
- if (arg && typeof arg === "object") {
514
- const o = arg as { expectedHash?: string; durability?: WriteDurability; mode?: number };
515
- const durability: WriteDurability = o.durability === "best-effort" ? "best-effort" : "full";
516
- return { expectedHash: o.expectedHash, durability, mode: o.mode };
517
- }
518
- return { durability: "full", mode: undefined };
519
- }
520
-
521
- export function atomicWriteFile(filePath: string, content: string, options?: AtomicWriteOptions): void {
522
- cancelPendingCoalescedWrite(filePath);
523
- const { durability, mode } = normalizeOptions(options);
524
- if (!isSymlinkSafeDirCached(filePath))
525
- throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
526
- // On Windows the parent directory may be referenced via a short-name alias
527
- // (e.g. RUNNER~1 vs runneradmin). mkdirSync on one form can succeed while
528
- // openSync on another form fails with ENOENT. We therefore ensure the dir
529
- // exists, trying the canonical (realpathSync.native) form as a fallback on
530
- // EPERM.
531
- //
532
- // CRITICAL: we NEVER rewrite `filePath`. The caller (e.g. createRunManifest)
533
- // builds filePath via canonicalizePath() (realpathSync.native) and will later
534
- // stat/read it back at that exact path. If we rewrote filePath to a different
535
- // realpath form here, the written file would land on a path that diverges
536
- // from the caller's path — making existsSync/readFileSync(callerPath) fail
537
- // with ENOENT even though the write "succeeded". Writing to the original
538
- // filePath guarantees the caller can always find the file it just wrote.
539
- const canonicalize = (p: string): string => {
540
- try {
541
- const r = fs.realpathSync.native(p);
542
- return r.startsWith("\\\\?\\") ? r.slice(4) : r;
543
- } catch {
544
- try {
545
- return fs.realpathSync(p);
546
- } catch {
547
- return p;
548
- }
549
- }
550
- };
551
- const dirPath = path.dirname(filePath);
552
- try {
553
- fs.mkdirSync(dirPath, { recursive: true });
554
- } catch (error) {
555
- if (process.platform === "win32" && (error as NodeJS.ErrnoException).code === "EPERM") {
556
- // mkdir hit a short/long-name alias wall — retry with the canonical
557
- // form. The write itself still targets the original filePath below.
558
- const realDir = canonicalize(dirPath);
559
- if (realDir !== dirPath) fs.mkdirSync(realDir, { recursive: true });
560
- } else {
561
- throw error;
562
- }
563
- }
564
- const tempPath = `${filePath}.${crypto.randomUUID()}.tmp`;
565
- // Write temp with restrictive permissions
566
- const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
567
- let fd: number | undefined;
568
- try {
569
- fd = fs.openSync(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, mode ?? 0o600);
570
- // Post-open verification: on Windows O_NOFOLLOW is 0, so verify FD is a regular file
571
- const openedStat = fs.fstatSync(fd);
572
- if (!openedStat.isFile()) {
573
- fs.closeSync(fd);
574
- throw new Error(`Refusing to write: opened path is not a regular file: ${tempPath}`);
575
- }
576
- fs.writeSync(fd, content, undefined, "utf-8");
577
- // FIX (2026-07-01 mailbox-replay CI flake investigation): fsync the data
578
- // before close. Without this, writeSync puts content in page cache but
579
- // the data may not be flushed to disk before the subsequent rename.
580
- // On shared CI runners (Ubuntu, high I/O pressure), a subsequent
581
- // readFileSync could see the OLD content if the page cache evicted
582
- // between write and read. fsyncSync forces the data to disk so the
583
- // rename + post-rename read always sees the new content. Cost: ~1ms
584
- // per write (acceptable for the small delivery.json / manifest.json
585
- // files this function writes; large state-store uses the async path).
586
- // F4: skip when durability is "best-effort" — see WriteDurability docs.
587
- if (durability === "full") fs.fsyncSync(fd);
588
- fs.closeSync(fd);
589
- try {
590
- // Issue 1 fix: re-check symlink safety immediately before rename.
591
- // Between the initial isSymlinkSafePath check (line 147) and here,
592
- // an attacker with control of an ancestor directory could plant a
593
- // symlink at the target path. If rename succeeds with a symlink at
594
- // target, the symlink is atomically replaced with attacker's content.
595
- // The post-rename lstat check only runs on rename failure, so we must
596
- // check BEFORE the rename to catch this TOCTOU race. Use the cached
597
- // wrapper for the dir chain — the pre-rename race only matters for the
598
- // *target* symlink swap, which the un-cached path check handles on the
599
- // first call. Here we just re-confirm nothing in the dir chain has been
600
- // planted symlink-wise since the initial call.
601
- if (!isSymlinkSafeDirCached(filePath)) {
602
- throw new Error(`Refusing to rename: target became a symlink or inside untrusted directory: ${filePath}`);
603
- }
604
- // Issue 1 fix: use link+unlink instead of rename to avoid following symlinks
605
- renameWithLinkSync(tempPath, filePath);
606
- // FIX (2026-07-01 mailbox-replay CI flake): fsync the parent directory
607
- // after rename so the directory entry update is durable. On most Linux
608
- // filesystems, rename is journaled but the journal flush isn't always
609
- // synchronous; without this, a subsequent open() after rename can
610
- // race and see ENOENT or stale content on high-IO CI runners.
611
- // We skip on Windows where directory fsync semantics differ (and
612
- // where the Windows-specific rename path in renameWithLinkSync already
613
- // uses MoveFileEx which is fully durable).
614
- // F4: honor durability — best-effort also skips the parent-dir fsync.
615
- if (durability === "full" && process.platform !== "win32") {
616
- try {
617
- const dirFd = fs.openSync(path.dirname(filePath), "r");
618
- fs.fsyncSync(dirFd);
619
- fs.closeSync(dirFd);
620
- } catch {
621
- /* best-effort — not all filesystems support directory fsync */
622
- }
623
- }
624
- } catch (renameError) {
625
- // Issue 4 fix: use finally block to guarantee temp file cleanup.
626
- // Between the initial isSymlinkSafePath check and rename attempt,
627
- // the file could have been replaced with a symlink (TOCTOU).
628
- // If lstat check below throws unexpectedly, finally ensures cleanup.
629
- try {
630
- const lstat = fs.lstatSync(filePath);
631
- if (lstat.isSymbolicLink()) {
632
- throw renameError;
633
- }
634
- } catch (checkError) {
635
- // Only ENOENT / ENOTDIR means the file genuinely doesn't exist — safe to proceed.
636
- // Re-throw everything else (EACCES, EPERM, EBUSY, etc.)
637
- const code = (checkError as NodeJS.ErrnoException).code;
638
- if (code !== "ENOENT" && code !== "ENOTDIR") {
639
- throw checkError;
640
- }
641
- }
642
- // Issue 2 fix: do NOT fall back to non-atomic writeFileSync.
643
- // The rename failed after retries — throw the error rather than
644
- // risking data corruption via a non-atomic write. Callers should
645
- // handle this error or use a different strategy for contended files.
646
- throw renameError;
647
- }
648
- } finally {
649
- // Issue 4 fix: always clean up temp file, regardless of success or error path.
650
- // This ensures no orphaned temp files remain when errors occur at any point.
651
- if (fd !== undefined) {
652
- try {
653
- fs.rmSync(tempPath, { force: true });
654
- } catch {
655
- /* best-effort */
656
- }
657
- }
658
- }
659
- }
660
-
661
- export async function atomicWriteFileAsync(filePath: string, content: string, options?: AtomicWriteOptions): Promise<void> {
662
- cancelPendingCoalescedWrite(filePath);
663
- const { durability } = normalizeOptions(options);
664
- // Phase 1.5 (RFC 15): when the worker-thread atomic writer is enabled
665
- // (PI_CREW_WORKER_ATOMIC_WRITER=1), dispatch to a dedicated worker thread
666
- // that performs SYNC fs ops with no internal yields. Mitigates the
667
- // non-deterministic V8/libuv crash during event-loop yields in multi-step
668
- // goal-wrapped workflows.
669
- if (isWorkerAtomicWriterEnabled()) {
670
- return atomicWriteFileViaWorker(filePath, content);
671
- }
672
- if (!isSymlinkSafeDirCached(filePath))
673
- throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
674
- await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
675
- const tempPath = `${filePath}.${crypto.randomUUID()}.tmp`;
676
- try {
677
- const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
678
- const fd = await fs.promises.open(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o600);
679
- // Post-open verification: on Windows O_NOFOLLOW is 0, so verify FD is a regular file
680
- const openedStat = await fd.stat();
681
- if (!openedStat.isFile()) {
682
- await fd.close();
683
- throw new Error(`Refusing to write: opened path is not a regular file: ${tempPath}`);
684
- }
685
- await fd.writeFile(content, "utf-8");
686
- // F4: skip data fsync when caller is best-effort. atomic rename below
687
- // still guarantees the reader sees either prior or new content, never torn.
688
- if (durability === "full") await fd.sync();
689
- await fd.close();
690
- // Re-check symlink safety immediately before rename.
691
- // Between the initial isSymlinkSafePath check and here,
692
- // an attacker with control of an ancestor directory could plant a
693
- // symlink at the target path. If rename succeeds with a symlink at
694
- // target, the symlink is atomically replaced with attacker's content.
695
- // The post-rename lstat check only runs on rename failure, so we must
696
- // check BEFORE the rename to catch this TOCTOU race.
697
- if (!isSymlinkSafeDirCached(filePath)) {
698
- throw new Error(`Refusing to rename: target became a symlink or inside untrusted directory: ${filePath}`);
699
- }
700
- // Issue 1 fix: use link+unlink instead of rename to avoid following symlinks.
701
- // Align with sync path: no content-match fallback after failed rename.
702
- // The racy readFile after failed rename is unreliable (another process
703
- // could write between the failed rename and the read) and inconsistent
704
- // with the sync path which just throws.
705
- await renameWithLinkAsync(tempPath, filePath);
706
- } catch (error) {
707
- try {
708
- await fs.promises.rm(tempPath, { force: true });
709
- } catch (cleanupError) {
710
- logInternalError("atomic-write.cleanupAsync", cleanupError, `tempPath=${tempPath}`);
711
- }
712
- throw error;
713
- }
714
- }
715
-
716
- export function atomicWriteJson<T>(filePath: string, value: T, options?: AtomicWriteOptions): void {
717
- atomicWriteFile(filePath, `${JSON.stringify(value, null, 2)}\n`, options);
718
- }
719
-
720
- export async function atomicWriteJsonAsync<T>(filePath: string, value: T, options?: AtomicWriteOptions): Promise<void> {
721
- await atomicWriteFileAsync(filePath, `${JSON.stringify(value, null, 2)}\n`, options);
722
- }
723
-
724
- // 2.1 — atomic-write coalescer. Buffer the latest payload per filePath and
725
- // flush after `coalesceMs` ms (default 50). Multiple writes to the same
726
- // path within the window collapse to one disk write (last value wins),
727
- // which is exactly the semantic that team-runner.ts merge loops need for
728
- // `saveRunTasks` and similar high-frequency state-store paths.
729
- //
730
- // Caveat: a `readJsonFile` call between buffer and flush sees the previous
731
- // on-disk content. Callers that need read-after-write within the window
732
- // must invoke `flushPendingAtomicWrites()` first (or pass through
733
- // `atomicWriteJson` which flushes synchronously).
734
- //
735
- // Auto-flush hooks: process exit / SIGTERM / SIGINT, plus an exposed
736
- // `flushPendingAtomicWrites()` for cleanupRuntime.
737
- interface CoalescedAtomicWrite {
738
- content: string;
739
- timer: ReturnType<typeof setTimeout>;
740
- coalesceMs: number;
741
- retryCount: number;
742
- /** Generation counter to detect stale flushes (Issue 2 fix) */
743
- generation: number;
744
- /** F4: durability knob carried into the underlying atomicWriteFile flush. */
745
- durability: WriteDurability;
746
- }
747
- const MAX_FLUSH_RETRIES = 5;
748
- const pendingAtomicWrites = new Map<string, CoalescedAtomicWrite>();
749
- const DEFAULT_ATOMIC_COALESCE_MS = 50;
750
- /** Issue 2 fix: generation counter for coalesced writes */
751
- let writeGeneration = 0;
752
-
753
- // Issue 1 fix: guard against concurrent AND re-entrant flushes using depth counter
754
- let flushInProgress = 0;
755
-
756
- /**
757
- * Buffer a JSON write and flush it after `coalesceMs` ms (default 50).
758
- * Multiple writes to the same path within the window collapse to one disk write.
759
- *
760
- * ST-7 escape hatch: pass `skipCoalesce: true` to bypass the buffer entirely
761
- * and write synchronously via `atomicWriteJson`. Use for terminal task status
762
- * transitions where a SIGKILL during the 50ms coalesce window must NOT lose
763
- * the terminal status update — otherwise crash recovery would see "running"
764
- * in tasks.json while events.jsonl already shows "completed", causing
765
- * double-execution / zombie detection. Defaults to `false` (buffered write)
766
- * so all existing callers preserve their behavior.
767
- *
768
- * @see The coalescing caveat: a `readJsonFile` call between buffer and flush
769
- * sees the previous on-disk content. Callers needing read-after-write
770
- * must call `flushPendingAtomicWrites()` first or use `atomicWriteJson`.
771
- */
772
- export function atomicWriteJsonCoalesced<T>(
773
- filePath: string,
774
- value: T,
775
- coalesceMs: number = DEFAULT_ATOMIC_COALESCE_MS,
776
- options?: AtomicWriteOptions,
777
- skipCoalesce: boolean = false,
778
- ): void {
779
- // ST-7: bypass coalescing for callers that need durable synchronous
780
- // semantics. atomicWriteJson goes through atomicWriteFile which uses
781
- // renameWithLinkSync + fsync — fully durable, no SIGKILL window.
782
- if (skipCoalesce) {
783
- atomicWriteJson(filePath, value, options);
784
- return;
785
- }
786
- const content = `${JSON.stringify(value, null, 2)}\n`;
787
- const previous = pendingAtomicWrites.get(filePath);
788
- if (previous) clearTimeout(previous.timer);
789
- const timer = setTimeout(() => flushOnePendingAtomicWrite(filePath), coalesceMs);
790
- timer.unref();
791
- // Issue 2 fix: increment generation for each new entry
792
- const generation = ++writeGeneration;
793
- const normalized = normalizeOptions(options);
794
- pendingAtomicWrites.set(filePath, {
795
- content,
796
- timer,
797
- coalesceMs,
798
- retryCount: 0,
799
- generation,
800
- durability: normalized.durability,
801
- });
802
- }
803
-
804
- function flushOnePendingAtomicWrite(filePath: string): void {
805
- const entry = pendingAtomicWrites.get(filePath);
806
- if (!entry) return;
807
- // Issue 2 fix: capture generation before flush to detect stale flushes.
808
- // If a new write arrives during the flush, the generation will change
809
- // and we will NOT delete the newer entry after the flush completes.
810
- const savedGeneration = entry.generation;
811
- clearTimeout(entry.timer);
812
- try {
813
- atomicWriteFile(filePath, entry.content, { durability: entry.durability });
814
- // Issue 2 fix: Verify generation hasn't changed before deleting.
815
- // A concurrent write may have replaced entry with a newer one during the flush.
816
- // Only delete if generation matches (not a newer entry).
817
- // This prevents orphaning newer entries that arrived during the flush.
818
- if (pendingAtomicWrites.get(filePath)?.generation === savedGeneration) {
819
- pendingAtomicWrites.delete(filePath);
820
- }
821
- } catch (error) {
822
- logInternalError("atomic-write.coalesced-flush", error, filePath, "error");
823
- // Issue 1 fix: set a fresh timer for failed entries before returning.
824
- // This ensures failed entries are retried without waiting for another
825
- // write to arrive. Only set timer if this entry is still current
826
- // (not replaced by a newer write during the flush).
827
- const current = pendingAtomicWrites.get(filePath);
828
- if (current?.generation === savedGeneration) {
829
- current.retryCount++;
830
- if (current.retryCount >= MAX_FLUSH_RETRIES) {
831
- // Max retries exceeded - remove entry and propagate error to callers
832
- pendingAtomicWrites.delete(filePath);
833
- // Re-throw so callers can handle the persistent failure
834
- throw error;
835
- }
836
- // Exponential backoff: base delay * 2^(retryCount-1), capped at 30 seconds
837
- const backoffMs = Math.min(30000, current.coalesceMs * 2 ** (current.retryCount - 1));
838
- const timer = setTimeout(() => flushOnePendingAtomicWrite(filePath), backoffMs);
839
- timer.unref();
840
- current.timer = timer;
841
- }
842
- }
843
- }
844
-
845
- /**
846
- * Cancel any pending coalesced write for `filePath`. An immediate (durable)
847
- * write supersedes a pending coalesced (buffered) write — the immediate write
848
- * IS the freshest data, so the stale buffered content must not be allowed to
849
- * fire later and clobber it.
850
- *
851
- * Without this, a sequence like persistSingleTaskUpdate (coalesced, 50ms) →
852
- * merge saveRunTasksAsync (immediate) leaves the coalesced entry pending; when
853
- * its timer fires it overwrites the merge result with a stale single-task
854
- * snapshot, losing other workers' results / attempt enrichment / graph
855
- * recompute. It also closes the crash window where tasks.json shows "running"
856
- * while events.jsonl already shows "completed" (re-run on recovery).
857
- */
858
- function cancelPendingCoalescedWrite(filePath: string): void {
859
- const pending = pendingAtomicWrites.get(filePath);
860
- if (pending) {
861
- clearTimeout(pending.timer);
862
- pendingAtomicWrites.delete(filePath);
863
- }
864
- }
865
-
866
- /** Flush every queued coalesced write synchronously. Safe to call any time. */
867
- export function flushPendingAtomicWrites(): void {
868
- if (flushInProgress > 0) return;
869
- flushInProgress++;
870
- try {
871
- for (const filePath of [...pendingAtomicWrites.keys()]) flushOnePendingAtomicWrite(filePath);
872
- } finally {
873
- flushInProgress--;
874
- }
875
- }
876
-
877
- // Defense-in-depth: signal handlers must return immediately.
878
- // Use setImmediate so the handler exits before any sync I/O runs.
879
- // This prevents the main thread from being blocked if a signal
880
- // arrives while the user is idle in the terminal.
881
- process.on("exit", () => flushPendingAtomicWrites());
882
- process.on("SIGTERM", () => setImmediate(() => flushPendingAtomicWrites()));
883
- process.on("SIGINT", () => setImmediate(() => flushPendingAtomicWrites()));
884
-
885
- export function readJsonFile<T>(filePath: string): T | undefined {
886
- try {
887
- return JSON.parse(fs.readFileSync(filePath, "utf-8")) as T;
888
- } catch (err) {
889
- const code = (err as NodeJS.ErrnoException).code;
890
- if (code === "ENOENT" || code === "ENOTDIR") {
891
- // Expected: file doesn't exist or path is not a directory
892
- return undefined;
893
- } else if (code === "EACCES" || code === "EPERM") {
894
- // Permission error - log as warning but still return undefined
895
- logInternalError("readJsonFile.permission", err, `filePath=${filePath}`);
896
- return undefined;
897
- } else {
898
- // Other unexpected errors - log as internal error
899
- logInternalError("readJsonFile", err, `filePath=${filePath}`);
900
- return undefined;
901
- }
902
- }
903
- }