@chankov/agent-fleet 1.0.0 → 1.0.2

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 (598) hide show
  1. package/.pi/agents/model-profiles.yaml +2 -2
  2. package/.pi/extensions/package-lock.json +77 -45
  3. package/.pi/harnesses/agent-hub/README.md +116 -16
  4. package/.pi/harnesses/agent-hub/budget-continuation.ts +73 -0
  5. package/.pi/harnesses/agent-hub/capability-confirmation.ts +47 -0
  6. package/.pi/harnesses/agent-hub/capability-packs.ts +180 -0
  7. package/.pi/harnesses/agent-hub/context-budget-snapshot.ts +105 -0
  8. package/.pi/harnesses/agent-hub/context-pressure.ts +191 -0
  9. package/.pi/harnesses/agent-hub/hub-state-audit.js +73 -0
  10. package/.pi/harnesses/agent-hub/index.ts +1095 -465
  11. package/.pi/harnesses/agent-hub/package.json +1 -1
  12. package/.pi/harnesses/agent-hub/posture.ts +72 -17
  13. package/.pi/harnesses/agent-hub/run-budget.js +73 -13
  14. package/.pi/harnesses/agent-hub/spawn.ts +14 -2
  15. package/.pi/harnesses/ask-user-remote/index.ts +59 -4
  16. package/.pi/harnesses/coms/package.json +1 -1
  17. package/.pi/harnesses/damage-control-continue/package.json +1 -1
  18. package/.pi/harnesses/lib/context-budget-child-prompt.ts +179 -0
  19. package/.pi/harnesses/lib/context-budget-hub-prompt.ts +116 -0
  20. package/.pi/harnesses/lib/context-budget-view.ts +107 -0
  21. package/.pi/harnesses/lib/context-budget.ts +114 -0
  22. package/.pi/harnesses/lib/fleet-dashboard-ops.ts +37 -0
  23. package/.pi/harnesses/lib/fleet-detail-view.ts +92 -2
  24. package/.pi/harnesses/package-lock.json +73 -80
  25. package/.versions/1.0.1/.pi/agents/dispatch-policy.yaml +32 -0
  26. package/.versions/1.0.1/.pi/agents/model-profiles.yaml +27 -0
  27. package/.versions/1.0.1/.pi/agents/peers.yaml +142 -0
  28. package/.versions/1.0.1/.pi/agents/teams.yaml +41 -0
  29. package/.versions/1.0.1/.pi/damage-control-rules.yaml +297 -0
  30. package/.versions/1.0.1/.pi/extensions/agent-fleet-update-check/README.md +57 -0
  31. package/.versions/1.0.1/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  32. package/.versions/1.0.1/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  33. package/.versions/1.0.1/.pi/extensions/btw/README.md +120 -0
  34. package/.versions/1.0.1/.pi/extensions/btw/index.ts +914 -0
  35. package/.versions/1.0.1/.pi/extensions/btw/package.json +6 -0
  36. package/.versions/1.0.1/.pi/extensions/btw/state.js +179 -0
  37. package/.versions/1.0.1/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
  38. package/.versions/1.0.1/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
  39. package/.versions/1.0.1/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  40. package/.versions/1.0.1/.pi/extensions/compact-and-continue/README.md +42 -0
  41. package/.versions/1.0.1/.pi/extensions/compact-and-continue/index.ts +120 -0
  42. package/.versions/1.0.1/.pi/extensions/compact-and-continue/package.json +6 -0
  43. package/.versions/1.0.1/.pi/extensions/mcp-bridge/README.md +46 -0
  44. package/.versions/1.0.1/.pi/extensions/mcp-bridge/index.ts +206 -0
  45. package/.versions/1.0.1/.pi/extensions/mcp-bridge/package.json +6 -0
  46. package/.versions/1.0.1/.pi/extensions/package-lock.json +1143 -0
  47. package/.versions/1.0.1/.pi/extensions/package.json +9 -0
  48. package/.versions/1.0.1/.pi/extensions/pi-voice-stt/README.md +205 -0
  49. package/.versions/1.0.1/.pi/extensions/pi-voice-stt/config.ts +198 -0
  50. package/.versions/1.0.1/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  51. package/.versions/1.0.1/.pi/extensions/pi-voice-stt/index.ts +248 -0
  52. package/.versions/1.0.1/.pi/extensions/pi-voice-stt/package.json +6 -0
  53. package/.versions/1.0.1/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  54. package/.versions/1.0.1/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  55. package/.versions/1.0.1/.pi/harnesses/agent-hub/README.md +1065 -0
  56. package/.versions/1.0.1/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  57. package/.versions/1.0.1/.pi/harnesses/agent-hub/artifacts.js +146 -0
  58. package/.versions/1.0.1/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
  59. package/.versions/1.0.1/.pi/harnesses/agent-hub/backend-policy.js +174 -0
  60. package/.versions/1.0.1/.pi/harnesses/agent-hub/context-window.js +106 -0
  61. package/.versions/1.0.1/.pi/harnesses/agent-hub/delegate.ts +435 -0
  62. package/.versions/1.0.1/.pi/harnesses/agent-hub/docs-lane.js +122 -0
  63. package/.versions/1.0.1/.pi/harnesses/agent-hub/drift-watchdog.js +211 -0
  64. package/.versions/1.0.1/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  65. package/.versions/1.0.1/.pi/harnesses/agent-hub/external-blocker.js +85 -0
  66. package/.versions/1.0.1/.pi/harnesses/agent-hub/footer.ts +35 -0
  67. package/.versions/1.0.1/.pi/harnesses/agent-hub/helpers.ts +266 -0
  68. package/.versions/1.0.1/.pi/harnesses/agent-hub/hub-state-audit.js +55 -0
  69. package/.versions/1.0.1/.pi/harnesses/agent-hub/index.ts +9343 -0
  70. package/.versions/1.0.1/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  71. package/.versions/1.0.1/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
  72. package/.versions/1.0.1/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
  73. package/.versions/1.0.1/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  74. package/.versions/1.0.1/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  75. package/.versions/1.0.1/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  76. package/.versions/1.0.1/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  77. package/.versions/1.0.1/.pi/harnesses/agent-hub/monitor-session-bridge.ts +266 -0
  78. package/.versions/1.0.1/.pi/harnesses/agent-hub/package.json +7 -0
  79. package/.versions/1.0.1/.pi/harnesses/agent-hub/peer-spawn-plan.ts +116 -0
  80. package/.versions/1.0.1/.pi/harnesses/agent-hub/posture.ts +103 -0
  81. package/.versions/1.0.1/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
  82. package/.versions/1.0.1/.pi/harnesses/agent-hub/research-retention.js +34 -0
  83. package/.versions/1.0.1/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  84. package/.versions/1.0.1/.pi/harnesses/agent-hub/return-contract.js +293 -0
  85. package/.versions/1.0.1/.pi/harnesses/agent-hub/return-extract.js +75 -0
  86. package/.versions/1.0.1/.pi/harnesses/agent-hub/review-findings.js +102 -0
  87. package/.versions/1.0.1/.pi/harnesses/agent-hub/run-budget.js +540 -0
  88. package/.versions/1.0.1/.pi/harnesses/agent-hub/run-namespace.js +87 -0
  89. package/.versions/1.0.1/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  90. package/.versions/1.0.1/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  91. package/.versions/1.0.1/.pi/harnesses/agent-hub/session-health.js +110 -0
  92. package/.versions/1.0.1/.pi/harnesses/agent-hub/spawn.ts +354 -0
  93. package/.versions/1.0.1/.pi/harnesses/agent-hub/version.ts +42 -0
  94. package/.versions/1.0.1/.pi/harnesses/ask-user-remote/README.md +53 -0
  95. package/.versions/1.0.1/.pi/harnesses/ask-user-remote/index.ts +477 -0
  96. package/.versions/1.0.1/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  97. package/.versions/1.0.1/.pi/harnesses/coms/README.md +100 -0
  98. package/.versions/1.0.1/.pi/harnesses/coms/index.ts +1767 -0
  99. package/.versions/1.0.1/.pi/harnesses/coms/package.json +7 -0
  100. package/.versions/1.0.1/.pi/harnesses/coms/version.ts +42 -0
  101. package/.versions/1.0.1/.pi/harnesses/damage-control-continue/README.md +124 -0
  102. package/.versions/1.0.1/.pi/harnesses/damage-control-continue/index.ts +536 -0
  103. package/.versions/1.0.1/.pi/harnesses/damage-control-continue/package.json +7 -0
  104. package/.versions/1.0.1/.pi/harnesses/damage-control-continue/version.ts +42 -0
  105. package/.versions/1.0.1/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
  106. package/.versions/1.0.1/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  107. package/.versions/1.0.1/.pi/harnesses/lib/fleet-dashboard-ops.ts +155 -0
  108. package/.versions/1.0.1/.pi/harnesses/lib/fleet-dashboard-view.ts +140 -0
  109. package/.versions/1.0.1/.pi/harnesses/lib/fleet-detail-view.ts +43 -0
  110. package/.versions/1.0.1/.pi/harnesses/lib/fleet-overlay.ts +26 -0
  111. package/.versions/1.0.1/.pi/harnesses/lib/fleet-panel.ts +34 -0
  112. package/.versions/1.0.1/.pi/harnesses/lib/fleet-read-model.ts +131 -0
  113. package/.versions/1.0.1/.pi/harnesses/lib/fleet-selection.ts +24 -0
  114. package/.versions/1.0.1/.pi/harnesses/lib/herdr-client.ts +472 -0
  115. package/.versions/1.0.1/.pi/harnesses/lib/herdr-presence.ts +399 -0
  116. package/.versions/1.0.1/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
  117. package/.versions/1.0.1/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  118. package/.versions/1.0.1/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
  119. package/.versions/1.0.1/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  120. package/.versions/1.0.1/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
  121. package/.versions/1.0.1/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  122. package/.versions/1.0.1/.pi/harnesses/lib/spawned-peers.js +190 -0
  123. package/.versions/1.0.1/.pi/harnesses/package-lock.json +2046 -0
  124. package/.versions/1.0.1/.pi/harnesses/package.json +10 -0
  125. package/.versions/1.0.1/.pi/prompts/af-build.md +24 -0
  126. package/.versions/1.0.1/.pi/prompts/af-code-simplify.md +22 -0
  127. package/.versions/1.0.1/.pi/prompts/af-plan.md +16 -0
  128. package/.versions/1.0.1/.pi/prompts/af-review.md +16 -0
  129. package/.versions/1.0.1/.pi/prompts/af-set-hermes-telegram.md +15 -0
  130. package/.versions/1.0.1/.pi/prompts/af-set-hermes-watchdog.md +6 -0
  131. package/.versions/1.0.1/.pi/prompts/af-ship.md +17 -0
  132. package/.versions/1.0.1/.pi/prompts/af-spec.md +15 -0
  133. package/.versions/1.0.1/.pi/prompts/af-test.md +19 -0
  134. package/.versions/1.0.1/.pi/skills/bowser/SKILL.md +145 -0
  135. package/.versions/1.0.1/.version +1 -0
  136. package/.versions/1.0.1/agents/architect.md +24 -0
  137. package/.versions/1.0.1/agents/bowser.md +27 -0
  138. package/.versions/1.0.1/agents/builder.md +54 -0
  139. package/.versions/1.0.1/agents/code-reviewer.md +208 -0
  140. package/.versions/1.0.1/agents/deep-researcher.md +32 -0
  141. package/.versions/1.0.1/agents/documenter.md +18 -0
  142. package/.versions/1.0.1/agents/orchestrator.md +72 -0
  143. package/.versions/1.0.1/agents/plan-reviewer.md +83 -0
  144. package/.versions/1.0.1/agents/planner.md +70 -0
  145. package/.versions/1.0.1/agents/releaser.md +24 -0
  146. package/.versions/1.0.1/agents/researcher.md +28 -0
  147. package/.versions/1.0.1/agents/security-auditor.md +167 -0
  148. package/.versions/1.0.1/agents/test-engineer.md +153 -0
  149. package/.versions/1.0.1/agents/web-debugger.md +43 -0
  150. package/.versions/1.0.1/agents/web-performance-auditor.md +193 -0
  151. package/.versions/1.0.1/bin/catalog/harness-runtime-closure.json +38 -0
  152. package/.versions/1.0.1/codex/CONDUCTOR.md +148 -0
  153. package/.versions/1.0.1/docs/ARCHITECTURE.md +337 -0
  154. package/.versions/1.0.1/docs/agent-fleet-setup.md +437 -0
  155. package/.versions/1.0.1/docs/claude-code-coms-bridge.md +128 -0
  156. package/.versions/1.0.1/docs/codex-remote-conductor.md +170 -0
  157. package/.versions/1.0.1/docs/coms-hermes-bridge.md +189 -0
  158. package/.versions/1.0.1/docs/getting-started.md +98 -0
  159. package/.versions/1.0.1/docs/npm-install.md +292 -0
  160. package/.versions/1.0.1/docs/pi-extensions.md +412 -0
  161. package/.versions/1.0.1/docs/pi-setup.md +74 -0
  162. package/.versions/1.0.1/docs/skill-anatomy.md +150 -0
  163. package/.versions/1.0.1/hermes/README.md +347 -0
  164. package/.versions/1.0.1/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
  165. package/.versions/1.0.1/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
  166. package/.versions/1.0.1/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  167. package/.versions/1.0.1/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  168. package/.versions/1.0.1/hermes/gates/gate-o-capability.md +8 -0
  169. package/.versions/1.0.1/hermes/gates/gate-o-validator-fixtures.json +1 -0
  170. package/.versions/1.0.1/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +770 -0
  171. package/.versions/1.0.1/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
  172. package/.versions/1.0.1/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
  173. package/.versions/1.0.1/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
  174. package/.versions/1.0.1/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
  175. package/.versions/1.0.1/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
  176. package/.versions/1.0.1/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
  177. package/.versions/1.0.1/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
  178. package/.versions/1.0.1/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
  179. package/.versions/1.0.1/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
  180. package/.versions/1.0.1/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
  181. package/.versions/1.0.1/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  182. package/.versions/1.0.1/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  183. package/.versions/1.0.1/hermes/skills/hub-conductor/SKILL.md +84 -0
  184. package/.versions/1.0.1/hermes/skills/hub-liaison/SKILL.md +84 -0
  185. package/.versions/1.0.1/hermes/skills/hub-watchdog/SKILL.md +76 -0
  186. package/.versions/1.0.1/hermes/skills/hub-watchdog/manifest.json +1 -0
  187. package/.versions/1.0.1/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
  188. package/.versions/1.0.1/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
  189. package/.versions/1.0.1/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
  190. package/.versions/1.0.1/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
  191. package/.versions/1.0.1/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
  192. package/.versions/1.0.1/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
  193. package/.versions/1.0.1/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
  194. package/.versions/1.0.1/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
  195. package/.versions/1.0.1/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
  196. package/.versions/1.0.1/hermes/watchdog-tests/__init__.py +0 -0
  197. package/.versions/1.0.1/hooks/coms-stop-hook.mjs +84 -0
  198. package/.versions/1.0.1/install-manifest.json +2745 -0
  199. package/.versions/1.0.1/justfile +272 -0
  200. package/.versions/1.0.1/manifest-meta.json +882 -0
  201. package/.versions/1.0.1/references/accessibility-checklist.md +160 -0
  202. package/.versions/1.0.1/references/definition-of-done.md +67 -0
  203. package/.versions/1.0.1/references/fleet-coordination-patterns.md +151 -0
  204. package/.versions/1.0.1/references/observability-checklist.md +91 -0
  205. package/.versions/1.0.1/references/orchestration-patterns.md +370 -0
  206. package/.versions/1.0.1/references/performance-checklist.md +153 -0
  207. package/.versions/1.0.1/references/prompting-patterns.md +380 -0
  208. package/.versions/1.0.1/references/security-checklist.md +179 -0
  209. package/.versions/1.0.1/references/testing-patterns.md +236 -0
  210. package/.versions/1.0.1/scripts/codex-conductor.ts +41 -0
  211. package/.versions/1.0.1/scripts/codex-remote-control.ts +167 -0
  212. package/.versions/1.0.1/scripts/coms-claude-bridge.ts +411 -0
  213. package/.versions/1.0.1/scripts/coms-cli.ts +484 -0
  214. package/.versions/1.0.1/scripts/coms-hermes-bridge.ts +413 -0
  215. package/.versions/1.0.1/scripts/fleet.ts +185 -0
  216. package/.versions/1.0.1/scripts/hermes-monitor-capability-runner.ts +25 -0
  217. package/.versions/1.0.1/scripts/hermes-monitor-scenario.ts +474 -0
  218. package/.versions/1.0.1/scripts/hermes-watchdog-capability-probe.ts +45 -0
  219. package/.versions/1.0.1/scripts/install-hermes-plugin.sh +180 -0
  220. package/.versions/1.0.1/scripts/lib/claude-bridge-core.ts +210 -0
  221. package/.versions/1.0.1/scripts/lib/codex-conductor.ts +88 -0
  222. package/.versions/1.0.1/scripts/lib/codex-remote-control.ts +480 -0
  223. package/.versions/1.0.1/scripts/lib/coms-envelope.ts +582 -0
  224. package/.versions/1.0.1/scripts/lib/fake-herdr-server.ts +88 -0
  225. package/.versions/1.0.1/scripts/lib/fleet-command.ts +266 -0
  226. package/.versions/1.0.1/scripts/lib/herdr-layout.ts +281 -0
  227. package/.versions/1.0.1/scripts/lib/hermes-bridge-core.ts +241 -0
  228. package/.versions/1.0.1/scripts/lib/hermes-monitor-events.ts +1 -0
  229. package/.versions/1.0.1/scripts/lib/hermes-monitor-herdr.ts +2 -0
  230. package/.versions/1.0.1/scripts/lib/hermes-monitor-model.ts +3 -0
  231. package/.versions/1.0.1/scripts/lib/hermes-monitor-registry.ts +2 -0
  232. package/.versions/1.0.1/scripts/lib/hermes-monitor-socket.ts +2 -0
  233. package/.versions/1.0.1/scripts/lib/hermes-monitor-store.ts +2 -0
  234. package/.versions/1.0.1/scripts/lib/monitor-env.ts +146 -0
  235. package/.versions/1.0.1/scripts/lib/peer-launch.ts +318 -0
  236. package/.versions/1.0.1/scripts/lib/persona-banner.ts +62 -0
  237. package/.versions/1.0.1/scripts/lib/spawn-stagger.ts +101 -0
  238. package/.versions/1.0.1/scripts/lib/team-project.ts +213 -0
  239. package/.versions/1.0.1/scripts/lib/team-snapshot.ts +147 -0
  240. package/.versions/1.0.1/scripts/peer-banner.ts +40 -0
  241. package/.versions/1.0.1/scripts/peer-launch.ts +259 -0
  242. package/.versions/1.0.1/scripts/team-snapshot.ts +237 -0
  243. package/.versions/1.0.1/scripts/team-up.ts +406 -0
  244. package/.versions/1.0.1/skills/_internal/grilling.md +11 -0
  245. package/.versions/1.0.1/skills/browser-testing-with-devtools/SKILL.md +351 -0
  246. package/.versions/1.0.1/skills/code-review-and-quality/SKILL.md +381 -0
  247. package/.versions/1.0.1/skills/compound-learning/SKILL.md +137 -0
  248. package/.versions/1.0.1/skills/context-engineering/SKILL.md +291 -0
  249. package/.versions/1.0.1/skills/deprecation-and-migration/SKILL.md +206 -0
  250. package/.versions/1.0.1/skills/designing-agents/SKILL.md +394 -0
  251. package/.versions/1.0.1/skills/designing-agents/pi-harness-authoring.md +222 -0
  252. package/.versions/1.0.1/skills/frontend-ui-engineering/SKILL.md +328 -0
  253. package/.versions/1.0.1/skills/git-workflow-and-versioning/SKILL.md +316 -0
  254. package/.versions/1.0.1/skills/idea-refine/SKILL.md +182 -0
  255. package/.versions/1.0.1/skills/idea-refine/examples.md +238 -0
  256. package/.versions/1.0.1/skills/idea-refine/frameworks.md +99 -0
  257. package/.versions/1.0.1/skills/idea-refine/refinement-criteria.md +113 -0
  258. package/.versions/1.0.1/skills/idea-refine/scripts/idea-refine.sh +15 -0
  259. package/.versions/1.0.1/skills/incremental-implementation/SKILL.md +287 -0
  260. package/.versions/1.0.1/skills/interview-me/SKILL.md +226 -0
  261. package/.versions/1.0.1/skills/orchestration-verification/SKILL.md +181 -0
  262. package/.versions/1.0.1/skills/peer-coms/SKILL.md +90 -0
  263. package/.versions/1.0.1/skills/performance-optimization/SKILL.md +350 -0
  264. package/.versions/1.0.1/skills/planning-and-task-breakdown/SKILL.md +254 -0
  265. package/.versions/1.0.1/skills/security-and-hardening/SKILL.md +461 -0
  266. package/.versions/1.0.1/skills/spec-driven-development/SKILL.md +257 -0
  267. package/.versions/1.0.1/skills/using-agent-skills/SKILL.md +199 -0
  268. package/.versions/1.0.1/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  269. package/.versions/1.0.1/vendor/agent-skills-upstream/LICENSE +21 -0
  270. package/.versions/1.0.1/vendor/agent-skills-upstream/README.md +11 -0
  271. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  272. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  273. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  274. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  275. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  276. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  277. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  278. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  279. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  280. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  281. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  282. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  283. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  284. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  285. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  286. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  287. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  288. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  289. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  290. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  291. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  292. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  293. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  294. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  295. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  296. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  297. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  298. package/.versions/1.0.1/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  299. package/.versions/1.0.2/.pi/agents/dispatch-policy.yaml +32 -0
  300. package/.versions/1.0.2/.pi/agents/model-profiles.yaml +27 -0
  301. package/.versions/1.0.2/.pi/agents/peers.yaml +142 -0
  302. package/.versions/1.0.2/.pi/agents/teams.yaml +41 -0
  303. package/.versions/1.0.2/.pi/damage-control-rules.yaml +297 -0
  304. package/.versions/1.0.2/.pi/extensions/agent-fleet-update-check/README.md +57 -0
  305. package/.versions/1.0.2/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  306. package/.versions/1.0.2/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  307. package/.versions/1.0.2/.pi/extensions/btw/README.md +120 -0
  308. package/.versions/1.0.2/.pi/extensions/btw/index.ts +914 -0
  309. package/.versions/1.0.2/.pi/extensions/btw/package.json +6 -0
  310. package/.versions/1.0.2/.pi/extensions/btw/state.js +179 -0
  311. package/.versions/1.0.2/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
  312. package/.versions/1.0.2/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
  313. package/.versions/1.0.2/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  314. package/.versions/1.0.2/.pi/extensions/compact-and-continue/README.md +42 -0
  315. package/.versions/1.0.2/.pi/extensions/compact-and-continue/index.ts +120 -0
  316. package/.versions/1.0.2/.pi/extensions/compact-and-continue/package.json +6 -0
  317. package/.versions/1.0.2/.pi/extensions/mcp-bridge/README.md +46 -0
  318. package/.versions/1.0.2/.pi/extensions/mcp-bridge/index.ts +206 -0
  319. package/.versions/1.0.2/.pi/extensions/mcp-bridge/package.json +6 -0
  320. package/.versions/1.0.2/.pi/extensions/package-lock.json +1175 -0
  321. package/.versions/1.0.2/.pi/extensions/package.json +9 -0
  322. package/.versions/1.0.2/.pi/extensions/pi-voice-stt/README.md +205 -0
  323. package/.versions/1.0.2/.pi/extensions/pi-voice-stt/config.ts +198 -0
  324. package/.versions/1.0.2/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  325. package/.versions/1.0.2/.pi/extensions/pi-voice-stt/index.ts +248 -0
  326. package/.versions/1.0.2/.pi/extensions/pi-voice-stt/package.json +6 -0
  327. package/.versions/1.0.2/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  328. package/.versions/1.0.2/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  329. package/.versions/1.0.2/.pi/harnesses/agent-hub/README.md +1156 -0
  330. package/.versions/1.0.2/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  331. package/.versions/1.0.2/.pi/harnesses/agent-hub/artifacts.js +146 -0
  332. package/.versions/1.0.2/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
  333. package/.versions/1.0.2/.pi/harnesses/agent-hub/backend-policy.js +174 -0
  334. package/.versions/1.0.2/.pi/harnesses/agent-hub/budget-continuation.ts +73 -0
  335. package/.versions/1.0.2/.pi/harnesses/agent-hub/capability-confirmation.ts +47 -0
  336. package/.versions/1.0.2/.pi/harnesses/agent-hub/capability-packs.ts +180 -0
  337. package/.versions/1.0.2/.pi/harnesses/agent-hub/context-budget-snapshot.ts +105 -0
  338. package/.versions/1.0.2/.pi/harnesses/agent-hub/context-pressure.ts +191 -0
  339. package/.versions/1.0.2/.pi/harnesses/agent-hub/context-window.js +106 -0
  340. package/.versions/1.0.2/.pi/harnesses/agent-hub/delegate.ts +435 -0
  341. package/.versions/1.0.2/.pi/harnesses/agent-hub/docs-lane.js +122 -0
  342. package/.versions/1.0.2/.pi/harnesses/agent-hub/drift-watchdog.js +211 -0
  343. package/.versions/1.0.2/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  344. package/.versions/1.0.2/.pi/harnesses/agent-hub/external-blocker.js +85 -0
  345. package/.versions/1.0.2/.pi/harnesses/agent-hub/footer.ts +35 -0
  346. package/.versions/1.0.2/.pi/harnesses/agent-hub/helpers.ts +266 -0
  347. package/.versions/1.0.2/.pi/harnesses/agent-hub/hub-state-audit.js +73 -0
  348. package/.versions/1.0.2/.pi/harnesses/agent-hub/index.ts +9909 -0
  349. package/.versions/1.0.2/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  350. package/.versions/1.0.2/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
  351. package/.versions/1.0.2/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
  352. package/.versions/1.0.2/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  353. package/.versions/1.0.2/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  354. package/.versions/1.0.2/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  355. package/.versions/1.0.2/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  356. package/.versions/1.0.2/.pi/harnesses/agent-hub/monitor-session-bridge.ts +266 -0
  357. package/.versions/1.0.2/.pi/harnesses/agent-hub/package.json +7 -0
  358. package/.versions/1.0.2/.pi/harnesses/agent-hub/peer-spawn-plan.ts +116 -0
  359. package/.versions/1.0.2/.pi/harnesses/agent-hub/posture.ts +158 -0
  360. package/.versions/1.0.2/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
  361. package/.versions/1.0.2/.pi/harnesses/agent-hub/research-retention.js +34 -0
  362. package/.versions/1.0.2/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  363. package/.versions/1.0.2/.pi/harnesses/agent-hub/return-contract.js +293 -0
  364. package/.versions/1.0.2/.pi/harnesses/agent-hub/return-extract.js +75 -0
  365. package/.versions/1.0.2/.pi/harnesses/agent-hub/review-findings.js +102 -0
  366. package/.versions/1.0.2/.pi/harnesses/agent-hub/run-budget.js +539 -0
  367. package/.versions/1.0.2/.pi/harnesses/agent-hub/run-namespace.js +87 -0
  368. package/.versions/1.0.2/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  369. package/.versions/1.0.2/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  370. package/.versions/1.0.2/.pi/harnesses/agent-hub/session-health.js +110 -0
  371. package/.versions/1.0.2/.pi/harnesses/agent-hub/spawn.ts +366 -0
  372. package/.versions/1.0.2/.pi/harnesses/agent-hub/version.ts +42 -0
  373. package/.versions/1.0.2/.pi/harnesses/ask-user-remote/README.md +53 -0
  374. package/.versions/1.0.2/.pi/harnesses/ask-user-remote/index.ts +532 -0
  375. package/.versions/1.0.2/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  376. package/.versions/1.0.2/.pi/harnesses/coms/README.md +100 -0
  377. package/.versions/1.0.2/.pi/harnesses/coms/index.ts +1767 -0
  378. package/.versions/1.0.2/.pi/harnesses/coms/package.json +7 -0
  379. package/.versions/1.0.2/.pi/harnesses/coms/version.ts +42 -0
  380. package/.versions/1.0.2/.pi/harnesses/damage-control-continue/README.md +124 -0
  381. package/.versions/1.0.2/.pi/harnesses/damage-control-continue/index.ts +536 -0
  382. package/.versions/1.0.2/.pi/harnesses/damage-control-continue/package.json +7 -0
  383. package/.versions/1.0.2/.pi/harnesses/damage-control-continue/version.ts +42 -0
  384. package/.versions/1.0.2/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
  385. package/.versions/1.0.2/.pi/harnesses/lib/context-budget-child-prompt.ts +179 -0
  386. package/.versions/1.0.2/.pi/harnesses/lib/context-budget-hub-prompt.ts +116 -0
  387. package/.versions/1.0.2/.pi/harnesses/lib/context-budget-view.ts +107 -0
  388. package/.versions/1.0.2/.pi/harnesses/lib/context-budget.ts +114 -0
  389. package/.versions/1.0.2/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  390. package/.versions/1.0.2/.pi/harnesses/lib/fixtures/context-budget-profiles.json +11 -0
  391. package/.versions/1.0.2/.pi/harnesses/lib/fixtures/hub-prompt-operator.legacy.txt +73 -0
  392. package/.versions/1.0.2/.pi/harnesses/lib/fixtures/hub-prompt-orchestrator.legacy.txt +73 -0
  393. package/.versions/1.0.2/.pi/harnesses/lib/fleet-dashboard-ops.ts +155 -0
  394. package/.versions/1.0.2/.pi/harnesses/lib/fleet-dashboard-view.ts +140 -0
  395. package/.versions/1.0.2/.pi/harnesses/lib/fleet-detail-view.ts +133 -0
  396. package/.versions/1.0.2/.pi/harnesses/lib/fleet-overlay.ts +26 -0
  397. package/.versions/1.0.2/.pi/harnesses/lib/fleet-panel.ts +34 -0
  398. package/.versions/1.0.2/.pi/harnesses/lib/fleet-read-model.ts +131 -0
  399. package/.versions/1.0.2/.pi/harnesses/lib/fleet-selection.ts +24 -0
  400. package/.versions/1.0.2/.pi/harnesses/lib/herdr-client.ts +472 -0
  401. package/.versions/1.0.2/.pi/harnesses/lib/herdr-presence.ts +399 -0
  402. package/.versions/1.0.2/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
  403. package/.versions/1.0.2/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  404. package/.versions/1.0.2/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
  405. package/.versions/1.0.2/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  406. package/.versions/1.0.2/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
  407. package/.versions/1.0.2/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  408. package/.versions/1.0.2/.pi/harnesses/lib/spawned-peers.js +190 -0
  409. package/.versions/1.0.2/.pi/harnesses/package-lock.json +2039 -0
  410. package/.versions/1.0.2/.pi/harnesses/package.json +10 -0
  411. package/.versions/1.0.2/.pi/prompts/af-build.md +24 -0
  412. package/.versions/1.0.2/.pi/prompts/af-code-simplify.md +22 -0
  413. package/.versions/1.0.2/.pi/prompts/af-plan.md +16 -0
  414. package/.versions/1.0.2/.pi/prompts/af-review.md +16 -0
  415. package/.versions/1.0.2/.pi/prompts/af-set-hermes-telegram.md +15 -0
  416. package/.versions/1.0.2/.pi/prompts/af-set-hermes-watchdog.md +6 -0
  417. package/.versions/1.0.2/.pi/prompts/af-ship.md +17 -0
  418. package/.versions/1.0.2/.pi/prompts/af-spec.md +15 -0
  419. package/.versions/1.0.2/.pi/prompts/af-test.md +19 -0
  420. package/.versions/1.0.2/.pi/skills/bowser/SKILL.md +145 -0
  421. package/.versions/1.0.2/.version +1 -0
  422. package/.versions/1.0.2/agents/architect.md +24 -0
  423. package/.versions/1.0.2/agents/bowser.md +27 -0
  424. package/.versions/1.0.2/agents/builder.md +54 -0
  425. package/.versions/1.0.2/agents/code-reviewer.md +208 -0
  426. package/.versions/1.0.2/agents/deep-researcher.md +32 -0
  427. package/.versions/1.0.2/agents/documenter.md +18 -0
  428. package/.versions/1.0.2/agents/orchestrator.md +20 -0
  429. package/.versions/1.0.2/agents/plan-reviewer.md +83 -0
  430. package/.versions/1.0.2/agents/planner.md +70 -0
  431. package/.versions/1.0.2/agents/releaser.md +24 -0
  432. package/.versions/1.0.2/agents/researcher.md +28 -0
  433. package/.versions/1.0.2/agents/security-auditor.md +167 -0
  434. package/.versions/1.0.2/agents/test-engineer.md +153 -0
  435. package/.versions/1.0.2/agents/web-debugger.md +43 -0
  436. package/.versions/1.0.2/agents/web-performance-auditor.md +193 -0
  437. package/.versions/1.0.2/bin/catalog/harness-runtime-closure.json +38 -0
  438. package/.versions/1.0.2/codex/CONDUCTOR.md +148 -0
  439. package/.versions/1.0.2/docs/ARCHITECTURE.md +369 -0
  440. package/.versions/1.0.2/docs/agent-fleet-setup.md +468 -0
  441. package/.versions/1.0.2/docs/claude-code-coms-bridge.md +128 -0
  442. package/.versions/1.0.2/docs/codex-remote-conductor.md +170 -0
  443. package/.versions/1.0.2/docs/coms-hermes-bridge.md +189 -0
  444. package/.versions/1.0.2/docs/getting-started.md +98 -0
  445. package/.versions/1.0.2/docs/npm-install.md +292 -0
  446. package/.versions/1.0.2/docs/pi-extensions.md +439 -0
  447. package/.versions/1.0.2/docs/pi-setup.md +74 -0
  448. package/.versions/1.0.2/docs/skill-anatomy.md +150 -0
  449. package/.versions/1.0.2/hermes/README.md +347 -0
  450. package/.versions/1.0.2/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
  451. package/.versions/1.0.2/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
  452. package/.versions/1.0.2/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  453. package/.versions/1.0.2/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  454. package/.versions/1.0.2/hermes/gates/gate-o-capability.md +8 -0
  455. package/.versions/1.0.2/hermes/gates/gate-o-validator-fixtures.json +1 -0
  456. package/.versions/1.0.2/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +770 -0
  457. package/.versions/1.0.2/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
  458. package/.versions/1.0.2/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
  459. package/.versions/1.0.2/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
  460. package/.versions/1.0.2/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
  461. package/.versions/1.0.2/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
  462. package/.versions/1.0.2/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
  463. package/.versions/1.0.2/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
  464. package/.versions/1.0.2/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
  465. package/.versions/1.0.2/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
  466. package/.versions/1.0.2/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
  467. package/.versions/1.0.2/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  468. package/.versions/1.0.2/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  469. package/.versions/1.0.2/hermes/skills/hub-conductor/SKILL.md +84 -0
  470. package/.versions/1.0.2/hermes/skills/hub-liaison/SKILL.md +84 -0
  471. package/.versions/1.0.2/hermes/skills/hub-watchdog/SKILL.md +76 -0
  472. package/.versions/1.0.2/hermes/skills/hub-watchdog/manifest.json +1 -0
  473. package/.versions/1.0.2/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
  474. package/.versions/1.0.2/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
  475. package/.versions/1.0.2/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
  476. package/.versions/1.0.2/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
  477. package/.versions/1.0.2/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
  478. package/.versions/1.0.2/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
  479. package/.versions/1.0.2/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
  480. package/.versions/1.0.2/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
  481. package/.versions/1.0.2/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
  482. package/.versions/1.0.2/hermes/watchdog-tests/__init__.py +0 -0
  483. package/.versions/1.0.2/hooks/coms-stop-hook.mjs +84 -0
  484. package/.versions/1.0.2/install-manifest.json +2745 -0
  485. package/.versions/1.0.2/justfile +272 -0
  486. package/.versions/1.0.2/manifest-meta.json +882 -0
  487. package/.versions/1.0.2/references/accessibility-checklist.md +160 -0
  488. package/.versions/1.0.2/references/definition-of-done.md +67 -0
  489. package/.versions/1.0.2/references/fleet-coordination-patterns.md +151 -0
  490. package/.versions/1.0.2/references/observability-checklist.md +91 -0
  491. package/.versions/1.0.2/references/orchestration-patterns.md +370 -0
  492. package/.versions/1.0.2/references/performance-checklist.md +153 -0
  493. package/.versions/1.0.2/references/prompting-patterns.md +380 -0
  494. package/.versions/1.0.2/references/security-checklist.md +179 -0
  495. package/.versions/1.0.2/references/testing-patterns.md +236 -0
  496. package/.versions/1.0.2/scripts/codex-conductor.ts +41 -0
  497. package/.versions/1.0.2/scripts/codex-remote-control.ts +167 -0
  498. package/.versions/1.0.2/scripts/coms-claude-bridge.ts +411 -0
  499. package/.versions/1.0.2/scripts/coms-cli.ts +484 -0
  500. package/.versions/1.0.2/scripts/coms-hermes-bridge.ts +413 -0
  501. package/.versions/1.0.2/scripts/fleet.ts +185 -0
  502. package/.versions/1.0.2/scripts/hermes-monitor-capability-runner.ts +25 -0
  503. package/.versions/1.0.2/scripts/hermes-monitor-scenario.ts +474 -0
  504. package/.versions/1.0.2/scripts/hermes-watchdog-capability-probe.ts +45 -0
  505. package/.versions/1.0.2/scripts/install-hermes-plugin.sh +180 -0
  506. package/.versions/1.0.2/scripts/lib/claude-bridge-core.ts +210 -0
  507. package/.versions/1.0.2/scripts/lib/codex-conductor.ts +88 -0
  508. package/.versions/1.0.2/scripts/lib/codex-remote-control.ts +480 -0
  509. package/.versions/1.0.2/scripts/lib/coms-envelope.ts +582 -0
  510. package/.versions/1.0.2/scripts/lib/fake-herdr-server.ts +88 -0
  511. package/.versions/1.0.2/scripts/lib/fleet-command.ts +266 -0
  512. package/.versions/1.0.2/scripts/lib/herdr-layout.ts +281 -0
  513. package/.versions/1.0.2/scripts/lib/hermes-bridge-core.ts +241 -0
  514. package/.versions/1.0.2/scripts/lib/hermes-monitor-events.ts +1 -0
  515. package/.versions/1.0.2/scripts/lib/hermes-monitor-herdr.ts +2 -0
  516. package/.versions/1.0.2/scripts/lib/hermes-monitor-model.ts +3 -0
  517. package/.versions/1.0.2/scripts/lib/hermes-monitor-registry.ts +2 -0
  518. package/.versions/1.0.2/scripts/lib/hermes-monitor-socket.ts +2 -0
  519. package/.versions/1.0.2/scripts/lib/hermes-monitor-store.ts +2 -0
  520. package/.versions/1.0.2/scripts/lib/monitor-env.ts +146 -0
  521. package/.versions/1.0.2/scripts/lib/peer-launch.ts +318 -0
  522. package/.versions/1.0.2/scripts/lib/persona-banner.ts +62 -0
  523. package/.versions/1.0.2/scripts/lib/spawn-stagger.ts +101 -0
  524. package/.versions/1.0.2/scripts/lib/team-project.ts +213 -0
  525. package/.versions/1.0.2/scripts/lib/team-snapshot.ts +147 -0
  526. package/.versions/1.0.2/scripts/peer-banner.ts +40 -0
  527. package/.versions/1.0.2/scripts/peer-launch.ts +259 -0
  528. package/.versions/1.0.2/scripts/team-snapshot.ts +237 -0
  529. package/.versions/1.0.2/scripts/team-up.ts +406 -0
  530. package/.versions/1.0.2/skills/_internal/grilling.md +11 -0
  531. package/.versions/1.0.2/skills/browser-testing-with-devtools/SKILL.md +351 -0
  532. package/.versions/1.0.2/skills/code-review-and-quality/SKILL.md +381 -0
  533. package/.versions/1.0.2/skills/compound-learning/SKILL.md +137 -0
  534. package/.versions/1.0.2/skills/context-engineering/SKILL.md +291 -0
  535. package/.versions/1.0.2/skills/deprecation-and-migration/SKILL.md +206 -0
  536. package/.versions/1.0.2/skills/designing-agents/SKILL.md +394 -0
  537. package/.versions/1.0.2/skills/designing-agents/pi-harness-authoring.md +222 -0
  538. package/.versions/1.0.2/skills/frontend-ui-engineering/SKILL.md +328 -0
  539. package/.versions/1.0.2/skills/git-workflow-and-versioning/SKILL.md +316 -0
  540. package/.versions/1.0.2/skills/idea-refine/SKILL.md +182 -0
  541. package/.versions/1.0.2/skills/idea-refine/examples.md +238 -0
  542. package/.versions/1.0.2/skills/idea-refine/frameworks.md +99 -0
  543. package/.versions/1.0.2/skills/idea-refine/refinement-criteria.md +113 -0
  544. package/.versions/1.0.2/skills/idea-refine/scripts/idea-refine.sh +15 -0
  545. package/.versions/1.0.2/skills/incremental-implementation/SKILL.md +287 -0
  546. package/.versions/1.0.2/skills/interview-me/SKILL.md +226 -0
  547. package/.versions/1.0.2/skills/orchestration-verification/SKILL.md +181 -0
  548. package/.versions/1.0.2/skills/peer-coms/SKILL.md +90 -0
  549. package/.versions/1.0.2/skills/performance-optimization/SKILL.md +350 -0
  550. package/.versions/1.0.2/skills/planning-and-task-breakdown/SKILL.md +254 -0
  551. package/.versions/1.0.2/skills/security-and-hardening/SKILL.md +461 -0
  552. package/.versions/1.0.2/skills/spec-driven-development/SKILL.md +257 -0
  553. package/.versions/1.0.2/skills/using-agent-skills/SKILL.md +199 -0
  554. package/.versions/1.0.2/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  555. package/.versions/1.0.2/vendor/agent-skills-upstream/LICENSE +21 -0
  556. package/.versions/1.0.2/vendor/agent-skills-upstream/README.md +11 -0
  557. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  558. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  559. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  560. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  561. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  562. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  563. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  564. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  565. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  566. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  567. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  568. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  569. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  570. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  571. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  572. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  573. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  574. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  575. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  576. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  577. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  578. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  579. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  580. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  581. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  582. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  583. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  584. package/.versions/1.0.2/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  585. package/CHANGELOG.md +15 -0
  586. package/README.md +4 -2
  587. package/agents/code-reviewer.md +1 -1
  588. package/agents/deep-researcher.md +1 -1
  589. package/agents/orchestrator.md +4 -56
  590. package/agents/plan-reviewer.md +1 -1
  591. package/agents/planner.md +1 -1
  592. package/agents/security-auditor.md +1 -1
  593. package/agents/test-engineer.md +1 -1
  594. package/docs/ARCHITECTURE.md +48 -16
  595. package/docs/agent-fleet-setup.md +33 -2
  596. package/docs/pi-extensions.md +29 -2
  597. package/install-manifest.json +2 -2
  598. package/package.json +2 -2
@@ -0,0 +1,1156 @@
1
+ # agent-hub
2
+
3
+ The unified Agent Fleet runtime for pi, with [`coms`](../coms/README.md) **embedded**. Bare
4
+ `just fleet` loads Fleet Core and starts `agent-hub` in **operator** posture with direct coding
5
+ and orchestration tools, but no standing native roster. The same live session can switch to
6
+ **orchestrator** posture, which removes direct coding tools and drives native specialists under
7
+ the Verification Contract. Fleet Core loads first: [`damage-control-continue`](../damage-control-continue/README.md),
8
+ [`ask-user-remote`](../ask-user-remote/README.md), STT, Compact & Continue, BTW, and the update
9
+ checker. Both postures can adjust the native roster, run research, collaborate with Pi/Claude
10
+ peers, and hand the session to a visible coms peer.
11
+
12
+ > Consolidates the retired `agent-team` dispatcher into this harness and embeds the ported `coms`
13
+ > P2P layer from [`pi-vs-claude-code`](https://github.com/disler/pi-vs-claude-code) by
14
+ > [disler](https://github.com/disler) (MIT). See the
15
+ > [extension catalog](../../../docs/pi-extensions.md) and the
16
+ > [design plan](../../../docs/plans/agent-hub/).
17
+
18
+ **Optional phone control:** `just fleet --agents <roster> --peers <preset> --project <name>` can supply the live peers for the experimental [Codex Android conductor](../../../docs/codex-remote-conductor.md). Configure Codex for the same project; do not also launch `just fleet conductor codex <team>` for the same peers. Hermes remains the inbound `ask_user` route, while Codex performs only human-confirmed, approval-gated outbound delegation.
19
+
20
+ ## Posture, roster, and topology
21
+
22
+ These are independent runtime axes:
23
+
24
+ - **Posture** — `/af-posture operator|orchestrator` switches prompt and active tools without
25
+ restarting or losing session state. Operator keeps `read`, `bash`, `edit`, `write`, approved
26
+ extension tools, and orchestration. Orchestrator withholds direct coding tools but keeps
27
+ dispatch, research, assertions, roster controls, `ask_user`, ready coms, and ready Herdr tools.
28
+ In orchestrator posture, raw Herdr panes are auxiliary-process orchestration—not a route around
29
+ delegation for reading, editing, testing, or implementing code.
30
+ - **Native roster** — local headless Pi specialists from `.pi/agents/teams.yaml`. Bare Fleet starts
31
+ empty; select one with `--agents frontend` or add one live with `/af-agents-add code-reviewer`.
32
+ - **Peer topology** — separate long-lived Pi or Claude Code processes from `peers.yaml`, connected
33
+ by coms and optionally placed in sibling Herdr panes. `--peers frontend` selects a standing
34
+ preset; `--herdr` creates a Hub-only workspace through the empty `base` preset.
35
+ - **Hub mode** — `/af-hub-mode` controls orchestration strictness and budgets; it does not change
36
+ posture, roster, or topology.
37
+
38
+ All Hub slash commands, including `/af-handoff`, are registered in both postures. A command whose
39
+ runtime capability is unavailable refuses with remediation rather than disappearing. `--no-coms`
40
+ disables only embedded coms; direct operator work and native dispatch remain available.
41
+
42
+ ### Automatic capability surfaces
43
+
44
+ Capability packs load **automatically** from the current request, posture, task tier, pending work,
45
+ and runtime state; there is no activation command. `core` is always present. Orchestrator posture
46
+ always includes `fleet`; explicit delegation/research, acceptance work, an existing coms peer, a
47
+ Herdr pane/watcher request, and explicit or imminent compaction respectively add `fleet`,
48
+ `verification`, `peer`, `workspace`, and `compaction`. A ready coms or Herdr runtime is only
49
+ **readiness**, not intent: its tools and policy remain model-inactive until requested.
50
+
51
+ Ambiguous delegation, peer, or workspace intent provisionally exposes the smallest relevant pack
52
+ and records its reason in the state capsule and `/af-context`. Before that pack's first side effect,
53
+ the Hub asks one focused `ask_user` confirmation. Confirming promotes it for the task; reject or
54
+ cancel removes it and leaves no message, child, or pane behind. Active task packs persist through
55
+ follow-up turns so a workflow does not lose tools. They shrink only through
56
+ `set_task_tier(new_task: true)` (apart from mandatory posture and pending-operation leases), never
57
+ merely because the next message sounds different.
58
+
59
+ `/af-context` separates stable replacement-prompt cost from the volatile state capsule and active
60
+ schemas. Inactive and ready-but-inactive packs cost zero model-visible characters. Provider totals,
61
+ including cache read/write when Pi supplies them, remain authoritative; deterministic character
62
+ figures are regression diagnostics and never invent provider usage.
63
+
64
+ ### Context-pressure and resume recovery
65
+
66
+ Pre-turn surface cost and live conversation pressure are different budgets. `/af-context` separates
67
+ the stable replacement prompt, volatile state capsule, and active tool schemas; user and assistant
68
+ messages plus tool results then accumulate during a turn. A long tool loop can therefore reach the
69
+ model window even while every standing prompt ceiling remains green.
70
+
71
+ The Hub samples live provider usage and projects each finalized tool result before another model
72
+ request:
73
+
74
+ - Below **80%**, pressure is `normal`.
75
+ - At **80%**, pressure becomes `warning`; the compact recovery surface is exposed transiently and
76
+ ordinary work may continue.
77
+ - At **90%**, the Hub aborts the next same-turn provider request, waits until the tool result and
78
+ aborted turn are persisted, and starts one automatic Pi compaction. Only one recovery may run at
79
+ a time. Input received while startup or same-turn recovery is active is retained in memory,
80
+ including images, then replayed once after compaction succeeds.
81
+
82
+ The status line and `/af-context` show the pressure phase, measured usage, both thresholds, episode,
83
+ and last recovery outcome. Persisted pressure diagnostics contain numeric/enumerated metadata only;
84
+ they never include prompts, tool output, credentials, error bodies, or compaction summaries.
85
+
86
+ If automatic recovery reports `failed`, the queued input remains retained. Use Pi's built-in manual
87
+ fallback, or switch to a model with a larger context window:
88
+
89
+ ```text
90
+ /compact Preserve the current goal, decisions, assertions, pending operations, blockers, and next step.
91
+ ```
92
+
93
+ A resumed orchestrator session can also require roster recovery. The Hub persists only the selected
94
+ team name and resolves it again against the current `.pi/agents/teams.yaml` and persona files. If the
95
+ team is missing, renamed, empty, or stale, the Hub preserves orchestrator posture, keeps direct coding
96
+ tools unavailable, and blocks model input rather than inventing a roster or silently downgrading.
97
+ Recover with one of these explicit choices:
98
+
99
+ ```text
100
+ /af-agents-team # select a currently valid team in the live session
101
+ /af-posture operator # explicitly leave delegate-only posture
102
+ just fleet --agents <name> # restart through the public Fleet CLI
103
+ just fleet --posture operator # restart explicitly as an operator
104
+ ```
105
+
106
+ For a direct Pi launch, the roster flag is `--agent-team <name>` and the posture flag is
107
+ `--posture operator`; explicit startup flags take precedence over persisted selections. Fix stale
108
+ team/persona declarations before selecting them.
109
+
110
+ The Pi session JSONL under `~/.pi/agent/sessions/` is the authoritative append-only conversation and
111
+ recovery record. Context overflow or a stale roster does **not** by itself mean that file is corrupt.
112
+ Inspect it through `/session`, resume it through `/resume` or Pi's session flags, and recover through
113
+ compaction or the commands above. Never edit, truncate, reorder, or synthesize JSONL entries to
114
+ recover a session.
115
+
116
+ ## What it does
117
+
118
+ The whole dispatch loop, end to end:
119
+
120
+ ```mermaid
121
+ sequenceDiagram
122
+ autonumber
123
+ actor U as You
124
+ participant H as Hub (dispatcher)
125
+ participant S as Specialist (e.g. builder)
126
+ participant R as Research helper
127
+ participant D as Disk (.pi/agent-sessions/)
128
+
129
+ U->>H: task
130
+ H->>D: set_assertions — Verification Contract persisted
131
+ H->>S: dispatch_agent (task + advisory scope)
132
+ S-->>H: NEEDS_RESEARCH: how does X work?
133
+ H->>R: spawn_research (researcher / deep-researcher)
134
+ R->>D: write findings file
135
+ R-->>H: one-line notice + path
136
+ H->>S: resume with file paths — never raw findings
137
+ S-->>H: structured return + named evidence
138
+ H->>D: update_assertion
139
+ H-->>U: Assertions: 2✓ 1○ 1✗ · open: A4
140
+ ```
141
+
142
+ Every borrowed idea from another harness passes one test before it lands: *does this persistently enter the dispatcher context?* If yes, it goes to disk or a one-line status instead.
143
+
144
+ `agent-hub` is the supported home for the former standalone dispatcher features:
145
+
146
+ - **Dispatcher grid** — a live dashboard of the active, dynamically adjustable native roster from `.pi/agents/teams.yaml`.
147
+ - **Context budget** — `/af-context` opens a separate read-only full-screen diagnostic in either posture. It shows provider totals and cache fields beside named, metadata-only estimates; `loaded-excluded` Pi inputs are discovered but contribute zero to the replacement Hub prompt. Each specialist, research helper, delegate, and peer remains a separate context plane with its own model window. Component token estimates are heuristic/provider-scaled, never exact claims; unavailable peer/provider detail is labelled explicitly and raw prompts, schemas, and conversation text are never retained or displayed.
148
+ - **Specialist delegation** — `dispatch_agent` sends writable tasks to configured specialists.
149
+ - **Research helpers** — `spawn_research` and `/af-research` launch read-only helper agents. Managed research children use a replacement read-only prompt with `--no-skills` and `--no-context-files`; managed specialists receive a selected context manifest (persona, applicable policy paths, and named skill paths) rather than inherited global skill/context loading. Two
150
+ `kind: research` personas ship by default: `researcher` (fast `gpt-5.3-codex-spark`) for simple
151
+ reads and `deep-researcher` (`gpt-5.5` / xhigh) for hard, cross-cutting investigation. The
152
+ orchestrator routes by persona; each persona's model + thinking level is shown in its catalog.
153
+ Finished helpers are **auto-pruned** so the research row doesn't grow without bound: auto-research
154
+ pipe helpers disappear as soon as they finish (their findings persist as `findings/*.md` files and
155
+ their handles are never resumed), while manual/persona helpers keep only the `research-keep` most
156
+ recently finished (default 4 — resumable via `/af-agents-cont rN`; older cards, and their session
157
+ files, are dropped oldest-first). Set `research-keep: <n>|all` in the overrides file to change
158
+ the cap. Running helpers are never pruned and `rN` handles are never reused.
159
+ - **Human handoff path** — `ask_user` is exposed by the `ask-user-remote` wrapper (capturing stock
160
+ `pi-ask-user` and optionally racing a `user-remote` bridge), so specialists can bubble decisions
161
+ back through the dispatcher.
162
+ - **Auto-research pipe (`NEEDS_RESEARCH:`)** — a specialist that lacks information pauses by ending
163
+ its turn with `NEEDS_RESEARCH: <question>` lines (mirror of the `ASK_USER:` protocol). The hub
164
+ intercepts them **in code**: it fans out read-only research helpers (max 4 questions per pause,
165
+ 2 pauses per dispatch), writes each helper's findings to `.pi/agent-sessions/findings/*.md`, and
166
+ resumes the specialist's session with the file paths. The dispatcher LLM sees only a one-line
167
+ notice — raw findings never enter its context. Findings files are wiped at session start.
168
+ - **Verification Contract (assertion ledger)** — the dispatcher owns a ledger of checkable
169
+ acceptance assertions built from the request *before* any builder runs, so a clearly stated
170
+ requirement is never silently dropped. `set_assertions` records the numbered, tagged assertions
171
+ (`test` | `runtime-ui` | `code-grep` | `manual`, one pass condition each, plus a required
172
+ `source` naming where the requirement comes from) and rebuilds the whole
173
+ ledger on a "wrong again" regression reset; `update_assertion` marks each one proven (named
174
+ evidence required), unproven, or failed after a verification gate; `get_assertions` reads the
175
+ full ledger (ids, tags, pass conditions, evidence) back. The hub persists the ledger to
176
+ `.pi/agent-sessions/assertions.json` (wiped at session start like `findings/`) and renders a
177
+ one-line status (`Assertions: 2✓ 1○ 1✗ · open: A4`) so the contract survives compaction without
178
+ re-flooding the dispatcher LLM context — after a compaction the dispatcher calls `get_assertions`
179
+ to recover the full text the status line omits. The `orchestrator` persona drives it — a deep-researcher
180
+ parity inventory for "behave like" requests, runtime proof for UI/visibility assertions, the
181
+ regression reset on a re-ask — per
182
+ [`orchestration-verification`](../../../skills/orchestration-verification/SKILL.md). The hub also
183
+ machine-parses each assertion-carrying specialist's structured return, writes the full raw output
184
+ to `.pi/agent-sessions/artifacts/returns/<agentKey>-run<N>.md`, surfaces only a compact
185
+ `details.structuredReturn` digest plus `details.returnPath`, and marks contract notices such as
186
+ missing assertion ids or evidence-less `assertions_proven` entries (demoted to unproven in the
187
+ tool text). `details.fullOutput` remains for `/af-zoom`/compatibility, but dispatcher-visible text is
188
+ digest + path oriented. `update_assertion(status: "proven")` validates evidence by assertion tag:
189
+ test evidence needs a command/test and outcome, `code-grep` needs pattern plus result sample,
190
+ manual needs user/`ask_user` confirmation, and `runtime-ui` needs an existing artifact path under
191
+ `.pi/agent-sessions/artifacts/evidence/`. **Advisory by design** (PRD open question 2): status is
192
+ surfaced and "proven" requires named evidence, but a dispatch is never hard-refused on an unproven
193
+ assertion — code-enforcement is the Checkpoint A decision. Two contract rules ARE enforced at the
194
+ tool: a batch with any sourceless assertion is refused with the offending ids named (a specialist
195
+ told to prove `A9` must be able to read its origin instead of spending a dispatch and an ASK_USER
196
+ cycle asking where `A9` was defined), and a batch over **8** open assertions is accepted with a
197
+ warning suggesting the split — declare the batch the next dispatches actually prove, and
198
+ `set_assertions` the next one when it starts.
199
+ - **Artifact bus** — session handoffs live under `.pi/agent-sessions/artifacts/` with conventional
200
+ `returns/`, `failures/`, `plans/`, `reviews/`, `inventories/`, and `evidence/` subdirectories, all
201
+ **archived** into an immutable `runs/<runId>/` namespace at session start rather than wiped (see
202
+ [Immutable per-run artifact namespaces](#immutable-per-run-artifact-namespaces-run-namespacejs)),
203
+ so a later session can never overwrite an earlier one's returns. `failures/` is separate on purpose: a run
204
+ that errored or timed out produced no specialist result, so its output goes there and the dispatch
205
+ result names it a **delivery failure** carrying no assertion evidence. Filing a 142-byte coms error
206
+ stub as `returns/code-reviewer-run4.md` once cost a 103-second dispatch investigating a review that
207
+ had in fact succeeded — only its reply was lost. `dispatch_agent` and `spawn_research` accept optional
208
+ `artifacts: string[]` paths (repo-relative or session-artifact-relative); the hub validates that
209
+ they stay inside the repo/session roots and injects only the path plus first heading/one-line
210
+ preview, never file bodies. Document-producing specialists are instructed to write plans, reviews,
211
+ inventories, and reports to the real session path
212
+ `.pi/agent-sessions/artifacts/<kind>/<agentKey>-run<N>.md` when their tools allow it, then report/pass
213
+ the artifact-relative handoff path `artifacts/<kind>/<agentKey>-run<N>.md`, finish with that path plus
214
+ a ≤10-line digest, and still include structured returns when assertions are carried. Repo-root
215
+ `./artifacts/...` files are not session artifacts. Planner's existing PLAN_FILE behavior is preserved;
216
+ the artifact path is an additional handoff channel.
217
+ - **Dispatch scope advisory** — `dispatch_agent` accepts optional `scope: string[]` for writable
218
+ builder-style runs. The orchestrator should derive these globs from the plan task's file list,
219
+ and skip scope for exploratory/reconnaissance work where the right files are not known yet. The
220
+ hub snapshots git status before the writable dispatch, diffs after the whole tool call (including
221
+ auto-research resumes), and reports out-of-scope paths in `details.scopeViolations` plus a ⚠ text
222
+ notice. This is advisory only: the hub never blocks completion, reverts files, or escalates
223
+ automatically. Known limitation: concurrent writable dispatches can only be attributed
224
+ approximately, so overlapping runs are flagged in the notice.
225
+ - **Agent controls** — `/af-zoom` inspects a live agent timeline; `/af-agents-history` replays the run as a
226
+ timeline (orchestrator turns, dispatches, research helpers) with per-agent durations, parallel-run
227
+ markers, and a grand total; kill/restart controls manage running child agents; per-agent `model:`
228
+ fields select models from team config. The `agents-*` commands address **both target kinds** —
229
+ team specialists by persona name, research helpers by `rN` handle (mirroring `/af-zoom`):
230
+ `/af-agents-kill <name|rN|all>` SIGTERMs a specialist (keeping its standing card), while on a
231
+ research helper it kills **and removes** the card + session — helpers are disposable by design
232
+ (`all` clears every helper); `/af-agents-restart <name|rN>` re-runs the last task fresh (a research
233
+ helper must be finished first); `/af-agents-cont rN <prompt>` resumes a finished helper's session.
234
+ The old `/af-research-rm` and `/af-research-clear` spellings remain as aliases of the kill semantics,
235
+ `/af-research-cont` of `/af-agents-cont`.
236
+ Restartable team specialists at or above 70% context render
237
+ their context percentage with a warning marker/color in dashboard and compact views, and their next
238
+ `dispatch_agent` result adds a `/af-agents-restart <persona>` hint. Research helpers are not warned,
239
+ and the hub never restarts specialists automatically.
240
+ - **Model switching** — a persona's frontmatter `models:` list declares the models it may switch to
241
+ (the default `model:` is implicitly a candidate). `/af-agent-model <persona>` picks from that list;
242
+ the choice lasts for the session and takes effect on the persona's next dispatch
243
+ (`/af-agents-restart <persona>` applies it immediately). The dot form
244
+ `/af-agent-model <persona>.<role>` switches a delegate sub-role's model instead — its candidates are
245
+ the role's declared default plus the parent persona's own candidate list; the switch is applied
246
+ when the parent is next dispatched (it lands in the serialized delegate config, so nested
247
+ children inherit it). `/af-models [profile]` applies a named profile
248
+ from `.pi/agents/model-profiles.yaml` — a macro over the same declared candidates, validated at
249
+ session start (a profile with any entry outside a persona's candidates is dropped whole, with an
250
+ error); profiles never touch sub-role models — only `/af-agent-model` reaches those. Nothing
251
+ outside the declared lists is ever selectable. When an effective project or session override
252
+ fails with a model/provider error or aborted request before work begins (including local-model
253
+ memory-limit failures), the hub retries once with the model originally declared in the persona
254
+ frontmatter. For **write-capable** runs this is pre-work only: no fallback occurs after text
255
+ output, a tool call, cancellation, timeout, drift stop, or a Pi process-spawn failure, avoiding
256
+ duplicate writes. **Read-only children and research helpers** (tools limited to
257
+ `read,grep,find,ls`) also retry once when the provider fails *mid-run* — re-running a reader
258
+ repeats nothing, and those are exactly the children that exist to protect their parent's context,
259
+ so losing one to a local-endpoint OOM halfway through discards work for no safety gain. A
260
+ terminated run (watchdog, deadline, cancellation) never retries either way: that is a verdict on
261
+ the work, not a provider outage. The failed attempt is removed from the child session before retry. Per project,
262
+ `model.<persona>:` / `models.<persona>:` keys under `## agent-hub` in
263
+ `.ai/agent-fleet-overrides.md` replace a persona's default model / candidate list.
264
+ Research personas (`researcher` / `deep-researcher`, `kind: research`) are switchable the same
265
+ way — `/af-agent-model <persona>` and `/af-agent-model-thinking <persona>` accept them alongside team
266
+ members. Since research helpers are spawned fresh on each `/af-research` / `spawn_research`, the
267
+ switch lands on their next spawn (there is no running instance to `/af-agents-restart`).
268
+ `/af-agent-models-substitute <source> <target>` is the global one-shot form: walks every loaded
269
+ persona (team + research + orchestrator), and for each whose **current effective model** is
270
+ `<source>` and whose declared candidates include `<target>`, sets the session override to
271
+ `<target>`. One-step flow — the dry-run summary (affected vs skipped, with reasons) is shown
272
+ inline, then the swap is applied immediately and takes effect on each persona's next dispatch
273
+ (`/af-agents-restart` to apply now). It never touches the dispatcher or delegate sub-roles.
274
+ - **Thinking levels** — each persona's frontmatter `thinking:` sets its pi `--thinking`
275
+ reasoning effort (`off` · `minimal` · `low` · `medium` · `high` · `xhigh`). `/af-agent-model-thinking
276
+ <persona>` switches it among those six levels for the session; like a model switch it takes effect
277
+ on the persona's next dispatch (`/af-agents-restart <persona>` applies it now), and selecting the
278
+ frontmatter default clears the override. The level shows as a short badge after the model
279
+ everywhere a model is rendered — `gpt-5.5 (xh)` in the dashboard cards and the compact below-editor
280
+ view (`min`/`low`/`med`/`hi`/`xh`; `off` shows no badge). Per project, a `thinking.<persona>:` key
281
+ under `## agent-hub` in `.ai/agent-fleet-overrides.md` replaces a persona's default level.
282
+ - **Mid-turn delegation (`delegate` tool)** — a persona that declares a `subagents:` map in its
283
+ frontmatter (`role: { model, tools? }` entries, or an indented `model:`/`tools:` block per role)
284
+ gets a real mid-turn `delegate(role, instruction, context?, allow_write?)` tool, injected as an
285
+ extra `-e delegate.ts` extension into its spawned process (the `delegate` tool name is appended to
286
+ its `--tools` allowlist — pi filters extension tools too). Only declared roles are spawnable, on
287
+ their declared models — model choice is configuration, never the child LLM's. Budgets are readable
288
+ refusals: at most 4 delegate children per dispatch, tree-wide, and a per-persona `delegate_depth:`
289
+ budget capped at 1 (the default). Children spawned with remaining depth 0 do not receive the
290
+ `delegate` extension/tool. Write safety: children run read-only (`read,grep,find,ls`) unless a
291
+ SINGLE live child gets `allow_write: true`, which inherits the parent's tools intersected with the
292
+ role's `tools:` cap; if a declared role cap leaves no available tools, delegation is refused.
293
+ Concurrent children are always forced read-only. Children stream timeline events through
294
+ `.pi/agent-sessions/delegations/<persona>/events.jsonl`; the hub tails it and renders nested rows
295
+ under the parent's card (child id, model, tokens, status),
296
+ each openable with `/af-zoom <child-id>`. Each child also writes its full final output to
297
+ `.pi/agent-sessions/delegations/<persona>/results/<childId>.md`; the parent receives only status,
298
+ a required final `DIGEST:` section (≤30 lines with path:line citations), and the result-file path.
299
+ If a child omits `DIGEST:`, the parent gets the first ~30 lines plus a no-DIGEST warning and the
300
+ result path. Spend rolls up: every child row and the parent's subtree
301
+ total show tokens, and a session-wide `Δ delegated` counter sits in the status line.
302
+ `/af-agents-kill` on the parent SIGTERMs its whole process group, so the delegation tree dies with
303
+ it. `context: fork` is accepted but treated as a summary brief in v1. Per project,
304
+ `subagents.<persona>.<role>:` and `delegate-depth.<persona>:` keys under `## agent-hub` in
305
+ `.ai/agent-fleet-overrides.md` replace individual sub-roles / the depth budget. An overridden
306
+ role retains its frontmatter model as a one-shot fallback under the same pre-work-only safety
307
+ rule; delegate cards and results show the model that ultimately ran. Six personas ship with
308
+ declared sub-roles, on a three-tier OpenAI model ladder — `gpt-5.3-codex-spark` for
309
+ recon/grep sweeps, `gpt-5.4` for analysis sweeps, the `gpt-5.5` (or opus) parent reserved for
310
+ synthesis and verdicts:
311
+ - `code-reviewer` — `preflight`+`docs` (spark), `quality`+`perf` (gpt-5.4); its first delegate
312
+ call is always `preflight`, which studies the project rules and the files under review and
313
+ returns a summary that drives the rest of the fan-out. Deep security review is not a
314
+ sub-role — it belongs to the separate `security-auditor` persona, which the reviewer
315
+ recommends dispatching when it spots deeper risk.
316
+ - `planner` — `scout`+`rules` (spark) fan out before the plan is drafted; `risk` (gpt-5.4)
317
+ optionally challenges the draft breakdown.
318
+ - `plan-reviewer` — `feasibility` (gpt-5.4) checks plan claims against the actual codebase;
319
+ `deps` (spark) verifies dependency ordering and file overlap. No preflight — the plan is
320
+ the map.
321
+ - `security-auditor` — solo `recon` (spark) maps the attack surface first, then
322
+ `input-sweep` (gpt-5.4) and `secrets-sweep` (spark) fan out; exploit reasoning stays with
323
+ the parent.
324
+ - `builder` — `recon` (spark) maps call sites before edits; `verifier` (spark, the one
325
+ `allow_write: true` child) runs the test suite after them. Implementation is never
326
+ delegated.
327
+ - `test-engineer` — `coverage-scout`+`conventions` (spark) inventory gaps and test patterns;
328
+ test writing is never delegated.
329
+ - **Dispatcher persona gate** — optional `persona-gate: on` can require an orchestrator persona at
330
+ session start; by default the dispatcher starts without the gate.
331
+ - **Default damage-control guardrails** — `just fleet` and `just fleet --no-coms` load the
332
+ `damage-control-continue` harness before `agent-hub`, so dispatcher tool calls are checked against
333
+ `.pi/damage-control-rules.yaml` and a blocked call feeds back instead of aborting the turn. A
334
+ guardrail is also re-loaded into every native specialist, research helper, and nested delegate
335
+ (see [Safety scope](#safety-scope)). Missing safety plumbing refuses child dispatch.
336
+ - **Embedded coms** — the dispatcher is a discoverable peer on the local machine. Multiple
337
+ `agent-hub` (or plain `coms`) sessions on the same box find each other through per-project registry
338
+ files and exchange messages over a unix socket (named pipe on Windows).
339
+
340
+ `/af-zoom <name|rN|child-id>` opens the selected agent's full-screen stream detail. For fleet rows,
341
+ it uses the [Fleet Dashboard detail controls](#fleet-dashboard-and-detail); a directly addressed
342
+ fallback stream keeps the legacy zoom controls. Both overlays size to the terminal.
343
+
344
+ ### `/af-agents-history`
345
+
346
+ `/af-agents-history` opens a read-only overlay (same chrome as `/af-zoom`) that replays the session as an
347
+ execution **tree**:
348
+
349
+ - **Orchestrator turns** — each dispatcher turn that actually dispatched something is a depth-0 row
350
+ labelled `(dispatcher)`. Chat-only turns add no rows.
351
+ - **Dispatched specialists and research helpers** nest one level beneath the turn that launched them;
352
+ **delegate sub-sub-agents** nest one level deeper still under the specialist that spawned them — in
353
+ start order at every level.
354
+ - **Parallel runs** — siblings whose run times overlap are marked with a `│→` connector, so a
355
+ concurrent fan-out reads as a visually grouped block.
356
+ - **Real-work durations** — each row shows that node's *own* work: its span **minus the time it spent
357
+ awaiting children**. A dispatcher blocked on six concurrent agents is credited only for the time it
358
+ actually worked between/around the awaits, never for the await itself — so the same wall-clock isn't
359
+ counted twice up the tree. The same subtraction applies to a specialist awaiting its own delegate
360
+ children. Format: plain seconds under a minute (`42sec`), `m:ss` above it (`10:20min` for 620s).
361
+ Running rows tick live (the overlay re-renders once a second) and a new dispatch appears the instant
362
+ it starts.
363
+ - **Footer** shows `Σ real work <total> · <n> runs (agents <a> + dispatchers <d>)` — the real work of
364
+ *everyone*: the dispatched specialists' and research helpers' full runtime (`agents`) plus each
365
+ dispatcher turn's own work (`dispatchers` — its span minus the time it awaited agents **and** the
366
+ human via `ask_user`). Wall-clock is deliberately **not** shown: it would fold in the idle gaps
367
+ while you're away between turns, and `ask_user` waits are subtracted for the same reason.
368
+
369
+ Navigate with `↑/↓`, press `G` to jump back to the live tail, and `Q`/`Esc` to close. The log resets
370
+ on each session start.
371
+
372
+ The agent view starts with the **compact widget** enabled: one line per *running* agent —
373
+ `name · context% · state` — *below* the input box, just above pi's status bar. Idle and done agents
374
+ are hidden, and the coms pool widget collapses too, so an idle session collapses to just the prompt
375
+ and footer. **`Alt+Shift+A`** toggles that widget on or off; the footer reports
376
+ `Alt+A fleet · Alt+Shift+A widget:compact|off`.
377
+
378
+ ### Fleet Dashboard and detail
379
+
380
+ Press **`Alt+A`** or run **`/af-agents-list`** to open the full-screen **Fleet Dashboard**. It is a
381
+ separate, live overlay—not an alternate compact-widget mode—and lists specialists, nested delegates,
382
+ research helpers, and coms peers. It shows status, hierarchy, model, context/tokens, elapsed time,
383
+ tool count, and recent work; its summary counts running/done/failed rows, overlap-aware wall time,
384
+ and visible token totals. Finished/idle/stale rows are hidden by default.
385
+
386
+ - **`↑`/`↓`** or **`j`/`k`** selects a row; **`PgUp`/`PgDn`** pages; **Enter** opens its full-screen
387
+ detail view.
388
+ - **`f`** starts a name/model/recent-work filter; type the query and press **Enter** to apply it, or
389
+ **Esc** to clear it. **`a`** toggles finished rows.
390
+ - **`x`** requests a kill and **`r`** requests a restart; press the same key again within two seconds
391
+ to confirm. Kill acts on a local running specialist, a coms-backed specialist, or a research helper.
392
+ Confirmed restart terminates a running specialist when necessary, clears its session, and re-dispatches
393
+ its previous task fresh; it is refused for peer/delegate rows, running research, and rows with no previous task.
394
+ - **`q`** or **Esc** closes the dashboard.
395
+
396
+ The detail view streams the selected local agent's text, thinking, and tool timeline. Use **`↑`/`↓`**,
397
+ **`PgUp`/`PgDn`**, and **End** to navigate/tail; **Enter** expands a selected tool call; **Ctrl+C**
398
+ copies the selected entry; and **`m`** replaces the log area with a visible full-screen picker
399
+ containing every model currently reported by Pi's available-model registry. Use **`↑`/`↓`**,
400
+ **`PgUp`/`PgDn`**, or **Home**/**End**, then **Enter** to apply; **Esc** cancels back to the logs.
401
+ Model switching works for local specialists, retained research helpers, and nested delegate roles.
402
+ It applies on the next dispatch/continuation and never interrupts
403
+ a running child. A coms-backed specialist stores the choice for native fallback runs; external coms
404
+ peers control their own model and have no picker. **Esc**/**`q`** returns to the dashboard. Coms peers
405
+ have no local transcript and show that explicitly. **`/af-zoom <name|rN>`** opens this same detail
406
+ view directly.
407
+
408
+ ### Version footer
409
+
410
+ `agent-hub` renders its local harness version first in its custom footer:
411
+ `agent fleet v<version> · <model><thinking> · <team>`. It replaces pi's default footer, so it does **not**
412
+ consume or render the shared version status; it reads its own adjacent stamped manifest directly.
413
+ The three persistent-UI harnesses (`agent-hub`, `coms`, and
414
+ `damage-control-continue`) still register that one shared key, which gives default footers one
415
+ version in stacked non-hub sessions. In the supported guardrail-plus-hub stack, the hub's custom
416
+ footer supplies the single visible version. Damage-Control can update its own safety status after
417
+ a violation without overwriting the shared version entry. The canonical source is the
418
+ repository-root `package.json`; the adjacent harness manifest is a synchronized stamp maintained
419
+ by `bin/sync-harness-versions.js`. Its local `version.ts` reader intentionally stays with the
420
+ harness for copied or symlinked installs, but those installs still need the pre-existing full
421
+ `.pi/harnesses/` dependency installation.
422
+
423
+ The `agent fleet` half of the label is an OSC 8 terminal hyperlink to the project homepage —
424
+ clickable in terminals that support hyperlinks, ignored (rendered as plain text) elsewhere, and
425
+ free of footer columns because pi strips OSC sequences before measuring width. It opens the
426
+ repository in a browser, not a TUI panel: pi has no mouse tracking, so a click never reaches the
427
+ harness. `AGENT_FLEET_NO_LINKS=1` restores the plain label on multiplexers that mangle OSC 8
428
+ (GNU screen, tmux before 3.4).
429
+
430
+ ### Voice dictation indicator
431
+
432
+ The custom footer renders the optional [`pi-voice-stt`](../../extensions/pi-voice-stt/README.md)
433
+ extension's recording indicator on a line **below the model line** — e.g.
434
+ `● REC 0:01 ⏎ send · esc cancel` while recording, or a `transcribing…` dot. Because agent-hub
435
+ replaces pi's built-in footer (where that indicator normally lives), it reads the extension's
436
+ `setStatus("voice-stt", …)` value via the footer data provider and surfaces it itself. The
437
+ indicator only appears once `pi-voice-stt` is installed and configured; otherwise the footer is
438
+ the single model line. Press **`Alt+S`** to start/stop dictation as in a normal pi session.
439
+
440
+ ### Compact-view agent switcher
441
+
442
+ With the **compact widget enabled**, the running-subagents list below the input doubles as a
443
+ switcher. **`Alt+]`** and **`Alt+[`** move a marker (`›` + highlight) to the next/previous running
444
+ subagent; **`Alt+\`** opens the full-screen detail view on the marked one (`q`/`Esc` to return).
445
+ This only changes what you *view* — **the input box always prompts the main session**, and `main` is
446
+ never a marker target (it is the session under the input, not a subagent). There is no transcript
447
+ takeover: a subagent stream is shown in an overlay, never by replacing the main scrollback. These
448
+ keys require the compact widget; use `/af-zoom <name>` or the Fleet Dashboard otherwise.
449
+
450
+ > Terminal note: `Alt+[` emits `ESC [` (a CSI prefix) and may be swallowed by some terminals'
451
+ > escape parsers; `Alt+]` and `Alt+\` are the reliable pair. `Alt+↑/↓/←/→` are reserved by the pi
452
+ > editor, which is why the switcher uses the bracket/backslash keys.
453
+ >
454
+ > On macOS, configure the outer terminal to send Option as Meta. For Zed, set
455
+ > `terminal.option_as_meta` to `true`; otherwise Option combinations produce composed characters.
456
+
457
+ ## Configuration
458
+
459
+ At session start, `agent-hub` reads `.ai/agent-fleet-overrides.md` in the workspace. The
460
+ canonical section name is `## agent-hub` (the legacy `## agent-team` name is still accepted):
461
+
462
+ ```markdown
463
+ ## agent-hub
464
+ # Replace Bulgarian with any language name.
465
+ language: Bulgarian
466
+ ```
467
+
468
+ Omit the section to keep the default `English`. `language` applies to dispatcher replies,
469
+ `ask_user` questions and `context` fields, handoff summaries, and user-facing status text;
470
+ specialist task strings stay in English.
471
+
472
+ The same section can point the team at the project's own rule files and documentation
473
+ entry points:
474
+
475
+ ```markdown
476
+ ## agent-hub
477
+ rules: docs/rules, .ai/rules
478
+ docs: Docs/AGENTS.md, Docs/architecture/ARCHITECTURE_OVERVIEW.md
479
+ ```
480
+
481
+ `rules:` lists repo-relative folders of HOW rules — implementation patterns the work must
482
+ comply with. Resolution is **index-first**: a folder with a top-level `README.md`/`index.md`
483
+ is treated as curated — personas read the index first and follow its loading manifest
484
+ (session bundles, conditional-load lists) instead of bulk-reading the tree; a folder without
485
+ an index is searched **recursively** through all subfolders. When set, every dispatched
486
+ specialist's system prompt gains a "Project rules" block naming the folders and the
487
+ resolution order; the planner and code-reviewer personas additionally validate their subject
488
+ against the relevant rules and pass them on (cited in plan acceptance criteria / handed to
489
+ delegate sub-reviewers).
490
+
491
+ `docs:` lists repo-relative WHAT/WHY documentation entry points — canonical files (e.g. an
492
+ `AGENTS.md`, an architecture overview) or doc folders (personas start from the folder's
493
+ README/index). Docs orient rather than bind: every dispatched specialist **and every research
494
+ helper** gains a "Project docs" block telling it to read the entry points relevant to its
495
+ task and follow their links instead of bulk-reading doc trees. The code-reviewer flags
496
+ changes that alter documented behavior without a doc update; the documenter treats the entry
497
+ points and the trees they link as the documentation it maintains.
498
+
499
+ The same section also tunes research-helper retention:
500
+
501
+ ```markdown
502
+ ## agent-hub
503
+ research-keep: 8
504
+ ```
505
+
506
+ `research-keep:` caps how many **finished** manual/persona research helpers stay resumable
507
+ (LRU by finish time, default 4; `all` disables the cap). Auto-research pipe helpers are
508
+ always pruned as soon as they finish, regardless of this key.
509
+
510
+ ### Bounded local-disk searches
511
+
512
+ Every `read`, `grep`, `find`, and `ls` call made by a native research helper or a nested
513
+ `delegate` child has a **parent-side** watchdog. The default is **120 seconds per tool call**;
514
+ it is a per-tool bound, not a whole-run deadline — the whole-run bound is the execution
515
+ mode's per-run deadline below. Configure it in the repository-standard overrides file:
516
+
517
+ ```markdown
518
+ ## agent-hub
519
+ recon-search-timeout-s: 120 # integer 1..3600
520
+ # recon-search-timeout-s: off # disable this per-tool watchdog
521
+ ```
522
+
523
+ Invalid values warn at session start and use 120. Calls are tracked independently by their
524
+ JSONL `toolCallId`; a repeated start/update cannot extend an existing deadline. A timeout returns
525
+ `tool_timeout` with the call metadata, ends the research/delegate lifecycle, sends SIGTERM to the
526
+ child's explicitly owned process group, then SIGKILL after a finite grace period. The parent also
527
+ has a final settlement timer, so it settles rather than waiting indefinitely for `close` or
528
+ inherited pipe drain. If child/process-group death cannot be confirmed after this bounded cleanup,
529
+ the timeout metadata reports `terminationConfirmed: false`: this prevents the parent hanging, but
530
+ may indicate an uninterruptible OS-level process that needs operator attention. This group
531
+ ownership covers descendants even when the pi leader exits first; nested delegates own their groups
532
+ and forward parent cancellation, avoiding detached-orphan processes. Caller
533
+ cancellation follows the same bounded cleanup path but is reported as `cancelled`, not
534
+ `tool_timeout`.
535
+
536
+ ### Execution modes & turn budgets
537
+
538
+ The hub runs one of three **execution modes** — `fast`, `standard` (default), `strict` —
539
+ with **per-user-turn budgets enforced in code**, not prose. This is the guardrail against
540
+ runaway orchestration (the observed failure mode: 100+ dispatches and 100M+ tokens for one
541
+ task, most of it re-billed stale specialist context).
542
+
543
+ | Budget (per user turn) | fast | standard | strict |
544
+ |-----------------------------------|--------|----------|---------|
545
+ | `dispatch_agent` calls | 2 | 8 | 24 |
546
+ | `spawn_research` calls | 1 | 4 | 12 |
547
+ | Turn wall clock | 15 min | 60 min | 240 min |
548
+ | Per-run deadline (specialist/research/delegate) | 10 min | 30 min | off |
549
+ | Specialist session recycled after | 3 runs | 5 runs | 5 runs |
550
+ | Nested delegation | off | on | on |
551
+
552
+ - **fast** — single-specialist path for small, low-risk asks; assertion ledger optional,
553
+ no nested delegation.
554
+ - **standard** — batched execution: one recon max, builder batches of 4–6 plan tasks with
555
+ one gate each, one review gate at the end.
556
+ - **strict** — the full Verification Contract (parity inventories, per-batch gates,
557
+ second confirming reads); use for production migrations and security-sensitive work.
558
+
559
+ When a budget is exhausted, `dispatch_agent`/`spawn_research` **refuse** with instructions
560
+ to summarize and ask one localized Yes/No `ask_user` question. **Yes** renews the turn budget
561
+ inside the same tool loop; the user does not type `continue` or run a slash command. A normal
562
+ new user message still opens a fresh turn window. Time blocked in any `ask_user` question is
563
+ excluded from the turn wall clock, so a slow human answer cannot exhaust the next dispatch.
564
+ Switch modes live with `/af-hub-mode fast|standard|strict` (no argument shows the current mode
565
+ and usage).
566
+ The live switch is deliberately **process/session-local**: it does not mutate another repository,
567
+ another pane, or the project's override file. A later `session_start` reapplies that repository's
568
+ configured default. Successful live switches and session-start default application append
569
+ `agent-hub-mode` entries to the Pi session record with an allowlisted identity (`cwd`, PID, Hub
570
+ session/project, and Herdr workspace/pane when available), so a mode change can be attributed to
571
+ the process that actually handled it. Set the project default and per-axis overrides in the
572
+ overrides file:
573
+
574
+ ```markdown
575
+ ## agent-hub
576
+ mode: standard # fast|standard|strict
577
+ max-dispatches-per-turn: 8 # integer or off
578
+ max-research-per-turn: 4 # integer or off
579
+ turn-wall-time-s: 3600 # integer or off
580
+ agent-turn-timeout-s: 1800 # whole-run deadline per spawned run; integer or off
581
+ session-recycle-runs: 5 # recycle a specialist session after N resumed runs; integer or off
582
+ run-history-keep: 10 # previous sessions' artifact archives to retain; integer or off
583
+ ```
584
+
585
+ #### Task budget (the bound a turn window cannot provide)
586
+
587
+ A per-message allowance cannot bound a task. In the run this guardrail comes from, every
588
+ steering message opened a fresh window of 8 dispatches and 60 minutes, so no counter ever
589
+ bound: one workspace stayed open **47 hours**, while the same change made in a narrow
590
+ workspace took **13 minutes**.
591
+
592
+ So there is a second envelope, **`TASK_BUDGET_MULTIPLIER` (3) × the turn envelope**, whose
593
+ counters are **not** reset by a user message:
594
+
595
+ | | per turn (standard, `feature`) | per task |
596
+ |---|---|---|
597
+ | `dispatch_agent` | 6 | 18 |
598
+ | `spawn_research` | 4 | 12 |
599
+ | clock | 60 min wall | 180 min **active** |
600
+
601
+ Exhausting it is a **hard stop**: the refusal says so, and another user message does not
602
+ reopen it. The hub asks one localized Yes/No `ask_user` question. **Yes** opens one audited
603
+ continuation tranche and resumes directly; it resets the task dispatch/research counters,
604
+ active-time clock, review allowance, and the current turn budget while preserving the task
605
+ tier, assertion ledger, capability packs, label, blockers, and accumulated progress. **No**
606
+ (or cancellation) stops. Each accepted tranche appends `agent-hub-budget-continuation` with
607
+ bounded prior usage and allowlisted process/session/pane identity.
608
+
609
+ `set_task_tier` with `new_task: true` remains the lifecycle action for genuinely different work.
610
+ It clears task identity/state as well as counters and appends an `agent-hub-task-reset` audit
611
+ entry. Do not use it merely to continue the same task. The status chip still shows both turn and
612
+ task usage (`… · task 4/18`).
613
+
614
+ The reasoning: three full envelopes still require an explicit human decision, but that decision
615
+ is now a single confirmation rather than a fake new task followed by a second message.
616
+
617
+ Both turn and task clocks charge **active time only** — turns that actually ran, minus the
618
+ time the dispatcher sat blocked on `ask_user`. Inter-turn idle costs nothing, because no turn
619
+ is open across it. Raw wall clock would bill a lunch break, an overnight pause, and every long
620
+ human answer against the task; at `fast` mode's 45-minute envelope a coffee break would
621
+ hard-stop a task with two dispatches spent. A false stop is worse than no stop — it teaches
622
+ people to reset the task window reflexively, and that reset is the one thing that has to
623
+ stay deliberate. Dispatch and research counts remain the honest hard stops.
624
+
625
+ The **auto-research pipe** (specialist emits `NEEDS_RESEARCH`, the hub fans out read-only
626
+ helpers in code) stays exempt from the TURN budget — it is hub mechanics, not a dispatcher
627
+ decision, and it must not steal the dispatcher's slots — but it **is** charged against the
628
+ task envelope. At 2 rounds × 4 questions per dispatch and 18 dispatches per task, leaving it
629
+ uncounted would have put 144 research runs inside the bound that is supposed to be the outer
630
+ one. When the task's research envelope is spent the pipe does not spawn and the specialist is
631
+ not resumed; the dispatch result says so.
632
+
633
+ Two related always-on behaviors: specialist **context pressure is measured over
634
+ input + cacheRead + cacheWrite** (resumed sessions re-send their whole accumulated context
635
+ as cache reads — counting `input` alone hid that entirely), and a specialist session is
636
+ **recycled** (fresh session, no `-c` resume) once it has served `session-recycle-runs` runs
637
+ or its measured context passes 60%. The dispatch result notes the recycle so the dispatcher
638
+ knows the specialist starts without session memory — task text and `artifacts:` paths must
639
+ carry the state, which the deliverable-to-file protocol already ensures.
640
+
641
+ Context is measured against **that agent's own** model window, resolved from pi's model
642
+ registry (`ctx.modelRegistry.find`) with the source recorded on every resolution. Dividing a
643
+ 49k local model's usage by the dispatcher's window is what produced unactionable readings
644
+ like `⚠ Planner context at 315%`; a reading above 100% now emits a one-time diagnostic that
645
+ names the window and where the number came from, so a mis-resolved window is distinguishable
646
+ from a genuine overflow. Two recycle rules follow from it: a session at or past a **full**
647
+ window is recycled unconditionally (no threshold override keeps it alive), and a resumed
648
+ session whose *projected* prompt — prior tokens plus this task — would overflow is recycled
649
+ **before** the spawn instead of after the run.
650
+
651
+ #### Per-provider concurrency
652
+
653
+ A dispatch may fan out to four delegate children at once and several specialists can be
654
+ mid-run, with nothing bounding how many requests land on one provider. That is fine against
655
+ a hosted endpoint and not against a local one. Requests are capped per process — **2 in
656
+ flight for `custom/*` by default, unlimited elsewhere**:
657
+
658
+ ```bash
659
+ AGENT_HUB_PROVIDER_LIMITS="custom=4" # raise the local cap
660
+ AGENT_HUB_PROVIDER_LIMITS="custom=off" # disable it
661
+ AGENT_HUB_PROVIDER_LIMITS="custom=2,ollama=1"
662
+ ```
663
+
664
+ Queued runs still execute — they wait for a permit, and the wait is announced rather than
665
+ looking like a hang. The cap applies per **level** of the delegation tree (each pi process
666
+ runs its own semaphore over the children it spawns), and a nested spawn reuses its parent's
667
+ permit, so a child can never wait on its own ancestor. The drift judge and the return
668
+ extractor are deliberately ungated: both run while a specialist holds a permit, so queueing
669
+ them behind it would stall the watchdog meant to stop it.
670
+
671
+ The per-run deadline lands as `turn_timeout` (exit 124) with partial output preserved, for
672
+ dispatched specialists, research helpers, and nested delegate children alike — a hung child
673
+ can no longer hold its parent for hours.
674
+
675
+ ### Task triage (complexity tiers)
676
+
677
+ The dispatcher classifies the current TASK with the `set_task_tier` tool BEFORE its first
678
+ dispatch — `trivial` / `small` / `feature` / `project` — and the hub lowers the enforced
679
+ dispatch/research caps to **min(mode, tier)**: trivial = 1 dispatch / 1 research,
680
+ small = 2 / 2, feature = 6 / 4, `project` defers to the mode. The tier shows in the
681
+ `hub-mode` status chip (`Mode: standard·small · …`), with a trailing `?` while it is only
682
+ assumed.
683
+
684
+ Skipping the call makes the hub assume **`small`**, not `feature`. Because the tier is
685
+ task-scoped, a skipped triage latches for the whole task — and skipped triage is precisely
686
+ the case where the dispatcher was not thinking about proportionality. Assuming `feature`
687
+ there would unlock planner/plan-reviewer/security-auditor, loosen the review caps, and hand
688
+ out the full feature envelope: the over-apparatus failure mode, granted by forgetting a tool
689
+ call. Assuming `small` costs one explicit escalation when the work really is bigger, which
690
+ is the cheap direction to be wrong in. An assumed tier is not a ratchet baseline either: the
691
+ dispatcher's own first `set_task_tier` is treated as an initial declaration, so it never
692
+ needs a `reason` it had no way to know it needed.
693
+
694
+ The tier is **task-scoped and ratcheted**. It survives the user's next message, and it
695
+ moves in one direction cheaply: **lowering it is always free, raising it requires a
696
+ `reason`** naming what the ask turned out to contain (refused in code otherwise). A
697
+ turn-scoped tier could not bind on a steered run — every correction reset it to null, the
698
+ next dispatch re-assumed `feature`, and the effective tier drifted to the ceiling, because
699
+ nobody ever re-declares `trivial` after a steering message.
700
+
701
+ Three guards are enforced in code, not prose:
702
+
703
+ - **Duplicate-dispatch guard** — refuses re-dispatching the same agent with a
704
+ near-identical task inside one turn.
705
+ - **Tier persona gate** — at `trivial`/`small`, `dispatch_agent`/`spawn_research` refuse
706
+ `planner`, `plan-reviewer`, `architect`, `security-auditor` and `deep-researcher`
707
+ (`run-budget.js`). Each opens a document/finding loop whose output then has to be
708
+ executed and re-reviewed; the escape hatch is raising the tier *with a reason*, not a
709
+ flag. The refusal costs no budget slot.
710
+ - **Review round cap** — review dispatches per TASK are capped by tier (trivial/small 1,
711
+ feature 2, project uncapped) and the (N+1)-th is refused without spending a budget slot.
712
+ This is where the review ratchet is actually cut: findings become requirements and the
713
+ enlarged requirement set justifies the next round, so the round is the thing to bound.
714
+ - **Review finding budget** — a review persona's dispatch carries a blocking-finding cap
715
+ tied to the tier (trivial 1, small 2, feature 5, project uncapped) plus the rule that a
716
+ blocking finding may only enforce an invariant the task/plan/rules already state. The hub
717
+ **counts** what came back (`review-findings.js`) and appends a visible notice when the
718
+ return exceeds the cap — it never reclassifies a finding. No rule the hub can evaluate
719
+ distinguishes "invents a manifest nobody asked for" from "this logs a connection string";
720
+ both are a heading and a bullet, and silently demoting the second by position would, on
721
+ the day it matters, move a real security finding into the section nobody acts on.
722
+
723
+ Every budget/gate refusal is counted in `/af-hub-report`.
724
+
725
+ ### Docs lane (`docs-lane.js`)
726
+
727
+ A dispatch whose declared `scope` is documentation only — `Docs/**`, `**/*.md`,
728
+ `artifacts/evidence/*.png`, `.changeset/**` — runs in the single-worker docs lane:
729
+
730
+ - dispatching a review persona (`code-reviewer`, `plan-reviewer`, `security-auditor`,
731
+ `test-engineer`) on it is **refused** and costs no budget slot;
732
+ - any other persona's result carries a note telling the dispatcher not to open a review
733
+ gate for it.
734
+
735
+ An absent or empty `scope` is never the lighter lane — unknown is not docs. The refusal is
736
+ overridable per dispatch with `review_reason: "<why>"` for the cases that do warrant a gate
737
+ (the doc publishes a credential, or states a contract other systems depend on).
738
+
739
+ ### External-blocker stop (`external-blocker.js`)
740
+
741
+ A specialist that cannot proceed without something outside the fleet's reach — an account,
742
+ a permission, a deployment credential, a telemetry destination, a console-only action —
743
+ emits `EXTERNAL_BLOCKED: <what is missing, who owns it, what it blocks>` (the protocol is
744
+ injected into every specialist prompt). The hub records it and **refuses the next
745
+ dispatch/research** with an owner-escalation packet: what is missing and who owns it, which
746
+ assertions are blocked, what is already proven and where, and the human's options (provide
747
+ access / waive as UNPROVEN / drop from scope).
748
+
749
+ The gate opens when the human has been addressed — an `ask_user` call, or the next user
750
+ message. Without `ask_user` installed it fires exactly once, so a session that cannot reach
751
+ the human can still finish and report instead of deadlocking.
752
+
753
+ This exists because the alternative is the most expensive failure mode observed: with no
754
+ correlation destination available, a run kept substituting internal work for the missing
755
+ external fact — scripts, manifests, fixtures, diagnostic packets — for hours, and the
756
+ assertion still ended UNPROVEN.
757
+
758
+ ### Immutable per-run artifact namespaces (`run-namespace.js`)
759
+
760
+ Session start used to `rm -rf` `.pi/agent-sessions/artifacts/`, and specialist returns were
761
+ named by a per-session counter (`returns/builder-run1.md`). Both halves of that failed at
762
+ once: the next session's `builder-run1.md` claimed the same path as the previous one's, and
763
+ the wipe deleted the originals first — a post-mortem had to record eleven implementation
764
+ returns and two review artifacts as NOT RECOVERABLE.
765
+
766
+ Now each session **archives** the previous session's artifacts into
767
+ `.pi/agent-sessions/runs/<runId>/artifacts/` — a namespace written once and never reused —
768
+ alongside a read-only `meta.json` (run id, archive time, project, workspace, per-kind
769
+ artifact counts) and an appended `runs/index.json`. `runId` is a sortable UTC timestamp plus
770
+ a random suffix, so two sessions starting in the same second still get distinct namespaces.
771
+ Retention is `run-history-keep` (default 10, `off` keeps everything); an empty artifact tree
772
+ is not archived. If archiving fails the artifacts are **left in place** rather than deleted:
773
+ a stale tree is recoverable, a deleted one is not.
774
+
775
+ ### Drift watchdog (in-flight observation)
776
+
777
+ An armed dispatch is observed **while it runs**, from the same JSON event stream that
778
+ drives the cards — not post-hoc:
779
+
780
+ - **Layer 1 — deterministic rules, zero tokens** (`drift-watchdog.js`): a write/edit
781
+ outside the dispatch's declared `scope` globs, the identical tool call repeated 4×,
782
+ 5 consecutive failed tool calls, or 200 total tool calls in one run.
783
+ - **Layer 2 — LLM judge, escalation only**: when a rule fires (single-flight, 90 s
784
+ cooldown), a one-shot cheap run (default model: the researcher persona's; override with
785
+ `watchdog-judge-model`) reads the original task + declared scope + recent tool trail and
786
+ answers `VERDICT: ON_TRACK|DRIFTING|STUCK`. Judge failures fail open.
787
+ - **Intervention**: DRIFTING/STUCK terminates the run as **`drift_stop`** (exit 125,
788
+ partial output preserved) and the dispatch result instructs: re-dispatch ONCE with a
789
+ corrected, narrowed task — never the same task unchanged.
790
+
791
+ Enablement is dynamic, precedence top to bottom: the `watchdog: true|false` param on a
792
+ single `dispatch_agent` call → a per-agent override (`/af-watchdog builder on|off|clear`) →
793
+ the hub-wide setting (`/af-watchdog on|off|auto`, default `auto`, project default via the
794
+ `watchdog:` overrides key). Read-only research helpers are not monitored — they already
795
+ run under the per-tool watchdog + turn deadline and cannot write.
796
+
797
+ ### Dynamic teams
798
+
799
+ Rosters start from `.pi/agents/teams.yaml` but are not frozen there:
800
+
801
+ - `/af-agents-add <persona>…` / `/af-agents-drop <persona>…` — restructure the ACTIVE team
802
+ live (drop refuses running or last members; session files are kept for re-adding).
803
+ - `/af-agents-save <name>` — persist the current roster as a named team back into
804
+ `teams.yaml` (targeted block upsert; comments and other teams untouched).
805
+ - `team_adjust` — the dispatcher itself may add/drop a persona **with a stated reason**;
806
+ disabled in fast mode, capped at 8 roster members, and every change is notified to the
807
+ human. The system prompt is rebuilt each turn, so changes take effect immediately.
808
+
809
+ ### `/af-hub-report`
810
+
811
+ Per-turn cost accounting: dispatches (agent, status, elapsed, billed/output tokens),
812
+ research runs, session recycles, drift stops, and budget/duplicate refusals — for the
813
+ current turn, the last completed turn, and session totals. Billed tokens count
814
+ input + cacheRead + cacheWrite, the same measure the recycler uses.
815
+
816
+ Paths that don't exist produce a session-start warning, never an error. The full key list for
817
+ `## agent-hub` (models, sub-roles, depth budgets, persona gate, research retention, watchdog,
818
+ mode/budget keys) is documented in `docs/agent-fleet-setup.md`.
819
+
820
+ ## The coms layer
821
+
822
+ > The runtime coordination protocols this layer implements (sentinels, push over
823
+ > polling, barriers, fan-out digests, racing) are catalogued in
824
+ > [references/fleet-coordination-patterns.md](../../../references/fleet-coordination-patterns.md).
825
+
826
+ ### Fleet tools (herdr)
827
+
828
+ Inside a [herdr](https://herdr.dev) pane with a live server, the dispatcher's tool
829
+ surface additionally gets (absent otherwise, like coms):
830
+
831
+ - `herdr_spawn_peer` — stand up a constrained Fleet peer through the shared peer-launch resolver.
832
+ The peer joins **this session's `--project` pool** (the model cannot override it), and a name
833
+ declared in `.pi/agents/peers.yaml` keeps its declared `runner:`/`extensions:`/`env_file:`,
834
+ including `runner: claude-code`; undeclared explicit shapes may select a Pi persona, identity-only
835
+ Fleet Core peer, or Claude Code. Manifest-declared env is the only env admitted. The peer gets a
836
+ sibling pane in the current workspace/tab, not a second process in the Hub pane. A spawn by name
837
+ therefore produces the same declared agent as a preset launch. A persona peer **boots idle**
838
+ and does nothing until a `coms_send` reaches it, so the call waits (bounded, ~45s) for it to
839
+ register and returns `peer_ready` plus its coms name instead of a bare pane id; on failure it
840
+ returns the pane's last output, which means the peer did not start rather than that it is slow.
841
+ Peers spawned but never addressed are named at turn end and in `/af-hub-report` with a close
842
+ suggestion — closing stays the human's call.
843
+ Mechanism: herdr's `pane.split` takes **no command** — it opens a shell — so the spawn splits,
844
+ waits for the pane's prompt, and types the argv (text and Enter sent separately, because bash
845
+ bracketed paste would swallow a newline). Only `layout.apply` pane nodes carry an argv, which is
846
+ why declarative preset layouts were never affected by this.
847
+ - `herdr_spawn_pane` — create an arbitrary command pane when a constrained/addressable Fleet peer
848
+ is not the desired shape; raw commands are intentionally excluded from `herdr_spawn_peer`.
849
+ Orchestrators may use this for auxiliary processes such as watchers or servers, never to bypass
850
+ delegate-only implementation policy.
851
+ - `herdr_read_pane` — bounded `pane.read` (≤200 lines), read-to-decide on workers/tools;
852
+ messaging still goes through coms, and peer busy state comes from `coms_list`, not from
853
+ reading the screen
854
+ - `herdr_close_pane` — kills a pane; **asks the human to confirm every call**; the
855
+ bash-level `herdr pane close`/`workspace close`/`server stop` verbs are hard-blocked
856
+ for spawned specialists by `.pi/damage-control-rules.yaml`
857
+ - `herdr_notify` — desktop notification to reach the human when they are away
858
+
859
+ This closes the fleet loop: spawn a worker, watch it, notify the human, tear it down —
860
+ without leaving the session. Claude Code panes join the same pool via the
861
+ [coms bridge](../../../docs/claude-code-coms-bridge.md).
862
+
863
+ ### Presence backend (herdr or files)
864
+
865
+ Presence is pluggable, exactly as in the standalone [coms harness](../coms/README.md#presence-backends-herdr-vs-files):
866
+ inside a [herdr](https://herdr.dev) pane with a live server, the ping cycle is replaced by
867
+ push events (`agent.list` + `events.subscribe`) and the hub reports itself into the herdr
868
+ sidebar (`custom_status` = `<name> <pct>% q<depth>`); everywhere else the original 10s
869
+ ping loop runs unchanged. The file registry is written in both backends, and the
870
+ pool-scope boundary is enforced identically.
871
+
872
+ ### Identity
873
+
874
+ Each session registers a coms identity at start-up, resolved in this precedence order:
875
+
876
+ 1. **CLI flags** — `--name`, `--purpose`, `--project`, `--color`, `--explicit`
877
+ 2. **Dispatcher persona frontmatter** — `name`, `description` (→ purpose), `color` from the
878
+ selected `kind: orchestrator` persona (see [persona sync](#persona--coms-purpose-sync))
879
+ 3. **Defaults** — auto-generated name `hub-<id>`, purpose `agent-hub dispatcher`, project
880
+ `default`, a deterministic color derived from the session id
881
+
882
+ Names are de-duplicated per project (`resolveUniqueName`), so two hubs that both want `architect`
883
+ become `architect` and `architect-2`. `--explicit` marks a **private** peer — kept out of every
884
+ pool by default, so it is neither listed nor reachable until a human opts in with `/af-coms --all`
885
+ (see [Pool scope is the reach boundary](#pool-scope-is-the-reach-boundary)). The registry lives
886
+ under `~/.pi/coms/projects/<project>/agents/<name>.json` and is created at runtime.
887
+
888
+ ### Commands & tools (local dispatcher plus coms)
889
+
890
+ - `/af-coms` — coms control surface (peer list / status)
891
+ - `/af-handoff <peer>` — hand the whole session off to a coms peer (see [Handoff](#handoff))
892
+ - `/af-compound [focus]` — end-of-session **compound-learning pass**: the dispatcher composes a
893
+ candidate-lessons brief from the session (corrections, recurring findings, root causes),
894
+ confirms it with the user, then dispatches the `documenter` to land the approved lessons as
895
+ minimal diffs on the project's `rules:`/`docs:` targets per `skills/compound-learning/SKILL.md`.
896
+ Requires the `documenter` persona in the active team; run it before `/af-handoff` or session end.
897
+ - `coms_list` — discover the peers in your pool: names, models, live context usage, purpose,
898
+ `pane_id`, and `status` (`idle` | `working` | `booting`). Check status before sending: `working`
899
+ means your send waits behind the peer's current turn, `booting` means it is not addressable yet.
900
+ This is the field whose absence drove 127 `herdr_read_pane` calls in one session. Scoped
901
+ to your project and excluding private peers; the LLM cannot widen it (see
902
+ [Pool scope is the reach boundary](#pool-scope-is-the-reach-boundary)).
903
+ - `coms_send` — send a prompt to a peer **in your pool**; returns a `msg_id`
904
+ - `coms_await` — **block** until that `msg_id`'s reply lands (default 30 min,
905
+ `PI_COMS_TIMEOUT_MS`)
906
+ - `coms_get` — **non-blocking** poll of a `msg_id` (status `pending|complete|error`)
907
+
908
+ `/af-coms` and `/af-handoff` tab-complete live peer names **in your pool**.
909
+
910
+ ### Pool scope is the reach boundary
911
+
912
+ The set of peers shown in the pool widget is the security boundary: **a peer is reachable only if it
913
+ is in your pool.** `coms_list`, `coms_send`, and `/af-handoff` all resolve targets through the same
914
+ `peersInScope()` helper, so the dispatcher can never message a peer it cannot see. Two knobs define
915
+ the pool, and **both are human-only** — the LLM cannot widen scope to reach more peers:
916
+
917
+ - **Project** — defaults to your own `identity.project`. A human can retarget with `/af-coms --project
918
+ <name>` (one project) or `/af-coms --all` (every project). `coms_list`'s own parameters cannot
919
+ override this; an LLM request for a wider project is clamped back to the current pool and flagged.
920
+ - **Explicit (private) peers** — excluded from every pool by default. `/af-coms --all` opts them in.
921
+
922
+ This closes a cross-project leak where a peer reachable through the mesh was *not* shown in the
923
+ default project-scoped pool — so it could be messaged without being "connected." Now the reachable
924
+ set is always a subset of what the widget shows. To reach a peer outside the pool, a human widens
925
+ scope first; the dispatcher is told to **ask** rather than attempt it, and not to pass cross-project
926
+ context to a peer the human has not approved.
927
+
928
+ ### Peer as subagent
929
+
930
+ The dispatcher uses a peer as a subagent by pairing the tools: `coms_send(target, prompt)` to
931
+ issue the task, then `coms_await(msg_id)` to block for the reply (or `coms_get` to poll). This sits
932
+ alongside `dispatch_agent` — local persona specialists are dispatched as subprocesses; remote peers
933
+ are reached over coms. The two paths stay explicit for the LLM, but
934
+ [coms-backed dispatch](#coms-backed-dispatch-dispatch-policyyaml) can route a `dispatch_agent` call
935
+ to a same-name peer under the hood. (The specialist-level `delegate` tool is a third,
936
+ nested path: a dispatched specialist spawning its own declared sub-agents — it does not auto-route
937
+ between local and remote either.) Multi-hop is inherited from coms: a peer handling a dispatched task can `coms_send`
938
+ onward, hops accumulating up to `MAX_HOPS` (5).
939
+
940
+ ### Coms-backed dispatch (dispatch-policy.yaml)
941
+
942
+ `just fleet --agents <roster> --peers <preset>` boots the Hub next to standing peers from
943
+ `.pi/agents/peers.yaml` — and some
944
+ of them (e.g. `code-reviewer`, `plan-reviewer` with `runner: claude-code`) intentionally share a name
945
+ with a team member. `.pi/agents/dispatch-policy.yaml` tells the dispatcher to serve such members
946
+ **through the peer** instead of spawning a native subagent:
947
+
948
+ ```yaml
949
+ default: native # coms = substitute ANY member with a live same-name pool peer
950
+ grace_s: 30 # poll window for coms-required members
951
+ substitutions:
952
+ code-reviewer:
953
+ prefer: coms
954
+ fallback: native # none = coms-required: refuse with guidance instead of spawning
955
+ # timeout_s: 3600 # per-member reply timeout (default PI_COMS_TIMEOUT_MS, 30 min)
956
+ ```
957
+
958
+ Semantics:
959
+
960
+ - **One API with an explicit override.** `dispatch_agent(..., backend: "auto"|"native"|"coms")`
961
+ defaults to `auto`, which follows this policy. `native` always starts the local Pi specialist even
962
+ when a same-name peer is live. `coms` requires that live same-name peer and never falls back to
963
+ native. The whole downstream pipeline — structured return contract,
964
+ `ASK_USER:` extraction, the NEEDS_RESEARCH auto-research pipe, assertions, history, the grid —
965
+ consumes a coms reply exactly like a subagent's final output (the dispatch protocols ride in the
966
+ message body, since a standing peer only receives a user prompt).
967
+ - **Decided per dispatch, against the live pool.** Hub and peers boot in parallel, so the first
968
+ dispatch may land before the peer registers: with `fallback: native` it runs natively (one notice
969
+ per member per team activation), and later dispatches pick up the peer once it is live. With
970
+ `fallback: none` the dispatch polls the pool for `grace_s` seconds, then refuses with remediation
971
+ steps. The name match is scoped to the coms pool — the same security boundary as `coms_send`.
972
+ - **Standing context is the point.** Re-dispatches (ASK_USER answers, research resumes) go back to
973
+ the same peer session, so a Claude Code reviewer keeps its review context across rounds.
974
+ - **Visibility.** The member's grid card shows a `⇄coms <peer-model>` badge, history entries are
975
+ annotated `(coms)`, and `/af-dispatch-policy` prints the resolved routing per member with live-peer
976
+ status.
977
+ - **Limitations.** `/af-agents-kill` on a coms-backed run only abandons the wait — the peer keeps
978
+ running in its own pane and cannot be killed from the hub (`/af-agents-restart` abandons, then
979
+ re-dispatches). `/af-zoom` shows only the final reply (there is no stream), tool counts stay 0, and
980
+ context% is a registry snapshot. `/af-agent-model` overrides apply only to native(-fallback) runs —
981
+ the peer's model is set in `peers.yaml`.
982
+
983
+ Missing file = everything native. HOW a peer runs (persona, model, `runner: claude-code`, env) stays
984
+ in `peers.yaml`; this file only decides WHEN the hub prefers a peer over a native spawn.
985
+
986
+ ### Handoff
987
+
988
+ `/af-handoff <peer>` transfers the session to another **main** agent. Following the plan's
989
+ **decision G1**, it does *not* try to extract a compaction summary; instead it asks the dispatcher
990
+ LLM to compose a **self-contained brief** ("everything the target needs, assume no shared history"),
991
+ then `coms_send`s that brief to the peer, `coms_await`s the reply, and relays it back — in the
992
+ configured user-facing language. When the handoff `coms_send` fires, the hub appends machine-generated
993
+ sections after the LLM brief: `## Verification ledger (verbatim, machine-appended)` with every current
994
+ assertion in canonical ledger form, and `## Artifact index` with artifact paths plus first headings.
995
+ The target peer must treat the machine-appended ledger as the contract, not the paraphrased brief.
996
+ The target peer takes over; the source relays the result. There is no raw session copy (pi sessions
997
+ aren't portable between live agents). The target must be a peer in your pool — `/af-handoff` resolves
998
+ through the same [scope boundary](#pool-scope-is-the-reach-boundary) as `coms_send`, so you cannot
999
+ hand a session to a peer you cannot see.
1000
+
1001
+ ### Pool widget
1002
+
1003
+ A live "pool" widget lists connected peers with name, model, and live context usage, refreshed by a
1004
+ ping cycle; a keepalive cycle re-writes this session's own registry entry (and self-heals it if an
1005
+ external prune removed it). Both timers are `unref`'d so they never hold the process open.
1006
+
1007
+ ### Persona → coms purpose sync
1008
+
1009
+ The dispatcher persona gate fires *after* coms init, so the identity's `purpose` starts from the
1010
+ flag/frontmatter/default and is then reconciled to the chosen persona: `syncComsPurpose()` maps the
1011
+ selected `kind: orchestrator` persona to `"<Name> — <description>"` and re-writes the live registry
1012
+ entry — **unless** `--purpose` was passed explicitly (an explicit flag always wins). Switching or
1013
+ resetting the persona via `/af-persona` re-syncs.
1014
+
1015
+ ### Graceful degradation
1016
+
1017
+ If the coms socket can't bind at start-up (`comsReady` stays `false`), the session degrades to a
1018
+ local dispatcher without coms: the `coms_*` tools are withheld from `setActiveTools`, the
1019
+ `/af-handoff` command refuses with a notice, and the "Peer agents (coms)" prompt section is omitted.
1020
+ Orchestration, research helpers, and the grid keep working.
1021
+
1022
+ ### Tool surface
1023
+
1024
+ `setActiveTools` always preserves the orchestration surface and adds runtime-ready capabilities.
1025
+ Operator posture also preserves the baseline direct/extension tools; orchestrator posture does not.
1026
+ Coms tools are active only when coms is ready, Herdr tools only in a live Herdr pane, and `ask_user`
1027
+ only when registered. Posture switching recomputes this list live without touching session state.
1028
+
1029
+ `set_assertions` / `update_assertion` / `get_assertions` are the always-on Verification Contract ledger tools (see
1030
+ [What it does](#what-it-does)); like `dispatch_agent` / `spawn_research` they are part of the
1031
+ orchestration surface the dispatcher persona never narrows.
1032
+
1033
+ The dispatcher persona is **flavor-only** (decision G4 / 9) — it enriches the role but never narrows
1034
+ this tool set, so coms and dispatch stay available regardless of the chosen persona.
1035
+
1036
+ ## Optional Hermes local monitor transport
1037
+
1038
+ The optional monitor is an Agent Fleet-owned transport boundary, not a Hermes runtime API or a
1039
+ bundled Hermes plugin. When enabled, `agent-hub` publishes dispatcher-turn and specialist-run
1040
+ state and owns generation-safe cancellation. A separate local Hermes UI or operator client may
1041
+ consume the owner-only discovery + Unix-socket contract documented in
1042
+ [`hermes/README.md`](../../../hermes/README.md#local-agent-hub-monitor-integration).
1043
+
1044
+ Set these before the hub starts:
1045
+
1046
+ ```bash
1047
+ export AGENT_FLEET_PROFILE_ID="approved-profile-id"
1048
+ export AGENT_FLEET_MONITOR_RUNTIME_DIR="/absolute/owner-only/runtime-root"
1049
+ ```
1050
+
1051
+ Both are required for monitor startup; the runtime root must be absolute and owner-only, and the
1052
+ profile ID must be a safe identifier. The monitor also starts only for a Herdr-backed hub with
1053
+ `HERDR_WORKSPACE_ID` and `HERDR_PANE_ID`; retain those values and `HERDR_SOCKET_PATH` in the
1054
+ standard `just fleet --agents <roster> --peers <preset>` flow. Workspace labels are display metadata, not monitor identity.
1055
+
1056
+ The live contract exposes three authenticated newline-delimited JSON requests: `snapshot`, cursor-
1057
+ based `output`, and exact-generation `cancel`. The monitor is local-only and fails closed when its
1058
+ profile discovery, lease, token, or Unix socket is unavailable. A native cancel targets only the
1059
+ matching hub-owned process generation. A coms cancel abandons the local wait only; its peer can
1060
+ continue. Neither path controls or closes a Herdr workspace/pane.
1061
+
1062
+ Example startup:
1063
+
1064
+ ```bash
1065
+ monitor_runtime="${XDG_RUNTIME_DIR:?}/agent-fleet-monitor"
1066
+ install -d -m 700 "$monitor_runtime"
1067
+ AGENT_FLEET_PROFILE_ID=dev \
1068
+ AGENT_FLEET_MONITOR_RUNTIME_DIR="$monitor_runtime" \
1069
+ just fleet --agents default --peers default
1070
+ ```
1071
+
1072
+ No Desktop/backend plugin installation is required or provided. Consumers must re-discover after
1073
+ lease or socket loss and must never persist or log the token.
1074
+
1075
+ ## Requires
1076
+
1077
+ - `.pi/agents/teams.yaml` for fixed specialist teams, the referenced persona `.md` files, and
1078
+ (strongly recommended) [`pi-ask-user`](https://github.com/edlsh/pi-ask-user).
1079
+ - `.pi/damage-control-rules.yaml` for every guarded `just fleet` Pi mode.
1080
+ - Nothing extra in-repo for coms — the peer registry lives at `~/.pi/coms/` and is created at
1081
+ runtime.
1082
+
1083
+ ## Usage
1084
+
1085
+ ```bash
1086
+ # Unified Fleet interface (Fleet Core + Agent Hub are loaded together)
1087
+ just fleet
1088
+ just fleet --posture operator --agents frontend --project myrepo
1089
+ just fleet --agents frontend --peers frontend --project myrepo
1090
+
1091
+ # equivalent direct guarded launch
1092
+ pi -e .pi/harnesses/damage-control-continue/index.ts -e .pi/harnesses/ask-user-remote/index.ts -e .pi/harnesses/agent-hub/index.ts
1093
+ pi -e .pi/harnesses/damage-control-continue/index.ts -e .pi/harnesses/ask-user-remote/index.ts -e .pi/harnesses/agent-hub/index.ts --name releaser --explicit
1094
+
1095
+ # direct unguarded launch, only when you intentionally want to skip damage-control
1096
+ pi -e .pi/harnesses/agent-hub/index.ts
1097
+ ```
1098
+
1099
+ Identity flags: `--name`, `--purpose`, `--project`, `--color`, `--explicit`.
1100
+
1101
+ ### Safety scope
1102
+
1103
+ `just fleet` and `just fleet --no-coms` load Fleet Core before `agent-hub`, so guardrails and `ask_user` apply
1104
+ to hub/dispatcher tool calls in that parent pi process — and because it is the *continue* variant, a
1105
+ blocked dispatcher call feeds back and the turn keeps going rather than aborting. Specialist and
1106
+ research agents are spawned as separate pi subprocesses with `--no-extensions` — but `agent-hub`
1107
+ resolves `damage-control-continue` from this session's `-e` flags, else the repo-local harness, and
1108
+ re-loads it into every native specialist, research helper, and nested delegate via explicit `-e`.
1109
+ `--no-extensions` keeps discovery off, so children never auto-load `.pi/extensions/` utilities or
1110
+ recursively re-load `agent-hub`; the explicit guardrail still checks every child's tool calls against
1111
+ `.pi/damage-control-rules.yaml`. Protected-path blocks escalate to the hub for explicit approval;
1112
+ protected deletions offer only Deny or Allow once, while inherently dangerous command patterns are
1113
+ non-exemptible. Denial or timeout blocks the call without aborting the child's turn. If continue
1114
+ cannot be resolved, dispatch is refused—children are never spawned unguarded. Research helpers are
1115
+ additionally read-only by construction. Guided setup enforces `agent-hub` ⇒
1116
+ `damage-control-continue` + `ask-user-remote`.
1117
+
1118
+ ### Related recipes
1119
+
1120
+ ```bash
1121
+ # Operator/native work without coms
1122
+ just fleet --no-coms
1123
+
1124
+ # Hub-only Herdr workspace and a combined topology
1125
+ just fleet --herdr --project af
1126
+ just fleet --agents default --peers docs --project af
1127
+ just fleet --agents default --peers docs --project af --dry-run
1128
+
1129
+ # Compatibility aliases (accepted with migration warnings)
1130
+ just fleet hub --solo
1131
+ just fleet team docs
1132
+
1133
+ # Snapshot refs / close cleanly / restore conversations
1134
+ just fleet snapshot docs
1135
+ just fleet down docs
1136
+ just fleet resume docs
1137
+ ```
1138
+
1139
+ `peers.yaml` groups reusable peers into named teams; each entry is `name` / `persona`
1140
+ (+ optional `model`). The persona's frontmatter `description`/`color` become the peer's
1141
+ coms purpose/color.
1142
+
1143
+ ## How it differs from its sources
1144
+
1145
+ - **Embedded, not stacked (decision 1).** coms is folded into this one `index.ts`; the identity
1146
+ flags are registered once. Loading `coms` as a second `-e` would double-register
1147
+ `--name/--purpose/...` and abort start-up.
1148
+ - **Single `session_start`.** coms init is folded into the former dispatcher's `session_start` and
1149
+ guarded by `if (!comsReady)`, so `/new` reuses the same peer identity (no leaked socket).
1150
+ - **Dispatcher is also a peer.** `setActiveTools` lists `coms_*` alongside `dispatch_agent` +
1151
+ `spawn_research` (+ `ask_user`); the system prompt gains a "Peer agents (coms)" section when coms
1152
+ is ready. The persona's `description` drives the coms `purpose` (decision 6 / Phase 6 peer
1153
+ mapping) instead of a static `--purpose`.
1154
+ - **`/af-handoff` uses an LLM-composed brief**, not a compaction-summary extraction (decision G1).
1155
+ - **Clean shutdown** SIGTERMs any running specialist/research children, clears the coms pool
1156
+ widget, and removes the registry entry on `session_shutdown` / SIGINT / SIGTERM.