@chankov/agent-fleet 0.0.8 → 0.0.9

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 (340) hide show
  1. package/.pi/agents/model-profiles.yaml +9 -2
  2. package/.pi/agents/peers.yaml +12 -16
  3. package/.pi/agents/teams.yaml +4 -2
  4. package/.pi/harnesses/agent-hub/README.md +20 -5
  5. package/.pi/harnesses/agent-hub/footer.ts +4 -2
  6. package/.pi/harnesses/agent-hub/index.ts +104 -11
  7. package/.pi/harnesses/agent-hub/package.json +1 -1
  8. package/.pi/harnesses/agent-hub/version.ts +25 -1
  9. package/.pi/harnesses/coms/README.md +8 -1
  10. package/.pi/harnesses/coms/package.json +1 -1
  11. package/.pi/harnesses/coms/version.ts +25 -1
  12. package/.pi/harnesses/damage-control-continue/README.md +8 -1
  13. package/.pi/harnesses/damage-control-continue/package.json +1 -1
  14. package/.pi/harnesses/damage-control-continue/version.ts +25 -1
  15. package/.pi/harnesses/lib/herdr-client.ts +10 -1
  16. package/.pi/harnesses/lib/spawned-peers.js +190 -0
  17. package/.versions/0.0.9/.claude/commands/build.md +44 -0
  18. package/.versions/0.0.9/.claude/commands/code-simplify.md +22 -0
  19. package/.versions/0.0.9/.claude/commands/design-agent.md +14 -0
  20. package/.versions/0.0.9/.claude/commands/doctor-agent-fleet.md +17 -0
  21. package/.versions/0.0.9/.claude/commands/orchestrate.md +112 -0
  22. package/.versions/0.0.9/.claude/commands/plan.md +16 -0
  23. package/.versions/0.0.9/.claude/commands/prime.md +22 -0
  24. package/.versions/0.0.9/.claude/commands/review.md +16 -0
  25. package/.versions/0.0.9/.claude/commands/set-hermes-telegram.md +15 -0
  26. package/.versions/0.0.9/.claude/commands/set-hermes-watchdog.md +6 -0
  27. package/.versions/0.0.9/.claude/commands/setup-agent-fleet.md +25 -0
  28. package/.versions/0.0.9/.claude/commands/ship.md +72 -0
  29. package/.versions/0.0.9/.claude/commands/spec.md +15 -0
  30. package/.versions/0.0.9/.claude/commands/test.md +19 -0
  31. package/.versions/0.0.9/.claude/commands/webperf.md +32 -0
  32. package/.versions/0.0.9/.claude/orchestrate-teams.yaml +24 -0
  33. package/.versions/0.0.9/.opencode/commands/af-build.md +17 -0
  34. package/.versions/0.0.9/.opencode/commands/af-code-simplify.md +16 -0
  35. package/.versions/0.0.9/.opencode/commands/af-compound.md +16 -0
  36. package/.versions/0.0.9/.opencode/commands/af-design-agent.md +15 -0
  37. package/.versions/0.0.9/.opencode/commands/af-doctor-agent-fleet.md +17 -0
  38. package/.versions/0.0.9/.opencode/commands/af-orchestrate.md +112 -0
  39. package/.versions/0.0.9/.opencode/commands/af-plan.md +16 -0
  40. package/.versions/0.0.9/.opencode/commands/af-prime.md +22 -0
  41. package/.versions/0.0.9/.opencode/commands/af-review.md +15 -0
  42. package/.versions/0.0.9/.opencode/commands/af-set-hermes-telegram.md +15 -0
  43. package/.versions/0.0.9/.opencode/commands/af-set-hermes-watchdog.md +6 -0
  44. package/.versions/0.0.9/.opencode/commands/af-setup-agent-fleet.md +15 -0
  45. package/.versions/0.0.9/.opencode/commands/af-ship.md +16 -0
  46. package/.versions/0.0.9/.opencode/commands/af-spec.md +16 -0
  47. package/.versions/0.0.9/.opencode/commands/af-test.md +21 -0
  48. package/.versions/0.0.9/.opencode/commands/af-webperf.md +32 -0
  49. package/.versions/0.0.9/.opencode/orchestrate-teams.yaml +24 -0
  50. package/.versions/0.0.9/.pi/agents/dispatch-policy.yaml +32 -0
  51. package/.versions/0.0.9/.pi/agents/model-profiles.yaml +27 -0
  52. package/.versions/0.0.9/.pi/agents/peers.yaml +142 -0
  53. package/.versions/0.0.9/.pi/agents/teams.yaml +41 -0
  54. package/.versions/0.0.9/.pi/damage-control-rules.yaml +297 -0
  55. package/.versions/0.0.9/.pi/extensions/agent-fleet-update-check/README.md +58 -0
  56. package/.versions/0.0.9/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  57. package/.versions/0.0.9/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  58. package/.versions/0.0.9/.pi/extensions/btw/README.md +118 -0
  59. package/.versions/0.0.9/.pi/extensions/btw/index.ts +917 -0
  60. package/.versions/0.0.9/.pi/extensions/btw/package.json +6 -0
  61. package/.versions/0.0.9/.pi/extensions/btw/state.js +179 -0
  62. package/.versions/0.0.9/.pi/extensions/chrome-devtools-mcp/README.md +58 -0
  63. package/.versions/0.0.9/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
  64. package/.versions/0.0.9/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  65. package/.versions/0.0.9/.pi/extensions/compact-and-continue/README.md +42 -0
  66. package/.versions/0.0.9/.pi/extensions/compact-and-continue/index.ts +120 -0
  67. package/.versions/0.0.9/.pi/extensions/compact-and-continue/package.json +6 -0
  68. package/.versions/0.0.9/.pi/extensions/mcp-bridge/README.md +46 -0
  69. package/.versions/0.0.9/.pi/extensions/mcp-bridge/index.ts +206 -0
  70. package/.versions/0.0.9/.pi/extensions/mcp-bridge/package.json +6 -0
  71. package/.versions/0.0.9/.pi/extensions/package-lock.json +1143 -0
  72. package/.versions/0.0.9/.pi/extensions/package.json +9 -0
  73. package/.versions/0.0.9/.pi/extensions/pi-voice-stt/README.md +201 -0
  74. package/.versions/0.0.9/.pi/extensions/pi-voice-stt/config.ts +198 -0
  75. package/.versions/0.0.9/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  76. package/.versions/0.0.9/.pi/extensions/pi-voice-stt/index.ts +248 -0
  77. package/.versions/0.0.9/.pi/extensions/pi-voice-stt/package.json +6 -0
  78. package/.versions/0.0.9/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  79. package/.versions/0.0.9/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  80. package/.versions/0.0.9/.pi/harnesses/agent-hub/README.md +872 -0
  81. package/.versions/0.0.9/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  82. package/.versions/0.0.9/.pi/harnesses/agent-hub/artifacts.js +146 -0
  83. package/.versions/0.0.9/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
  84. package/.versions/0.0.9/.pi/harnesses/agent-hub/backend-policy.js +153 -0
  85. package/.versions/0.0.9/.pi/harnesses/agent-hub/context-window.js +106 -0
  86. package/.versions/0.0.9/.pi/harnesses/agent-hub/delegate.ts +435 -0
  87. package/.versions/0.0.9/.pi/harnesses/agent-hub/drift-watchdog.js +211 -0
  88. package/.versions/0.0.9/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  89. package/.versions/0.0.9/.pi/harnesses/agent-hub/footer.ts +31 -0
  90. package/.versions/0.0.9/.pi/harnesses/agent-hub/helpers.ts +248 -0
  91. package/.versions/0.0.9/.pi/harnesses/agent-hub/index.ts +8702 -0
  92. package/.versions/0.0.9/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  93. package/.versions/0.0.9/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
  94. package/.versions/0.0.9/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
  95. package/.versions/0.0.9/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  96. package/.versions/0.0.9/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  97. package/.versions/0.0.9/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  98. package/.versions/0.0.9/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  99. package/.versions/0.0.9/.pi/harnesses/agent-hub/monitor-session-bridge.ts +257 -0
  100. package/.versions/0.0.9/.pi/harnesses/agent-hub/package.json +7 -0
  101. package/.versions/0.0.9/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
  102. package/.versions/0.0.9/.pi/harnesses/agent-hub/research-retention.js +34 -0
  103. package/.versions/0.0.9/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  104. package/.versions/0.0.9/.pi/harnesses/agent-hub/return-contract.js +293 -0
  105. package/.versions/0.0.9/.pi/harnesses/agent-hub/return-extract.js +75 -0
  106. package/.versions/0.0.9/.pi/harnesses/agent-hub/run-budget.js +181 -0
  107. package/.versions/0.0.9/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  108. package/.versions/0.0.9/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  109. package/.versions/0.0.9/.pi/harnesses/agent-hub/session-health.js +110 -0
  110. package/.versions/0.0.9/.pi/harnesses/agent-hub/spawn.ts +354 -0
  111. package/.versions/0.0.9/.pi/harnesses/agent-hub/version.ts +42 -0
  112. package/.versions/0.0.9/.pi/harnesses/ask-user-remote/README.md +19 -0
  113. package/.versions/0.0.9/.pi/harnesses/ask-user-remote/index.ts +321 -0
  114. package/.versions/0.0.9/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  115. package/.versions/0.0.9/.pi/harnesses/coms/README.md +100 -0
  116. package/.versions/0.0.9/.pi/harnesses/coms/index.ts +1767 -0
  117. package/.versions/0.0.9/.pi/harnesses/coms/package.json +7 -0
  118. package/.versions/0.0.9/.pi/harnesses/coms/version.ts +42 -0
  119. package/.versions/0.0.9/.pi/harnesses/damage-control-continue/README.md +124 -0
  120. package/.versions/0.0.9/.pi/harnesses/damage-control-continue/index.ts +536 -0
  121. package/.versions/0.0.9/.pi/harnesses/damage-control-continue/package.json +7 -0
  122. package/.versions/0.0.9/.pi/harnesses/damage-control-continue/version.ts +42 -0
  123. package/.versions/0.0.9/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
  124. package/.versions/0.0.9/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  125. package/.versions/0.0.9/.pi/harnesses/lib/herdr-client.ts +472 -0
  126. package/.versions/0.0.9/.pi/harnesses/lib/herdr-presence.ts +399 -0
  127. package/.versions/0.0.9/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
  128. package/.versions/0.0.9/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  129. package/.versions/0.0.9/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
  130. package/.versions/0.0.9/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  131. package/.versions/0.0.9/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
  132. package/.versions/0.0.9/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  133. package/.versions/0.0.9/.pi/harnesses/lib/spawned-peers.js +190 -0
  134. package/.versions/0.0.9/.pi/harnesses/package-lock.json +35 -0
  135. package/.versions/0.0.9/.pi/harnesses/package.json +9 -0
  136. package/.versions/0.0.9/.pi/prompts/af-build.md +24 -0
  137. package/.versions/0.0.9/.pi/prompts/af-code-simplify.md +22 -0
  138. package/.versions/0.0.9/.pi/prompts/af-doctor-agent-fleet.md +15 -0
  139. package/.versions/0.0.9/.pi/prompts/af-plan.md +16 -0
  140. package/.versions/0.0.9/.pi/prompts/af-review.md +16 -0
  141. package/.versions/0.0.9/.pi/prompts/af-set-hermes-telegram.md +15 -0
  142. package/.versions/0.0.9/.pi/prompts/af-set-hermes-watchdog.md +6 -0
  143. package/.versions/0.0.9/.pi/prompts/af-setup-agent-fleet.md +27 -0
  144. package/.versions/0.0.9/.pi/prompts/af-ship.md +17 -0
  145. package/.versions/0.0.9/.pi/prompts/af-spec.md +15 -0
  146. package/.versions/0.0.9/.pi/prompts/af-test.md +19 -0
  147. package/.versions/0.0.9/.pi/skills/bowser/SKILL.md +145 -0
  148. package/.versions/0.0.9/.version +1 -0
  149. package/.versions/0.0.9/agents/architect.md +24 -0
  150. package/.versions/0.0.9/agents/bowser.md +27 -0
  151. package/.versions/0.0.9/agents/builder.md +54 -0
  152. package/.versions/0.0.9/agents/code-reviewer.md +204 -0
  153. package/.versions/0.0.9/agents/deep-researcher.md +32 -0
  154. package/.versions/0.0.9/agents/documenter.md +18 -0
  155. package/.versions/0.0.9/agents/orchestrator.md +66 -0
  156. package/.versions/0.0.9/agents/plan-reviewer.md +62 -0
  157. package/.versions/0.0.9/agents/planner.md +70 -0
  158. package/.versions/0.0.9/agents/releaser.md +24 -0
  159. package/.versions/0.0.9/agents/researcher.md +28 -0
  160. package/.versions/0.0.9/agents/security-auditor.md +167 -0
  161. package/.versions/0.0.9/agents/test-engineer.md +153 -0
  162. package/.versions/0.0.9/agents/web-debugger.md +43 -0
  163. package/.versions/0.0.9/agents/web-performance-auditor.md +193 -0
  164. package/.versions/0.0.9/codex/CONDUCTOR.md +148 -0
  165. package/.versions/0.0.9/docs/ARCHITECTURE.md +262 -0
  166. package/.versions/0.0.9/docs/agent-fleet-setup.md +366 -0
  167. package/.versions/0.0.9/docs/claude-code-coms-bridge.md +109 -0
  168. package/.versions/0.0.9/docs/codex-remote-conductor.md +170 -0
  169. package/.versions/0.0.9/docs/coms-hermes-bridge.md +189 -0
  170. package/.versions/0.0.9/docs/getting-started.md +231 -0
  171. package/.versions/0.0.9/docs/npm-install.md +337 -0
  172. package/.versions/0.0.9/docs/opencode-setup.md +249 -0
  173. package/.versions/0.0.9/docs/pi-extensions.md +356 -0
  174. package/.versions/0.0.9/docs/pi-setup.md +476 -0
  175. package/.versions/0.0.9/docs/skill-anatomy.md +150 -0
  176. package/.versions/0.0.9/hermes/README.md +347 -0
  177. package/.versions/0.0.9/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
  178. package/.versions/0.0.9/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
  179. package/.versions/0.0.9/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  180. package/.versions/0.0.9/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  181. package/.versions/0.0.9/hermes/gates/gate-o-capability.md +8 -0
  182. package/.versions/0.0.9/hermes/gates/gate-o-validator-fixtures.json +1 -0
  183. package/.versions/0.0.9/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +770 -0
  184. package/.versions/0.0.9/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
  185. package/.versions/0.0.9/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
  186. package/.versions/0.0.9/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
  187. package/.versions/0.0.9/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
  188. package/.versions/0.0.9/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
  189. package/.versions/0.0.9/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
  190. package/.versions/0.0.9/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
  191. package/.versions/0.0.9/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
  192. package/.versions/0.0.9/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
  193. package/.versions/0.0.9/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
  194. package/.versions/0.0.9/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  195. package/.versions/0.0.9/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  196. package/.versions/0.0.9/hermes/skills/hub-conductor/SKILL.md +84 -0
  197. package/.versions/0.0.9/hermes/skills/hub-liaison/SKILL.md +84 -0
  198. package/.versions/0.0.9/hermes/skills/hub-watchdog/SKILL.md +76 -0
  199. package/.versions/0.0.9/hermes/skills/hub-watchdog/manifest.json +1 -0
  200. package/.versions/0.0.9/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
  201. package/.versions/0.0.9/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
  202. package/.versions/0.0.9/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
  203. package/.versions/0.0.9/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
  204. package/.versions/0.0.9/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
  205. package/.versions/0.0.9/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
  206. package/.versions/0.0.9/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
  207. package/.versions/0.0.9/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
  208. package/.versions/0.0.9/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
  209. package/.versions/0.0.9/hermes/watchdog-tests/__init__.py +0 -0
  210. package/.versions/0.0.9/hooks/SIMPLIFY-IGNORE.md +90 -0
  211. package/.versions/0.0.9/hooks/coms-stop-hook.mjs +84 -0
  212. package/.versions/0.0.9/hooks/hooks.json +14 -0
  213. package/.versions/0.0.9/hooks/session-start.sh +74 -0
  214. package/.versions/0.0.9/hooks/simplify-ignore.sh +302 -0
  215. package/.versions/0.0.9/justfile +254 -0
  216. package/.versions/0.0.9/references/accessibility-checklist.md +160 -0
  217. package/.versions/0.0.9/references/definition-of-done.md +67 -0
  218. package/.versions/0.0.9/references/fleet-coordination-patterns.md +151 -0
  219. package/.versions/0.0.9/references/observability-checklist.md +91 -0
  220. package/.versions/0.0.9/references/orchestration-patterns.md +370 -0
  221. package/.versions/0.0.9/references/performance-checklist.md +153 -0
  222. package/.versions/0.0.9/references/prompting-patterns.md +380 -0
  223. package/.versions/0.0.9/references/security-checklist.md +179 -0
  224. package/.versions/0.0.9/references/testing-patterns.md +236 -0
  225. package/.versions/0.0.9/scripts/codex-conductor.ts +41 -0
  226. package/.versions/0.0.9/scripts/codex-remote-control.ts +167 -0
  227. package/.versions/0.0.9/scripts/coms-claude-bridge.ts +401 -0
  228. package/.versions/0.0.9/scripts/coms-cli.ts +484 -0
  229. package/.versions/0.0.9/scripts/coms-hermes-bridge.ts +413 -0
  230. package/.versions/0.0.9/scripts/fleet.ts +168 -0
  231. package/.versions/0.0.9/scripts/hermes-monitor-capability-runner.ts +25 -0
  232. package/.versions/0.0.9/scripts/hermes-monitor-scenario.ts +474 -0
  233. package/.versions/0.0.9/scripts/hermes-watchdog-capability-probe.ts +45 -0
  234. package/.versions/0.0.9/scripts/install-hermes-plugin.sh +180 -0
  235. package/.versions/0.0.9/scripts/lib/claude-bridge-core.ts +165 -0
  236. package/.versions/0.0.9/scripts/lib/codex-conductor.ts +88 -0
  237. package/.versions/0.0.9/scripts/lib/codex-remote-control.ts +480 -0
  238. package/.versions/0.0.9/scripts/lib/coms-envelope.ts +582 -0
  239. package/.versions/0.0.9/scripts/lib/fake-herdr-server.ts +88 -0
  240. package/.versions/0.0.9/scripts/lib/fleet-command.ts +111 -0
  241. package/.versions/0.0.9/scripts/lib/herdr-layout.ts +281 -0
  242. package/.versions/0.0.9/scripts/lib/hermes-bridge-core.ts +241 -0
  243. package/.versions/0.0.9/scripts/lib/hermes-monitor-events.ts +1 -0
  244. package/.versions/0.0.9/scripts/lib/hermes-monitor-herdr.ts +2 -0
  245. package/.versions/0.0.9/scripts/lib/hermes-monitor-model.ts +3 -0
  246. package/.versions/0.0.9/scripts/lib/hermes-monitor-registry.ts +2 -0
  247. package/.versions/0.0.9/scripts/lib/hermes-monitor-socket.ts +2 -0
  248. package/.versions/0.0.9/scripts/lib/hermes-monitor-store.ts +2 -0
  249. package/.versions/0.0.9/scripts/lib/monitor-env.ts +120 -0
  250. package/.versions/0.0.9/scripts/lib/peer-launch.ts +314 -0
  251. package/.versions/0.0.9/scripts/lib/persona-banner.ts +62 -0
  252. package/.versions/0.0.9/scripts/lib/spawn-stagger.ts +101 -0
  253. package/.versions/0.0.9/scripts/lib/team-project.ts +193 -0
  254. package/.versions/0.0.9/scripts/lib/team-snapshot.ts +147 -0
  255. package/.versions/0.0.9/scripts/peer-banner.ts +40 -0
  256. package/.versions/0.0.9/scripts/peer-launch.ts +259 -0
  257. package/.versions/0.0.9/scripts/team-snapshot.ts +237 -0
  258. package/.versions/0.0.9/scripts/team-up.ts +360 -0
  259. package/.versions/0.0.9/skills/_internal/grilling.md +11 -0
  260. package/.versions/0.0.9/skills/browser-testing-with-devtools/SKILL.md +352 -0
  261. package/.versions/0.0.9/skills/code-review-and-quality/SKILL.md +381 -0
  262. package/.versions/0.0.9/skills/compound-learning/SKILL.md +137 -0
  263. package/.versions/0.0.9/skills/context-engineering/SKILL.md +291 -0
  264. package/.versions/0.0.9/skills/deprecation-and-migration/SKILL.md +206 -0
  265. package/.versions/0.0.9/skills/designing-agents/SKILL.md +394 -0
  266. package/.versions/0.0.9/skills/designing-agents/pi-harness-authoring.md +222 -0
  267. package/.versions/0.0.9/skills/frontend-ui-engineering/SKILL.md +328 -0
  268. package/.versions/0.0.9/skills/git-workflow-and-versioning/SKILL.md +316 -0
  269. package/.versions/0.0.9/skills/guided-workspace-setup/SKILL.md +544 -0
  270. package/.versions/0.0.9/skills/guided-workspace-setup/companion-manifest.json +38 -0
  271. package/.versions/0.0.9/skills/idea-refine/SKILL.md +182 -0
  272. package/.versions/0.0.9/skills/idea-refine/examples.md +238 -0
  273. package/.versions/0.0.9/skills/idea-refine/frameworks.md +99 -0
  274. package/.versions/0.0.9/skills/idea-refine/refinement-criteria.md +113 -0
  275. package/.versions/0.0.9/skills/idea-refine/scripts/idea-refine.sh +15 -0
  276. package/.versions/0.0.9/skills/incremental-implementation/SKILL.md +287 -0
  277. package/.versions/0.0.9/skills/interview-me/SKILL.md +226 -0
  278. package/.versions/0.0.9/skills/orchestration-verification/SKILL.md +181 -0
  279. package/.versions/0.0.9/skills/peer-coms/SKILL.md +90 -0
  280. package/.versions/0.0.9/skills/performance-optimization/SKILL.md +350 -0
  281. package/.versions/0.0.9/skills/planning-and-task-breakdown/SKILL.md +236 -0
  282. package/.versions/0.0.9/skills/security-and-hardening/SKILL.md +461 -0
  283. package/.versions/0.0.9/skills/spec-driven-development/SKILL.md +245 -0
  284. package/.versions/0.0.9/skills/using-agent-skills/SKILL.md +199 -0
  285. package/.versions/0.0.9/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  286. package/.versions/0.0.9/vendor/agent-skills-upstream/LICENSE +21 -0
  287. package/.versions/0.0.9/vendor/agent-skills-upstream/README.md +11 -0
  288. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  289. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  290. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  291. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  292. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  293. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  294. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  295. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  296. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  297. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  298. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  299. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  300. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  301. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  302. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  303. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  304. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  305. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  306. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  307. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  308. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  309. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  310. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  311. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  312. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  313. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  314. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  315. package/.versions/0.0.9/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  316. package/CHANGELOG.md +38 -0
  317. package/agents/architect.md +1 -0
  318. package/agents/bowser.md +1 -0
  319. package/agents/builder.md +1 -0
  320. package/agents/code-reviewer.md +4 -5
  321. package/agents/deep-researcher.md +2 -1
  322. package/agents/orchestrator.md +1 -0
  323. package/agents/plan-reviewer.md +3 -1
  324. package/agents/planner.md +3 -2
  325. package/agents/security-auditor.md +1 -0
  326. package/agents/test-engineer.md +3 -1
  327. package/agents/web-debugger.md +1 -0
  328. package/agents/web-performance-auditor.md +1 -0
  329. package/docs/ARCHITECTURE.md +1 -1
  330. package/docs/pi-extensions.md +66 -3
  331. package/justfile +10 -1
  332. package/package.json +2 -2
  333. package/scripts/fleet.ts +22 -3
  334. package/scripts/lib/fleet-command.ts +5 -3
  335. package/scripts/lib/herdr-layout.ts +18 -0
  336. package/scripts/lib/peer-launch.ts +314 -0
  337. package/scripts/lib/team-project.ts +3 -1
  338. package/scripts/peer-launch.ts +259 -0
  339. package/skills/guided-workspace-setup/companion-manifest.json +2 -0
  340. package/.pi/harnesses/agent-hub/spawned-peers.js +0 -74
@@ -0,0 +1,181 @@
1
+ // Execution modes & per-turn budgets — the pure policy core behind the hub's
2
+ // runaway-orchestration guardrails. Budgets are PER USER TURN: a new user
3
+ // message opens a fresh window, so "budget exhausted" naturally means "stop,
4
+ // summarize, ask the user". Everything here is data + pure functions so the
5
+ // policy is unit-testable away from the 7k-line harness.
6
+ //
7
+ // A budget value of `null` means "off"/unlimited for that axis.
8
+
9
+ export const HUB_MODES = ["fast", "standard", "strict"];
10
+ export const DEFAULT_HUB_MODE = "standard";
11
+
12
+ // Task tiers — the dispatcher's per-turn complexity triage. Tier caps only
13
+ // lower the dispatch/research axes (min with the mode budget): a trivial ask
14
+ // must not burn a standard-mode budget on ceremony, while `project` defers
15
+ // entirely to the mode. Unset tier is treated as "feature".
16
+ export const TASK_TIERS = ["trivial", "small", "feature", "project"];
17
+ export const DEFAULT_TASK_TIER = "feature";
18
+
19
+ export const TIER_CAPS = {
20
+ trivial: { maxDispatches: 1, maxResearch: 1 },
21
+ small: { maxDispatches: 2, maxResearch: 2 },
22
+ feature: { maxDispatches: 6, maxResearch: 4 },
23
+ project: { maxDispatches: null, maxResearch: null },
24
+ };
25
+
26
+ /** "Small", " TRIVIAL " → canonical tier name, or null when unrecognized. */
27
+ export function normalizeTaskTier(value) {
28
+ const v = String(value ?? "").trim().toLowerCase();
29
+ return TASK_TIERS.includes(v) ? v : null;
30
+ }
31
+
32
+ // Session-recycle context threshold (percent, measured over input+cacheRead+
33
+ // cacheWrite): beyond this, resuming the specialist session mostly re-bills
34
+ // stale context, so a fresh session is cheaper than the memory is worth.
35
+ export const RECYCLE_CONTEXT_PCT = 60;
36
+
37
+ // Hard ceiling: at or past a full window the accumulated session no longer
38
+ // fits, so no threshold override may keep it alive. Session 1 of the
39
+ // post-mortem logged 315% → 176% → 100% while the configured threshold was
40
+ // still being consulted as if it were advisory.
41
+ export const HARD_RECYCLE_CONTEXT_PCT = 100;
42
+
43
+ export const MODE_BUDGETS = {
44
+ fast: {
45
+ maxDispatches: 2,
46
+ maxResearch: 1,
47
+ wallMs: 15 * 60_000,
48
+ agentTurnMs: 10 * 60_000,
49
+ recycleRuns: 3,
50
+ delegation: false,
51
+ },
52
+ standard: {
53
+ maxDispatches: 8,
54
+ maxResearch: 4,
55
+ wallMs: 60 * 60_000,
56
+ agentTurnMs: 30 * 60_000,
57
+ recycleRuns: 5,
58
+ delegation: true,
59
+ },
60
+ strict: {
61
+ maxDispatches: 24,
62
+ maxResearch: 12,
63
+ wallMs: 240 * 60_000,
64
+ agentTurnMs: null,
65
+ recycleRuns: 5,
66
+ delegation: true,
67
+ },
68
+ };
69
+
70
+ /** "Fast", " STRICT " → canonical mode name, or null when unrecognized. */
71
+ export function normalizeHubMode(value) {
72
+ const v = String(value ?? "").trim().toLowerCase();
73
+ return HUB_MODES.includes(v) ? v : null;
74
+ }
75
+
76
+ /**
77
+ * Effective budget for a mode with per-project overrides applied.
78
+ * Override fields (all optional): maxDispatches, maxResearch, wallMs,
79
+ * agentTurnMs, recycleRuns — a number replaces the mode default, `null` turns
80
+ * the axis off, `undefined` keeps the default. `delegation` is mode-owned.
81
+ * A declared `tier` (task tier) then LOWERS the dispatch and research caps to
82
+ * the tier cap — overrides raise/disable the mode side, but the tier keeps a
83
+ * simple ask from spending the whole envelope. No tier (null/undefined) means
84
+ * no tier caps: the caller decides when to assume DEFAULT_TASK_TIER.
85
+ */
86
+ export function resolveTurnBudget(mode, overrides = {}, tier = undefined) {
87
+ const base = MODE_BUDGETS[normalizeHubMode(mode) ?? DEFAULT_HUB_MODE];
88
+ const pick = (key) => (overrides[key] === undefined ? base[key] : overrides[key]);
89
+ const caps = TIER_CAPS[normalizeTaskTier(tier)] ?? { maxDispatches: null, maxResearch: null };
90
+ const lower = (value, cap) => {
91
+ if (cap == null) return value;
92
+ if (value == null) return cap;
93
+ return Math.min(value, cap);
94
+ };
95
+ return {
96
+ maxDispatches: lower(pick("maxDispatches"), caps.maxDispatches),
97
+ maxResearch: lower(pick("maxResearch"), caps.maxResearch),
98
+ wallMs: pick("wallMs"),
99
+ agentTurnMs: pick("agentTurnMs"),
100
+ recycleRuns: pick("recycleRuns"),
101
+ delegation: base.delegation,
102
+ };
103
+ }
104
+
105
+ function refusalTail(mode) {
106
+ return "Do NOT retry this call in this turn. Summarize progress so far (including " +
107
+ "unproven assertions and artifact paths), then ask the user whether to continue — " +
108
+ "the next user message starts a fresh budget window. The user can widen budgets " +
109
+ `with /af-hub-mode (current: ${mode}) or the max-*-per-turn / turn-wall-time-s keys ` +
110
+ "in .ai/agent-fleet-overrides.md.";
111
+ }
112
+
113
+ /**
114
+ * Gate one dispatcher tool call against the turn budget.
115
+ * kind: "dispatch" | "research"; counters: { dispatches, research } — calls
116
+ * already made this turn. Returns null when allowed, else { reason, message }.
117
+ */
118
+ export function checkTurnBudget(kind, counters, budget, elapsedWallMs, mode = DEFAULT_HUB_MODE) {
119
+ if (budget.wallMs != null && elapsedWallMs >= budget.wallMs) {
120
+ return {
121
+ reason: "wall",
122
+ message: `⚠ Turn budget exhausted: wall clock at ${Math.round(elapsedWallMs / 60_000)} min ` +
123
+ `(limit ${Math.round(budget.wallMs / 60_000)} min in ${mode} mode). ${refusalTail(mode)}`,
124
+ };
125
+ }
126
+ if (kind === "dispatch" && budget.maxDispatches != null && counters.dispatches >= budget.maxDispatches) {
127
+ return {
128
+ reason: "dispatches",
129
+ message: `⚠ Turn budget exhausted: ${counters.dispatches} of ${budget.maxDispatches} ` +
130
+ `dispatch_agent calls used in ${mode} mode. ${refusalTail(mode)}`,
131
+ };
132
+ }
133
+ if (kind === "research" && budget.maxResearch != null && counters.research >= budget.maxResearch) {
134
+ return {
135
+ reason: "research",
136
+ message: `⚠ Turn budget exhausted: ${counters.research} of ${budget.maxResearch} ` +
137
+ `spawn_research calls used in ${mode} mode. ${refusalTail(mode)}`,
138
+ };
139
+ }
140
+ return null;
141
+ }
142
+
143
+ /**
144
+ * Recycle the specialist's accumulated session before this run? True when the
145
+ * session already served `recycleRuns` runs, its context reached a full window
146
+ * (HARD_RECYCLE_CONTEXT_PCT, not overridable), or it passed the configured
147
+ * RECYCLE_CONTEXT_PCT — resuming past any of those mostly re-bills stale
148
+ * context on every subsequent model call.
149
+ */
150
+ export function shouldRecycleSession(runsSinceFresh, contextPct, budget, thresholdPct = RECYCLE_CONTEXT_PCT) {
151
+ if (runsSinceFresh <= 0) return false;
152
+ if (contextPct >= HARD_RECYCLE_CONTEXT_PCT) return true;
153
+ if (budget.recycleRuns != null && runsSinceFresh >= budget.recycleRuns) return true;
154
+ return contextPct >= thresholdPct;
155
+ }
156
+
157
+ /**
158
+ * The one case recycling cannot fix: a *fresh* session already measured over a
159
+ * full window means a single run overflowed on its own, so there is no
160
+ * accumulated history to drop. Either `contextWindow` is wrong for that
161
+ * provider or the run genuinely ran over — both need a human, not a retry.
162
+ * Returns the diagnostic line, or null when recycling covers the situation.
163
+ */
164
+ export function contextOverflowDiagnostic(runsSinceFresh, contextPct, { agent = "agent", model = "unknown model" } = {}) {
165
+ if (runsSinceFresh > 0) return null;
166
+ if (!(contextPct >= HARD_RECYCLE_CONTEXT_PCT)) return null;
167
+ return (
168
+ `⚠ ${agent} measured ${Math.round(contextPct)}% context on a fresh session (${model}) — ` +
169
+ "recycling cannot help, one run overflowed the window on its own. Either the resolved " +
170
+ "contextWindow is wrong for this provider or the run genuinely ran over: check the model's " +
171
+ "declared window and narrow the task's inputs."
172
+ );
173
+ }
174
+
175
+ /** One-line status chip: "Mode: standard·small · 1/2 disp · 0/2 res". */
176
+ export function budgetStatusLine(mode, counters, budget, tier = null) {
177
+ const cap = (n) => (n == null ? "∞" : String(n));
178
+ const tierSuffix = tier ? `·${tier}` : "";
179
+ return `Mode: ${mode}${tierSuffix} · ${counters.dispatches}/${cap(budget.maxDispatches)} disp · ` +
180
+ `${counters.research}/${cap(budget.maxResearch)} res`;
181
+ }
@@ -0,0 +1,22 @@
1
+ import { existsSync } from "node:fs";
2
+ import { join, resolve } from "node:path";
3
+
4
+ const CONTINUE_ENTRY = /damage-control-continue[/\\]index\.ts$/;
5
+ const MISSING_SAFETY_ERROR = "damage-control-continue harness not found — guarded child dispatch refused";
6
+
7
+ /** Resolve only the surviving continue harness; never downgrade to an unguarded or hard-stop child. */
8
+ export function resolveSafetyHarness(cwd: string, argv: string[] = process.argv): string | null {
9
+ for (let i = 0; i < argv.length - 1; i++) {
10
+ if (argv[i] !== "-e" && argv[i] !== "--extension") continue;
11
+ const candidate = resolve(argv[i + 1]);
12
+ if (CONTINUE_ENTRY.test(candidate) && existsSync(candidate)) return candidate;
13
+ }
14
+ const local = join(cwd, ".pi", "harnesses", "damage-control-continue", "index.ts");
15
+ return existsSync(local) ? local : null;
16
+ }
17
+
18
+ export function requireSafetyHarness(path: string | null):
19
+ | { ok: true; extensions: string[] }
20
+ | { ok: false; error: string } {
21
+ return path ? { ok: true, extensions: [path] } : { ok: false, error: MISSING_SAFETY_ERROR };
22
+ }
@@ -0,0 +1,103 @@
1
+ import { execFileSync } from "node:child_process";
2
+
3
+ export function snapshotWorktree(cwd) {
4
+ const status = gitStatus(cwd);
5
+ if (status.skipped) return { skipped: true, reason: status.reason, paths: new Set() };
6
+ return { skipped: false, paths: new Set(status.paths) };
7
+ }
8
+
9
+ export function diffAgainst(snapshot, cwd) {
10
+ const current = snapshotWorktree(cwd);
11
+ if (snapshot?.skipped || current.skipped) {
12
+ return { skipped: true, reason: snapshot?.reason || current.reason || "scope gate skipped", paths: [] };
13
+ }
14
+ const before = snapshot?.paths instanceof Set ? snapshot.paths : new Set(snapshot?.paths || []);
15
+ const paths = [...current.paths].filter((p) => !before.has(p)).sort();
16
+ return { skipped: false, paths };
17
+ }
18
+
19
+ export function checkScope(changedPaths, scopeGlobs) {
20
+ const scopes = (scopeGlobs || []).map(normalizePath).filter(Boolean);
21
+ const inScope = [];
22
+ const outOfScope = [];
23
+ for (const rawPath of changedPaths || []) {
24
+ const changed = normalizePath(rawPath);
25
+ if (!changed) continue;
26
+ if (scopes.some((scope) => matchesScope(changed, scope))) inScope.push(changed);
27
+ else outOfScope.push(changed);
28
+ }
29
+ return { inScope: uniqueSorted(inScope), outOfScope: uniqueSorted(outOfScope) };
30
+ }
31
+
32
+ function gitStatus(cwd) {
33
+ try {
34
+ const output = execFileSync("git", ["-C", cwd, "status", "--porcelain", "--untracked-files=all"], {
35
+ encoding: "utf-8",
36
+ stdio: ["ignore", "pipe", "pipe"],
37
+ });
38
+ return { skipped: false, paths: parsePorcelain(output) };
39
+ } catch (err) {
40
+ return { skipped: true, reason: err?.message || "not a git worktree" };
41
+ }
42
+ }
43
+
44
+ function parsePorcelain(output) {
45
+ const paths = [];
46
+ for (const line of String(output || "").split(/\r?\n/)) {
47
+ if (!line.trim()) continue;
48
+ let file = line.slice(3).trim();
49
+ const rename = file.match(/ -> (.+)$/);
50
+ if (rename) file = rename[1];
51
+ paths.push(normalizePath(unquotePorcelainPath(file)));
52
+ }
53
+ return uniqueSorted(paths.filter(Boolean));
54
+ }
55
+
56
+ function matchesScope(changedPath, scope) {
57
+ if (hasGlob(scope)) return globToRegExp(scope).test(changedPath);
58
+ const dir = scope.endsWith("/") ? scope.slice(0, -1) : scope;
59
+ return changedPath === dir || changedPath.startsWith(`${dir}/`);
60
+ }
61
+
62
+ function hasGlob(scope) {
63
+ return /[*?]/.test(scope);
64
+ }
65
+
66
+ function globToRegExp(glob) {
67
+ let out = "^";
68
+ for (let i = 0; i < glob.length; i++) {
69
+ const c = glob[i];
70
+ if (c === "*") {
71
+ if (glob[i + 1] === "*") {
72
+ out += ".*";
73
+ i++;
74
+ } else {
75
+ out += "[^/]*";
76
+ }
77
+ } else {
78
+ out += escapeRegExp(c);
79
+ }
80
+ }
81
+ out += "$";
82
+ return new RegExp(out);
83
+ }
84
+
85
+ function normalizePath(value) {
86
+ return String(value || "").trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/");
87
+ }
88
+
89
+ function uniqueSorted(values) {
90
+ return [...new Set(values)].sort();
91
+ }
92
+
93
+ function unquotePorcelainPath(value) {
94
+ const trimmed = String(value || "").trim();
95
+ if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
96
+ try { return JSON.parse(trimmed); } catch { return trimmed.slice(1, -1); }
97
+ }
98
+ return trimmed;
99
+ }
100
+
101
+ function escapeRegExp(value) {
102
+ return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
103
+ }
@@ -0,0 +1,110 @@
1
+ // Session-file health — the pure policy behind never handing pi a session file
2
+ // it will refuse. `spawnPiAgent` passes `--session <file>` on every run, so one
3
+ // corrupt `<agentKey>.json` bricks a persona for the rest of the session: every
4
+ // dispatch dies in ~1s with an empty result, and drop + re-add does not help
5
+ // because the file survives the roster change.
6
+ //
7
+ // A pi session file is JSONL whose FIRST record is the header
8
+ // `{"type":"session","version":N,...}`. Both files that pi rejected in the
9
+ // field (`builder.json.corrupt-*`, `builder.json.invalid-gate-p`) start with a
10
+ // `{"type":"message",...}` record instead — they were truncated at the head, so
11
+ // the conversation begins mid-chain. That single check separates them from the
12
+ // session files that were healthy but retired for other reasons.
13
+
14
+ export const SESSION_HEADER_TYPE = "session";
15
+
16
+ /**
17
+ * Would pi accept this session file body? Returns `{ ok, reason }`; `reason` is
18
+ * null when ok, and a human-readable cause otherwise (it reaches the dispatcher
19
+ * verbatim, so it must explain what happened, not just that something did).
20
+ */
21
+ export function isUsablePiSession(text) {
22
+ const body = String(text ?? "");
23
+ if (!body.trim()) return { ok: false, reason: "session file is empty" };
24
+
25
+ const firstLine = body.split(/\r?\n/).find((line) => line.trim());
26
+ let header;
27
+ try {
28
+ header = JSON.parse(firstLine);
29
+ } catch {
30
+ return { ok: false, reason: "first record is not valid JSON — the file is truncated or not a pi session" };
31
+ }
32
+ if (!header || typeof header !== "object" || Array.isArray(header)) {
33
+ return { ok: false, reason: "first record is not a JSON object" };
34
+ }
35
+ if (header.type !== SESSION_HEADER_TYPE) {
36
+ return {
37
+ ok: false,
38
+ reason: `first record is "${header.type ?? "(no type)"}", not a "${SESSION_HEADER_TYPE}" header — ` +
39
+ "the file was truncated at the head and the conversation starts mid-chain",
40
+ };
41
+ }
42
+ return { ok: true, reason: null };
43
+ }
44
+
45
+ /** `builder.json` → `builder.json.corrupt-2026-07-25T09-14-02-123Z` (no colons: portable filename). */
46
+ export function quarantineName(file, now = new Date()) {
47
+ const stamp = new Date(now).toISOString().replace(/[:.]/g, "-");
48
+ return `${file}.corrupt-${stamp}`;
49
+ }
50
+
51
+ /**
52
+ * The observed post-hoc signature of a session file pi rejects: it exits
53
+ * non-zero having produced no output at all, and says so on stderr. Validation
54
+ * cannot catch every reason pi refuses a file, so this is the second net — and
55
+ * the run never started, which is what makes a retry safe.
56
+ */
57
+ export function isCorruptSessionExit({ code, output, stderr } = {}) {
58
+ if (code === 0 || code == null) return false;
59
+ if (String(output ?? "").trim()) return false;
60
+ return /not a valid pi session|invalid pi session/i.test(String(stderr ?? ""));
61
+ }
62
+
63
+ /**
64
+ * Unconditionally quarantine a file that pi itself rejected. This is distinct
65
+ * from `quarantineIfUnusable`: the local header check may consider the file
66
+ * healthy even though pi applies a stricter invariant. A clean retry is allowed
67
+ * only after the rejected path has actually been moved aside.
68
+ */
69
+ export function forceQuarantineSession(file, io) {
70
+ if (!io.existsSync(file)) return { ok: true, quarantined: null, error: null };
71
+ const target = quarantineName(file, io.now ? io.now() : new Date());
72
+ try {
73
+ io.renameSync(file, target);
74
+ return { ok: true, quarantined: target, error: null };
75
+ } catch (err) {
76
+ return {
77
+ ok: false,
78
+ quarantined: null,
79
+ error: `could not quarantine pi-rejected session: ${err instanceof Error ? err.message : String(err)}`,
80
+ };
81
+ }
82
+ }
83
+
84
+ /**
85
+ * Check `file` and move it aside when pi would reject it. `io` supplies the fs
86
+ * calls (`existsSync`, `readFileSync`, `renameSync`) and an optional `now`.
87
+ * Returns `{ usable, quarantined, reason }` — `quarantined` is the path the bad
88
+ * file was moved to, so the caller can name it for the human.
89
+ */
90
+ export function quarantineIfUnusable(file, io) {
91
+ if (!io.existsSync(file)) return { usable: false, quarantined: null, reason: null };
92
+
93
+ let verdict;
94
+ try {
95
+ verdict = isUsablePiSession(io.readFileSync(file, "utf-8"));
96
+ } catch (err) {
97
+ verdict = { ok: false, reason: `session file unreadable: ${err instanceof Error ? err.message : String(err)}` };
98
+ }
99
+ if (verdict.ok) return { usable: true, quarantined: null, reason: null };
100
+
101
+ const target = quarantineName(file, io.now ? io.now() : new Date());
102
+ try {
103
+ io.renameSync(file, target);
104
+ return { usable: false, quarantined: target, reason: verdict.reason };
105
+ } catch {
106
+ // Could not move it aside — still refuse to resume it. Starting clean
107
+ // overwrites the bad file, which is the outcome we want anyway.
108
+ return { usable: false, quarantined: null, reason: verdict.reason };
109
+ }
110
+ }