@e4779/pi-fabric 0.102.0-fork.16 → 0.105.0-fork.22

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 (562) hide show
  1. package/README.md +44 -13
  2. package/THIRD_PARTY_NOTICES.md +10 -2
  3. package/dist/activity/store.d.ts +3 -0
  4. package/dist/activity/store.d.ts.map +1 -1
  5. package/dist/activity/workflow-items.d.ts +33 -0
  6. package/dist/activity/workflow-items.d.ts.map +1 -0
  7. package/dist/actors/binding-store.d.ts.map +1 -1
  8. package/dist/actors/manager.d.ts +6 -0
  9. package/dist/actors/manager.d.ts.map +1 -1
  10. package/dist/actors/mesh-monitor.d.ts +2 -2
  11. package/dist/actors/mesh-monitor.d.ts.map +1 -1
  12. package/dist/actors/registry-store.d.ts.map +1 -1
  13. package/dist/actors/types.d.ts +11 -0
  14. package/dist/actors/types.d.ts.map +1 -1
  15. package/dist/agents/child-env.d.ts +29 -0
  16. package/dist/agents/child-env.d.ts.map +1 -0
  17. package/dist/agents/fork-seed.d.ts +21 -0
  18. package/dist/agents/fork-seed.d.ts.map +1 -0
  19. package/dist/agents/handoff.d.ts +7 -1
  20. package/dist/agents/handoff.d.ts.map +1 -1
  21. package/dist/agents/hosted-run.d.ts +63 -0
  22. package/dist/agents/hosted-run.d.ts.map +1 -0
  23. package/dist/agents/manager.d.ts +21 -1
  24. package/dist/agents/manager.d.ts.map +1 -1
  25. package/dist/agents/request.d.ts.map +1 -1
  26. package/dist/agents/runner-notice.d.ts +7 -0
  27. package/dist/agents/runner-notice.d.ts.map +1 -0
  28. package/dist/agents/runner-protocol.d.ts +158 -0
  29. package/dist/agents/runner-protocol.d.ts.map +1 -0
  30. package/dist/agents/runner-registry.d.ts +223 -0
  31. package/dist/agents/runner-registry.d.ts.map +1 -0
  32. package/dist/agents/transports/process-transport.d.ts.map +1 -1
  33. package/dist/agents/transports/process-utils.d.ts +4 -1
  34. package/dist/agents/transports/process-utils.d.ts.map +1 -1
  35. package/dist/agents/types.d.ts +89 -4
  36. package/dist/agents/types.d.ts.map +1 -1
  37. package/dist/agents/worktree-manager.d.ts +21 -0
  38. package/dist/agents/worktree-manager.d.ts.map +1 -1
  39. package/dist/agents/write-guard.d.ts +16 -0
  40. package/dist/agents/write-guard.d.ts.map +1 -0
  41. package/dist/agents/write-guard.js +13 -0
  42. package/dist/agents/write-guard.js.map +7 -0
  43. package/dist/agents.js +13 -12
  44. package/dist/agents.js.map +1 -1
  45. package/dist/assessment.d.ts +3 -0
  46. package/dist/assessment.d.ts.map +1 -0
  47. package/dist/assessment.js +15 -0
  48. package/dist/assessment.js.map +7 -0
  49. package/dist/audit/assessment.d.ts +74 -0
  50. package/dist/audit/assessment.d.ts.map +1 -0
  51. package/dist/audit/details.d.ts +4 -0
  52. package/dist/audit/details.d.ts.map +1 -1
  53. package/dist/audit/index.d.ts +1 -0
  54. package/dist/audit/index.d.ts.map +1 -1
  55. package/dist/audit/projection.d.ts +2 -1
  56. package/dist/audit/projection.d.ts.map +1 -1
  57. package/dist/audit/trace.d.ts +16 -1
  58. package/dist/audit/trace.d.ts.map +1 -1
  59. package/dist/cache/leases.d.ts +2 -1
  60. package/dist/cache/leases.d.ts.map +1 -1
  61. package/dist/capture/interceptor.d.ts.map +1 -1
  62. package/dist/chunks/chunk-2USMWEE6.js +81 -0
  63. package/dist/chunks/chunk-2USMWEE6.js.map +7 -0
  64. package/dist/chunks/chunk-2Y24ML7H.js +115 -0
  65. package/dist/chunks/chunk-2Y24ML7H.js.map +7 -0
  66. package/dist/chunks/chunk-3GJJG2FV.js +1329 -0
  67. package/dist/chunks/chunk-3GJJG2FV.js.map +7 -0
  68. package/dist/chunks/{chunk-5VTBHJN3.js → chunk-3KDUMDPZ.js} +153 -29
  69. package/dist/chunks/chunk-3KDUMDPZ.js.map +7 -0
  70. package/dist/chunks/chunk-4RTHQGES.js +189 -0
  71. package/dist/chunks/chunk-4RTHQGES.js.map +7 -0
  72. package/dist/chunks/{chunk-ZZ66L3W5.js → chunk-5MNLVHF5.js} +30 -7
  73. package/dist/chunks/chunk-5MNLVHF5.js.map +7 -0
  74. package/dist/chunks/{chunk-RAO6TQFP.js → chunk-5XBYFSI5.js} +26 -6
  75. package/dist/chunks/chunk-5XBYFSI5.js.map +7 -0
  76. package/dist/chunks/{chunk-J2HV2URQ.js → chunk-7EYJE4TW.js} +1 -1
  77. package/dist/chunks/{chunk-J2HV2URQ.js.map → chunk-7EYJE4TW.js.map} +2 -2
  78. package/dist/chunks/{chunk-57CMH4SW.js → chunk-7JU7Z4XQ.js} +2 -2
  79. package/dist/chunks/chunk-7QKKLBHJ.js +33 -0
  80. package/dist/chunks/chunk-7QKKLBHJ.js.map +7 -0
  81. package/dist/chunks/chunk-7XRUMDV7.js +235 -0
  82. package/dist/chunks/chunk-7XRUMDV7.js.map +7 -0
  83. package/dist/chunks/{chunk-DUJ46TIP.js → chunk-ABJCSNZO.js} +4 -4
  84. package/dist/chunks/chunk-B2Y4364O.js +78 -0
  85. package/dist/chunks/chunk-B2Y4364O.js.map +7 -0
  86. package/dist/chunks/{chunk-4TKPBEPB.js → chunk-BVJBYFHD.js} +9 -3
  87. package/dist/chunks/{chunk-4TKPBEPB.js.map → chunk-BVJBYFHD.js.map} +2 -2
  88. package/dist/chunks/{chunk-KP4ANT6L.js → chunk-C7EEG6SM.js} +2 -2
  89. package/dist/chunks/{chunk-NHMICIEU.js → chunk-CCHZXF6K.js} +3 -3
  90. package/dist/chunks/{chunk-W63E3WEO.js → chunk-CXTTLBUV.js} +3 -2
  91. package/dist/chunks/chunk-CXTTLBUV.js.map +7 -0
  92. package/dist/chunks/{chunk-HOX6VW45.js → chunk-CYMDX3XP.js} +1 -1
  93. package/dist/chunks/{chunk-HOX6VW45.js.map → chunk-CYMDX3XP.js.map} +1 -1
  94. package/dist/chunks/chunk-DK35W6U7.js +259 -0
  95. package/dist/chunks/chunk-DK35W6U7.js.map +7 -0
  96. package/dist/chunks/{chunk-5JN5AWNV.js → chunk-DZ4WN5XJ.js} +3 -3
  97. package/dist/chunks/chunk-EXWS4ZS3.js +6490 -0
  98. package/dist/chunks/chunk-EXWS4ZS3.js.map +7 -0
  99. package/dist/chunks/{chunk-QHYBSIIO.js → chunk-FB24AOIJ.js} +39 -37
  100. package/dist/chunks/{chunk-QHYBSIIO.js.map → chunk-FB24AOIJ.js.map} +1 -1
  101. package/dist/chunks/chunk-FSB2VIRZ.js +435 -0
  102. package/dist/chunks/chunk-FSB2VIRZ.js.map +7 -0
  103. package/dist/chunks/{chunk-PNDYFU64.js → chunk-GJVPP3NN.js} +81 -11
  104. package/dist/chunks/chunk-GJVPP3NN.js.map +7 -0
  105. package/dist/chunks/{chunk-B5D6GA77.js → chunk-GYPDGW27.js} +100 -92
  106. package/dist/chunks/chunk-GYPDGW27.js.map +7 -0
  107. package/dist/chunks/{chunk-LEFBW2GK.js → chunk-IAFI4A2I.js} +44 -2
  108. package/dist/chunks/{chunk-LEFBW2GK.js.map → chunk-IAFI4A2I.js.map} +3 -3
  109. package/dist/chunks/{chunk-PWS2OXLV.js → chunk-IIPKG52D.js} +1 -1
  110. package/dist/chunks/chunk-IIPKG52D.js.map +7 -0
  111. package/dist/chunks/chunk-ITVLKXCI.js +266 -0
  112. package/dist/chunks/chunk-ITVLKXCI.js.map +7 -0
  113. package/dist/chunks/chunk-JKQARSWR.js +265 -0
  114. package/dist/chunks/chunk-JKQARSWR.js.map +7 -0
  115. package/dist/chunks/{chunk-AYBIR4YV.js → chunk-KJZAOENY.js} +6 -4
  116. package/dist/chunks/chunk-KJZAOENY.js.map +7 -0
  117. package/dist/chunks/{chunk-74BA4VSX.js → chunk-KQ6R5EWR.js} +1462 -1405
  118. package/dist/chunks/chunk-KQ6R5EWR.js.map +7 -0
  119. package/dist/chunks/chunk-L22K5BWU.js +180 -0
  120. package/dist/chunks/chunk-L22K5BWU.js.map +7 -0
  121. package/dist/chunks/{chunk-7XJB2USB.js → chunk-LOLCTWJF.js} +4 -4
  122. package/dist/chunks/{chunk-QETG2GVX.js → chunk-M5IN6DMF.js} +34 -31
  123. package/dist/chunks/chunk-M5IN6DMF.js.map +7 -0
  124. package/dist/chunks/{chunk-64O5L7EW.js → chunk-M6IRQ3QT.js} +2 -2
  125. package/dist/chunks/{chunk-TX6E5W7H.js → chunk-NTC2MCB6.js} +1 -1
  126. package/dist/chunks/chunk-NTC2MCB6.js.map +7 -0
  127. package/dist/chunks/{chunk-EPYLZWJV.js → chunk-OVBKQCYL.js} +2 -2
  128. package/dist/chunks/{chunk-YV2PHCDB.js → chunk-PYFJW3HC.js} +16 -2
  129. package/dist/chunks/{chunk-YV2PHCDB.js.map → chunk-PYFJW3HC.js.map} +3 -3
  130. package/dist/chunks/{chunk-Z5Y65YBX.js → chunk-PYQM7KPL.js} +3 -2
  131. package/dist/chunks/{chunk-BEJF2JX2.js → chunk-QLFDPXK7.js} +33 -2
  132. package/dist/chunks/chunk-QLFDPXK7.js.map +7 -0
  133. package/dist/chunks/chunk-QUWC6YCN.js +125 -0
  134. package/dist/chunks/chunk-QUWC6YCN.js.map +7 -0
  135. package/dist/chunks/{chunk-DKVJREDI.js → chunk-QY7YK7M6.js} +2 -2
  136. package/dist/chunks/{chunk-WMJ2AVQQ.js → chunk-R5F6CHW2.js} +34 -18
  137. package/dist/chunks/chunk-R5F6CHW2.js.map +7 -0
  138. package/dist/chunks/chunk-S3IRPDSO.js +57 -0
  139. package/dist/chunks/chunk-S3IRPDSO.js.map +7 -0
  140. package/dist/chunks/{chunk-7BG5COXB.js → chunk-SVDHQUTM.js} +21 -4
  141. package/dist/chunks/chunk-SVDHQUTM.js.map +7 -0
  142. package/dist/chunks/{chunk-HG4DMARW.js → chunk-T5CU2GPZ.js} +116 -26
  143. package/dist/chunks/chunk-T5CU2GPZ.js.map +7 -0
  144. package/dist/chunks/{chunk-RIFG4HS6.js → chunk-TFFZVLR2.js} +141 -9
  145. package/dist/chunks/chunk-TFFZVLR2.js.map +7 -0
  146. package/dist/chunks/{chunk-BUQZBG6O.js → chunk-U2UBUKNQ.js} +136 -136
  147. package/dist/chunks/chunk-U2UBUKNQ.js.map +7 -0
  148. package/dist/chunks/chunk-U366I5K2.js +363 -0
  149. package/dist/chunks/chunk-U366I5K2.js.map +7 -0
  150. package/dist/chunks/{chunk-4NF3S3NM.js → chunk-UTOBAZ5T.js} +1 -1
  151. package/dist/chunks/chunk-UTOBAZ5T.js.map +7 -0
  152. package/dist/chunks/chunk-V73NIH6B.js +127 -0
  153. package/dist/chunks/chunk-V73NIH6B.js.map +7 -0
  154. package/dist/chunks/{chunk-PN4EKNRE.js → chunk-VON4TSO3.js} +132 -12
  155. package/dist/chunks/chunk-VON4TSO3.js.map +7 -0
  156. package/dist/chunks/{chunk-5ZJV4LAX.js → chunk-VPRJOD4Y.js} +4 -4
  157. package/dist/chunks/{chunk-FDIEQEXS.js → chunk-VSDUSNIA.js} +4 -4
  158. package/dist/chunks/chunk-VSDUSNIA.js.map +7 -0
  159. package/dist/chunks/{chunk-RG22JKIC.js → chunk-W7X4XEQU.js} +2 -2
  160. package/dist/chunks/{chunk-LV4IT75S.js → chunk-WLLXKS6I.js} +2 -2
  161. package/dist/chunks/chunk-WOLUDZVR.js +197 -0
  162. package/dist/chunks/chunk-WOLUDZVR.js.map +7 -0
  163. package/dist/chunks/{chunk-YVDBHS4C.js → chunk-WREA4RNR.js} +3 -3
  164. package/dist/chunks/{chunk-QE2JFB7F.js → chunk-WYUV6WL3.js} +16 -6
  165. package/dist/chunks/chunk-WYUV6WL3.js.map +7 -0
  166. package/dist/chunks/{chunk-NGGI6LDC.js → chunk-X2TRSE7D.js} +2 -2
  167. package/dist/chunks/{chunk-VRAGOMN4.js → chunk-YRDCJZZW.js} +34 -1
  168. package/dist/chunks/chunk-YRDCJZZW.js.map +7 -0
  169. package/dist/chunks/{chunk-CC63CY6R.js → chunk-YYSZBD7S.js} +17 -261
  170. package/dist/chunks/chunk-YYSZBD7S.js.map +7 -0
  171. package/dist/chunks/{chunk-A4VP7HDF.js → chunk-ZLNJDTCN.js} +2 -2
  172. package/dist/chunks/{chunk-G4CSXNBT.js → chunk-ZXKYU6CH.js} +42 -5
  173. package/dist/chunks/chunk-ZXKYU6CH.js.map +7 -0
  174. package/dist/cli/decisions.d.ts +8 -0
  175. package/dist/cli/decisions.d.ts.map +1 -0
  176. package/dist/cli/decisions.js +131 -0
  177. package/dist/cli/decisions.js.map +7 -0
  178. package/dist/cli/index.d.ts +3 -0
  179. package/dist/cli/index.d.ts.map +1 -0
  180. package/dist/cli/index.js +56 -0
  181. package/dist/cli/index.js.map +7 -0
  182. package/dist/cli/mesh.d.ts +3 -0
  183. package/dist/cli/mesh.d.ts.map +1 -0
  184. package/dist/cli/mesh.js +126 -0
  185. package/dist/cli/mesh.js.map +7 -0
  186. package/dist/commands/fabric.d.ts.map +1 -1
  187. package/dist/compaction/carry.d.ts +23 -0
  188. package/dist/compaction/carry.d.ts.map +1 -0
  189. package/dist/compaction/hook.d.ts +9 -0
  190. package/dist/compaction/hook.d.ts.map +1 -1
  191. package/dist/compaction/hook.js +6 -6
  192. package/dist/compaction/orphan-repair.d.ts +11 -0
  193. package/dist/compaction/orphan-repair.d.ts.map +1 -0
  194. package/dist/compaction/orphan-repair.js +75 -0
  195. package/dist/compaction/orphan-repair.js.map +7 -0
  196. package/dist/compaction/owner.d.ts +26 -0
  197. package/dist/compaction/owner.d.ts.map +1 -0
  198. package/dist/compaction/owner.js +26 -0
  199. package/dist/compaction/owner.js.map +7 -0
  200. package/dist/compaction/pressure.d.ts +19 -0
  201. package/dist/compaction/pressure.d.ts.map +1 -0
  202. package/dist/compaction/render.d.ts +4 -0
  203. package/dist/compaction/render.d.ts.map +1 -1
  204. package/dist/compaction/threshold.d.ts +6 -1
  205. package/dist/compaction/threshold.d.ts.map +1 -1
  206. package/dist/components/configuration.js +6 -6
  207. package/dist/components/provider-component.d.ts +1 -1
  208. package/dist/components/provider-component.d.ts.map +1 -1
  209. package/dist/config.d.ts +45 -2
  210. package/dist/config.d.ts.map +1 -1
  211. package/dist/core/action-registry.d.ts +5 -1
  212. package/dist/core/action-registry.d.ts.map +1 -1
  213. package/dist/core/action-registry.js +8 -8
  214. package/dist/core/approval-controller.d.ts +5 -1
  215. package/dist/core/approval-controller.d.ts.map +1 -1
  216. package/dist/core/approval-overrides.d.ts +11 -0
  217. package/dist/core/approval-overrides.d.ts.map +1 -0
  218. package/dist/core/atomic-write.d.ts +77 -0
  219. package/dist/core/atomic-write.d.ts.map +1 -1
  220. package/dist/core/compact-controller.d.ts +8 -0
  221. package/dist/core/compact-controller.d.ts.map +1 -1
  222. package/dist/core/file-lock.d.ts.map +1 -1
  223. package/dist/core/foreground-tools.d.ts +45 -0
  224. package/dist/core/foreground-tools.d.ts.map +1 -0
  225. package/dist/core/provider-bindings.d.ts +10 -1
  226. package/dist/core/provider-bindings.d.ts.map +1 -1
  227. package/dist/core/provider-operations.js.map +1 -1
  228. package/dist/core/tool-ownership.d.ts +18 -2
  229. package/dist/core/tool-ownership.d.ts.map +1 -1
  230. package/dist/decisions/command.d.ts +5 -0
  231. package/dist/decisions/command.d.ts.map +1 -0
  232. package/dist/decisions/command.js +74 -0
  233. package/dist/decisions/command.js.map +7 -0
  234. package/dist/decisions/host.d.ts +24 -0
  235. package/dist/decisions/host.d.ts.map +1 -0
  236. package/dist/decisions/store.d.ts +147 -0
  237. package/dist/decisions/store.d.ts.map +1 -0
  238. package/dist/durable.d.ts +38 -0
  239. package/dist/durable.d.ts.map +1 -0
  240. package/dist/durable.js +274 -0
  241. package/dist/durable.js.map +7 -0
  242. package/dist/entropy/index.js +10 -9
  243. package/dist/execution-service.d.ts +41 -1
  244. package/dist/execution-service.d.ts.map +1 -1
  245. package/dist/extension-bootstrap.d.ts +7 -0
  246. package/dist/extension-bootstrap.d.ts.map +1 -0
  247. package/dist/extension-bootstrap.js +51 -0
  248. package/dist/extension-bootstrap.js.map +7 -0
  249. package/dist/extension.d.ts +8 -0
  250. package/dist/extension.d.ts.map +1 -0
  251. package/dist/fabric-exec-tool.d.ts.map +1 -1
  252. package/dist/fabric-runtime-state.d.ts +8 -0
  253. package/dist/fabric-runtime-state.d.ts.map +1 -1
  254. package/dist/fabric-runtime-state.js +2432 -346
  255. package/dist/fabric-runtime-state.js.map +4 -4
  256. package/dist/fabric-state.d.ts +22 -0
  257. package/dist/fabric-state.d.ts.map +1 -1
  258. package/dist/host-compatibility.d.ts +1 -1
  259. package/dist/host-compatibility.d.ts.map +1 -1
  260. package/dist/index.d.ts +5 -6
  261. package/dist/index.d.ts.map +1 -1
  262. package/dist/index.js +68 -6250
  263. package/dist/index.js.map +4 -4
  264. package/dist/jev/observation.js +5 -5
  265. package/dist/jev-fabric/bridge.d.ts +15 -0
  266. package/dist/jev-fabric/bridge.d.ts.map +1 -1
  267. package/dist/jev-fabric/client.js +1 -1
  268. package/dist/jev-fabric/client.js.map +2 -2
  269. package/dist/jev-fabric/operations.d.ts +2 -0
  270. package/dist/jev-fabric/operations.d.ts.map +1 -1
  271. package/dist/jev-fabric/operations.js +1 -1
  272. package/dist/jev-fabric/operations.js.map +2 -2
  273. package/dist/jev-fabric/resolve.js +1 -1
  274. package/dist/jev-fabric/resolve.js.map +2 -2
  275. package/dist/jev.js +9 -9
  276. package/dist/lifecycle/types.d.ts.map +1 -1
  277. package/dist/memory/client.d.ts +3 -0
  278. package/dist/memory/client.d.ts.map +1 -1
  279. package/dist/memory/digest.js +2 -2
  280. package/dist/memory/discovery.js +6 -6
  281. package/dist/memory/expand-service.d.ts.map +1 -1
  282. package/dist/memory/file-worker.d.ts.map +1 -1
  283. package/dist/memory/file-worker.js +10 -9
  284. package/dist/memory/file-worker.js.map +2 -2
  285. package/dist/memory/host-source.d.ts +2 -1
  286. package/dist/memory/host-source.d.ts.map +1 -1
  287. package/dist/memory/normalize.js +5 -5
  288. package/dist/memory/portable.d.ts +3 -1
  289. package/dist/memory/portable.d.ts.map +1 -1
  290. package/dist/memory/request-cache.d.ts +4 -2
  291. package/dist/memory/request-cache.d.ts.map +1 -1
  292. package/dist/memory/request-context.d.ts +3 -0
  293. package/dist/memory/request-context.d.ts.map +1 -1
  294. package/dist/memory/search.js +7 -7
  295. package/dist/memory/worker-provider.d.ts.map +1 -1
  296. package/dist/memory/worker-provider.js +10 -10
  297. package/dist/memory.js +14 -13
  298. package/dist/memory.js.map +2 -2
  299. package/dist/mesh/grants.d.ts +86 -0
  300. package/dist/mesh/grants.d.ts.map +1 -0
  301. package/dist/mesh/store.d.ts +89 -0
  302. package/dist/mesh/store.d.ts.map +1 -1
  303. package/dist/programs/host.d.ts +22 -0
  304. package/dist/programs/host.d.ts.map +1 -0
  305. package/dist/programs/host.js +171 -0
  306. package/dist/programs/host.js.map +7 -0
  307. package/dist/programs/source.d.ts +16 -0
  308. package/dist/programs/source.d.ts.map +1 -0
  309. package/dist/programs/store.d.ts +81 -0
  310. package/dist/programs/store.d.ts.map +1 -0
  311. package/dist/protocol.d.ts +153 -0
  312. package/dist/protocol.d.ts.map +1 -1
  313. package/dist/protocol.js +15 -1
  314. package/dist/providers/agents-actions.d.ts.map +1 -1
  315. package/dist/providers/agents-message-router.d.ts.map +1 -1
  316. package/dist/providers/agents-progress.d.ts.map +1 -1
  317. package/dist/providers/agents-provider.d.ts +3 -0
  318. package/dist/providers/agents-provider.d.ts.map +1 -1
  319. package/dist/providers/cache-provider.d.ts +1 -1
  320. package/dist/providers/cache-provider.d.ts.map +1 -1
  321. package/dist/providers/compact-provider.d.ts +13 -1
  322. package/dist/providers/compact-provider.d.ts.map +1 -1
  323. package/dist/providers/decisions-provider.d.ts +17 -0
  324. package/dist/providers/decisions-provider.d.ts.map +1 -0
  325. package/dist/providers/jev-provider.js +9 -9
  326. package/dist/providers/memory-provider.d.ts.map +1 -1
  327. package/dist/providers/memory-provider.js +9 -9
  328. package/dist/providers/mesh-provider.d.ts +4 -0
  329. package/dist/providers/mesh-provider.d.ts.map +1 -1
  330. package/dist/providers/pi-native-mcp.d.ts.map +1 -1
  331. package/dist/providers/pi-tools-provider.d.ts.map +1 -1
  332. package/dist/providers/programs-provider.d.ts +18 -0
  333. package/dist/providers/programs-provider.d.ts.map +1 -0
  334. package/dist/providers/state-provider.d.ts +4 -1
  335. package/dist/providers/state-provider.d.ts.map +1 -1
  336. package/dist/providers/thinking-provider.d.ts +15 -0
  337. package/dist/providers/thinking-provider.d.ts.map +1 -0
  338. package/dist/residency/actor-client.js +3 -3
  339. package/dist/residency/client.d.ts.map +1 -1
  340. package/dist/residency/host.d.ts +21 -0
  341. package/dist/residency/host.d.ts.map +1 -1
  342. package/dist/residency/host.js +28 -22
  343. package/dist/residency/launcher-owner.d.ts +2 -0
  344. package/dist/residency/launcher-owner.d.ts.map +1 -1
  345. package/dist/residency/launcher.js +35 -20
  346. package/dist/residency/launcher.js.map +3 -3
  347. package/dist/residency/pi-entry.js +26 -22
  348. package/dist/residency/pi-entry.js.map +1 -1
  349. package/dist/residency/protocol.d.ts +12 -2
  350. package/dist/residency/protocol.d.ts.map +1 -1
  351. package/dist/runners.d.ts +9 -0
  352. package/dist/runners.d.ts.map +1 -0
  353. package/dist/runners.js +182 -0
  354. package/dist/runners.js.map +7 -0
  355. package/dist/runtime/core-override-guest-types.js +2 -2
  356. package/dist/runtime/cpython-child-source.d.ts.map +1 -1
  357. package/dist/runtime/cpython-runtime.d.ts.map +1 -1
  358. package/dist/runtime/cpython-runtime.js +35 -7
  359. package/dist/runtime/cpython-runtime.js.map +2 -2
  360. package/dist/runtime/deadline-pause.d.ts +26 -0
  361. package/dist/runtime/deadline-pause.d.ts.map +1 -0
  362. package/dist/runtime/guest-types.d.ts +1 -1
  363. package/dist/runtime/guest-types.d.ts.map +1 -1
  364. package/dist/runtime/guest-types.js +1 -1
  365. package/dist/runtime/kernel.d.ts +3 -0
  366. package/dist/runtime/kernel.d.ts.map +1 -1
  367. package/dist/runtime/monty-runtime.d.ts.map +1 -1
  368. package/dist/runtime/monty-runtime.js +33 -12
  369. package/dist/runtime/monty-runtime.js.map +2 -2
  370. package/dist/runtime/node-process-runtime.d.ts.map +1 -1
  371. package/dist/runtime/node-process-runtime.js +4 -3
  372. package/dist/runtime/orchestration.d.ts.map +1 -1
  373. package/dist/runtime/quickjs-runtime.d.ts.map +1 -1
  374. package/dist/runtime/quickjs-runtime.js +2 -1
  375. package/dist/runtime/typescript-kernel.js +8 -7
  376. package/dist/runtime/typescript-kernel.js.map +1 -1
  377. package/dist/runtime-state-builtins.d.ts.map +1 -1
  378. package/dist/schema/controller.d.ts.map +1 -1
  379. package/dist/schema/policy.d.ts.map +1 -1
  380. package/dist/scope.d.ts +69 -0
  381. package/dist/scope.d.ts.map +1 -0
  382. package/dist/scope.js +37 -0
  383. package/dist/scope.js.map +7 -0
  384. package/dist/speculation/eligibility.d.ts.map +1 -1
  385. package/dist/speculation/python-scanner.js +1 -1
  386. package/dist/speculation/python-scanner.js.map +2 -2
  387. package/dist/speculation/scanner.js +1 -1
  388. package/dist/speculation/scanner.js.map +2 -2
  389. package/dist/state/binding.d.ts +17 -0
  390. package/dist/state/binding.d.ts.map +1 -0
  391. package/dist/state/store.d.ts +8 -2
  392. package/dist/state/store.d.ts.map +1 -1
  393. package/dist/state/types.d.ts +23 -2
  394. package/dist/state/types.d.ts.map +1 -1
  395. package/dist/storage/retention.d.ts +7 -0
  396. package/dist/storage/retention.d.ts.map +1 -1
  397. package/dist/storage/scratch.d.ts.map +1 -1
  398. package/dist/thinking-control.d.ts +64 -0
  399. package/dist/thinking-control.d.ts.map +1 -0
  400. package/dist/thinking-control.js +15 -0
  401. package/dist/thinking-control.js.map +7 -0
  402. package/dist/thinking.d.ts +61 -0
  403. package/dist/thinking.d.ts.map +1 -1
  404. package/dist/topology/control-plane.d.ts +13 -0
  405. package/dist/topology/control-plane.d.ts.map +1 -1
  406. package/dist/topology/participant-directory.d.ts +2 -0
  407. package/dist/topology/participant-directory.d.ts.map +1 -1
  408. package/dist/topology/provider-participants.d.ts +72 -0
  409. package/dist/topology/provider-participants.d.ts.map +1 -0
  410. package/dist/topology/records.d.ts.map +1 -1
  411. package/dist/topology/types.d.ts +13 -3
  412. package/dist/topology/types.d.ts.map +1 -1
  413. package/dist/type-error-guidance.js +170 -0
  414. package/dist/type-error-guidance.js.map +7 -0
  415. package/dist/ui/controller.d.ts.map +1 -1
  416. package/dist/ui/conversation-chrome.d.ts +2 -0
  417. package/dist/ui/conversation-chrome.d.ts.map +1 -1
  418. package/dist/ui/conversation-chrome.js +1 -1
  419. package/dist/ui/conversation-latest.d.ts +10 -0
  420. package/dist/ui/conversation-latest.d.ts.map +1 -0
  421. package/dist/ui/conversation-native-reader.js +2 -1
  422. package/dist/ui/conversation-native-reader.js.map +1 -1
  423. package/dist/ui/conversation-render.d.ts +2 -1
  424. package/dist/ui/conversation-render.d.ts.map +1 -1
  425. package/dist/ui/conversation-scrollbar.d.ts +22 -0
  426. package/dist/ui/conversation-scrollbar.d.ts.map +1 -0
  427. package/dist/ui/conversation-selection.d.ts +2 -2
  428. package/dist/ui/conversation-selection.d.ts.map +1 -1
  429. package/dist/ui/conversation-targets.d.ts.map +1 -1
  430. package/dist/ui/conversation-targets.js +2 -2
  431. package/dist/ui/conversation.d.ts +3 -0
  432. package/dist/ui/conversation.d.ts.map +1 -1
  433. package/dist/ui/conversation.js +253 -34
  434. package/dist/ui/conversation.js.map +4 -4
  435. package/dist/ui/dashboard-fabric-graph.d.ts.map +1 -1
  436. package/dist/ui/dashboard.js +14 -15
  437. package/dist/ui/dashboard.js.map +2 -2
  438. package/dist/ui/image-overlays.d.ts +16 -0
  439. package/dist/ui/image-overlays.d.ts.map +1 -0
  440. package/dist/ui/image-overlays.js +10 -0
  441. package/dist/ui/image-overlays.js.map +7 -0
  442. package/dist/ui/kitty-viewport.d.ts +24 -0
  443. package/dist/ui/kitty-viewport.d.ts.map +1 -0
  444. package/dist/ui/retention.d.ts +14 -0
  445. package/dist/ui/retention.d.ts.map +1 -0
  446. package/dist/ui/settings-sections-execution.d.ts.map +1 -1
  447. package/dist/ui/settings.d.ts.map +1 -1
  448. package/dist/ui/settings.js +27 -16
  449. package/dist/ui/settings.js.map +2 -2
  450. package/dist/ui/transcript.d.ts +2 -1
  451. package/dist/ui/transcript.d.ts.map +1 -1
  452. package/dist/ui/types.d.ts +2 -1
  453. package/dist/ui/types.d.ts.map +1 -1
  454. package/dist/ui/widget.d.ts +4 -2
  455. package/dist/ui/widget.d.ts.map +1 -1
  456. package/dist/verified/generated/authority-kernel.js +1 -1
  457. package/dist/verified/generated/kernel.js +1 -1
  458. package/dist/verified/generated/lifecycle-kernel.js +1 -1
  459. package/dist/verified/generated/manifest.json +7 -7
  460. package/dist/verified/generated/provider-kernel.js +1 -1
  461. package/dist/verified/generated/storage-kernel.js +1 -1
  462. package/dist/worker/options.d.ts.map +1 -1
  463. package/dist/worker/options.js +14 -0
  464. package/dist/worker/options.js.map +2 -2
  465. package/dist/worker/questions.d.ts +46 -0
  466. package/dist/worker/questions.d.ts.map +1 -0
  467. package/dist/worker/questions.js +87 -0
  468. package/dist/worker/questions.js.map +7 -0
  469. package/dist/worker/result.d.ts +3 -0
  470. package/dist/worker/result.d.ts.map +1 -0
  471. package/dist/worker/result.js +7493 -0
  472. package/dist/worker/result.js.map +7 -0
  473. package/dist/worker/run-record.js +10 -113
  474. package/dist/worker/run-record.js.map +3 -3
  475. package/dist/worker/startup.d.ts +8 -0
  476. package/dist/worker/startup.d.ts.map +1 -0
  477. package/dist/worker.js +111 -22
  478. package/dist/worker.js.map +4 -4
  479. package/docs/agents.md +197 -3
  480. package/docs/architecture.md +8 -1
  481. package/docs/audit-trace.md +36 -1
  482. package/docs/background-tasks.md +25 -1
  483. package/docs/certification.md +1 -1
  484. package/docs/compaction.md +64 -0
  485. package/docs/components.md +1 -0
  486. package/docs/configuration.md +105 -10
  487. package/docs/decisions.md +144 -0
  488. package/docs/durable-pi.md +186 -0
  489. package/docs/interface.md +10 -1
  490. package/docs/kitty-images.md +89 -0
  491. package/docs/licenses/typebox-mit.txt +23 -0
  492. package/docs/memory-recall.md +5 -3
  493. package/docs/programmatic-compaction.md +67 -11
  494. package/docs/programs.md +137 -0
  495. package/docs/provider-capabilities.md +23 -1
  496. package/docs/providers.md +158 -0
  497. package/docs/residency-runtime.md +64 -0
  498. package/docs/schema-enforcement.md +5 -3
  499. package/docs/shell-composition.md +6 -6
  500. package/docs/skills.md +2 -1
  501. package/docs/speculation.md +2 -1
  502. package/docs/state-layer.md +26 -4
  503. package/docs/thinking.md +48 -0
  504. package/docs/verified-kernels.md +1 -1
  505. package/package.json +48 -12
  506. package/scripts/test-verified-kernels.mjs +1 -1
  507. package/scripts/verified-kernels.mjs +1 -1
  508. package/skillsets/python/fabric-exec/SKILL.md +2 -2
  509. package/skillsets/python/fabric-exec/references/agents.md +9 -4
  510. package/skillsets/python/fabric-exec/references/mesh.md +9 -0
  511. package/skillsets/python/fabric-graph/SKILL.md +109 -0
  512. package/skillsets/python/fabric-guide/SKILL.md +2 -1
  513. package/skillsets/typescript/fabric-exec/SKILL.md +20 -2
  514. package/skillsets/typescript/fabric-exec/references/agents.md +10 -4
  515. package/skillsets/typescript/fabric-exec/references/mesh.md +10 -0
  516. package/skillsets/typescript/fabric-graph/SKILL.md +112 -0
  517. package/skillsets/typescript/fabric-guide/SKILL.md +2 -1
  518. package/skillsets/typescript/fabric-workflow/SKILL.md +1 -1
  519. package/dist/chunks/chunk-4NF3S3NM.js.map +0 -7
  520. package/dist/chunks/chunk-5VTBHJN3.js.map +0 -7
  521. package/dist/chunks/chunk-74BA4VSX.js.map +0 -7
  522. package/dist/chunks/chunk-7BG5COXB.js.map +0 -7
  523. package/dist/chunks/chunk-AYBIR4YV.js.map +0 -7
  524. package/dist/chunks/chunk-B5D6GA77.js.map +0 -7
  525. package/dist/chunks/chunk-BEJF2JX2.js.map +0 -7
  526. package/dist/chunks/chunk-BUQZBG6O.js.map +0 -7
  527. package/dist/chunks/chunk-CC63CY6R.js.map +0 -7
  528. package/dist/chunks/chunk-FDIEQEXS.js.map +0 -7
  529. package/dist/chunks/chunk-G4CSXNBT.js.map +0 -7
  530. package/dist/chunks/chunk-HG4DMARW.js.map +0 -7
  531. package/dist/chunks/chunk-KAD7UWT2.js +0 -99
  532. package/dist/chunks/chunk-KAD7UWT2.js.map +0 -7
  533. package/dist/chunks/chunk-MGWQOKBV.js +0 -30
  534. package/dist/chunks/chunk-MGWQOKBV.js.map +0 -7
  535. package/dist/chunks/chunk-PN4EKNRE.js.map +0 -7
  536. package/dist/chunks/chunk-PNDYFU64.js.map +0 -7
  537. package/dist/chunks/chunk-PWS2OXLV.js.map +0 -7
  538. package/dist/chunks/chunk-QE2JFB7F.js.map +0 -7
  539. package/dist/chunks/chunk-QETG2GVX.js.map +0 -7
  540. package/dist/chunks/chunk-RAO6TQFP.js.map +0 -7
  541. package/dist/chunks/chunk-RIFG4HS6.js.map +0 -7
  542. package/dist/chunks/chunk-TX6E5W7H.js.map +0 -7
  543. package/dist/chunks/chunk-VRAGOMN4.js.map +0 -7
  544. package/dist/chunks/chunk-W63E3WEO.js.map +0 -7
  545. package/dist/chunks/chunk-WMJ2AVQQ.js.map +0 -7
  546. package/dist/chunks/chunk-ZZ66L3W5.js.map +0 -7
  547. /package/dist/chunks/{chunk-57CMH4SW.js.map → chunk-7JU7Z4XQ.js.map} +0 -0
  548. /package/dist/chunks/{chunk-DUJ46TIP.js.map → chunk-ABJCSNZO.js.map} +0 -0
  549. /package/dist/chunks/{chunk-KP4ANT6L.js.map → chunk-C7EEG6SM.js.map} +0 -0
  550. /package/dist/chunks/{chunk-NHMICIEU.js.map → chunk-CCHZXF6K.js.map} +0 -0
  551. /package/dist/chunks/{chunk-5JN5AWNV.js.map → chunk-DZ4WN5XJ.js.map} +0 -0
  552. /package/dist/chunks/{chunk-7XJB2USB.js.map → chunk-LOLCTWJF.js.map} +0 -0
  553. /package/dist/chunks/{chunk-64O5L7EW.js.map → chunk-M6IRQ3QT.js.map} +0 -0
  554. /package/dist/chunks/{chunk-EPYLZWJV.js.map → chunk-OVBKQCYL.js.map} +0 -0
  555. /package/dist/chunks/{chunk-Z5Y65YBX.js.map → chunk-PYQM7KPL.js.map} +0 -0
  556. /package/dist/chunks/{chunk-DKVJREDI.js.map → chunk-QY7YK7M6.js.map} +0 -0
  557. /package/dist/chunks/{chunk-5ZJV4LAX.js.map → chunk-VPRJOD4Y.js.map} +0 -0
  558. /package/dist/chunks/{chunk-RG22JKIC.js.map → chunk-W7X4XEQU.js.map} +0 -0
  559. /package/dist/chunks/{chunk-LV4IT75S.js.map → chunk-WLLXKS6I.js.map} +0 -0
  560. /package/dist/chunks/{chunk-YVDBHS4C.js.map → chunk-WREA4RNR.js.map} +0 -0
  561. /package/dist/chunks/{chunk-NGGI6LDC.js.map → chunk-X2TRSE7D.js.map} +0 -0
  562. /package/dist/chunks/{chunk-A4VP7HDF.js.map → chunk-ZLNJDTCN.js.map} +0 -0
@@ -53,6 +53,16 @@ Monty is always sandboxed, including under schema enforce, and does not require
53
53
 
54
54
  Every raised deadline is capped by `executor.maxTimeoutMs` (default `900000`, i.e. 15 minutes: the former undocumented clamp, now explicit), which itself can be raised up to the hard implementation maximum of 24 hours. Values above a cap are visibly normalized down to the cap during config load and the effective values are shown in `/fabric` settings, never silently surprising. A per-invocation request or ref floor takes effect even when the ref is unknown to Fabric, so captured tools, MCP calls, and future host calls all run within an intentionally longer deadline without Fabric knowing their argument semantics. Existing `pi.bash` behavior (extending the deadline from an explicit `timeout` argument) is unchanged, and deadline expiry still cancels the active host call and any child process it owns.
55
55
 
56
+ `executor.humanWaitRefs` (default `["extensions.ask"]`) lists exact host-call refs (no wildcards) that wait for a person. While at least one such call is in flight, the program deadline is **paused**: a foreground question can wait as long as the person needs. When the last one settles, the program continues with the budget it had left, so guest work before and after the wait still counts. A host-call floor that arrives during the pause raises that remaining budget. Cancelling `fabric_exec` (Esc or an aborted signal) still stops the program and the pending call at once, and CPU-slice and memory limits are unchanged. Set `[]` to bound human waits by the normal deadline again:
57
+
58
+ ```json
59
+ {
60
+ "executor": {
61
+ "humanWaitRefs": ["extensions.ask"]
62
+ }
63
+ }
64
+ ```
65
+
56
66
  `executor.shellHangMs` (default `120000` / 2 minutes, max `600000` / 10 minutes, `0` disables) is a nested-shell wait budget, not a program deadline. When a `pi.bash` / `pi.powershell` await exceeds it, Fabric **settles the await successfully** (`ok: true`) with a still-running notice, pid, and live output path while the process keeps writing that file. `background: true` (alias `run_in_background`) detaches immediately with the same envelope. Inspect with `pi.read(logPath)` and stop by running `kill <pid>` through `pi.bash`. Do not poll. An explicit shell `timeout` remains a hard cap. **ctrl+b twice** spills early (tmux-safe); **ctrl+k** kills the waiting command. Session shutdown aborts leftover processes, except `durable: true` tasks, which detach to their jev-fabric store. Captured shell overrides normally keep their own execution semantics; an extension can opt into [Fabric-owned bash execution with middleware](shell-middleware.md) to preserve its environment/output filters while gaining the same background handling.
57
67
 
58
68
  `executor.jevFabric` configures the optional jev-fabric backend for [durable tasks](background-tasks.md#durable-tasks-through-jev-fabric) and [interactive sessions](shell-composition.md). `binary` (default `""`, also `"auto"`) picks your compatible install outside the workspace, then the bundled package; an explicit executable name or trusted absolute path (no shell arguments) is used or the call fails, never falling back. See [which jev-fabric](shell-composition.md#which-jev-fabric). `home` empty uses `JEV_FABRIC_HOME`, else `<cwd>/.jev-fabric-native`: the store other harnesses in the same project share by default. `timeoutMs` (default one hour, up to 24 hours) is a durable job's lifetime when the call gives no explicit `timeout`. Nothing runs or loads until the first `durable: true` call.
@@ -66,7 +76,7 @@ effective timeout = min(
66
76
  )
67
77
  ```
68
78
 
69
- where absent values do not participate. Orchestration programs (`agents.run` / `agents.wait` / `agents.ask`, `workflow.agent`, ...) keep their separate `agents.timeoutMs` floor, which is unaffected by `executor.maxTimeoutMs`.
79
+ where absent values do not participate, and time spent inside a `humanWaitRefs` call is not counted. Orchestration programs (`agents.run` / `agents.wait` / `agents.ask`, `workflow.agent`, ...) keep their separate `agents.timeoutMs` floor, which is unaffected by `executor.maxTimeoutMs`.
70
80
 
71
81
  ## Full reference
72
82
 
@@ -82,6 +92,7 @@ where absent values do not participate. Orchestration programs (`agents.run` / `
82
92
  "timeoutMs": 120000,
83
93
  "maxTimeoutMs": 900000,
84
94
  "hostCallTimeouts": {},
95
+ "humanWaitRefs": ["extensions.ask"],
85
96
  "shellHangMs": 120000,
86
97
  "memoryLimitBytes": 67108864,
87
98
  "maxOutputChars": 100000,
@@ -93,7 +104,9 @@ where absent values do not participate. Orchestration programs (`agents.run` / `
93
104
  "write": "allow",
94
105
  "execute": "allow",
95
106
  "network": "allow",
96
- "agent": "allow"
107
+ "agent": "allow",
108
+ "headless": "deny",
109
+ "headlessTimeoutMs": 300000
97
110
  },
98
111
  "capture": {
99
112
  "enabled": true,
@@ -114,6 +127,10 @@ where absent values do not participate. Orchestration programs (`agents.run` / `
114
127
  "fovea_impact": "read"
115
128
  }
116
129
  },
130
+ "foreground": {
131
+ "tools": [],
132
+ "maxTools": 4
133
+ },
117
134
  "mcp": {
118
135
  "enabled": true,
119
136
  "disableOAuth": true,
@@ -161,7 +178,9 @@ where absent values do not participate. Orchestration programs (`agents.run` / `
161
178
  "budgetUsd": 0,
162
179
  "maxTokensPerChild": 0,
163
180
  "sessionExport": true,
164
- "sessionExportDir": ""
181
+ "sessionExportDir": "",
182
+ "childQuestions": "cancel",
183
+ "childQuestionTimeoutMs": 600000
165
184
  },
166
185
  "components": [
167
186
  {
@@ -183,7 +202,10 @@ where absent values do not participate. Orchestration programs (`agents.run` / `
183
202
  "updateDebounceMs": 100
184
203
  },
185
204
  "compaction": {
186
- "engine": "fabric"
205
+ "engine": "fabric",
206
+ "outputReserveTokens": 0,
207
+ "pressureBands": { "warn": 0.6, "urgent": 0.8 },
208
+ "repairOrphans": true
187
209
  },
188
210
  "retention": {
189
211
  "orphanedTempRunMs": 21600000,
@@ -204,6 +226,9 @@ where absent values do not participate. Orchestration programs (`agents.run` / `
204
226
  "sources": [
205
227
  { "id": "laptop", "kind": "fs", "root": "/home/me/pi-archive" }
206
228
  ]
229
+ },
230
+ "trace": {
231
+ "assessment": false
207
232
  }
208
233
  }
209
234
  ```
@@ -224,6 +249,14 @@ Unknown definitions stay visible as waiting. They do not fail the Fabric runtime
224
249
 
225
250
  `speculation` configures opportunistic pre-launch of read-class calls while the model streams a `fabric_exec` program; see [speculative PTC](speculation.md) for the correctness contract. `speculation.enabled` (default `true`) masters the feature. `speculation.maxConcurrent` (1-32, default 4) caps in-flight speculative calls. `speculation.maxEntries` (1-1024, default 64) bounds retained unserved entries per turn. `speculation.maxBufferBytes` (64 KiB-64 MiB, default 2 MiB) caps the per-stream partial-argument buffer. `speculation.entryTtlMs` (5 s-30 min, default 180000) expires unserved entries. `speculation.mcpAllowlist` (default empty) enables Tier-B speculation of read-only MCP tools with `server.tool` or `server.*` patterns.
226
251
 
252
+ ## Thinking bounds
253
+
254
+ `thinking.bounds` (`{"min"?: level, "max"?: level}`, default `{}`) bounds every thinking level Fabric selects: [`thinking.set`](thinking.md), each child run's `thinking`, and the bounds a child inherits. Levels are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. An omitted end leaves that side to the active model's supported levels. Unknown keys, unknown level names, and `min` above `max` fail configuration loading. A Fabric child intersects this value with its parent's `PI_FABRIC_THINKING_BOUNDS` and never widens it.
255
+
256
+ ```json
257
+ { "thinking": { "bounds": { "min": "low", "max": "high" } } }
258
+ ```
259
+
227
260
  ## Prewalk executor
228
261
 
229
262
  `prewalk.enabled` defaults to `true` and is the persistent master switch. Turn it off under **Prewalk → Enabled** in `/fabric settings`, or run `/fabric prewalk --disable`; both save to project scope in a trusted project and global scope otherwise. Disabling also cancels any live arm. `/fabric prewalk --enable` turns it back on. `/fabric prewalk --off` only cancels the current arm for this session and does not change the saved master switch.
@@ -360,9 +393,31 @@ const result = await extensions.project_status({ verbose: true });
360
393
  return result.text;
361
394
  ```
362
395
 
363
- The result keeps `content`, exposes text content as `text`, and carries `details`, `structuredContent` when supplied, `isError`, `terminate`, and source provenance. On Pi 0.99, callable captures use native `ctx.executeTool()` with nested IDs, validation, middleware, and usage accounting. Shells and tools with `prepareArguments()` retain Fabric's adapted execution boundary to preserve scoped cwd, nonzero-exit settlement before redaction, and exactly-once preparation. Both paths use the owning extension's tool context and apply `tool_call`, `tool_result`, and `tool_execution_*` handlers. Tools withdrawn with native `exposure: "hidden"` are not captured.
396
+ The result keeps `content`, exposes text content as `text`, and carries `details`, `structuredContent` when supplied, `isError`, `terminate`, and source provenance. On Pi 1.0, callable captures use native `ctx.executeTool()` with nested IDs, validation, middleware, and usage accounting. Shells and tools with `prepareArguments()` retain Fabric's adapted execution boundary to preserve scoped cwd, nonzero-exit settlement before redaction, and exactly-once preparation. Both paths use the owning extension's tool context and apply `tool_call`, `tool_result`, and `tool_execution_*` handlers. Tools withdrawn with native `exposure: "hidden"` are not captured.
397
+
398
+ In full code mode and Schema enforce mode, `fabric_exec` is the only model-declared tool unless a [foreground policy](#foreground-tools) names others in full code mode. Pi 1.0 native `prepareLoadout` and per-request transcript projection hide all other declarations without removing tools from the native callable set. This includes native `codemode`, `tool_search`, MCP tools, and late registrations; `setActiveTools()` cannot open a second model-facing path. Inside Fabric, `pi.read`, `pi.bash`, and other built-ins still route through captured overrides when present. `extensions.read` exposes the override's native result shape. Native MCP tools are also callable by their captured names, for example `extensions.mcp__server__tool(...)`.
399
+
400
+ ### Foreground tools
401
+
402
+ Some extension tools only work as a direct model turn: a question to the human, a turn-steering control, a context or skill loader. `foreground` keeps a short list of them declared beside `fabric_exec` in full code mode:
403
+
404
+ ```json
405
+ {
406
+ "foreground": {
407
+ "tools": [
408
+ { "name": "ask_user_question", "owner": "pi-ask", "reason": "human-input" }
409
+ ],
410
+ "maxTools": 4
411
+ }
412
+ }
413
+ ```
364
414
 
365
- In full code mode and Schema enforce mode, `fabric_exec` is the only model-declared tool. Pi 0.99 native `prepareLoadout` and per-request transcript projection hide all other declarations without removing tools from the native callable set. This includes native `codemode`, `tool_search`, MCP tools, and late registrations; `setActiveTools()` cannot open a second model-facing path. Inside Fabric, `pi.read`, `pi.bash`, and other built-ins still route through captured overrides when present. `extensions.read` exposes the override's native result shape. Native MCP tools are also callable by their captured names, for example `extensions.mcp__server__tool(...)`.
415
+ - Each entry needs `name`, `owner` (free text naming the extension that registers the tool), and `reason`: `turn-steering`, `human-input`, `context-control`, or `skill-loading`. At most 64 entries; `maxTools` is an integer from 0 to 8 (default 4). A malformed entry or `fabric_exec` as a name fails config loading.
416
+ - Fabric resolves the list in order against the live registry. It refuses Pi core tools (`read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`), other Pi built-ins such as native `codemode`, unregistered or `hidden` tools, inactive tools, tools outside an inherited child tool allowlist, duplicates, and entries beyond `maxTools`.
417
+ - Schema enforce mode and managed hosts refuse the whole policy: only `fabric_exec` stays declared. Orchestration-only mode already declares Pi's active set, so the policy has no effect there.
418
+ - Refusals are never silent. Fabric shows one warning per session (or logs it without a UI), and `/fabric status` lists the declared and refused foreground tools with each reason.
419
+ - A foreground tool keeps its program path: it stays callable as `extensions.<name>`. A direct model call runs Pi's `tool_call` hooks and Fabric's approval policy with the same ref (`extensions.<name>`), the same `capture.risks` class, and the same `approvals.actions` override as the program call.
420
+ - The declared foreground set is part of the prompt-cache fence beside active tool names, and the [tool placement query](providers.md#tool-placement-query) reports these tools as `model` and lists them in `programCallable`.
366
421
 
367
422
  A compatible exact-name core override is an additive extension of its existing `pi.<name>` slot. In effective full-code execution (including Schema enforce mode, which treats execution as full-code even when `fullCodeMode` is false), the current override schema contributes a bounded, schema-derived object overload without replacing Fabric's built-in positional, bare-string, shorthand, or alias forms. Fabric keeps each slot's established normalized result contract (`string` for read-like tools and `{ ok, output, details }` for bash/edit/write). The registry still validates the normalized arguments authoritatively; Fabric does not prove that an override schema is a superset of the built-in schema. Schema enforce mode still applies its host gate: read-like core refs remain available, while protected mutations and external effects are blocked or must use the schema transaction path. An override's `promptSnippet` and `promptGuidelines`, when present, are appended as guidance for the corresponding `pi.<name>` identity and are not advertised as a second extension tool. Registration, replacement, reload, and removal are observed on the next execution and prompt build; no generated declaration or prompt state is persisted. Generated overloads widen the known numeric fields (`offset`, `limit`, `timeout`, `context`) to `number | string`, matching built-in runtime normalization; an override with a stricter numeric schema still rejects the string form at registry validation, so read the error and retry. Each generated overload takes a single object argument; the built-in two-argument signature such as `pi.read(args, options?)` remains available from the base slot unchanged.
368
423
 
@@ -376,6 +431,26 @@ Fabric risk classes are `read`, `write`, `execute`, `network`, and `agent`. Appr
376
431
  - Extension tool names appear in the prompt as a names-only roster; descriptions and schemas are resolved on demand via `tools.list` / `tools.search` / `tools.describe` before first use.
377
432
  - An `ask` policy emits a warning notification and opens an explicit **Allow once** / **Allow for this session** / **Deny** permission prompt. These options match Claude-style approval scopes. **Allow once** authorizes only the requested action. **Allow for this session** keeps that risk class authorized until the current Pi session ends. The TUI uses an inline wizard. RPC clients receive the equivalent `select` dialog.
378
433
  - Fabric serializes concurrent requests so a one-time approval never silently widens to sibling calls. Session-wide grants apply to native calls and to `fabric_exec`. Escape, dismissal, unavailable interactive UI, and session restart all fail closed.
434
+ - `approvals.headless` (default `"deny"`) chooses what an approval does without an interactive UI. `"decision"` raises a durable user-held approval decision for `fabric_exec` actions and waits up to `approvals.headlessTimeoutMs` (default `300000`, bounded to 1 s..24 h). Only an explicit approve answer from `/fabric decisions` or `pi-fabric decisions answer` runs the action once; deny, cancel, expiry, and abort deny it. Any other value keeps `"deny"`. See [durable decisions](decisions.md#headless-approvals).
435
+
436
+ ### Per-action approval overrides
437
+
438
+ `approvals.actions` overrides the risk-class mode for individual actions (default: none):
439
+
440
+ ```json
441
+ {
442
+ "approvals": {
443
+ "write": "allow",
444
+ "actions": {
445
+ "delegate.*": "ask",
446
+ "delegate.status": "allow",
447
+ "pi.bash": "deny"
448
+ }
449
+ }
450
+ }
451
+ ```
452
+
453
+ Keys are an exact ref (`provider.action`, including multi-segment refs such as `mcp.github.search`) or a provider wildcard (`provider.*`). Values are `allow`, `ask`, or `deny`. An exact key beats a wildcard, which beats the risk-class mode. Other wildcard forms, unknown values, and more than 256 entries are configuration errors; Fabric never drops them silently. Overrides apply to every approval path keyed by a ref: actions inside `fabric_exec`, top-level native tools (`pi.<tool>` for Pi built-ins, `extensions.<tool>` otherwise), and Jev program observation. `deny` is absolute: inherited child risk grants and **Allow for this session** cannot lift it. `allow` and `ask` replace the risk-class mode and otherwise keep its semantics, including session grants for `ask`. Speculative prefetch only considers refs whose effective mode is `allow`. Overrides do not bypass Schema enforce or other host gates.
379
454
 
380
455
  ### Auto approval mode
381
456
 
@@ -432,7 +507,7 @@ Authentication uses `/login jev`/`TYPESAFE_API_KEY` on the TypeSafe route, the e
432
507
  Fabric clears inactive run artifacts by age. It never truncates active JSONL files. The defaults are:
433
508
 
434
509
  - `retention.orphanedTempRunMs`: reclaim a managed temporary run root six hours after a sweep **first notices** its owner is dead, provided its contents and descendant liveness can be verified. Live owners/descendants are preserved. Closed, shutdown-confirmed incomplete runs use the same grace from close.
435
- - `retention.oneShotRunMs`: retain terminal one-shot agent run artifacts for 24 hours. An explicit `agents.cleanup()` may remove them sooner. Graceful shutdown with `agents.retainRuns: true` marks managed roots closed; empty roots are removed immediately. `retainRuns: false` requests deletion after child transports stop, including for managed temporary roots.
510
+ - `retention.oneShotRunMs`: retain terminal one-shot agent run artifacts for 24 hours. An explicit `agents.cleanup()` may remove them sooner. Graceful shutdown with `agents.retainRuns: true` marks managed roots closed; empty roots are removed immediately. `retainRuns: false` requests deletion after child transports stop, including for managed temporary roots. Inherited nested roots belong to the enclosing agent run: a child manager stops its session children but leaves their terminal status and transcripts for that run's cleanup/retention or the root-session shutdown.
436
511
  - `retention.actorRunArchiveMs`: retain terminal actor run archives for seven days. Fabric always preserves the latest run for each actor.
437
512
 
438
513
  Run housekeeping begins on actual agent storage use (not manager startup), continues during use, and runs best-effort on close. It never applies cache pressure to agent runs or truncates their JSONL/actor `session.jsonl` files. Caller-owned run roots retain their existing explicit-cleanup semantics. Symlink roots/markers, wrong-uid files, malformed ownership, unknown contents, and unverifiable incomplete descendants are preserved. `/fabric settings` exposes all three values under **Retention**. Changing them requires `/fabric reload`.
@@ -449,12 +524,14 @@ Reader checkpoints are lossless live state: they are **never pressure-evicted**.
449
524
 
450
525
  ## Agents
451
526
 
452
- `agents.runner` selects the default harness: `"pi"`, `"claude"`, or `"veda"`. `agents.model` is the optional Pi `provider/id` override. `agents.claude.model` is the optional canonical Claude runtime key. `agents.claude.binary` defaults to `claude`. You can supply an absolute path or a wrapper. `PI_FABRIC_CLAUDE_BINARY` overrides it for the current process. `/fabric settings` enumerates Claude models from that binary in the background and stores the two runner defaults independently. `agents.modelAdmission` defaults to `strict`: a Pi child run fails when the model it reports after selection differs from the requested key. Set it to `permissive` when a virtual provider key (for example a `pi-multiprovider` entry) resolves to a concrete backend at stream time; Fabric then records the reported attribution and continues, including when a later assistant frame names that backend. Permissive admission still fails a child that reports no model or starts work before admission.
527
+ `agents.runner` selects the default harness: `"pi"`, `"claude"`, `"veda"`, or the id of a runner registered through `pi-fabric/runners` ([custom runners](agents.md#custom-runners)). A well-formed id that no extension registers is kept, and launches fail closed until the runner is registered. Before the first turn of each session, Fabric warns once when the configured runner is still unregistered, suggests a close built-in or registered id for likely typos, and lists the registered runners. Malformed ids fall back to `"pi"`. `agents.model` is the optional Pi `provider/id` override. `agents.claude.model` is the optional canonical Claude runtime key. `agents.claude.binary` defaults to `claude`. You can supply an absolute path or a wrapper. `PI_FABRIC_CLAUDE_BINARY` overrides it for the current process. `/fabric settings` enumerates Claude models from that binary in the background and stores the two runner defaults independently. `agents.modelAdmission` defaults to `strict`: a Pi child run fails when the model it reports after selection differs from the requested key. Set it to `permissive` when a virtual provider key (for example a `pi-multiprovider` entry) resolves to a concrete backend at stream time; Fabric then records the reported attribution and continues, including when a later assistant frame names that backend. Permissive admission still fails a child that reports no model or starts work before admission.
453
528
 
454
529
  The `veda` runner drives the [Veda CLI](https://github.com/kennyfrc/veda) as the child harness. `agents.veda.binary` defaults to `veda`. An absolute path or wrapper works, and `PI_FABRIC_VEDA_BINARY` overrides it for the current process. `agents.veda.backend` selects which backend Veda wraps: `agy` (Antigravity CLI, the default), `codex`, `claude-code`, `droid`, `pi`, or another backend registered by the installed Veda build. Fabric passes this value through unchanged and never hardcodes AGY. `agents.veda.model` is an optional backend-specific model or Veda alias. When you omit it, Veda selects its own backend default. `agents.veda.persona` picks the global Veda persona: `navigator-plan`, `navigator-chat` (default), `reviewer`, `worker`, or a custom persona under `~/.config/veda/personas/<name>/AGENTS.md`. Per-run selection overrides it through `agents.run({ persona })`. You can also edit the Veda backend, persona, and model in the Fabric settings panel under Agents. Each child runs one headless `veda --json` prompt with an isolated `fabric-<run-id>` session, so parallel children never share Veda selection or conversation state. Veda sessions lack persistence, and steering is unsupported. Veda children are **not** recursively Fabric-equipped (`recursive: true` is rejected), and they cannot back persistent actors.
455
530
 
456
531
  A JS runtime launches each Fabric worker module. Fabric reuses the current runtime when `process.execPath` names `node` or `bun`. For a Bun-compiled Pi binary, `process.execPath` names the `pi` executable. Fabric then uses `PI_FABRIC_NODE_BINARY` or the first `node` or `bun` on `PATH`. The resolved runtime launches the workers. `PI_FABRIC_NODE_BINARY` overrides this choice for the current process. The Node-process executor (`executor.runtime: "node-process"`) requires Node.js because it uses `--eval` and `--input-type=module`; the Bun-process executor (`executor.runtime: "bun-process"`) requires Bun because it uses `--eval`.
457
532
 
533
+ Workers require Node.js 24+ (or Bun) and report an explicit startup failure on older Node versions. Pi-managed installs intentionally omit physical host peers such as `typebox`; do not repair this by installing all Pi peers. Fabric ships a private, self-contained worker validator while keeping the extension's TypeBox host-mapped. Missing worker dependencies or bootstrap modules are reported in the run status before any model call. The process transport also retains a bounded stderr tail for failures that cannot write a status record.
534
+
458
535
  Other agent settings:
459
536
 
460
537
  - `thinking`: default reasoning effort (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`), default `medium`.
@@ -469,6 +546,9 @@ Other agent settings:
469
546
  - `notifyOnComplete`: show concise detached `agents.spawn()` completion notices and batch unread results for Main at a safe tool-turn boundary (or wake idle Main). `wait`/`join` and terminal `status` retract pending notifications; running/UI status does not. Escape/error parks results until new input.
470
547
  - `sessionExport`: export each agent run's usage as an attributed pi-format session file (on by default).
471
548
  - `sessionExportDir`: override the export store root (default `~/.pi-fabric/agent`, with `PI_FABRIC_AGENT_DIR` taking precedence).
549
+ - `worktree.setup`: optional shell command (`/bin/sh`, or `cmd.exe` on Windows) run in each new `worktree: true` checkout before the child starts (unset by default; blank values are ignored). A per-request `worktreeSetup` overrides it, and a non-zero exit fails the launch. See [worktree results and setup](agents.md#transports).
550
+ - `childQuestions`: `"cancel"` (default) cancels every dialog a Pi child opens; `"route"` forwards it to the parent's UI, or to a root-held [decision](decisions.md#routed-child-questions) when the parent has no UI.
551
+ - `childQuestionTimeoutMs`: default deadline for a routed child dialog (default `600000`, bounded to 1 s..24 h); a dialog's own timeout wins.
472
552
 
473
553
  ### Usage tracking with external tools
474
554
 
@@ -504,7 +584,7 @@ By default Fabric still uses mcporter. To borrow specific servers already config
504
584
 
505
585
  Run `/fabric reload` after changing this selection. Configuring or enabling a native server itself remains Pi's job (`/mcp`, `pi mcp`, and `/reload`). SDK hosts must supply Pi's `createMcpExtension()` and bind extensions; Fabric does not install it or start another native client. No existing MCP configuration or credentials are migrated. An empty list restores the default ownership.
506
586
 
507
- Selected servers keep Fabric's `mcp.<server>.<tool>` names, sanitizer aliases, discovery, static argument checking, normalized `{ text, content, structuredContent }` results, and `display: { name, description }` execution metadata. Raw MCP identity comes from Pi's namespace/label metadata, not its potentially hashed tool identifier. Tool descriptions and input schemas come from the live native registration; Pi's `CallToolResult` output-schema envelope is unwrapped. Genuine schema differences invalidate old normal-form plans rather than being concealed. Other servers keep the existing mcporter behavior. Selected tools are advertised once under `mcp.*`; existing `extensions.mcp__...` references remain callable when extension capture is enabled, but are not repeated in discovery or the extension roster.
587
+ Selected servers keep Fabric's `mcp.<server>.<tool>` names, sanitizer aliases, discovery, static argument checking, normalized `{ text, content, structuredContent }` results, and `display: { name, description }` execution metadata. Raw MCP identity comes from Pi's namespace/label metadata, not its potentially hashed tool identifier. Tool descriptions and input schemas come from the live native registration; Pi's `CallToolResult` output-schema envelope is unwrapped. Schema differences invalidate old normal-form plans; Fabric does not conceal them. Other servers keep the existing mcporter behavior. Selected tools are advertised once under `mcp.*`; existing `extensions.mcp__...` references remain callable when extension capture is enabled, but are not repeated in discovery or the extension roster.
508
588
 
509
589
  Both Fabric policy and Pi's tool middleware apply. Native redactions, progress, nested usage and cancellation remain authoritative; one Fabric invocation emits one Fabric trace operation. Read-only MCP annotations do not change Fabric's conservative network risk. Pi-owned tools remain subject to hidden/deferred exposure and child tool allowlists. A missing, withdrawn, blocked or failed native tool never falls back to mcporter, even if mcporter has a server with the same name. Fabric does not connect or revalidate that duplicate. Ambiguous sanitized names require exact names via `mcp.call` (an exact legacy server name retains precedence over a native alias). Resolving a native server alias may load mcporter's configuration names to check ambiguity, but does not connect those servers.
510
590
 
@@ -514,7 +594,7 @@ Pi owns native startup connections and OAuth; this option does not make Pi's own
514
594
 
515
595
  ### mcporter and shared options
516
596
 
517
- - `mcp.nativeServers`: exact Pi-owned server names, default `[]`. Invalid selections fail rather than silently changing ownership.
597
+ - `mcp.nativeServers`: exact Pi-owned server names, default `[]`. Invalid selections fail without changing ownership.
518
598
  - `mcp.disableOAuth`: for mcporter, calls may use cached credentials but cannot launch new interactive OAuth flows. Pi-owned servers use Pi's authentication settings instead.
519
599
  - `mcp.callTimeoutMs`: per-call timeout bound.
520
600
  - `mcp.allowDynamicServers`: permit `mcp.register()` of ephemeral servers.
@@ -582,10 +662,25 @@ Each entry has three keys:
582
662
 
583
663
  The `fs` adapter derives each session's `revision` from the SHA-256 of the file bytes, so mtime-only touches keep follow pointers valid while content changes invalidate them. Enumeration is bounded by `memory.maxSessions` and reported through coverage reasons (`fs_source_max_sessions`, `fs_source_scan_capped`); a capped archive is never presented as complete. Ranking, branches, and expansion follow the normal engine paths described in [memory recall](memory-recall.md#portable-host-sources).
584
664
 
665
+ ## Principal and scope
666
+
667
+ Scope is host-issued and has no config key. A project or global setting cannot grant or widen a principal.
668
+
669
+ - `PI_FABRIC_SCOPE`: JSON `{ version?: 1, principal: { id, issuer?: "host" }, grants: [{ resource, actions }], digest?, parentDigest? }`. At most 64 grants; `actions` from `read`, `write`, `execute`.
670
+ - `PI_FABRIC_SCOPE_FILE`: path to the same JSON, at most 64 KiB. Set only one of the two.
671
+
672
+ Fabric reads both once when the extension initializes. An embedding process can call `issueRootScope()` from `pi-fabric/scope` before `session_start`. Malformed JSON, an unreadable file, a digest mismatch, or conflicting issuance makes every provider call fail with a clear error. Fabric never falls back to an unscoped session. Fabric children receive their derived scope through `PI_FABRIC_SCOPE`. See [principal and scope](providers.md#principal-and-scope).
673
+
585
674
  ## Compaction
586
675
 
587
676
  The deterministic, LLM-free compaction engine is on by default. It keeps Pi's bounded `keepRecentTokens` continuity tail. `compaction.targetContextRatio` sets a hard occupancy ceiling. Set `compaction.engine` to `"pi"` to restore pi-core compaction. When pi-vcc is also installed, Fabric takes precedence for automatic compaction. An explicit `/pi-vcc` command always uses pi-vcc's engine. See [compaction](compaction.md) for invariants, loss guarantees, sections, and limits.
588
677
 
678
+ `compaction.outputReserveTokens` (default `0`, disabled; integer up to 100,000,000) compacts at the settled boundary once the window headroom falls below the reserve. `compaction.pressureBands` (default `{ "warn": 0.6, "urgent": 0.8 }`, requires `0 < warn < urgent < 1`, otherwise defaults) labels `compact.pressure()` readings. `compaction.repairOrphans` (default `true`) drops orphaned tool results and fills missing ones in the outgoing context. See [headroom trigger](compaction.md#headroom-trigger) and [orphaned tool-result repair](compaction.md#orphaned-tool-result-repair).
679
+
680
+ ## Execution trace
681
+
682
+ `trace.assessment` (default `false`) adds a redacted `FabricAssessmentTraceV1` beside each `fabric_exec` execution trace: per-operation durations, model/Jev/classifier attribution, and token usage and cost where an operation reports them, plus program totals. It never stores arguments, results, code, or error prose, and the deterministic trace is unchanged. See [assessment projection](audit-trace.md#assessment-projection).
683
+
589
684
  ## Catalog repairs
590
685
 
591
686
  Silent invocation repairs are on by default. `repairs.enabled` controls the catalog-scoped table at `~/.pi/agent/fabric/repairs/current.json`. Inspect it with `/fabric repairs`. See [catalog repairs](repairs.md).
@@ -0,0 +1,144 @@
1
+ # Durable decisions
2
+
3
+ A decision is a pending question that outlives the call that raised it: an approval, a question, or an escalation. Fabric stores each decision in the project mesh, so a headless session, a resident host, a child agent, and a person at another terminal all see the same record. A human answers through `/fabric decisions` or the `pi-fabric decisions` CLI. A program answers only decisions that are held by its participant.
4
+
5
+ Three sources raise decisions:
6
+
7
+ - programs, through `decisions.raise`;
8
+ - headless approvals, when `approvals.headless` is `"decision"`;
9
+ - routed child dialogs, when `agents.childQuestions` is `"route"` and the parent session has no interactive UI.
10
+
11
+ ## Record
12
+
13
+ Decisions live under the reserved mesh key prefix `decisions/<id>`. `mesh.get` and `mesh.list` can read them, and `mesh.put` and `mesh.delete` refuse the prefix.
14
+
15
+ ```ts
16
+ {
17
+ id: "dec_…",
18
+ kind: "approval" | "question" | "escalation",
19
+ title, // 1..200 characters
20
+ body?, // up to 4000 characters
21
+ options?: [{ id, label }], // up to 12; ids match [A-Za-z0-9][A-Za-z0-9._:-]{0,63}
22
+ input: "text" | "confirm" | "select" | "editor",
23
+ raisedBy: { participantId, runId?, sessionId? },
24
+ holder: "root" | "user" | "supervisor:<participantId>",
25
+ createdAt, deadline?, // epoch ms
26
+ onExpire: "cancel" | "default" | "escalate",
27
+ defaultOptionId?,
28
+ escalation?: { chain, hop, hopTimeoutMs, onFinal: "cancel" | "default" },
29
+ history?: [{ holder, until, reason: "expired" | "escalated", text?, by? }],
30
+ status: "open" | "answered" | "expired" | "cancelled",
31
+ answer?: { optionId?, text?, answeredBy, via, at },
32
+ }
33
+ ```
34
+
35
+ - `input` defaults to `"select"` when `options` are given and to `"text"` otherwise. `"confirm"` without options gets `yes` and `no`. `"text"` and `"editor"` take no options.
36
+ - `deadline` is an epoch-ms time at most 30 days ahead. `timeoutMs` (1 s to 30 days) is the relative form. Pass one of them.
37
+ - `onExpire: "default"` needs `defaultOptionId` and a deadline. An expired decision then carries `answer: { optionId: defaultOptionId, answeredBy: "deadline", via: "expiry" }`. With `"cancel"` (the default) it expires with no answer.
38
+ - Every transition leaves `open` through a mesh compare-and-swap, so two answerers cannot both win. The loser gets `Decision <id> is answered, not open`.
39
+ - Expiry is lazy: the first reader after the deadline (`get`, `list`, `wait`, an answer attempt, the CLI) writes the `expired` record. A decision with a passed deadline is never answered.
40
+ - Each transition also publishes a wake hint on the `fabric.decisions` mesh topic (`decision.raised`, `decision.escalated`, `decision.answered`, `decision.expired`, `decision.cancelled`, data `{ id, kind, holder, status, title, hop? }`). The record stays authoritative.
41
+ - A mesh root keeps at most 200 open decisions. Resolved decisions stay for 7 days and are pruned first when the store reaches 500 records.
42
+
43
+ ## Guest API
44
+
45
+ ```ts
46
+ const { id } = await decisions.raise({
47
+ kind: "escalation",
48
+ title: "Deploy to production?",
49
+ body: "Migration 42 drops a column.",
50
+ options: [{ id: "go", label: "Deploy" }, { id: "hold", label: "Hold" }],
51
+ timeoutMs: 30 * 60_000,
52
+ onExpire: "default",
53
+ defaultOptionId: "hold",
54
+ });
55
+ const decision = await decisions.wait({ id }); // resolves on answer, expiry, or cancel
56
+ if (decision.answer?.optionId === "go") { /* … */ }
57
+ ```
58
+
59
+ Python uses the same calls, for example `await decisions.raise(title="Deploy?", input="confirm")`.
60
+
61
+ | Action | Risk | Result |
62
+ | --- | --- | --- |
63
+ | `decisions.raise({kind?, title, body?, options?, input?, holder?, deadline? \| timeoutMs?, onExpire?, defaultOptionId?, escalation?})` | agent | `{ id }` |
64
+ | `decisions.wait({id, timeoutMs?})` | read | the record once it leaves `open`; the still-open record when `timeoutMs` passes |
65
+ | `decisions.list({status?, holder?, limit?})` | read, no effect, speculation-eligible | records, newest first (limit 1..200, default 50); `holder` matches the current holder |
66
+ | `decisions.answer({id, optionId?, text?})` | agent | the answered record |
67
+ | `decisions.escalate({id, reason?})` | agent | the record, now held by the next holder in its chain |
68
+ | `decisions.cancel({id})` | agent | the cancelled record |
69
+
70
+ `wait` polls the mesh and stops when the calling program is aborted. `holder` defaults to `"user"`.
71
+
72
+ ## Who may answer
73
+
74
+ | Holder | `decisions.answer` from a program | `/fabric decisions`, `pi-fabric decisions` |
75
+ | --- | --- | --- |
76
+ | `user` | refused | allowed |
77
+ | `root` | a root session participant (`mesh.self().kind === "main"`) | allowed |
78
+ | `supervisor:<participantId>` | that participant only | allowed |
79
+
80
+ A program also cannot answer a decision that it raised in the same `fabric_exec` call, whatever the holder. This keeps a model from approving its own request. `decisions.escalate` follows the same rules. `decisions.cancel` is open to the raiser and to an authorized holder. Fabric checks the holder against the exact record that the compare-and-swap replaces, so a holder that lost a decision to an escalation cannot still answer it.
81
+
82
+ ## Escalation chains
83
+
84
+ `onExpire: "escalate"` hands an unanswered decision to the next holder when a deadline passes, and the decision stays `open`:
85
+
86
+ ```ts
87
+ const { id } = await decisions.raise({
88
+ title: "Retry the flaky migration?",
89
+ options: [{ id: "retry", label: "Retry" }, { id: "skip", label: "Skip" }],
90
+ holder: "supervisor:run-lead",
91
+ onExpire: "escalate",
92
+ escalation: { hopTimeoutMs: 15 * 60_000, onFinal: "default" },
93
+ defaultOptionId: "skip",
94
+ });
95
+ ```
96
+
97
+ - `escalation.chain` lists holders in order with the holder grammar above: at most 8 entries, no duplicates, and the first entry equals `holder`. Without it the chain climbs from the holder: `supervisor:<id>` then `root` then `user`, `root` then `user`, and `user` alone. Fabric freezes the chain on the record at raise time.
98
+ - `escalation.hopTimeoutMs` (1 s to 7 days, default 10 minutes) is each hop's time. The first hop ends at `deadline` or `timeoutMs` when given, else one hop after the raise. Each later hop ends one `hopTimeoutMs` after the previous deadline, so a reader that arrives late applies every elapsed hop in one compare-and-swap.
99
+ - `escalation.onFinal` (`"cancel"` by default, or `"default"`, which needs `defaultOptionId`) resolves the decision when the last holder's deadline passes, exactly like a plain `onExpire`.
100
+ - A move sets `holder` to the next chain entry, advances `escalation.hop`, appends `{ holder, until, reason: "expired" }` to `history` for the previous holder, and publishes `decision.escalated`. Expiry stays lazy: `get`, `list`, `wait`, an answer attempt, the TUI, and the CLI all apply it. Two racing readers cannot both move the decision.
101
+ - `decisions.escalate({ id, reason? })` lets the current holder pass the decision up now. The next holder gets a fresh `hopTimeoutMs`, and `history` records `reason: "escalated"`, the `text` (up to 500 characters), and `by`. Fabric refuses it for a decision without a further holder, which includes every decision without `onExpire: "escalate"`.
102
+ - Authority follows the holder. After a move the previous holder can no longer answer or escalate, and a decision that reaches `user` is answered only by a person.
103
+ - `/fabric decisions` and `pi-fabric decisions list` show the hop and chain, for example `hop 2/3 chain=supervisor:run-lead>root>user`.
104
+
105
+ Records from before escalation chains carry neither `escalation` nor `history` and expire as before.
106
+
107
+ Authority for the human surfaces is local file access to the mesh root. Until principals and scopes land, anyone who can write the mesh root as the same OS user can answer any decision.
108
+
109
+ ## Headless approvals
110
+
111
+ `approvals.headless` controls what happens when an action needs approval (`ask`, or an `auto` escalation) and the session has no interactive UI:
112
+
113
+ - `"deny"` (default) fails the call, as before.
114
+ - `"decision"` raises a `kind: "approval"` decision held by `"user"` with options `approve` and `deny`, and waits for it inside the calling program's abort signal. The deadline is `approvals.headlessTimeoutMs` (default 5 minutes) with `onExpire: "cancel"`. Only an `approve` answer runs the action, once. A deny, a cancellation, an expiry, or an aborted program denies it. Fabric never approves automatically.
115
+
116
+ The decision path covers actions called through `fabric_exec`. Direct native tool approvals in a headless session still fail closed. Session-wide grants ("Allow write access for this session") stay a UI-only choice.
117
+
118
+ ## Routed child questions
119
+
120
+ By default a child Pi run cancels every dialog (`select`, `confirm`, `input`, `editor`) that its extensions open. With `agents.childQuestions: "route"`, the child's worker forwards the dialog to the parent:
121
+
122
+ 1. The worker writes a lifecycle record `{ event: "question", data: { requestId, method, title, message?, options?, placeholder?, prefill?, timeout } }` and sets `blockedOn: { since }` on the run record.
123
+ 2. The parent AgentManager asks through its own interactive UI when it has one, with the child's name prefixed to the title. A parent that is itself an RPC child asks through its own UI channel, so questions climb to the first session with a person or a headless root.
124
+ 3. Without an interactive UI, the parent raises a `kind: "question"` decision held by `"root"`. `select` options become `o1`, `o2`, … (the first 12), and `confirm` becomes `yes`/`no`. The run record then shows `blockedOn: { decisionId, since }`.
125
+ 4. The answer goes back through the run's steer channel as `{ type: "ui_response", requestId, value? | confirmed? | cancelled? }`, and the worker forwards it to the child as `extension_ui_response`.
126
+
127
+ The deadline is the dialog's own timeout, or `agents.childQuestionTimeoutMs` (default 10 minutes). The worker owns that deadline and answers `cancelled` when it passes, so a child never waits on a parent that has gone away. A settled run cancels its open question decision. Only the `pi` runner routes dialogs.
128
+
129
+ ## Human surfaces
130
+
131
+ - `/fabric decisions [id]` lists open decisions, then answers the picked one through native dialogs (`select` for options, with a "Cancel this decision" entry, and `input` or `editor` for text). Answers record `via: "tui"`.
132
+ - `pi-fabric decisions list --root <meshRoot> [--status open|answered|expired|cancelled|all] [--holder h] [--limit n] [--json]` prints decisions from outside any Pi session. `--root` defaults to `$PI_FABRIC_MESH_ROOT`. The project mesh root is `.pi/fabric/mesh` unless `mesh.root` says otherwise.
133
+ - `pi-fabric decisions answer --root <meshRoot> <id> (--option <id> | --text <t>) [--json]` answers one decision with `via: "cli"` and the OS user name as `answeredBy`. Exit code 1 reports a refused answer (not open, unknown option), and 2 reports a usage error.
134
+
135
+ ## Configuration
136
+
137
+ | Key | Default | Meaning |
138
+ | --- | --- | --- |
139
+ | `approvals.headless` | `"deny"` | `"decision"` turns no-UI approvals into user-held decisions |
140
+ | `approvals.headlessTimeoutMs` | `300000` | headless approval deadline (1 s to 24 h) |
141
+ | `agents.childQuestions` | `"cancel"` | `"route"` forwards child dialogs to the parent |
142
+ | `agents.childQuestionTimeoutMs` | `600000` | default routed dialog deadline (1 s to 24 h) |
143
+
144
+ Decisions need `mesh.enabled`. Managed hosts do not expose `decisions.*`. Schema enforce mode allows `decisions.list` and blocks the other actions.
@@ -0,0 +1,186 @@
1
+ # Opt-in Pi durable hosted runner
2
+
3
+ `pi-fabric/durable` exports `createPiDurableRunner`, `PiDurableRunner`,
4
+ `PiDurableRunnerOptions`, `PiDurableStorageOptions`, `PiDurableStorageLease`, and
5
+ `PiDurableLocator`. It does not register a runner or change the default Pi runner.
6
+ Importing the entry and constructing the factory do not load either optional runtime.
7
+
8
+ This adapter targets the **published** experimental
9
+ `@earendil-works/pi-durable@1.0.0` and `@earendil-works/chord@1.0.0` APIs.
10
+ First start/attach checks both installed versions and loads them lazily. Missing or
11
+ incompatible peers produce an explicit error. Host credentials remain in `Models`
12
+ and the environment, never in the locator.
13
+
14
+ ## Host setup
15
+
16
+ Install the optional peers only in a host that uses this adapter:
17
+
18
+ ```sh
19
+ bun add @earendil-works/pi-durable@1.0.0 @earendil-works/chord@1.0.0
20
+ ```
21
+
22
+ ```ts
23
+ import { createPiDurableRunner } from "pi-fabric/durable";
24
+ import { registerAgentRunner } from "pi-fabric/runners";
25
+ import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
26
+
27
+ // Supply a configured pi-ai Models collection and a durable Registry.
28
+ // Install only trusted tool implementations in that registry.
29
+ const runner = createPiDurableRunner({
30
+ id: "pi-durable", // default; must not collide with another registration
31
+ models,
32
+ registry,
33
+ env: ({ cwd }) => new NodeExecutionEnv({ cwd: cwd! }),
34
+ allowedModels: [{ provider: "openai", modelId: "your-model-id" }],
35
+ storage: { kind: "jsonl", directory: "/absolute/private/durable-runs" },
36
+ // Required for standard residency: "durable":
37
+ // residentModule: "/absolute/path/to/host-registration.mjs",
38
+ });
39
+ const unregister = registerAgentRunner(runner);
40
+
41
+ // An AgentManager / agents.run call must explicitly select this runner,
42
+ // provider/model, and exact registered tool names:
43
+ // { runner: "pi-durable", model: "openai/your-model-id",
44
+ // task: "...", tools: ["read"], recursive: false, thinking: "off" }
45
+
46
+ // Detach only after the host has stopped delivering requests to this instance.
47
+ await runner.close();
48
+ unregister();
49
+ ```
50
+
51
+ `residentModule` must be a real host-owned ES module that registers the adapter
52
+ with the same storage and credentials in the resident process. Merely setting the
53
+ path does not create a daemon. A session-resident runner needs no resident module.
54
+ The factory does not discover providers or select a default model. Thinking is
55
+ passed explicitly (omission means `off` at the adapter boundary); unsupported
56
+ levels are rejected; the adapter does not clamp them.
57
+
58
+ ## Storage and ownership
59
+
60
+ There is one isolated durable Session/root conversation **per Fabric run ID**.
61
+
62
+ ### Built-in JSONL
63
+
64
+ `{ kind: "jsonl", directory }` opens the published Node JSONL backend with
65
+ `fsync: true`. Files live under `directory/sha256(runId)`; an atomic mkdir of
66
+ `directory/sha256(runId).writer` grants exclusive ownership. The base directory is
67
+ canonicalized before opening the lock and storage, so symlink aliases contend for
68
+ the same filesystem lock. A process-global ownership set also rejects two active
69
+ adapter instances with the same identity/run ID. An active run retains ownership,
70
+ including after settlement, until `close()`.
71
+
72
+ **No automatic stale-lock stealing.** Any existing lock (including malformed,
73
+ empty, unknown or remote ownership) is a refusal, never evidence of death. This
74
+ avoids both lease-timeout false deaths and the two-contender read/dead/unlink race.
75
+ Locks are intentionally empty and contain no credentials. Keep the directory
76
+ private to cooperating trusted hosts; this is not a hostile-filesystem sandbox.
77
+
78
+ After a crash, the host must:
79
+
80
+ 1. Quiesce **all** recovery contenders/writers for this storage/run.
81
+ 2. Positively establish that the previous process and any invocation using the
82
+ storage have terminated (e.g. the supervised process's exit receipt). Timeouts,
83
+ old mtimes, missing heartbeats, and unknown PID namespaces are insufficient.
84
+ 3. Remove only the exact empty `sha256(runId).writer` directory while recovery is
85
+ administratively serialized. Never blindly unlink a possibly replaced lock.
86
+ 4. Reopen a new factory instance with the same directory and call attach using
87
+ Fabric's persisted locator/context. Do not call start to repair missing work.
88
+
89
+ SIGKILL recovery is tested with exactly this manual restore procedure. Automatic
90
+ unattended crash recovery needs a host factory that supplies an appropriate lock.
91
+ JSONL durability remains subject to the published storage/filesystem contract;
92
+ this adapter does not promise power-loss-proof filesystem metadata.
93
+
94
+ ### Host-provided storage
95
+
96
+ ```ts
97
+ storage: {
98
+ kind: "factory",
99
+ identity: "tenant-a-durable-v1", // stable opaque identity, no secret required
100
+ async acquire(runId) {
101
+ // Acquire an exclusive process/host-wide lease; OS crash-released locking
102
+ // can provide unattended recovery. Open the SAME isolated storage for runId.
103
+ return { storage, async release() { /* release ownership, not work */ } };
104
+ },
105
+ }
106
+ ```
107
+
108
+ `acquire` must reject conflicting ownership, including other processes and
109
+ aliases, and must return a distinct isolated storage namespace per run ID.
110
+ It must clean up partial acquisition on failure. The adapter closes storage via
111
+ Harness before `release`, never releases while its invocations still run, and
112
+ joins accepted open/start operations during `close`. In-memory storage is useful
113
+ for tests but is not restart persistence. Failed closure/release fails closed;
114
+ its lease remains owned, and competing writers are refused. Well-behaved
115
+ host tools must observe cancellation: upstream close joins even tools that ignore
116
+ it, so such tools can block close indefinitely.
117
+
118
+ ## Admission, attach, and reporting
119
+
120
+ Fabric persists the pure JSON locator before `start`. It contains backend/version,
121
+ a storage identity hash, and Fabric run ID only. `start` commits a request manifest
122
+ and submits with **requestId = Fabric run ID**. Repeated starts, including after
123
+ reopen, reuse the committed submission. A changed task/model/tools/cwd/thinking/
124
+ system prompt under that run ID is rejected.
125
+
126
+ `attach` looks up the existing root and `submissionByRequest`; it never creates a
127
+ conversation or submits an input. A locator with no admitted submission throws;
128
+ the existing HostedRun protocol records the outcome as **indeterminate**, not
129
+ retryable work. A crash between manifest creation and submission is therefore
130
+ not automatically repaired. Locators must be retained with Fabric's context.
131
+
132
+ Committed conversation snapshots feed progress (turns, calls, current tool,
133
+ partial text), cumulative model/tool usage, and transcript messages/tool events.
134
+ Transcript attachment reconstructs the current committed history; it does not
135
+ rerun effects or guarantee exactly-once transcript delivery across host restarts.
136
+ The final submission maps to completed/text, aborted/stopped, or unanswered/failed.
137
+ Liveness is running, settled, cancelled, interrupted, or unknown. Unowned/missing
138
+ work is unknown; explicit stop returns unconfirmed when no owned submission exists.
139
+
140
+ `stop` aborts the owned root's work, including background descendants, and joins
141
+ it. `close` instead seals the adapter, detaches observers, closes Harness without
142
+ writing an abort outcome, joins invocations, and releases ownership. A new
143
+ factory instance can attach afterward. `close` is idempotent, but a closed
144
+ instance cannot reopen. This is a resource lifecycle surface, not a sleep/wake
145
+ capability. Fabric's own explicit stop/shutdown/deadline policy is unchanged.
146
+
147
+ ## Tools and limitations
148
+
149
+ Only names in `request.tools` are selected. Unknown names and unknown/disallowed
150
+ provider/model keys fail closed before admission. Registered tool definitions
151
+ are resolved last-installed-wins, host tool wrappers are applied in registry
152
+ order, and selected implementations are pinned in a private per-open registry.
153
+ Changes to the host registry do not rewrite in-flight code; reopen resolves the
154
+ host's current definitions and refuses missing requested names.
155
+
156
+ **This is a tool-only Registry integration.** Host extension sections, hooks,
157
+ and custom tasks are not installed in the private registry. The request system
158
+ prompt becomes conversation instructions; cwd is handed to the host environment.
159
+ Tool execution remains trusted host code, not a security sandbox. Host tools can
160
+ use their durable execution API; the adapter does not claim to confine arbitrary
161
+ host side effects or sub-work they create. Tool result `addTools` and `handoff`
162
+ controls are rejected. The requested allowlist stays fixed.
163
+
164
+ There is no built-in Fabric tool bridge, kernel, or JavaScript continuation
165
+ restoration. Replay is the published explicit task/checkpoint protocol: tools
166
+ are unsafe by default, and interruption returns an error. An uncertain side effect
167
+ is not replayed. Only a host's explicit replay-safe tool declaration
168
+ permits replay; the adapter never blanket-marks tools safe. A host-registered
169
+ `fabric_exec` implementation is always forced unsafe even if the host accidentally
170
+ marks it safe; no Fabric bridge is synthesized.
171
+
172
+ Unsupported capabilities fail closed: recursive Fabric, kernels, branch/session
173
+ seeding, actors/persistent sessions, write confinement, scopes, structured output
174
+ schemas, image input, routed questions, explicit compaction, sleep/wake, steering,
175
+ and follow-up. Steering/follow-up are intentionally absent: the published queue
176
+ semantics are not claimed to extend Fabric's one-submission completion boundary.
177
+
178
+ ## Evidence
179
+
180
+ `tests/durable-runner.test.ts` exercises the real published packages with offline
181
+ faux models, MemoryStorage and fsync JSONL: real AgentManager execution, duplicate
182
+ admission, reopen/attach, cancellable unsafe interruption, a killed
183
+ process/manual recovery/no replay, exclusive ownership, stale-lock refusal,
184
+ close/open races, exact tools/model/thinking, usage/progress, cancellation and
185
+ unsupported requests. `tests/optional-durable-startup.test.ts` independently
186
+ checks dependency-free import and no automatic registration.