@e4779/pi-fabric 0.131.4-fork.33 → 0.138.1-fork.1

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 (435) hide show
  1. package/README.md +8 -0
  2. package/dist/actors/context.d.ts.map +1 -1
  3. package/dist/agents/clone-first-worktree.d.ts +2 -0
  4. package/dist/agents/clone-first-worktree.d.ts.map +1 -1
  5. package/dist/agents/completion-inbox.d.ts +2 -1
  6. package/dist/agents/completion-inbox.d.ts.map +1 -1
  7. package/dist/agents/handoff.d.ts.map +1 -1
  8. package/dist/agents/manager.d.ts.map +1 -1
  9. package/dist/agents/worktree-manager.d.ts +4 -1
  10. package/dist/agents/worktree-manager.d.ts.map +1 -1
  11. package/dist/agents/worktree-paths.d.ts +8 -3
  12. package/dist/agents/worktree-paths.d.ts.map +1 -1
  13. package/dist/agents.js +6 -1
  14. package/dist/agents.js.map +1 -1
  15. package/dist/async-settlement.d.ts +1 -1
  16. package/dist/async-settlement.d.ts.map +1 -1
  17. package/dist/audit/details.d.ts.map +1 -1
  18. package/dist/capture/catalog.d.ts +2 -0
  19. package/dist/capture/catalog.d.ts.map +1 -1
  20. package/dist/capture/interceptor.d.ts.map +1 -1
  21. package/dist/chunks/{chunk-7N7IC3Z2.js → chunk-2CD7HLVP.js} +3 -84
  22. package/dist/chunks/chunk-2CD7HLVP.js.map +7 -0
  23. package/dist/chunks/{chunk-7YNE4NB2.js → chunk-2MELFQCQ.js} +2 -2
  24. package/dist/chunks/{chunk-HSEZPCL5.js → chunk-2OC4YJOL.js} +3 -3
  25. package/dist/chunks/{chunk-TXCNZCZP.js → chunk-2QJ4MNS6.js} +2 -2
  26. package/dist/chunks/{chunk-F6A6MQ6G.js → chunk-2WPTD6BI.js} +11 -15
  27. package/dist/chunks/chunk-2WPTD6BI.js.map +7 -0
  28. package/dist/chunks/{chunk-QOEOKW2X.js → chunk-3QH6JAE3.js} +2 -2
  29. package/dist/chunks/chunk-4U47NCP2.js +88 -0
  30. package/dist/chunks/chunk-4U47NCP2.js.map +7 -0
  31. package/dist/chunks/{chunk-OJ4HAALD.js → chunk-5VZEAAHD.js} +10 -9
  32. package/dist/chunks/chunk-5VZEAAHD.js.map +7 -0
  33. package/dist/chunks/{chunk-LKYLD5SN.js → chunk-6HM4TX7L.js} +10 -8
  34. package/dist/chunks/chunk-6HM4TX7L.js.map +7 -0
  35. package/dist/chunks/{chunk-L6H46CPY.js → chunk-6NNL5LOG.js} +2 -2
  36. package/dist/chunks/{chunk-7TB7NXSL.js → chunk-7CIQQOOD.js} +11 -3
  37. package/dist/chunks/{chunk-7TB7NXSL.js.map → chunk-7CIQQOOD.js.map} +2 -2
  38. package/dist/chunks/{chunk-RWKQ5SRW.js → chunk-7ZFPVOV2.js} +2 -2
  39. package/dist/chunks/{chunk-PUBHBEYO.js → chunk-B2FIGOPI.js} +2 -2
  40. package/dist/chunks/{chunk-HRDMBGMY.js → chunk-BLT66VHH.js} +331 -22
  41. package/dist/chunks/chunk-BLT66VHH.js.map +7 -0
  42. package/dist/chunks/{chunk-4WKD3YM3.js → chunk-C3UPHOJW.js} +3 -3
  43. package/dist/chunks/{chunk-G2DZJ5LK.js → chunk-CB72SLHB.js} +451 -134
  44. package/dist/chunks/chunk-CB72SLHB.js.map +7 -0
  45. package/dist/chunks/{chunk-B5L3X3ID.js → chunk-CCJ6PUZJ.js} +1 -1
  46. package/dist/chunks/{chunk-B5L3X3ID.js.map → chunk-CCJ6PUZJ.js.map} +1 -1
  47. package/dist/chunks/{chunk-FK73YJKV.js → chunk-DWM63MAJ.js} +21 -9
  48. package/dist/chunks/chunk-DWM63MAJ.js.map +7 -0
  49. package/dist/chunks/{chunk-56NMRVTV.js → chunk-FFJ7TV66.js} +32 -29
  50. package/dist/chunks/chunk-FFJ7TV66.js.map +7 -0
  51. package/dist/chunks/{chunk-LRSZFYUC.js → chunk-FUMALXYQ.js} +15 -15
  52. package/dist/chunks/chunk-FUMALXYQ.js.map +7 -0
  53. package/dist/chunks/{chunk-TJZYM2SP.js → chunk-G3RQ3HUK.js} +8 -3
  54. package/dist/chunks/{chunk-TJZYM2SP.js.map → chunk-G3RQ3HUK.js.map} +2 -2
  55. package/dist/chunks/{chunk-RAA3FAYZ.js → chunk-GNPTDN6K.js} +2 -2
  56. package/dist/chunks/{chunk-XFOSUGLU.js → chunk-JCGEW5OQ.js} +5 -5
  57. package/dist/chunks/{chunk-CXYJJ3HZ.js → chunk-LJ2MG6U2.js} +3 -3
  58. package/dist/chunks/{chunk-3MOY6WIB.js → chunk-LRBDEAKB.js} +3 -3
  59. package/dist/chunks/{chunk-2RWNVCFD.js → chunk-MPFBOVOD.js} +1 -1
  60. package/dist/chunks/{chunk-2RWNVCFD.js.map → chunk-MPFBOVOD.js.map} +1 -1
  61. package/dist/chunks/{chunk-NQ7IWEIF.js → chunk-MQGRQMVM.js} +2 -2
  62. package/dist/chunks/{chunk-3VK6UGAN.js → chunk-O5SHIUIL.js} +6 -1
  63. package/dist/chunks/chunk-O5SHIUIL.js.map +7 -0
  64. package/dist/chunks/{chunk-U6Y6TKJL.js → chunk-OK2EKY3M.js} +15 -11
  65. package/dist/chunks/chunk-OK2EKY3M.js.map +7 -0
  66. package/dist/chunks/{chunk-DGUXJSYA.js → chunk-OR44GYXD.js} +70 -3
  67. package/dist/chunks/chunk-OR44GYXD.js.map +7 -0
  68. package/dist/chunks/{chunk-DGERP4VL.js → chunk-P4TALNLX.js} +11 -10
  69. package/dist/chunks/chunk-P4TALNLX.js.map +7 -0
  70. package/dist/chunks/{chunk-4BYS4ZLY.js → chunk-PHGPOSCP.js} +267 -71
  71. package/dist/chunks/chunk-PHGPOSCP.js.map +7 -0
  72. package/dist/chunks/{chunk-3XT5WHSG.js → chunk-QAGEWWCJ.js} +260 -59
  73. package/dist/chunks/chunk-QAGEWWCJ.js.map +7 -0
  74. package/dist/chunks/{chunk-WKFRGICG.js → chunk-RBYRHS24.js} +2 -2
  75. package/dist/chunks/{chunk-ZHROHNEE.js → chunk-RFNYH7S7.js} +8 -8
  76. package/dist/chunks/{chunk-VGRUWTMG.js → chunk-RPZJVLML.js} +472 -466
  77. package/dist/chunks/chunk-RPZJVLML.js.map +7 -0
  78. package/dist/chunks/{chunk-H57KPL3V.js → chunk-S2JWFXW5.js} +2 -2
  79. package/dist/chunks/{chunk-LZ2ZXOCU.js → chunk-SSB2JN3I.js} +168 -5
  80. package/dist/chunks/chunk-SSB2JN3I.js.map +7 -0
  81. package/dist/chunks/{chunk-RKJPBTBB.js → chunk-SVQ7ZHEQ.js} +33 -16
  82. package/dist/chunks/chunk-SVQ7ZHEQ.js.map +7 -0
  83. package/dist/chunks/{chunk-MPMEK3IQ.js → chunk-TV5NCPPS.js} +6 -5
  84. package/dist/chunks/chunk-TV5NCPPS.js.map +7 -0
  85. package/dist/chunks/{chunk-XOBLUZMB.js → chunk-UIVMSMSQ.js} +10 -1
  86. package/dist/chunks/chunk-UIVMSMSQ.js.map +7 -0
  87. package/dist/chunks/{chunk-QGTD3LAZ.js → chunk-UYS5VZUU.js} +9 -3
  88. package/dist/chunks/chunk-UYS5VZUU.js.map +7 -0
  89. package/dist/chunks/{chunk-HRVYXRWZ.js → chunk-V5RZK45W.js} +37 -3
  90. package/dist/chunks/chunk-V5RZK45W.js.map +7 -0
  91. package/dist/chunks/{chunk-KIFOEBYJ.js → chunk-VEXCD3RA.js} +2 -2
  92. package/dist/chunks/{chunk-GS67KDMV.js → chunk-VN7AE3EY.js} +2 -2
  93. package/dist/chunks/{chunk-HFDJWLMS.js → chunk-WFGJUVTH.js} +106 -65
  94. package/dist/chunks/chunk-WFGJUVTH.js.map +7 -0
  95. package/dist/chunks/chunk-WMULZZER.js +196 -0
  96. package/dist/chunks/chunk-WMULZZER.js.map +7 -0
  97. package/dist/chunks/{chunk-QNMQJNXE.js → chunk-X4HDI7RT.js} +14 -4
  98. package/dist/chunks/chunk-X4HDI7RT.js.map +7 -0
  99. package/dist/chunks/{chunk-MX53BRAC.js → chunk-XBAOTA4U.js} +2 -2
  100. package/dist/chunks/{chunk-MSDL7U6Q.js → chunk-XQCNVH3Y.js} +4 -4
  101. package/dist/chunks/{chunk-4PBW54I2.js → chunk-YC6NV7FK.js} +88 -54
  102. package/dist/chunks/chunk-YC6NV7FK.js.map +7 -0
  103. package/dist/chunks/{chunk-6GWDGTHC.js → chunk-YLO62DWD.js} +4 -4
  104. package/dist/cli/decisions.js +2 -2
  105. package/dist/cli/mesh.js +3 -3
  106. package/dist/commands/fabric-handler.d.ts.map +1 -1
  107. package/dist/commands/fabric-handler.js +18 -4
  108. package/dist/commands/fabric-handler.js.map +2 -2
  109. package/dist/commands/fabric.d.ts.map +1 -1
  110. package/dist/compaction/branch-summary.d.ts.map +1 -1
  111. package/dist/compaction/claim-events.js +9 -9
  112. package/dist/compaction/hook.d.ts.map +1 -1
  113. package/dist/compaction/hook.js +6 -6
  114. package/dist/compaction/normalize.d.ts +9 -0
  115. package/dist/compaction/normalize.d.ts.map +1 -1
  116. package/dist/compaction/owner.js +7 -7
  117. package/dist/compaction/projections.d.ts +18 -2
  118. package/dist/compaction/projections.d.ts.map +1 -1
  119. package/dist/compaction/qa.d.ts +3 -2
  120. package/dist/compaction/qa.d.ts.map +1 -1
  121. package/dist/compaction/render.d.ts +3 -0
  122. package/dist/compaction/render.d.ts.map +1 -1
  123. package/dist/compaction/threshold.d.ts.map +1 -1
  124. package/dist/compaction/user-activity.d.ts +31 -0
  125. package/dist/compaction/user-activity.d.ts.map +1 -0
  126. package/dist/components/configuration.js +4 -4
  127. package/dist/config.d.ts +13 -6
  128. package/dist/config.d.ts.map +1 -1
  129. package/dist/core/action-registry.d.ts +1 -1
  130. package/dist/core/action-registry.d.ts.map +1 -1
  131. package/dist/core/action-registry.js +10 -9
  132. package/dist/core/approval-controller.d.ts +3 -0
  133. package/dist/core/approval-controller.d.ts.map +1 -1
  134. package/dist/core/atomic-write.d.ts +1 -0
  135. package/dist/core/atomic-write.d.ts.map +1 -1
  136. package/dist/core/attached-monitors.d.ts +39 -0
  137. package/dist/core/attached-monitors.d.ts.map +1 -0
  138. package/dist/core/control-abort.d.ts +3 -0
  139. package/dist/core/control-abort.d.ts.map +1 -0
  140. package/dist/core/crash-guard.d.ts +15 -0
  141. package/dist/core/crash-guard.d.ts.map +1 -0
  142. package/dist/core/execution-guidelines.d.ts +6 -0
  143. package/dist/core/execution-guidelines.d.ts.map +1 -0
  144. package/dist/core/guidance-delivery.d.ts +19 -0
  145. package/dist/core/guidance-delivery.d.ts.map +1 -0
  146. package/dist/core/lifecycle-settlement.d.ts +9 -0
  147. package/dist/core/lifecycle-settlement.d.ts.map +1 -0
  148. package/dist/core/observation-actions.d.ts +9 -0
  149. package/dist/core/observation-actions.d.ts.map +1 -0
  150. package/dist/core/pasted-images.d.ts +12 -0
  151. package/dist/core/pasted-images.d.ts.map +1 -0
  152. package/dist/core/pasted-images.js +139 -0
  153. package/dist/core/pasted-images.js.map +7 -0
  154. package/dist/core/permission-queue.d.ts +32 -0
  155. package/dist/core/permission-queue.d.ts.map +1 -0
  156. package/dist/core/permission-queue.js +104 -0
  157. package/dist/core/permission-queue.js.map +7 -0
  158. package/dist/core/prompt-guidance.d.ts +1 -0
  159. package/dist/core/prompt-guidance.d.ts.map +1 -1
  160. package/dist/core/prompt-guidance.js +52 -3
  161. package/dist/core/prompt-guidance.js.map +3 -3
  162. package/dist/core/provider-operations.js +1 -1
  163. package/dist/core/shell-inbox.d.ts +1 -1
  164. package/dist/core/shell-inbox.d.ts.map +1 -1
  165. package/dist/core/shell-jobs.d.ts +28 -1
  166. package/dist/core/shell-jobs.d.ts.map +1 -1
  167. package/dist/core/shell-monitor.d.ts +1 -0
  168. package/dist/core/shell-monitor.d.ts.map +1 -1
  169. package/dist/durable/worker.js +0 -42
  170. package/dist/durable/worker.js.map +3 -3
  171. package/dist/durable-extension.d.ts +2 -2
  172. package/dist/durable-extension.d.ts.map +1 -1
  173. package/dist/durable-extension.js +215 -1
  174. package/dist/durable-extension.js.map +3 -3
  175. package/dist/entropy/index.d.ts +2 -0
  176. package/dist/entropy/index.d.ts.map +1 -1
  177. package/dist/entropy/index.js +23 -13
  178. package/dist/entropy/pool-store.d.ts +8 -1
  179. package/dist/entropy/pool-store.d.ts.map +1 -1
  180. package/dist/entropy/pool-worker.d.ts +18 -0
  181. package/dist/entropy/pool-worker.d.ts.map +1 -0
  182. package/dist/entropy/pool-writer.d.ts +23 -0
  183. package/dist/entropy/pool-writer.d.ts.map +1 -0
  184. package/dist/entropy/pool.d.ts +11 -0
  185. package/dist/entropy/pool.d.ts.map +1 -1
  186. package/dist/entropy/sessions.d.ts +5 -0
  187. package/dist/entropy/sessions.d.ts.map +1 -1
  188. package/dist/execution-service.d.ts.map +1 -1
  189. package/dist/extension-bootstrap.d.ts.map +1 -1
  190. package/dist/extension-bootstrap.js +19 -19
  191. package/dist/extension.d.ts.map +1 -1
  192. package/dist/fabric-exec-tool.d.ts.map +1 -1
  193. package/dist/fabric-runtime-state.d.ts.map +1 -1
  194. package/dist/fabric-runtime-state.js +534 -261
  195. package/dist/fabric-runtime-state.js.map +4 -4
  196. package/dist/fabric-state.d.ts.map +1 -1
  197. package/dist/index.js +40 -30
  198. package/dist/index.js.map +1 -1
  199. package/dist/jev/client.js +2 -2
  200. package/dist/jev/observation.js +7 -6
  201. package/dist/jev.js +12 -11
  202. package/dist/main-agent.d.ts.map +1 -1
  203. package/dist/managed-host.d.ts +4 -0
  204. package/dist/managed-host.d.ts.map +1 -1
  205. package/dist/memory/discovery.js +6 -6
  206. package/dist/memory/expand-service.d.ts.map +1 -1
  207. package/dist/memory/file-worker.js +9 -8
  208. package/dist/memory/file-worker.js.map +1 -1
  209. package/dist/memory/history-paging.d.ts +9 -0
  210. package/dist/memory/history-paging.d.ts.map +1 -0
  211. package/dist/memory/history-paging.js +164 -0
  212. package/dist/memory/history-paging.js.map +7 -0
  213. package/dist/memory/index.d.ts.map +1 -1
  214. package/dist/memory/normalize.js +5 -5
  215. package/dist/memory/outline-service.d.ts +7 -0
  216. package/dist/memory/outline-service.d.ts.map +1 -0
  217. package/dist/memory/request-cache.d.ts +3 -1
  218. package/dist/memory/request-cache.d.ts.map +1 -1
  219. package/dist/memory/request-context.d.ts +1 -0
  220. package/dist/memory/request-context.d.ts.map +1 -1
  221. package/dist/memory/request-limits.d.ts +2 -0
  222. package/dist/memory/request-limits.d.ts.map +1 -1
  223. package/dist/memory/search.js +7 -6
  224. package/dist/memory/worker-provider.d.ts.map +1 -1
  225. package/dist/memory/worker-provider.js +10 -9
  226. package/dist/memory.d.ts +16 -1
  227. package/dist/memory.d.ts.map +1 -1
  228. package/dist/memory.js +64 -12
  229. package/dist/memory.js.map +1 -1
  230. package/dist/mesh/store.d.ts +2 -1
  231. package/dist/mesh/store.d.ts.map +1 -1
  232. package/dist/programs/host.js +2 -2
  233. package/dist/protocol.d.ts +5 -0
  234. package/dist/protocol.d.ts.map +1 -1
  235. package/dist/protocol.js +1 -1
  236. package/dist/providers/agents-actions.d.ts.map +1 -1
  237. package/dist/providers/agents-message-router.d.ts +1 -0
  238. package/dist/providers/agents-message-router.d.ts.map +1 -1
  239. package/dist/providers/agents-provider.d.ts +2 -0
  240. package/dist/providers/agents-provider.d.ts.map +1 -1
  241. package/dist/providers/jev-provider.js +12 -11
  242. package/dist/providers/memory-provider.d.ts +4 -0
  243. package/dist/providers/memory-provider.d.ts.map +1 -1
  244. package/dist/providers/memory-provider.js +9 -8
  245. package/dist/providers/pi-read-operations.d.ts +24 -0
  246. package/dist/providers/pi-read-operations.d.ts.map +1 -0
  247. package/dist/providers/pi-tools-provider.d.ts +7 -0
  248. package/dist/providers/pi-tools-provider.d.ts.map +1 -1
  249. package/dist/providers/sessions-provider.d.ts +1 -1
  250. package/dist/providers/sessions-provider.d.ts.map +1 -1
  251. package/dist/providers/tasks-provider.d.ts +3 -1
  252. package/dist/providers/tasks-provider.d.ts.map +1 -1
  253. package/dist/residency/actor-client.js +3 -3
  254. package/dist/residency/client.d.ts.map +1 -1
  255. package/dist/residency/host.d.ts.map +1 -1
  256. package/dist/residency/host.js +17 -16
  257. package/dist/residency/launcher.js +1 -1
  258. package/dist/residency/pi-entry.js +17 -16
  259. package/dist/residency/pi-entry.js.map +1 -1
  260. package/dist/residency/protocol.d.ts +2 -0
  261. package/dist/residency/protocol.d.ts.map +1 -1
  262. package/dist/runtime/core-override-guest-types.js +2 -2
  263. package/dist/runtime/cpython-runtime.d.ts.map +1 -1
  264. package/dist/runtime/cpython-runtime.js +7 -6
  265. package/dist/runtime/cpython-runtime.js.map +2 -2
  266. package/dist/runtime/guest-types.d.ts +1 -1
  267. package/dist/runtime/guest-types.d.ts.map +1 -1
  268. package/dist/runtime/guest-types.js +1 -1
  269. package/dist/runtime/monty-runtime.d.ts.map +1 -1
  270. package/dist/runtime/monty-runtime.js +7 -6
  271. package/dist/runtime/monty-runtime.js.map +2 -2
  272. package/dist/runtime/node-process-runtime.d.ts.map +1 -1
  273. package/dist/runtime/node-process-runtime.js +6 -6
  274. package/dist/runtime/quickjs-runtime.d.ts.map +1 -1
  275. package/dist/runtime/quickjs-runtime.js +4 -4
  276. package/dist/runtime/type-checker.d.ts.map +1 -1
  277. package/dist/runtime/type-checker.js +1 -1
  278. package/dist/runtime/typescript-kernel.js +10 -10
  279. package/dist/runtime-state-builtins.d.ts +2 -0
  280. package/dist/runtime-state-builtins.d.ts.map +1 -1
  281. package/dist/schema/policy.d.ts.map +1 -1
  282. package/dist/speculation/eligibility.d.ts.map +1 -1
  283. package/dist/speculation/store.d.ts.map +1 -1
  284. package/dist/topology/participant-directory.d.ts +1 -0
  285. package/dist/topology/participant-directory.d.ts.map +1 -1
  286. package/dist/topology/peer-presence.d.ts.map +1 -1
  287. package/dist/topology/provider-participants.d.ts +1 -0
  288. package/dist/topology/provider-participants.d.ts.map +1 -1
  289. package/dist/type-error-guidance.js +1 -1
  290. package/dist/ui/code-preview-shell.d.ts +1 -0
  291. package/dist/ui/code-preview-shell.d.ts.map +1 -1
  292. package/dist/ui/controller.d.ts.map +1 -1
  293. package/dist/ui/conversation-chrome.d.ts.map +1 -1
  294. package/dist/ui/conversation-chrome.js +2 -2
  295. package/dist/ui/conversation-feedback.d.ts +8 -0
  296. package/dist/ui/conversation-feedback.d.ts.map +1 -0
  297. package/dist/ui/conversation-latest.d.ts.map +1 -1
  298. package/dist/ui/conversation-native-reader.d.ts.map +1 -1
  299. package/dist/ui/conversation-native-reader.js +3 -3
  300. package/dist/ui/conversation-native-reader.js.map +2 -2
  301. package/dist/ui/conversation-render.d.ts.map +1 -1
  302. package/dist/ui/conversation.d.ts +1 -0
  303. package/dist/ui/conversation.d.ts.map +1 -1
  304. package/dist/ui/conversation.js +139 -86
  305. package/dist/ui/conversation.js.map +4 -4
  306. package/dist/ui/core-tool-render.d.ts.map +1 -1
  307. package/dist/ui/dashboard-fabric-graph.d.ts.map +1 -1
  308. package/dist/ui/dashboard.js +47 -48
  309. package/dist/ui/dashboard.js.map +3 -3
  310. package/dist/ui/fabric-render.d.ts.map +1 -1
  311. package/dist/ui/format.d.ts.map +1 -1
  312. package/dist/ui/highlight.d.ts.map +1 -1
  313. package/dist/ui/permissions.d.ts +18 -0
  314. package/dist/ui/permissions.d.ts.map +1 -0
  315. package/dist/ui/permissions.js +178 -0
  316. package/dist/ui/permissions.js.map +7 -0
  317. package/dist/ui/row-balance.d.ts +1 -1
  318. package/dist/ui/row-balance.d.ts.map +1 -1
  319. package/dist/ui/settings-sections-execution.d.ts.map +1 -1
  320. package/dist/ui/settings-values.d.ts.map +1 -1
  321. package/dist/ui/settings.js +37 -31
  322. package/dist/ui/settings.js.map +2 -2
  323. package/dist/ui/shell-hang-keys.d.ts.map +1 -1
  324. package/dist/ui/shell-tasks.d.ts.map +1 -1
  325. package/dist/ui/shell-tasks.js +28 -11
  326. package/dist/ui/shell-tasks.js.map +2 -2
  327. package/dist/ui/structured.d.ts.map +1 -1
  328. package/dist/ui/tool-display.d.ts +18 -2
  329. package/dist/ui/tool-display.d.ts.map +1 -1
  330. package/dist/ui/truncate.d.ts +3 -0
  331. package/dist/ui/truncate.d.ts.map +1 -0
  332. package/dist/ui/widget.d.ts +7 -2
  333. package/dist/ui/widget.d.ts.map +1 -1
  334. package/dist/verified/context.d.ts +35 -0
  335. package/dist/verified/context.d.ts.map +1 -0
  336. package/dist/verified/execution.d.ts +7 -0
  337. package/dist/verified/execution.d.ts.map +1 -0
  338. package/dist/verified/generated/context.d.ts +6 -0
  339. package/dist/verified/generated/context.js +51 -0
  340. package/dist/verified/generated/execution.d.ts +5 -0
  341. package/dist/verified/generated/execution.js +32 -0
  342. package/dist/verified/generated/manifest.json +34 -3
  343. package/dist/verified/generated/prompt-guidance.d.ts +4 -0
  344. package/dist/verified/generated/prompt-guidance.js +17 -0
  345. package/dist/worker/recovery-watchdog.d.ts +7 -0
  346. package/dist/worker/recovery-watchdog.d.ts.map +1 -1
  347. package/dist/worker/recovery-watchdog.js +66 -4
  348. package/dist/worker/recovery-watchdog.js.map +2 -2
  349. package/dist/worker.js +22 -3
  350. package/dist/worker.js.map +2 -2
  351. package/docs/agents.md +37 -4
  352. package/docs/architecture.md +13 -0
  353. package/docs/background-tasks.md +81 -5
  354. package/docs/benchmarks/cli-resume-2026-11-09.json +1260 -0
  355. package/docs/benchmarks/interactivity-2026-11-09.json +2280 -0
  356. package/docs/benchmarks/resume-latency-2026-11-09.json +12105 -0
  357. package/docs/benchmarks/resume-startup-fix-2026-11-09.json +5452 -0
  358. package/docs/benchmarks/session-memory-2026-11-09.json +1320 -0
  359. package/docs/benchmarks/session-memory-fix-2026-11-09.json +280 -0
  360. package/docs/compaction.md +59 -23
  361. package/docs/configuration.md +53 -11
  362. package/docs/entropy.md +4 -1
  363. package/docs/history-paging.md +99 -0
  364. package/docs/interactivity-investigation.md +109 -0
  365. package/docs/interface.md +2 -2
  366. package/docs/jev.md +1 -1
  367. package/docs/memory-recall.md +42 -1
  368. package/docs/providers.md +24 -1
  369. package/docs/resume-latency-investigation.md +249 -0
  370. package/docs/session-memory-investigation.md +223 -0
  371. package/docs/verified-kernels.md +56 -0
  372. package/package.json +211 -211
  373. package/proofs/context.ts +139 -0
  374. package/proofs/execution.ts +48 -0
  375. package/proofs/index.ts +6 -0
  376. package/proofs/prompt-guidance.ts +38 -0
  377. package/scripts/verified-kernels.ts +1 -1
  378. package/skillsets/python/fabric-council/SKILL.md +31 -21
  379. package/skillsets/python/fabric-exec/SKILL.md +1 -1
  380. package/skillsets/python/fabric-exec/references/agents.md +2 -0
  381. package/skillsets/python/fabric-guide/SKILL.md +1 -0
  382. package/skillsets/python/fabric-memory/SKILL.md +82 -0
  383. package/skillsets/typescript/fabric-council/SKILL.md +26 -17
  384. package/skillsets/typescript/fabric-exec/SKILL.md +3 -2
  385. package/skillsets/typescript/fabric-exec/references/agents.md +1 -0
  386. package/skillsets/typescript/fabric-guide/SKILL.md +1 -0
  387. package/skillsets/typescript/fabric-memory/SKILL.md +87 -0
  388. package/dist/chunks/chunk-3VK6UGAN.js.map +0 -7
  389. package/dist/chunks/chunk-3XT5WHSG.js.map +0 -7
  390. package/dist/chunks/chunk-4BYS4ZLY.js.map +0 -7
  391. package/dist/chunks/chunk-4PBW54I2.js.map +0 -7
  392. package/dist/chunks/chunk-56NMRVTV.js.map +0 -7
  393. package/dist/chunks/chunk-7N7IC3Z2.js.map +0 -7
  394. package/dist/chunks/chunk-DGERP4VL.js.map +0 -7
  395. package/dist/chunks/chunk-DGUXJSYA.js.map +0 -7
  396. package/dist/chunks/chunk-F6A6MQ6G.js.map +0 -7
  397. package/dist/chunks/chunk-FK73YJKV.js.map +0 -7
  398. package/dist/chunks/chunk-G2DZJ5LK.js.map +0 -7
  399. package/dist/chunks/chunk-HFDJWLMS.js.map +0 -7
  400. package/dist/chunks/chunk-HRDMBGMY.js.map +0 -7
  401. package/dist/chunks/chunk-HRVYXRWZ.js.map +0 -7
  402. package/dist/chunks/chunk-LKYLD5SN.js.map +0 -7
  403. package/dist/chunks/chunk-LRSZFYUC.js.map +0 -7
  404. package/dist/chunks/chunk-LZ2ZXOCU.js.map +0 -7
  405. package/dist/chunks/chunk-MPMEK3IQ.js.map +0 -7
  406. package/dist/chunks/chunk-OJ4HAALD.js.map +0 -7
  407. package/dist/chunks/chunk-QGTD3LAZ.js.map +0 -7
  408. package/dist/chunks/chunk-QNMQJNXE.js.map +0 -7
  409. package/dist/chunks/chunk-RKJPBTBB.js.map +0 -7
  410. package/dist/chunks/chunk-U6Y6TKJL.js.map +0 -7
  411. package/dist/chunks/chunk-VGRUWTMG.js.map +0 -7
  412. package/dist/chunks/chunk-XOBLUZMB.js.map +0 -7
  413. package/dist/durable/openai-sse-patch.d.ts +0 -21
  414. package/dist/durable/openai-sse-patch.d.ts.map +0 -1
  415. /package/dist/chunks/{chunk-7YNE4NB2.js.map → chunk-2MELFQCQ.js.map} +0 -0
  416. /package/dist/chunks/{chunk-HSEZPCL5.js.map → chunk-2OC4YJOL.js.map} +0 -0
  417. /package/dist/chunks/{chunk-TXCNZCZP.js.map → chunk-2QJ4MNS6.js.map} +0 -0
  418. /package/dist/chunks/{chunk-QOEOKW2X.js.map → chunk-3QH6JAE3.js.map} +0 -0
  419. /package/dist/chunks/{chunk-L6H46CPY.js.map → chunk-6NNL5LOG.js.map} +0 -0
  420. /package/dist/chunks/{chunk-RWKQ5SRW.js.map → chunk-7ZFPVOV2.js.map} +0 -0
  421. /package/dist/chunks/{chunk-PUBHBEYO.js.map → chunk-B2FIGOPI.js.map} +0 -0
  422. /package/dist/chunks/{chunk-4WKD3YM3.js.map → chunk-C3UPHOJW.js.map} +0 -0
  423. /package/dist/chunks/{chunk-RAA3FAYZ.js.map → chunk-GNPTDN6K.js.map} +0 -0
  424. /package/dist/chunks/{chunk-XFOSUGLU.js.map → chunk-JCGEW5OQ.js.map} +0 -0
  425. /package/dist/chunks/{chunk-CXYJJ3HZ.js.map → chunk-LJ2MG6U2.js.map} +0 -0
  426. /package/dist/chunks/{chunk-3MOY6WIB.js.map → chunk-LRBDEAKB.js.map} +0 -0
  427. /package/dist/chunks/{chunk-NQ7IWEIF.js.map → chunk-MQGRQMVM.js.map} +0 -0
  428. /package/dist/chunks/{chunk-WKFRGICG.js.map → chunk-RBYRHS24.js.map} +0 -0
  429. /package/dist/chunks/{chunk-ZHROHNEE.js.map → chunk-RFNYH7S7.js.map} +0 -0
  430. /package/dist/chunks/{chunk-H57KPL3V.js.map → chunk-S2JWFXW5.js.map} +0 -0
  431. /package/dist/chunks/{chunk-KIFOEBYJ.js.map → chunk-VEXCD3RA.js.map} +0 -0
  432. /package/dist/chunks/{chunk-GS67KDMV.js.map → chunk-VN7AE3EY.js.map} +0 -0
  433. /package/dist/chunks/{chunk-MX53BRAC.js.map → chunk-XBAOTA4U.js.map} +0 -0
  434. /package/dist/chunks/{chunk-MSDL7U6Q.js.map → chunk-XQCNVH3Y.js.map} +0 -0
  435. /package/dist/chunks/{chunk-6GWDGTHC.js.map → chunk-YLO62DWD.js.map} +0 -0
@@ -0,0 +1,99 @@
1
+ # Historical payload paging and cancellation
2
+
3
+ Fabric can release Pi core's strong references to **inactive historical message
4
+ payloads** without deleting session history or creating a replacement session.
5
+ `memory.pageHistory` defaults to `true` and is independent of the memory-search
6
+ index's `enabled` setting. Set it to `false` in `fabric.json` to opt out before
7
+ loading a session.
8
+
9
+ ## What changes
10
+
11
+ At a real turn boundary or committed compaction, Fabric consults core's
12
+ `buildContextEntries()` and leaves every active-context entry untouched. Inactive
13
+ message fields of at least 16 KiB (such as content, output and details) are
14
+ serialized to a private temporary archive. Only those bulky fields become
15
+ synchronous read-through accessors backed by weak references. Entry and message
16
+ objects, plus ordinary role/usage/timestamp metadata, stay resident and keep their
17
+ identities. TPS and accounting can inspect metadata without hydrating the body.
18
+ Once no reader retains a payload, GC can release it; a later field read hydrates
19
+ the same JSON value. Object-valued fields retain identity while a reader holds them.
20
+
21
+ Entry identities, IDs, parents, labels, custom extension records and the original
22
+ session JSONL are unchanged. Consumers which cache entry arrays (such as
23
+ `pi-tps`) still hold the very same entries. Tree navigation, copying a historical
24
+ message and serialization continue to read through the normal APIs. A consumer
25
+ which independently retains the **content array or another paged payload** can
26
+ still keep it alive; retaining just the entry/message metadata does not. Fabric
27
+ cannot revoke another extension's references.
28
+
29
+ The code is loaded lazily at actual first use, not at registration or idle boot.
30
+ Paging yields between groups of entries and stops on cancellation, navigation,
31
+ session replacement or shutdown. Existing historical accessors installed by
32
+ other extensions are not replaced. Unsupported host adapters are skipped.
33
+
34
+ ## Compatibility and storage limits
35
+
36
+ - This relies on Pi's append-only historical-entry convention. **In-place nested
37
+ mutation of an inactive historical message is unsupported**: after collection,
38
+ hydration restores its archived JSON snapshot. Whole-message assignment remains
39
+ supported. Extensions which edit old message objects should disable paging.
40
+ - Paged objects are JSON snapshots, not cross-GC identity guarantees. Non-JSON payloads
41
+ which fail serialization stay in memory. Small payloads and custom entries also
42
+ remain resident. Metadata and active context are not bounded by this feature.
43
+ - Archives use a private temporary directory and a mode-0600 file. They are kept
44
+ until their entries are collected so a retained entry is still readable after
45
+ a session switch or extension reload. Normal process exit removes archives;
46
+ a crash may leave temporary files for the OS/user to clean up. They contain
47
+ conversation data, like the original session logs.
48
+ - History browsing, export or other consumers can hydrate many messages again.
49
+ Those payloads become collectible after readers let go. This does not promise
50
+ low peak memory while opening an existing large session, nor immediate RSS
51
+ reduction after collection.
52
+ - Actor observation now uses core's active-context projection, including
53
+ compaction and branch summaries. It no longer reads the entire historical
54
+ branch on each streaming event.
55
+
56
+ ## Abort responsiveness
57
+
58
+ Aborted `agent_start`, `turn_end`, `agent_end` and `agent_settled` hooks no longer wait for mesh
59
+ lifecycle publication. The lifecycle broker still serializes those writes and
60
+ owns their shutdown drain. Errors from detached writes are handled. Completed
61
+ run boundaries retain their existing awaited publication order.
62
+
63
+ Actor observation and tool-error analysis are skipped for already-aborted
64
+ contexts. This removes two Fabric-side stalls: an awaited mesh lock (whose
65
+ configured timeout is 10 seconds), and scanning historical payloads when an abort
66
+ is already in progress. It does not change provider cancellation, child-process
67
+ termination grace periods, or other extensions' hooks; a live profile is still
68
+ needed to attribute any remaining lag.
69
+
70
+ ## Verified results (2026-11-09)
71
+
72
+ A fresh Linux process on the remote fallback passed 104 targeted tests across
73
+ nine files, typechecking, the full build and the lazy-graph assertion.
74
+
75
+ | Scenario | After compaction | After paging / next Fabric turn |
76
+ | --- | ---: | ---: |
77
+ | Core manager, 600 MiB history | 635.93 MiB heap | 51.91 MiB heap |
78
+ | Real SDK + compiled Fabric, 256 MiB history | 318.43 MiB heap | 100.53 MiB heap |
79
+
80
+ The manager probe confirmed that all 19,090 retired content arrays were
81
+ collectible, verified an exact cold read, and verified the original session
82
+ file hash was unchanged. The SDK probe completed three Fabric executions across
83
+ the original session and two replacements without extension errors.
84
+
85
+ RSS remained high. The manager correctness probe also reads the complete source
86
+ file to hash it, so its peak RSS is not a pager-only measurement. See the
87
+ [raw measurements](benchmarks/session-memory-fix-2026-11-09.json) for full memory
88
+ columns and limitations. These tests do not measure live macOS abort latency.
89
+
90
+ ## Verification
91
+
92
+ Targeted tests cover historical JSON and entry identity, active-context
93
+ protection, navigation, labels, custom state, unchanged source files,
94
+ cooperative cancellation, foreign accessors, and lifecycle publication ordering.
95
+ The isolated `scripts/benchmark-session-memory.mjs --mode paged` case additionally
96
+ forces GC and asserts that retired content arrays are gone, then reads a cold
97
+ payload back and verifies it. The `fabric` case exercises the compiled extension
98
+ through the real SDK with an offline provider. See
99
+ [the investigation](session-memory-investigation.md) for baseline measurements.
@@ -0,0 +1,109 @@
1
+ # Interactivity during fabric_exec
2
+
3
+ Pi stuttered during long sessions, most of all while `fabric_exec` ran nested
4
+ calls and at the end of each `fabric_exec` turn. This records what the
5
+ profiles showed, what changed, and how to measure it again.
6
+
7
+ ## How it was measured
8
+
9
+ `scripts/benchmark-interactivity.mjs` runs the bundled Pi CLI in a Linux
10
+ pseudo-terminal with a scripted offline model, so no network, credentials or
11
+ personal history are involved. Each turn issues one `fabric_exec` with N
12
+ nested `pi.read` calls and one `pi.bash` call (or, in the `core` control, the
13
+ same calls as direct Pi tool calls). Per turn it records wall and CPU time,
14
+ event-loop delay (how long a keystroke would wait), GC time, heap, and a count
15
+ of synchronous file writes by target. The active and idle phases are
16
+ CPU-profiled in process and summarized by package and function.
17
+
18
+ ```sh
19
+ node scripts/benchmark-interactivity.mjs --variant fabric \
20
+ --pi-cli <pi-coding-agent>/dist/bundle/cli.js --out /tmp/out \
21
+ --turns 30 --calls 24 --seed-mesh-kb 2000 --seed-pool-mb 30
22
+ ```
23
+
24
+ `--seed-mesh-kb` and `--seed-pool-mb` create a synthetic project mesh state
25
+ and a machine-wide entropy observation pool of realistic size before Pi
26
+ starts. A long-lived machine had a 1.95 MB mesh `state.json` and a 33.6 MB
27
+ `observation-pool.json`. With the small files of a fresh fixture, both costs
28
+ below stay hidden.
29
+
30
+ ## What the profiles showed
31
+
32
+ The TypeScript guest compiler was a small steady cost: about 13 ms per
33
+ `fabric_exec` once warm. Its first use still blocks for about 0.5 s while the
34
+ compiler and the first program load.
35
+
36
+ Two costs scaled with the machine's accumulated state.
37
+
38
+ 1. **Mesh presence, once per nested call.** `PiToolsProvider` emits
39
+ `tool_execution_end` for each nested call. Fabric's handler notes main
40
+ activity, which schedules a participant refresh. Each refresh rewrote the
41
+ root record (its `updatedAt` always differs), the legacy session record
42
+ and the host lease: three locked, synchronous read-parse-serialize-rename
43
+ cycles of the whole project mesh state, per nested call. A turn with 24
44
+ nested calls made 75 such rewrites; 60 calls made 183. Every other Pi
45
+ session in the project then re-read the changed file.
46
+ 2. **Entropy observation pool, once per `fabric_exec` turn.** After a turn
47
+ with `fabric_exec`, the entropy compile merged the session's observations
48
+ into the machine-wide pool: parse the whole pool, merge, serialize it,
49
+ read the old file back to compare, then serialize it again to write. With
50
+ a 33.6 MB pool, the parse alone took 88 ms and each pretty-printed
51
+ serialization 75 ms on an idle process, all on Pi's main thread, with
52
+ about 170 MB of short-lived heap.
53
+
54
+ A third, smaller cost came from bounding the persisted `fabric_exec` details
55
+ to 512 KiB: the bound re-serialized the whole record after dropping each
56
+ audit, which is quadratic in the size of a large run's results.
57
+
58
+ ## Changes
59
+
60
+ - `ParticipantDirectory` distinguishes a renewal (`refresh()`, the heartbeat
61
+ and startup) from an event refresh (`scheduleRefresh()`). An event refresh
62
+ writes only records whose content changed apart from `updatedAt`, and
63
+ leaves the lease to the heartbeat. Any refresh renews once the last renewal
64
+ is a heartbeat old, so timestamps and leases are never older than before.
65
+ A status change (idle to running, queued messages) still publishes at once.
66
+ - The observation-pool update runs on a worker thread
67
+ (`src/entropy/pool-writer.ts`). The main thread keeps the cooperative,
68
+ identity-cached per-window summaries and sends only those. The worker takes
69
+ the cross-process lock, rebases on the latest pool, and writes the bytes it
70
+ compared, serializing once. If a worker cannot start, the update runs in
71
+ process as before. The worker runs the existing lazy entropy entry, so the
72
+ startup graph is unchanged.
73
+ - Presence reads list legacy actor states only under a live legacy root's
74
+ `actors/<sessionId>/` prefix, with the same order and result. Listing all of
75
+ `actors/` deep-cloned every actor state in the project on each refresh,
76
+ which became the largest remaining cost once the writes were gone.
77
+ - The locked pool rewrite compares against the text it already read, so the
78
+ pool is read once per update.
79
+ - `createFabricPersistedExecutionDetails` drops oversized members with a
80
+ running byte estimate and confirms each stop with one real measurement. Its
81
+ output is identical to measuring after every drop.
82
+
83
+ ## Results
84
+
85
+ Linux pseudo-terminal, Pi 1.5.0, 30 turns of 24 nested calls, seeded with a
86
+ 2.2 MB mesh state and a 21 MB pool. Before and after alternated in one batch
87
+ on the same exclusive VM; medians per turn of two runs each:
88
+
89
+ | | before | after |
90
+ |---|---|---|
91
+ | CPU per turn, all threads | 1,483 and 1,095 ms | 245 and 238 ms |
92
+ | wall time per turn | 1,399 and 1,046 ms | 189 and 177 ms |
93
+ | worst event-loop stall per turn | 270 and 203 ms | 18 and 17 ms |
94
+ | worst stall in the run | 459 and 244 ms | 33 and 26 ms |
95
+ | GC per turn | 43 and 30 ms | 3.5 and 3.9 ms |
96
+ | mesh state rewrites per turn | 78 and 75 | 0 |
97
+
98
+ The first `fabric_exec` stall (451 to 501 ms) is unchanged. Raw rows are in
99
+ `docs/benchmarks/interactivity-2026-11-09.json`.
100
+
101
+ ## Remaining
102
+
103
+ - The first `fabric_exec` of a session still blocks for about 0.5 s while the
104
+ TypeScript compiler loads.
105
+ - The heartbeat still renews every 5 s with three locked rewrites of the mesh
106
+ state (root record, legacy session record, lease). Idle CPU is close to the
107
+ core-only control.
108
+ - Each nested call still emits `tool_execution_end` to every extension, by
109
+ design, so other extensions' handlers run per nested call.
package/docs/interface.md CHANGED
@@ -26,13 +26,13 @@ See [Background tasks and monitors](background-tasks.md) for completion delivery
26
26
 
27
27
  ## Agent list
28
28
 
29
- The Fabric widget sits at the bottom of the screen, below Pi's footer and a blank row, as in Claude Code. Its header is the main session's row: `● FAB-3` shows the session's [peer label](agents.md#peer-labels-and-queue-gates), followed by the current run's declared name and totals. A new session takes its label at its first Fabric use, so a session that has done nothing yet shows none. Without a label it reads `● Fabric`. A session with a label also shows it on the right of the editor's top border, in a badge like the one a conversation window shows for its target, whether or not the list is showing. While the list has no row to select, with no agent, actor worker, or shell task (idle actors have none), it takes no rows. The badge yields to Pi's own border text, such as a scroll indicator, and needs the list to be placed after the footer; otherwise the header row stays. Below it, running agents and actors are listed as a tree, above any background shell tasks, each child under its parent and indented by depth. Each row shows a circle, the participant's name, what it is doing, its model, tool calls, tokens, and elapsed time. What it is doing is the latest display name the agent declared for a `fabric_exec` call, which holds until it declares another; before that, the row shows the current tool or `thinking`. A finished row shows its result or error. The circle's colour is the status: accent while running, green when done, red on failure. Shell tasks list one per row after agents and actors, within the same row budget. Shell rows are selectable like agents: **Enter** or a click on a shell opens that task's detail with its output, status, and stop action. There is no secondary task-list overlay. **Esc** closes a task opened this way in one step, and focus returns to the list. Lines disclose progressively: when a line is too wide, its statistics drop first, then its title or activity is shortened, and its key hints go last. Pi gives extensions no slot below its footer, so Fabric registers an empty below-editor widget and places the list after the footer itself, in both the fullscreen and the regular renderer. Pi's footer and footers from other extensions stay as they are. In fullscreen mode, the list uses only the rows left after Pi's editor, other widgets (including Better OpenAI's status line), and footer, keeping at least one transcript row. It shrinks or temporarily disappears when those need the space, and returns when space is available. If Pi's layout is not the one Fabric expects, the list falls back to below the editor and stays last among the widgets other extensions place there. Press **↓** in an empty editor to move into the list; **ctrl+shift+e**, **`/fabric focus`**, or a click on a row also focuses it. The filled circle `●` marks the selected row, and **↑↓** or **j/k** moves it. **↑** on the top row returns to the editor. **Enter** or a click opens the participant's full conversation, where you can read its whole transcript, see its model and thinking level, and steer it or send a follow-up. Closing that view returns focus to the list. As in Claude Code, there is no inline preview: the conversation is where a participant's activity is shown. In Pi's fullscreen renderer, hovering the pointer over a row fills its circle too. Pi turns on hover tracking only outside tmux, zellij, and screen, and there is no event for leaving the widget, so the hover clears when the pointer crosses the header or the next key is pressed. **Esc** returns focus to the editor; while the list has focus, Esc does not halt background workers. Any other key returns focus to the editor and reaches it, so typing, Ctrl+C, and shortcuts keep working; only a click on a participant row takes focus. The list never grows past `ui.maxRows` on focus and remains bounded by half the terminal height and the space left in the fullscreen dock. Arrow keys and the mouse wheel over the list scroll within that viewport, keeping every participant and task reachable without moving the footer. When content overflows, a bottom cue row stays reserved across the whole scroll range: `↓ N more` appears there while children remain below, and the row is blank at the end. `↑ N more` appears in the main header when children are above the viewport. Very short viewports prioritize the header and a reachable child over the cue. Short or idle lists do not reserve a large empty area.
29
+ The Fabric widget sits at the bottom of the screen, below Pi's footer and a blank row, as in Claude Code. Its header is the main session's row: `● FAB-3` shows the session's [peer label](agents.md#peer-labels-and-queue-gates), followed by the current run's declared name and totals. A new session takes its label at its first Fabric use, so a session that has done nothing yet shows none. Without a label it reads `● Fabric`. A session with a label also shows it on the right of the editor's top border, in a badge like the one a conversation window shows for its target, whether or not the list is showing. While the list has no row to select, with no agent, actor worker, or shell task (idle actors have none), it takes no rows. The badge yields to Pi's own border text, such as a scroll indicator, and needs the list to be placed after the footer; otherwise the header row stays. Below it, running agents and actors are listed as a tree, above any background shell tasks, each child under its parent and indented by depth. Each row shows a circle, the participant's name, what it is doing, its model, tool calls, tokens, and elapsed time. What it is doing is the latest display name the agent declared for a `fabric_exec` call, which holds until it declares another; before that, the row shows the current tool or `thinking`. A finished row shows its result or error. The circle's colour is the status: accent while running, green when done, red on failure. Shell tasks list one per row after agents and actors, within the same row budget. Shell rows are selectable like agents: **Enter** or a click on a shell opens that task's detail with its output, status, and stop action. There is no secondary task-list overlay. **Esc** closes a task opened this way in one step, and focus returns to the list. Lines disclose progressively: when a line is too wide, its statistics drop first, then its title or activity is shortened, and its key hints go last. Pi gives extensions no slot below its footer, so Fabric registers an empty below-editor widget and places the list after the footer itself, in both the fullscreen and the regular renderer. Pi's footer and footers from other extensions stay as they are. In fullscreen mode, the list uses only the rows left after Pi's editor, other widgets (including Better OpenAI's status line), and footer, keeping at least one transcript row. It shrinks or temporarily disappears when those need the space, and returns when space is available. If Pi's layout is not the one Fabric expects, the list falls back to below the editor and stays last among the widgets other extensions place there. Press **↓** in an empty editor to move into the list; **ctrl+shift+e**, **`/fabric focus`**, or a click on a row also focuses it. The filled circle `●` marks the selected row, and **↑↓** or **j/k** moves it. **↑** on the top row returns to the editor. **Enter** or a click opens the participant's full conversation, where you can read its whole transcript, see its model and thinking level, and steer it or send a follow-up. Closing that view returns focus to the list. As in Claude Code, there is no inline preview: the conversation is where a participant's activity is shown. In Pi's fullscreen renderer, hovering the pointer over a row fills its circle too. Pi turns on hover tracking only outside tmux, zellij, and screen, and there is no event for leaving the widget, so the hover clears when the pointer crosses the header or the next key is pressed. **Esc** returns focus to the editor; while the list has focus, Esc does not halt background workers. Any other key returns focus to the editor and reaches it, so typing, Ctrl+C, and shortcuts keep working; only a click on a participant row takes focus. The list never grows past `ui.maxRows` on focus and remains bounded by half the terminal height and the space left in the fullscreen dock. Arrow keys and the mouse wheel over the list scroll within that viewport, keeping every participant and task reachable without moving the footer. When content overflows, a bottom cue row shows `↓ N more` while children remain below. At the end, another agent or shell row replaces the cue, filling the viewport without changing its height. `↑ N more` appears in the main header when children are above the viewport. Very short viewports prioritize the header and a reachable child over the cue. Short or idle lists do not reserve a large empty area.
30
30
 
31
31
  ## Focused conversations
32
32
 
33
33
  Press **Enter** on a row of the agent list, or run **`/fabric chat`**, to open a full-screen conversation without going through the dashboard. `/fabric chat <id-or-name>` opens a specific agent or actor; Tab completes exact participant IDs, including nested agents. Ambiguous names or ID prefixes are rejected; use an exact participant ID to select the intended target. In the dashboard, **Shift+C** opens the selected participant.
34
34
 
35
- The first implicit open prefers a currently active child over stale history; later opens remember a valid selection. The view keeps a lossless native Pi transcript and a multiline Pi editor together, independently of the dashboard’s bounded transcript projection. It uses Pi’s real user, assistant, thinking, tool, skill, custom-message, and summary components, including registered tool renderers such as `fabric_exec`, with complete tool details and native expansion behavior. User backgrounds and editor rules span the terminal width, with Pi's configured output padding, editor padding, and code-block indentation inside them. Markdown and tool previews use the configured Shiki theme. A one-row gap belongs to the transcript's end, not the fixed input dock, so it scrolls away and leaves history unobstructed. While the selected participant is active, the native-style `Working` indicator stays in the editor border; the transcript uses a fallback only when that border is out of view. The directory/name footer row includes a compact `read-only` badge when needed; status, model, and thinking metadata are not repeated in a separate header. The footer below the editor shows the selected participant's directory, known branch, model, thinking level, and its current or last run's token, cache, and cost totals, tool calls, and elapsed time, for example `↑43k ↓2.2k R147k $0.122 · 12 calls · 3m04s · ?/272k ctx`. A running participant shows `Working` on the border, so the line names the status only once the run settles, such as `completed · …` or `failed · …`. Unknown usage and context occupancy are marked explicitly; Main's statistics are never substituted. A target badge sits on the upper-right editor border, replacing the standalone transcript breadcrumb. Like the main editor's label badge, it is filled with the border's own colour, which Pi sets from the thinking level, so it changes when the reasoning level does; its text is black or white, whichever has the higher contrast against that colour, and a border drawn without colour gets a plain label. It shows the target's own name, shortened on narrow terminals, and marks read-only targets; lineage lives in the agent list below the window. Native working and draft-scroll labels share the border without adding a row. Main and other participants keep running: opening, navigating, and closing the view never calls Pi's session-replacement API or starts another worker. Selecting Main restores the original Pi conversation, including its editor. Child drafts and scroll positions survive switching targets and reopening the view for the lifetime of this Pi session.
35
+ The first implicit open prefers a currently active child over stale history; later opens remember a valid selection. The view keeps a lossless native Pi transcript and a multiline Pi editor together, independently of the dashboard’s bounded transcript projection. When the initial byte-bounded history page leaves the live viewport underfilled, normal refreshes backfill at most one older page each until it fills or history ends; pinned history is not moved, and rendering itself never reads extra pages. It uses Pi’s real user, assistant, thinking, tool, skill, custom-message, and summary components, including registered tool renderers such as `fabric_exec`, with complete tool details and native expansion behavior. User backgrounds and editor rules span the terminal width, with Pi's configured output padding, editor padding, and code-block indentation inside them. Markdown and tool previews use the configured Shiki theme. A one-row gap above the editor belongs to the fixed input dock, matching Pi, so it remains visible while scrolling through history without doubling the gap at the live bottom. While the selected participant is active, the native-style `Working` indicator stays in the editor border; the transcript uses a fallback only when that border is out of view. Hidden Fabric agent/actor feedback is shown as the same bounded, sanitized `Agent …` status text used by Main's notifications; its raw envelope and structured data stay hidden. Other extensions' hidden messages stay hidden. The directory/name footer row includes a compact `read-only` badge when needed; status, model, and thinking metadata are not repeated in a separate header. The footer below the editor shows the selected participant's directory, known branch, model, thinking level, and its current or last run's token, cache, and cost totals, tool calls, and elapsed time, for example `↑43k ↓2.2k R147k $0.122 · 12 calls · 3m04s · ?/272k ctx`. A running participant shows `Working` on the border, so the line names the status only once the run settles, such as `completed · …` or `failed · …`. Unknown usage and context occupancy are marked explicitly; Main's statistics are never substituted. A target badge sits on the upper-right editor border, replacing the standalone transcript breadcrumb. Like the main editor's label badge, it is filled with the border's own colour, which Pi sets from the thinking level, so it changes when the reasoning level does; its text is black or white, whichever has the higher contrast against that colour, and a border drawn without colour gets a plain label. It shows the target's own name, shortened on narrow terminals, and marks read-only targets; lineage lives in the agent list below the window. Native working and draft-scroll labels share the border without adding a row. Main and other participants keep running: opening, navigating, and closing the view never calls Pi's session-replacement API or starts another worker. Selecting Main restores the original Pi conversation, including its editor. Child drafts and scroll positions survive switching targets and reopening the view for the lifetime of this Pi session.
36
36
 
37
37
  The same agent list sits at the bottom of the conversation window, below its footer, with the same key hints, so `↓ to manage` and `⏎ open · ↑↓ select · esc back` tell whether the keys go to the editor or to the list. The participant on screen keeps the filled circle, and the header row is Main. **↓** in an empty editor moves into the list, **Enter** or a click switches to the selected participant, selecting Main returns to the native session, and a shell row opens the tasks view over the window. **Esc** or **↑** on the top row returns to the editor. This list replaces the former target picker and its cycling and parent/child keys.
38
38
 
package/docs/jev.md CHANGED
@@ -330,7 +330,7 @@ return {id:observer.id, state:observer.state};
330
330
 
331
331
  ### Delivery, freshness, and interruption
332
332
 
333
- Delivery defaults to off. Opt into `"steer"` or legacy `"followUp"` (both deliver Main feedback as hidden steering); `triggerTurn` defaults to false and never wakes idle Main when false. UI hosts show a bounded notification naming the advisor instead of a chat bubble. The full advice remains in model context and session audit, with actual and requested delivery modes. `maxAdvice` bounds delivery attempts for the run (feedback/stale suppression does not consume a delivery attempt) (1–16, default 4). Advice must be sent before requesting the next event; it needs the last consumed event ID and must still match the latest completed-turn/task/context revision and age limit. A next turn may be in flight; a newer completed turn, real input, compaction, or cancellation invalidates old advice. The check is at enqueue time, not a guarantee that context cannot change before Main consumes a queued message.
333
+ Delivery defaults to off. Opt into `"steer"` or legacy `"followUp"` (both deliver Main feedback as hidden steering); `triggerTurn` defaults to false and never wakes idle Main when false. UI hosts show a bounded notification naming the advisor and omit the chat bubble. The full advice remains in model context and session audit, with actual and requested delivery modes. `maxAdvice` bounds delivery attempts for the run (feedback/stale suppression does not consume a delivery attempt) (1–16, default 4). Advice must be sent before requesting the next event; it needs the last consumed event ID and must still match the latest completed-turn/task/context revision and age limit. A next turn may be in flight; a newer completed turn, real input, compaction, or cancellation invalidates old advice. The check is at enqueue time, not a guarantee that context cannot change before Main consumes a queued message.
334
334
 
335
335
  There is at most **one delivery attempt across all Jev observers per external user input**. Automatic continuations and extension-injected input do not reset this feedback latch. Duplicate, stale, disabled, over-budget, feedback-gated, or failed deliveries return `{delivered:false,reason}`; failures are not replayed. This prevents an advisor from repeatedly waking/steering Main based on its own intervention. Additional turns may still be classified and recorded within budget. Broader separately granted tools retain their own authority; these safeguards specifically govern `jev.advise`.
336
336
 
@@ -140,7 +140,13 @@ Every cache record stores the exact session file path, branch mode, lineage
140
140
  fingerprint, privacy policy, and a SHA-256 `sourceHash`, along with source
141
141
  mtime and size. A same-size rewrite that preserves mtime still invalidates
142
142
  the record. Fabric creates cache directories with `0700` permissions and
143
- cache files with `0600` permissions on a best-effort basis.
143
+ cache files with `0600` permissions on a best-effort basis. A refresh publishes
144
+ complete JSON with a same-directory rename. Fabric and standalone pi-recall
145
+ coordinate publication and eviction with a per-entry `.lock` directory. A
146
+ contended write is skipped, not waited on; the query still uses the session
147
+ JSONL. A hard process kill can leave an empty `.lock` that disables cache
148
+ updates for one entry. Remove it only after stopping all clients using that
149
+ index. Older releases do not participate in the lock protocol.
144
150
 
145
151
  A hot shard holds bounded normalized entry text plus `indexCoverage`. Each
146
152
  cold digest contains:
@@ -498,6 +504,41 @@ An optional inclusive `entryRange` can bound explicit single-session recall.
498
504
  Both endpoints must be valid normalized indices. Out-of-range or negative
499
505
  addresses return `index_out_of_bounds`; Fabric never clamps them.
500
506
 
507
+ ## Session outline
508
+
509
+ `memory.outline` maps one resolved session before reading it. It resolves the
510
+ session with the same `source`, `branches`, and pointer arguments as
511
+ `memory.expand` and returns a deterministic skeleton: one bounded row per
512
+ normalized entry with `index`, `type`, `role`, `tool`, a whitespace-collapsed
513
+ single-line `preview` (at most 120 characters, never splitting a surrogate
514
+ pair), and `size`, the entry-text length a later `memory.expand` returns for
515
+ that index. No scores, no ranking, no continuation. `maxEntries` caps the rows
516
+ (default 200); `total` counts the entries that match `role`, or all entries
517
+ when no role is set, and `truncated` is true only when matching entries
518
+ exceed the returned rows. `entryCount` always counts the resolved session
519
+ before any filter. When the session's index coverage is incomplete (a host
520
+ source that retained only part of the session), the response carries
521
+ `coverage: { complete: false, reasons }` to identify the partial view.
522
+
523
+ An optional `role` argument filters the skeleton by exact normalized role, and
524
+ `memory.expand` accepts the same `role` argument: it filters the resolved
525
+ selection before chunking and rides the continuation in `next.args`. An empty
526
+ match returns a plain empty view with `next: null`.
527
+
528
+ ```ts
529
+ const map = await memory.outline({ session });
530
+ const userRows = map.entries.filter((row) => row.role === "user");
531
+ // Expand a matching row only after checking it exists. An outline with no
532
+ // user row (or an empty session) has no index 0 to read.
533
+ const first = userRows.length > 0
534
+ ? await memory.expand({
535
+ session, indices: [userRows[0]!.index],
536
+ expectedSourceHash: map.sourceHash,
537
+ expectedLineageFingerprint: map.lineageFingerprint,
538
+ })
539
+ : null;
540
+ ```
541
+
501
542
  ## Expansion and guest-local computation
502
543
 
503
544
  `memory.expand` re-reads full, untruncated normalized records. It accepts
package/docs/providers.md CHANGED
@@ -51,6 +51,27 @@ async invoke(actionName, args, context) {
51
51
  }
52
52
  ```
53
53
 
54
+ ## Provider-owned human waits
55
+
56
+ During `fabric_exec`, a trusted provider can use `context.humanWait` to pause the
57
+ native program deadline around an authenticated human decision:
58
+
59
+ ```ts
60
+ const wait = () => askAuthorizedPerson(context.signal);
61
+ const decision = await (context.humanWait ? context.humanWait(wait) : wait());
62
+ // Perform authorized tool work after the wait, outside the paused interval.
63
+ ```
64
+
65
+ During `fabric_exec`, the invocation context always has a `humanWait` property.
66
+ Its value is `undefined` under an explicit hard whole-script deadline (`timeout_ms`)
67
+ or when the caller has no native pause capability. Cancellation still uses
68
+ `context.signal`; providers must honor it. Overlapping waits keep the deadline
69
+ paused until the last one settles. CPU-slice and memory limits are unchanged.
70
+ Never wrap tool dispatch, network work, or guest execution in this callback. It
71
+ changes deadline accounting only and grants no permission to perform an action.
72
+ `executor.humanWaitRefs` controls whole-call pauses separately; an empty list does
73
+ not disable a trusted provider's explicit human-decision pause.
74
+
54
75
  ## Provider participants
55
76
 
56
77
  A provider that starts its own long-running work, such as a delegate that launches runs on another system, can register each run as a participant. Inside `fabric_exec`, `context.participants` is present (it is absent in other host contexts such as speculation, so check it):
@@ -243,7 +264,7 @@ await piFabric(pi, { managedHost: {
243
264
  foreground: ["ask_user_questions", "ai_todo_write", "run_delegated_task"],
244
265
  guidance: "Apply the host's workflow and receipt-reconciliation policy.",
245
266
  skillReader: "mcp.files.read",
246
- executor: { maxCpuSliceMs: 1000 },
267
+ executor: { maxCpuSliceMs: 1000, maxOutputChars: 262144, maxNestedResultChars: 2000000 },
247
268
  compaction: "pi",
248
269
  } });
249
270
  ```
@@ -252,6 +273,8 @@ await piFabric(pi, { managedHost: {
252
273
  - Stable execution guidance names only the host-authorized provider namespaces and is emitted once through the execution-guidance slot. Tool and `code` descriptions stay short and refer to it. `guidance` appends trusted host instructions once to the system prompt; the existing execution guidance slot can still replace the default. Provider registration remains v1: its event and payload do not change.
253
274
  - `skillReader` names the host's dotted callable reader, for example `mcp.files.read`. Without it, Fabric omits its skill-loading instruction and delegated-skill hint. Managed hosts supply their own skill resources; Fabric does not contribute bundled coding workflows.
254
275
  - `executor.maxCpuSliceMs` defaults to `1000`, must be a positive safe integer, and limits uninterrupted guest CPU, not host-provider execution. Whole-program timeouts remain separate.
276
+ - `executor.maxOutputChars` defaults to `50000`; `executor.maxNestedResultChars` defaults to `2000000`. Both accept positive safe integers from host code only, without coercion or clamping to the default. Omitted, `undefined`, or `null` options keep the default; other invalid values throw. Final model output and nested provider results are bounded independently. Native-result calls retain their separate 16,777,216-character ceiling.
277
+ - `fabric_exec.maxOutputTokens` can lower the final output ceiling (estimated at four characters per token), never raise it. Omit it when returning full contracts to use the host ceiling; large results still need projection or paging.
255
278
  - `compaction` is `"fabric"` by default, preserving existing behavior; `"pi"` leaves compaction to the embedding host and its saved formats.
256
279
 
257
280
  Options are copied when the host is created. Later mutation of the caller's arrays or executor object cannot widen the host policy. See the [migration and changelog](managed-host-migration.md).
@@ -0,0 +1,249 @@
1
+ # Small-session resume latency investigation
2
+
3
+ ## What was reproduced
4
+
5
+ Measured on 2026-11-09 with the real Pi 1.5.0 SDK and compiled Fabric, on a
6
+ supercomputer `large` boat VM: AMD Ryzen 9 9950X, four pinned vCPUs of eight,
7
+ exclusive placement, no co-tenants. Each profile runs in a fresh Node 24.22.1
8
+ process. The two synthetic session files contain four short user messages each.
9
+ No personal histories, authentication files, or live model requests are used.
10
+ The full-stack replica contains the user's 25 other extension packages, their
11
+ public model catalogs, and Fabric in the configured order (27 file entrypoints;
12
+ 28 loaded factories including the offline test provider).
13
+
14
+ | Scenario | Three subsequent session switches |
15
+ | --- | --- |
16
+ | Core plus offline test provider | 8.32 / 11.80 / 12.22 ms |
17
+ | Fabric, not yet activated by a tool call | 28.60 / 17.26 / 15.52 ms |
18
+ | Fabric after executing `fabric_exec` | 283.69 / 274.01 / 271.70 ms |
19
+ | Fabric defaults after executing `fabric_exec` | 313.94 / 288.09 / 312.03 ms |
20
+ | Full extension stack, same cwd | 83.78 / 74.63 / 78.50 ms |
21
+ | Full extension stack, alternating cwd | 386.53 / 329.04 / 276.46 ms |
22
+
23
+ Reading the small session files took 0.10–0.19 ms. This does not explain a
24
+ multi-second pause. The activated-Fabric cases spend 252–294 ms in the Fabric
25
+ `session_shutdown` hook; that is a real smaller contribution, not a reproduced
26
+ 5–10 second delay. The individual closer responsible has not been isolated.
27
+
28
+ The first full-stack runtime creation took **3957.53 ms**, of which
29
+ **3721.43 ms** was resource/extension loading and **117.76 ms** was extension
30
+ binding. A following fresh-process profile on the same VM, with warmed disk and
31
+ transpile caches, created the initial full-stack runtime in **918.17 ms**.
32
+ These are separate cache conditions, not repeat samples of one distribution.
33
+ Core import precedes these runtime-creation measurements and is recorded
34
+ separately in the evidence. No millisecond threshold is used as a test gate.
35
+
36
+ ### Where the first full-stack load spent time
37
+
38
+ Pi's loader timing deltas, including module import/compilation/transpilation:
39
+
40
+ | Entry | Import | Factory |
41
+ | --- | ---: | ---: |
42
+ | pi-better-openai | 640 ms | 2 ms |
43
+ | pi-multiprovider | 374 ms | 2 ms |
44
+ | Fabric | 25 ms | 301 ms |
45
+ | pi-queue-steer | 221 ms | 2 ms |
46
+ | pi-math | 214 ms | 8 ms |
47
+ | pi-better-grok | 191 ms | 1 ms |
48
+ | pi-neuralwatt-provider main entry | 181 ms | 1 ms |
49
+
50
+ These are observations of this ordered stack, not clean independent package
51
+ benchmarks: shared dependencies and loader cache state affect attribution.
52
+ They do show that the expensive work happens before most `session_start` hooks.
53
+
54
+ ## Why session size can be irrelevant
55
+
56
+ `AgentSessionRuntime.switchSession()` does more than load JSONL: it tears down
57
+ the previous runtime and constructs/binds a replacement. Resource loading
58
+ therefore occurs even for a four-message session.
59
+
60
+ Pi's `loadExtensionsCached()` caches module factories, not initialized extension
61
+ instances. `useExtensionCacheCwd()` invalidates that module cache when cwd
62
+ changes. Same-cwd replacements still run factories; cross-cwd replacements
63
+ also import the modules again. In the full-stack profiles, resource reload was
64
+ 7.95–8.86 ms within one cwd and 180.10–254.13 ms across cwd changes. This is a
65
+ verified extra cost, but still not a reproduced multi-second warm switch.
66
+
67
+ History paging begins at `agent_start` or after compaction, not while reading
68
+ these files. There was no large inactive payload to page in this experiment.
69
+ It is not the explanation for the measured initial extension-loading cost.
70
+
71
+ ## What is not established
72
+
73
+ This was an isolated **SDK/headless** profile, not a recording of the user's
74
+ macOS TUI. It excludes terminal rendering, real provider credentials and network
75
+ behavior, real global/project settings, resource discovery over the user's
76
+ filesystem, and interaction with the resume picker. `hasUI`/TUI-only behavior is
77
+ not represented. The full-stack cases did not warm Fabric through a tool call;
78
+ those costs were measured separately and are not claimed to be additive.
79
+
80
+ A 5–10 second pause **after selecting a session in an already-running Pi** has
81
+ not been reproduced. Cold extension loading is a demonstrated seconds-scale
82
+ cost; it must not be presented as complete attribution of that warm pause.
83
+ Distinguish opening the picker, choosing an item, and waiting for the first
84
+ model response before optimizing the wrong phase.
85
+
86
+ ## Follow-up: `pi --session …` and a visible startup screen
87
+
88
+ The user clarified that this is a fresh CLI launch with `--session`, rather
89
+ than an in-process session switch. The earlier warm-switch measurements are
90
+ not a reproduction of that path. In particular, multi-second extension imports
91
+ happen **before** the TUI is constructed, so that number alone cannot explain
92
+ a pause after a startup screen is already visible.
93
+
94
+ Reading the installed 1.5.0 bundled CLI and its corresponding sources shows:
95
+
96
+ 1. The session is selected/opened and extensions imported before constructing
97
+ `InteractiveMode`.
98
+ 2. `init()` starts the terminal UI, waits for terminal colors (bounded by about
99
+ 100 ms), then ensures `fd`/`rg` and binds extensions in TUI mode.
100
+ 3. Binding awaits `session_start` and resource-discovery handlers. It then adds
101
+ loaded-resource information and startup notices.
102
+ 4. The initial transcript is constructed and `renderNow()` paints it.
103
+ 5. The normal background model-catalog refresh starts only after `init()`.
104
+ `updateAvailableProviderCount()` itself reads an existing snapshot; it does
105
+ not initiate a network refresh.
106
+
107
+ A real changelog is suppressed if `session.state.messages.length > 0`. A
108
+ visible **release-notes** screen for a populated session is therefore a useful
109
+ anomaly to investigate, not grounds for assuming a network timeout. The
110
+ startup header/resource list is a different visible milestone.
111
+
112
+ `scripts/benchmark-cli-resume.mjs` now tests the actual bundled CLI under a
113
+ Linux pseudo-terminal, with both four-message and empty-session controls.
114
+ The buffered-tracer run completed all three cases on the same exclusive boat VM:
115
+
116
+ | Bundled CLI case | Before TUI construction | `init()` duration | First restored transcript write |
117
+ | --- | ---: | ---: | ---: |
118
+ | Core, four messages | 269 ms | 127 ms | 396 ms from preload |
119
+ | Full stack, four messages | 6,106 ms | 387 ms | 6,491 ms from preload |
120
+ | Full stack, empty session | 1,012 ms | 534 ms | Not applicable |
121
+
122
+ These are individual samples with different cache states, not a latency
123
+ threshold or an isolated comparison of per-package costs. The full-stack
124
+ resumed case spent 245 ms binding TUI extensions and 1.11 ms constructing the
125
+ initial transcript. Both populated cases reported `coreChangelog: false` and
126
+ no extension changelogs; the empty control reported `coreChangelog: true`.
127
+ The seconds-scale pre-TUI time is real, but does not prove the cause of a
128
+ seconds-long pause **after a newly painted banner** on the user's Mac. A
129
+ terminal write is also not proof of when the terminal application painted it.
130
+ The successful trace and placement receipt are saved in
131
+ `docs/benchmarks/cli-resume-2026-11-09.json`. Per-hook disk writes were removed
132
+ before this final run to avoid perturbing the measured path.
133
+
134
+ It uses the same tracer that can be enabled for a user's real launch:
135
+
136
+ ```sh
137
+ PI_RESUME_TRACE=/tmp/pi-resume-startup.json \
138
+ node --import /path/to/pi-fabric/scripts/trace-cli-startup.mjs \
139
+ "$(command -v pi)" --session YOUR_EXISTING_SESSION_ARGUMENT
140
+ ```
141
+
142
+ Run from the **same cwd** as the usual command, using the same session argument.
143
+ Node 24+ is required. No `PI_OFFLINE` or benchmark flag should be set for this
144
+ real-launch trace: the normal session should remain open and behave normally.
145
+
146
+ The opt-in tracer patches only the current process in memory. It does not
147
+ modify the installed package, global settings, or session history. It records
148
+ phase/hook names, extension paths, elapsed times, and loaded-message counts,
149
+ not conversation text or credentials. It buffers at most 2,000 records, writes
150
+ the trace at initialization completion (or process exit), then stops collecting.
151
+ The specified output file is replaced. This is diagnostic instrumentation, not
152
+ a production startup fix; it must not be enabled globally through NODE_OPTIONS.
153
+
154
+ ## Next changes worth testing
155
+
156
+ 1. Defer optional UI/renderer/controller dependency graphs in the heaviest
157
+ extensions until the feature is used. Factory time alone is not the budget:
158
+ import/compilation is the larger part here.
159
+ 2. Investigate preserving cwd-independent module factories in Pi's loader while
160
+ still creating fresh per-session extension state. Do not reuse mutable
161
+ extension instances or blindly keep cwd-dependent modules.
162
+ 3. Isolate the warmed Fabric shutdown closer before changing cleanup semantics.
163
+ 4. If the reported problem is a warm in-TUI switch, collect that exact path with
164
+ the user's settings/provider state. Do not infer a network timeout or blame
165
+ the fast-resume picker from these headless measurements.
166
+
167
+ ## Trace from the user's actual launch
168
+
169
+ The user ran the tracer against this session on macOS. The trace contained 140
170
+ loaded messages and 34 extensions, and finished initialization at 8,829 ms:
171
+
172
+ | Phase | Time |
173
+ | --- | ---: |
174
+ | Before constructing the TUI | 5,353 ms |
175
+ | Binding startup hooks and resources | 2,464 ms |
176
+ | Fabric's first `session_start` hook (inside binding) | 1,561 ms |
177
+ | multiprovider's `session_start` hook (inside binding) | 501 ms |
178
+ | Constructing transcript components | 463 ms |
179
+ | Initial terminal render | 410 ms |
180
+
181
+ The two startup model-refresh operations overlap other startup work; their
182
+ elapsed times must **not** be added to these totals. The session was loaded
183
+ correctly, and neither core nor extension changelogs were eligible. These are
184
+ one traced launch's observations, not a before/after benchmark.
185
+
186
+ ### First-use MCP initialization
187
+
188
+ Actor recovery can activate the full Fabric runtime before the first tool call.
189
+ Registering its built-in MCP provider also called `warmup()`, which hydrates the
190
+ descriptor cache and, on a cache miss/configuration change, imports mcporter and
191
+ resolves configurations. Although not awaited directly, that module evaluation
192
+ competes on the main thread while startup hooks are awaited. Backgrounding an
193
+ import does not make its CPU work free.
194
+
195
+ Built-in registration no longer starts this work. MCP remains registered, and
196
+ its existing first `list`/`describe`/`invoke` path hydrates the cache and performs
197
+ normal discovery. An actor that requires MCP can still initialize it
198
+ through capability resolution. This does not postpone actor recovery, change
199
+ provider authorization, or disable MCP. The mount/first-use regression is in
200
+ `tests/mcp-lazy-import.test.ts`; existing cached/live/native-provider tests cover
201
+ the provider's subsequent behavior.
202
+
203
+ This change addresses one eager-startup path. It does **not** claim to fix the
204
+ 5.35-second pre-TUI extension load, the other extensions' hooks, or Pi's initial
205
+ transcript rendering. A second real launch on the user's Mac is needed to
206
+ establish the end-to-end improvement there.
207
+
208
+ The CLI fixture's `--eager-actors` case now enables MCP as well as restoring an
209
+ idle actor. The original fixture disabled MCP and therefore missed this path.
210
+
211
+ The final exclusive-VM run passed all 78 tests in the eight selected suites,
212
+ whole-program typechecking, the host-free lazy-graph assertion, and the final
213
+ build. All 12 synthetic CLI launches completed. The two first-use warm launches
214
+ spent 316 and 393 ms in Fabric's startup hook; the final eager warm control took
215
+ 377 ms. These overlap: this small run does **not** establish a consistent latency
216
+ improvement. In particular, the first eager launch (8.42 s total) must not be
217
+ compared with subsequent warmed first-use launches (1.76–1.84 s) as a claimed
218
+ speedup. The structural regression verifies removal of unwanted startup work;
219
+ end-to-end improvement on the user's Mac remains unmeasured. Full synthetic
220
+ records and placement are in
221
+ `docs/benchmarks/resume-startup-fix-2026-11-09.json`.
222
+
223
+ ## Reproducing the controls
224
+
225
+ Run on a prepared remote checkout, never the laptop for timing claims:
226
+
227
+ ```sh
228
+ bun install --frozen-lockfile
229
+ bun run build
230
+ node scripts/benchmark-resume-latency.mjs --variant core --cycles 3
231
+ node scripts/benchmark-resume-latency.mjs --variant fabric --cycles 3
232
+ node scripts/benchmark-resume-latency.mjs --variant fabric --warm --cycles 3
233
+ node scripts/benchmark-resume-latency.mjs --variant fabric-default --warm --cycles 3
234
+ ```
235
+
236
+ For the full stack, supply a JSON array of absolute extension package/file
237
+ paths, with the correct order and installed dependencies:
238
+
239
+ ```sh
240
+ node scripts/benchmark-resume-latency.mjs --variant stack --extensions-file paths.json --cycles 3
241
+ node scripts/benchmark-resume-latency.mjs --variant stack --extensions-file paths.json --cross-cwd --cycles 3
242
+ ```
243
+
244
+ The benchmark asserts extension loading, completed switches, and successful
245
+ Fabric execution in warmed cases. `completed: true` marks successful current
246
+ probe runs. A failure's partial timing record is not a passed profile. Timings
247
+ are nested/inclusive; do not sum overlapping `model.refresh` and parent spans.
248
+ Raw successful phase records, loader timing groups, and placement receipts are
249
+ in `docs/benchmarks/resume-latency-2026-11-09.json`.