@e4779/pi-fabric 0.92.42-fork.7 → 0.96.4-fork.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (296) hide show
  1. package/LAWS.bend +502 -0
  2. package/PROOF.bend +452 -0
  3. package/README.md +5 -1
  4. package/THIRD_PARTY_NOTICES.md +9 -0
  5. package/dist/agents/handoff.d.ts +2 -1
  6. package/dist/agents/handoff.d.ts.map +1 -1
  7. package/dist/agents/manager.d.ts +2 -0
  8. package/dist/agents/manager.d.ts.map +1 -1
  9. package/dist/agents.js +6 -5
  10. package/dist/agents.js.map +1 -1
  11. package/dist/chunks/{chunk-3TXOQ5MG.js → chunk-3CJETB4S.js} +828 -204
  12. package/dist/chunks/chunk-3CJETB4S.js.map +7 -0
  13. package/dist/chunks/{chunk-IUCVOZRX.js → chunk-3SIXBW6A.js} +2 -2
  14. package/dist/chunks/chunk-4E63LJDD.js +468 -0
  15. package/dist/chunks/chunk-4E63LJDD.js.map +7 -0
  16. package/dist/chunks/{chunk-AAHHYDTO.js → chunk-4NF3S3NM.js} +1 -1
  17. package/dist/chunks/{chunk-AAHHYDTO.js.map → chunk-4NF3S3NM.js.map} +2 -2
  18. package/dist/chunks/{chunk-2SWRVIYJ.js → chunk-754HA6KO.js} +2 -2
  19. package/dist/chunks/{chunk-K6DHXXF5.js → chunk-B2IVWASP.js} +2 -2
  20. package/dist/chunks/{chunk-ZDNGXLEC.js → chunk-B4HECUJI.js} +2 -2
  21. package/dist/chunks/{chunk-H6DDV6E2.js → chunk-CSJSHBAT.js} +5 -5
  22. package/dist/chunks/{chunk-MW5VI7IW.js → chunk-D4B4CCTA.js} +2 -2
  23. package/dist/chunks/{chunk-EDL4JDW7.js → chunk-EBWMC3OO.js} +2 -2
  24. package/dist/chunks/{chunk-4NUTVNS2.js → chunk-F72MAIQY.js} +31 -368
  25. package/dist/chunks/chunk-F72MAIQY.js.map +7 -0
  26. package/dist/chunks/{chunk-W3FRE4VI.js → chunk-FDIEQEXS.js} +2 -2
  27. package/dist/chunks/{chunk-7A6NVHB5.js → chunk-FJSHRHOR.js} +7 -4
  28. package/dist/chunks/chunk-FJSHRHOR.js.map +7 -0
  29. package/dist/chunks/{chunk-PSNXUZMY.js → chunk-G2F2RDZI.js} +5 -47
  30. package/dist/chunks/chunk-G2F2RDZI.js.map +7 -0
  31. package/dist/chunks/{chunk-3WIGAX56.js → chunk-JCV54SSP.js} +2 -2
  32. package/dist/chunks/chunk-KS44WKJJ.js +51 -0
  33. package/dist/chunks/chunk-KS44WKJJ.js.map +7 -0
  34. package/dist/chunks/{chunk-3H7SDWZI.js → chunk-LNLQ2LX3.js} +22 -1
  35. package/dist/chunks/chunk-LNLQ2LX3.js.map +7 -0
  36. package/dist/chunks/{chunk-G4LADAYY.js → chunk-OINADFEF.js} +8 -3
  37. package/dist/chunks/chunk-OINADFEF.js.map +7 -0
  38. package/dist/chunks/{chunk-UQ4LTUH4.js → chunk-OUAC6O5C.js} +36 -9
  39. package/dist/chunks/chunk-OUAC6O5C.js.map +7 -0
  40. package/dist/chunks/{chunk-MQG5QKGI.js → chunk-Q5BMTL6A.js} +217 -95
  41. package/dist/chunks/chunk-Q5BMTL6A.js.map +7 -0
  42. package/dist/chunks/{chunk-IK6PPFWG.js → chunk-QFKHAAZA.js} +11 -11
  43. package/dist/chunks/chunk-QFKHAAZA.js.map +7 -0
  44. package/dist/chunks/{chunk-RTXZHKMS.js → chunk-QNMQJNXE.js} +7 -3
  45. package/dist/chunks/chunk-QNMQJNXE.js.map +7 -0
  46. package/dist/chunks/{chunk-U5FYOMG5.js → chunk-UBPFGMDQ.js} +6 -2
  47. package/dist/chunks/chunk-UBPFGMDQ.js.map +7 -0
  48. package/dist/chunks/{chunk-FLKGJPCN.js → chunk-ULQFHZJE.js} +4 -1
  49. package/dist/chunks/chunk-ULQFHZJE.js.map +7 -0
  50. package/dist/chunks/{chunk-7VAZ4N43.js → chunk-V3PIO7QL.js} +2 -2
  51. package/dist/chunks/{chunk-MGDLRV2R.js → chunk-VQGO4P7C.js} +2 -2
  52. package/dist/chunks/{chunk-XT4346N7.js → chunk-WXSELMFV.js} +9 -3
  53. package/dist/chunks/chunk-WXSELMFV.js.map +7 -0
  54. package/dist/chunks/{chunk-D5WKZONW.js → chunk-X3IRR7CV.js} +2 -2
  55. package/dist/chunks/{chunk-IJL3QK3J.js → chunk-Y57UHPIK.js} +1 -1
  56. package/dist/chunks/{chunk-IJL3QK3J.js.map → chunk-Y57UHPIK.js.map} +1 -1
  57. package/dist/chunks/{chunk-RKRVOBVO.js → chunk-YC3QQDZ3.js} +2 -2
  58. package/dist/chunks/{chunk-Q4XJ4PYL.js → chunk-ZRI433JP.js} +299 -83
  59. package/dist/chunks/chunk-ZRI433JP.js.map +7 -0
  60. package/dist/chunks/{chunk-36B4AIRT.js → chunk-ZTXZ6JDO.js} +2 -2
  61. package/dist/commands/fabric.d.ts.map +1 -1
  62. package/dist/compaction/bounds.d.ts +4 -0
  63. package/dist/compaction/bounds.d.ts.map +1 -1
  64. package/dist/compaction/branch-summary.d.ts.map +1 -1
  65. package/dist/compaction/dialogue.d.ts +24 -0
  66. package/dist/compaction/dialogue.d.ts.map +1 -0
  67. package/dist/compaction/hook.d.ts +6 -2
  68. package/dist/compaction/hook.d.ts.map +1 -1
  69. package/dist/compaction/hook.js +6 -5
  70. package/dist/compaction/instructions.d.ts +1 -0
  71. package/dist/compaction/instructions.d.ts.map +1 -1
  72. package/dist/compaction/projections.d.ts +3 -3
  73. package/dist/compaction/projections.d.ts.map +1 -1
  74. package/dist/compaction/qa.d.ts.map +1 -1
  75. package/dist/compaction/render.d.ts +11 -0
  76. package/dist/compaction/render.d.ts.map +1 -1
  77. package/dist/components/configuration.js +2 -3
  78. package/dist/components/effect-policy.d.ts +2 -0
  79. package/dist/components/effect-policy.d.ts.map +1 -1
  80. package/dist/components/effect-scope.d.ts.map +1 -1
  81. package/dist/components/supervisor.d.ts +1 -1
  82. package/dist/components/supervisor.d.ts.map +1 -1
  83. package/dist/core/action-registry.d.ts +14 -2
  84. package/dist/core/action-registry.d.ts.map +1 -1
  85. package/dist/core/action-registry.js +7 -5
  86. package/dist/core/provider-bindings.d.ts +8 -2
  87. package/dist/core/provider-bindings.d.ts.map +1 -1
  88. package/dist/core/provider-operations.d.ts +28 -0
  89. package/dist/core/provider-operations.d.ts.map +1 -0
  90. package/dist/core/provider-operations.js +201 -0
  91. package/dist/core/provider-operations.js.map +7 -0
  92. package/dist/core/shell-inbox.d.ts +13 -0
  93. package/dist/core/shell-inbox.d.ts.map +1 -0
  94. package/dist/core/shell-jobs.d.ts +51 -7
  95. package/dist/core/shell-jobs.d.ts.map +1 -1
  96. package/dist/core/shell-limits.d.ts +3 -0
  97. package/dist/core/shell-limits.d.ts.map +1 -0
  98. package/dist/core/shell-monitor.d.ts +51 -0
  99. package/dist/core/shell-monitor.d.ts.map +1 -0
  100. package/dist/entropy/index.js +8 -7
  101. package/dist/entropy/normal-form.d.ts.map +1 -1
  102. package/dist/execution-service.d.ts +1 -1
  103. package/dist/execution-service.d.ts.map +1 -1
  104. package/dist/fabric-runtime-state.d.ts +1 -1
  105. package/dist/fabric-runtime-state.d.ts.map +1 -1
  106. package/dist/fabric-runtime-state.js +1124 -325
  107. package/dist/fabric-runtime-state.js.map +4 -4
  108. package/dist/index.js +155 -44
  109. package/dist/index.js.map +3 -3
  110. package/dist/jev/observation.js +5 -3
  111. package/dist/jev.d.ts +0 -1
  112. package/dist/jev.d.ts.map +1 -1
  113. package/dist/jev.js +9 -13
  114. package/dist/memory/digest.d.ts.map +1 -1
  115. package/dist/memory/digest.js +2 -1
  116. package/dist/memory/discovery.js +6 -5
  117. package/dist/memory/expand-service.d.ts.map +1 -1
  118. package/dist/memory/file-worker.js +9 -8
  119. package/dist/memory/file-worker.js.map +1 -1
  120. package/dist/memory/index.d.ts.map +1 -1
  121. package/dist/memory/normalize.d.ts.map +1 -1
  122. package/dist/memory/normalize.js +5 -4
  123. package/dist/memory/search.js +7 -6
  124. package/dist/memory/worker-provider.js +10 -9
  125. package/dist/memory.js +9 -8
  126. package/dist/memory.js.map +1 -1
  127. package/dist/mesh/store.d.ts.map +1 -1
  128. package/dist/prewalk/handoff.d.ts +1 -1
  129. package/dist/prewalk/handoff.d.ts.map +1 -1
  130. package/dist/protocol.d.ts +2 -0
  131. package/dist/protocol.d.ts.map +1 -1
  132. package/dist/protocol.js +1 -1
  133. package/dist/providers/jev-provider.d.ts +1 -1
  134. package/dist/providers/jev-provider.d.ts.map +1 -1
  135. package/dist/providers/jev-provider.js +9 -7
  136. package/dist/providers/memory-provider.js +9 -8
  137. package/dist/providers/pi-tools-provider.d.ts.map +1 -1
  138. package/dist/providers/tasks-provider.d.ts +12 -0
  139. package/dist/providers/tasks-provider.d.ts.map +1 -0
  140. package/dist/residency/host.js +10 -9
  141. package/dist/residency/pi-entry.js +10 -9
  142. package/dist/residency/pi-entry.js.map +1 -1
  143. package/dist/runtime/core-override-guest-types.js +2 -2
  144. package/dist/runtime/guest-types.d.ts +1 -1
  145. package/dist/runtime/guest-types.d.ts.map +1 -1
  146. package/dist/runtime/guest-types.js +1 -1
  147. package/dist/runtime/monty-runtime.js +1 -2
  148. package/dist/runtime/monty-runtime.js.map +1 -1
  149. package/dist/runtime/typescript-kernel.js +2 -2
  150. package/dist/runtime-state-builtins.d.ts +1 -1
  151. package/dist/runtime-state-builtins.d.ts.map +1 -1
  152. package/dist/schema/controller.d.ts.map +1 -1
  153. package/dist/state/store.d.ts.map +1 -1
  154. package/dist/ui/controller.d.ts +1 -0
  155. package/dist/ui/controller.d.ts.map +1 -1
  156. package/dist/ui/conversation-targets.js +2 -2
  157. package/dist/ui/conversation.js +7 -7
  158. package/dist/ui/dashboard.js +9 -9
  159. package/dist/ui/highlight.d.ts.map +1 -1
  160. package/dist/ui/languages/bend.d.ts +4 -0
  161. package/dist/ui/languages/bend.d.ts.map +1 -0
  162. package/dist/ui/languages/bend.js +73 -0
  163. package/dist/ui/languages/bend.js.map +7 -0
  164. package/dist/ui/settings.js +1 -2
  165. package/dist/ui/settings.js.map +1 -1
  166. package/dist/ui/shell-hang-keys.d.ts.map +1 -1
  167. package/dist/ui/shell-tasks.d.ts +22 -0
  168. package/dist/ui/shell-tasks.d.ts.map +1 -0
  169. package/dist/ui/shell-tasks.js +161 -0
  170. package/dist/ui/shell-tasks.js.map +7 -0
  171. package/dist/ui/shiki-catalog.d.ts +2 -1
  172. package/dist/ui/shiki-catalog.d.ts.map +1 -1
  173. package/dist/ui/snapshot.d.ts.map +1 -1
  174. package/dist/ui/types.d.ts +1 -0
  175. package/dist/ui/types.d.ts.map +1 -1
  176. package/dist/ui/widget.d.ts.map +1 -1
  177. package/dist/verified/authority.d.ts +17 -0
  178. package/dist/verified/authority.d.ts.map +1 -0
  179. package/dist/verified/generated/authority-kernel.d.ts +10 -0
  180. package/dist/verified/generated/authority-kernel.js +116 -0
  181. package/dist/verified/generated/kernel.d.ts +31 -0
  182. package/dist/verified/generated/kernel.js +351 -0
  183. package/dist/verified/generated/lifecycle-kernel.d.ts +7 -0
  184. package/dist/verified/generated/lifecycle-kernel.js +155 -0
  185. package/dist/verified/generated/manifest.json +54 -0
  186. package/dist/verified/generated/provider-kernel.d.ts +9 -0
  187. package/dist/verified/generated/provider-kernel.js +80 -0
  188. package/dist/verified/generated/storage-kernel.d.ts +11 -0
  189. package/dist/verified/generated/storage-kernel.js +98 -0
  190. package/dist/verified/memory.d.ts +11 -0
  191. package/dist/verified/memory.d.ts.map +1 -0
  192. package/dist/verified/nat.d.ts +2 -0
  193. package/dist/verified/nat.d.ts.map +1 -0
  194. package/dist/verified/policy.d.ts +37 -0
  195. package/dist/verified/policy.d.ts.map +1 -0
  196. package/dist/verified/resources.d.ts +14 -0
  197. package/dist/verified/resources.d.ts.map +1 -0
  198. package/dist/verified/storage.d.ts +32 -0
  199. package/dist/verified/storage.d.ts.map +1 -0
  200. package/dist/worker/recovery-watchdog.d.ts +12 -0
  201. package/dist/worker/recovery-watchdog.d.ts.map +1 -0
  202. package/dist/worker/recovery-watchdog.js +41 -0
  203. package/dist/worker/recovery-watchdog.js.map +7 -0
  204. package/dist/worker.js +70 -20
  205. package/dist/worker.js.map +2 -2
  206. package/docs/agents.md +20 -14
  207. package/docs/architecture.md +1 -1
  208. package/docs/background-tasks.md +140 -0
  209. package/docs/compaction.md +91 -28
  210. package/docs/components.md +5 -1
  211. package/docs/configuration.md +6 -6
  212. package/docs/foreman.md +4 -4
  213. package/docs/harnesses.md +95 -0
  214. package/docs/interface.md +7 -0
  215. package/docs/jev.md +59 -52
  216. package/docs/kernels.md +2 -2
  217. package/docs/licenses/bend-apache-2.0.txt +202 -0
  218. package/docs/memory-recall.md +1 -1
  219. package/docs/programmatic-compaction.md +13 -2
  220. package/docs/provider-capabilities.md +197 -0
  221. package/docs/shell-middleware.md +3 -3
  222. package/docs/skills.md +1 -1
  223. package/docs/verified-kernels.md +278 -0
  224. package/package.json +14 -4
  225. package/proofs/abi.json +308 -0
  226. package/proofs/authority-abi.json +7 -0
  227. package/proofs/authority-kernel.bend +23 -0
  228. package/proofs/authority-proof.bend +74 -0
  229. package/proofs/authority-spec.bend +30 -0
  230. package/proofs/authority-state.bend +43 -0
  231. package/proofs/authority-types.d.ts +3 -0
  232. package/proofs/kernel.bend +139 -0
  233. package/proofs/lifecycle-abi.json +3 -0
  234. package/proofs/lifecycle-kernel.bend +11 -0
  235. package/proofs/lifecycle-proof.bend +249 -0
  236. package/proofs/lifecycle-spec.bend +261 -0
  237. package/proofs/lifecycle-types.d.ts +4 -0
  238. package/proofs/lifecycle.bend +119 -0
  239. package/proofs/provider-abi.json +4 -0
  240. package/proofs/provider-kernel.bend +14 -0
  241. package/proofs/provider-plans.bend +28 -0
  242. package/proofs/provider-spec.bend +14 -0
  243. package/proofs/provider-types.d.ts +5 -0
  244. package/proofs/resource-proof.bend +633 -0
  245. package/proofs/resource-spec.bend +133 -0
  246. package/proofs/resources.bend +160 -0
  247. package/proofs/state-kernel.bend +17 -0
  248. package/proofs/state-plans.bend +40 -0
  249. package/proofs/state-proof.bend +42 -0
  250. package/proofs/state-spec.bend +26 -0
  251. package/proofs/storage-abi.json +3 -0
  252. package/proofs/storage-kernel.bend +11 -0
  253. package/proofs/storage-plans.bend +100 -0
  254. package/proofs/storage-proof.bend +176 -0
  255. package/proofs/storage-spec.bend +70 -0
  256. package/proofs/storage-types.d.ts +8 -0
  257. package/proofs/types.d.ts +7 -0
  258. package/scripts/test-verified-kernels.mjs +107 -0
  259. package/scripts/verified-kernels.mjs +136 -0
  260. package/skillsets/python/fabric-jev/SKILL.md +13 -9
  261. package/skillsets/typescript/fabric-exec/SKILL.md +4 -2
  262. package/skillsets/typescript/fabric-jev/SKILL.md +13 -9
  263. package/dist/chunks/chunk-3H7SDWZI.js.map +0 -7
  264. package/dist/chunks/chunk-3TXOQ5MG.js.map +0 -7
  265. package/dist/chunks/chunk-4NUTVNS2.js.map +0 -7
  266. package/dist/chunks/chunk-77PDIBK2.js +0 -129
  267. package/dist/chunks/chunk-77PDIBK2.js.map +0 -7
  268. package/dist/chunks/chunk-7A6NVHB5.js.map +0 -7
  269. package/dist/chunks/chunk-FLKGJPCN.js.map +0 -7
  270. package/dist/chunks/chunk-G4LADAYY.js.map +0 -7
  271. package/dist/chunks/chunk-IK6PPFWG.js.map +0 -7
  272. package/dist/chunks/chunk-MQG5QKGI.js.map +0 -7
  273. package/dist/chunks/chunk-PSNXUZMY.js.map +0 -7
  274. package/dist/chunks/chunk-Q4XJ4PYL.js.map +0 -7
  275. package/dist/chunks/chunk-RTXZHKMS.js.map +0 -7
  276. package/dist/chunks/chunk-U5FYOMG5.js.map +0 -7
  277. package/dist/chunks/chunk-UQ4LTUH4.js.map +0 -7
  278. package/dist/chunks/chunk-XT4346N7.js.map +0 -7
  279. package/dist/jev/browser.d.ts +0 -37
  280. package/dist/jev/browser.d.ts.map +0 -1
  281. package/dist/jev/browser.js +0 -13
  282. package/dist/jev/browser.js.map +0 -7
  283. /package/dist/chunks/{chunk-IUCVOZRX.js.map → chunk-3SIXBW6A.js.map} +0 -0
  284. /package/dist/chunks/{chunk-2SWRVIYJ.js.map → chunk-754HA6KO.js.map} +0 -0
  285. /package/dist/chunks/{chunk-K6DHXXF5.js.map → chunk-B2IVWASP.js.map} +0 -0
  286. /package/dist/chunks/{chunk-ZDNGXLEC.js.map → chunk-B4HECUJI.js.map} +0 -0
  287. /package/dist/chunks/{chunk-H6DDV6E2.js.map → chunk-CSJSHBAT.js.map} +0 -0
  288. /package/dist/chunks/{chunk-MW5VI7IW.js.map → chunk-D4B4CCTA.js.map} +0 -0
  289. /package/dist/chunks/{chunk-EDL4JDW7.js.map → chunk-EBWMC3OO.js.map} +0 -0
  290. /package/dist/chunks/{chunk-W3FRE4VI.js.map → chunk-FDIEQEXS.js.map} +0 -0
  291. /package/dist/chunks/{chunk-3WIGAX56.js.map → chunk-JCV54SSP.js.map} +0 -0
  292. /package/dist/chunks/{chunk-7VAZ4N43.js.map → chunk-V3PIO7QL.js.map} +0 -0
  293. /package/dist/chunks/{chunk-MGDLRV2R.js.map → chunk-VQGO4P7C.js.map} +0 -0
  294. /package/dist/chunks/{chunk-D5WKZONW.js.map → chunk-X3IRR7CV.js.map} +0 -0
  295. /package/dist/chunks/{chunk-RKRVOBVO.js.map → chunk-YC3QQDZ3.js.map} +0 -0
  296. /package/dist/chunks/{chunk-36B4AIRT.js.map → chunk-ZTXZ6JDO.js.map} +0 -0
@@ -99,7 +99,7 @@ preflight, and callers requiring all final errors to throw should omit `settle`.
99
99
 
100
100
  ## Model-context economy
101
101
 
102
- Fabric caps final `fabric_exec` output at 50,000 characters by default, which matches Pi's built-in 50KB tool ceiling. Failed executions get a tighter 20,000-character visible ceiling, and the complete output stays in the same private artifact. An oversized structured return shares that budget across every multiline section and preserves both ends with explicit omission markers. Unstructured output keeps its global beginning and end. Fabric writes the complete output to a mode-`0600` temporary artifact and includes the artifact path inside the visible ceiling. The model can then retrieve a targeted range without carrying the entire result. Type-check diagnostics use the same ceiling. Models should still filter noisy commands and return only useful evidence, because source-side projection preserves more relevant information than post-format truncation. When a later nested call fails after earlier calls completed, the error adds a bounded list of completed refs and paths. The model can inspect that list before repeating side effects. Nested outputs the guest did not return are never exposed. Raw media never enters those text channels: image payloads in `fabric_exec` logs, results, and error text, in worker event lines, and in actor host events are replaced by a `{type: "image", mediaIndex, mimeType, redacted: true}` descriptor and hoisted out of band, so a nested `pi.read` image stays available to a multimodal model without pushing hundreds of KB of base64 into one serialized line. A child event line that only exceeds the 4 MB cap because it embeds raw base64 is sanitized instead of failing the run.
102
+ Fabric caps final `fabric_exec` output at 50,000 characters by default, which matches Pi's built-in 50KB tool ceiling. Failed executions get a tighter 20,000-character visible ceiling, and the complete output stays in the same private artifact. An oversized structured return shares that budget across every multiline section and preserves both ends with explicit omission markers. Unstructured output keeps its global beginning and end. Fabric writes the complete output to a mode-`0600` temporary artifact and includes the artifact path inside the visible ceiling. The model can then retrieve a targeted range without carrying the entire result. Type-check diagnostics use the same ceiling. Models should still filter noisy commands and return only useful evidence, because source-side projection preserves more relevant information than post-format truncation. When a later nested call fails after earlier calls completed, the error adds a bounded list of completed refs and paths. The model can inspect that list before repeating side effects. Nested outputs the guest did not return are never exposed. Raw media never enters those text channels: image payloads in `fabric_exec` logs, results, and error text, in worker event lines, and in actor host events are replaced by a `{type: "image", mediaIndex, mimeType, redacted: true}` descriptor and hoisted out of band, so a nested `pi.read` image stays available to a multimodal model without pushing hundreds of KB of base64 into one serialized line. A child event line that only exceeds the 4 MB cap because it embeds raw base64 is sanitized to avoid failing the run.
103
103
 
104
104
  ## Federated participant topology
105
105
 
@@ -0,0 +1,140 @@
1
+ # Background tasks and monitors
2
+
3
+ Fabric-managed `pi.bash` and `pi.powershell` commands have session-owned job IDs.
4
+ `background: true`, the shell hang threshold, or Ctrl+B twice detaches a command;
5
+ an explicit shell `timeout` remains a hard cap. Completed jobs have terminal states
6
+ (`exited`, `failed`, `killed`, `timed_out`), not the old `spilled` state. `exited`
7
+ means exit code zero, not that the user's assignment is verified.
8
+
9
+ ```ts
10
+ const result = await pi.bash({cmd: "bun run build", background: true, description: "Build bundle"});
11
+ return result; // details.taskId, pid, logPath when detached
12
+ ```
13
+
14
+ Completion sends a bounded, batched automated event to the **owning Pi session**.
15
+ The same mechanism works inside a Fabric-enabled child: it does not route child
16
+ shell output directly into the parent's Main. No LLM is used to wait for a process.
17
+ Events are outcomes, not user input or approval. Idle wakeups do not compete with
18
+ already queued messages. Aborted/error turns suspend wakeups until new user input;
19
+ branch navigation discards delivery from old-frontier jobs. Session shutdown/reload
20
+ closes the inbox before aborting jobs, so cleanup cannot start a new turn.
21
+ Print-mode processes do not stay alive indefinitely just to receive late events.
22
+
23
+ ## Agent awareness and yielding
24
+
25
+ Before each model request, Fabric projects one bounded live-task reminder into
26
+ context, independently of the returned `fabric_exec` value. Even if a program
27
+ discards the nested shell result, the owning agent can see that work is running.
28
+ The reminder is reconstructed from live session state after context compaction;
29
+ it is not a persisted transcript entry and **never triggers a turn** itself.
30
+ Unchanged task state keeps the same message; elapsed time and process output do
31
+ not churn it. It includes at most eight task IDs and short, quoted labels, with
32
+ an omitted count for additional jobs.
33
+
34
+ For ordinary detached commands and wake-enabled monitors, it tells the agent to
35
+ continue independent work or **end the turn if it needs their results**. Completion
36
+ (or a matching monitor event) can resume the owning agent; polling and sleep loops
37
+ are unnecessary. UI-only monitors are explicitly marked **no automatic wakeup**,
38
+ including on completion, so the agent must not yield expecting them to resume it.
39
+ Pending required results are not evidence that the assignment is complete.
40
+
41
+ Foreground, completed, stopping, and abandoned-branch jobs are excluded. Abort/error
42
+ suspension suppresses the reminder until new input, just like automatic delivery.
43
+ Reload/session shutdown removes the context hook along with the inbox. Awareness
44
+ works without a terminal and does not restore processes across Pi restarts.
45
+
46
+ ## Inspection and control
47
+
48
+ - `/fabric tasks` or **Ctrl+Alt+T** opens the lazy inspector. A single task opens
49
+ directly. `/fabric tasks <id-or-unique-prefix>` opens a specific task.
50
+ - The widget shows up to three tasks, elapsed time, and the command or short
51
+ description. It stays alive after the Fabric program returns. Completion hints
52
+ expire after 30 seconds; retained jobs remain in the inspector.
53
+ - Enter opens detail; arrows/PageUp/PageDown scroll the bounded output tail; G
54
+ follows the tail; x twice within three seconds stops; Esc backs out/closes.
55
+ - Elapsed time and time since last output are separate. A quiet shell is not
56
+ automatically classified as stuck. Opening/closing the inspector doesn't stop it.
57
+ - `ui.enabled` and `ui.widget` retain their existing meaning. Rendering is TUI-only;
58
+ task tools and notifications do not require a terminal.
59
+
60
+ Tasks are a discoverable provider, **not a new sandbox global**:
61
+
62
+ ```ts
63
+ return await tools.call({ref: "tasks.list", args: {}});
64
+ return await tools.call({ref: "tasks.get", args: {id: taskId}});
65
+ return await tools.call({ref: "tasks.stop", args: {id: taskId}});
66
+ ```
67
+
68
+ `get` returns metadata and an 8KB output tail and acknowledges pending agent delivery.
69
+ `stop` targets a stored job's abort controller, never an arbitrary or recycled PID.
70
+ Stopping a task does not wake the agent. Tasks are local to this runtime; IDs and
71
+ live processes are not restored across Pi restarts. Up to 256 completed handles
72
+ are retained for at most 24 hours. Logs use Fabric's private scratch retention.
73
+ The 1MiB in-memory tail and 8MiB disk log limits remain unchanged: a log is **not a
74
+ full-output archive**, and truncation is disclosed.
75
+
76
+ ## Programmatic wait and watch
77
+
78
+ For a bounded controller such as `jev.run`/`spawn`, use event-driven task calls:
79
+
80
+ ```ts
81
+ const receipt = await tools.call({ref:"tasks.wait",args:{id:taskId,timeoutMs:30000}});
82
+ // For tasks started with monitor (prefer delivery:"ui" for code-owned supervision):
83
+ const batch = await tools.call({ref:"tasks.watch",args:{id:taskId,after:0,timeoutMs:5000}});
84
+ return {receipt,batch};
85
+ ```
86
+
87
+ - `wait` returns `{task,output,timedOut}`. It waits for terminal metadata, then reads the bounded tail; inspect `task.status` and `task.exitCode`. A successful terminal read acknowledges pending delivery like `get`. A timeout returns the current snapshot, not a failed-process verdict.
88
+ - `watch` requires an opt-in monitor. The launch-time `monitor.match` is the case-sensitive literal filter. It returns `{task,reason,lines,omitted,nextCursor}` when a new batch exists, the task finishes, or the observation ceiling expires. `reason` is `event`, `finished`, or `timeout`; a final event may precede `finished` on the next call.
89
+ - Start `after` at 0; pass the returned `nextCursor` on later calls. Only the latest batch (at most eight previews) is retained. `omitted` counts matching previews lost since the supplied cursor, including intermediate overwritten batches. A cursor from the future is rejected. Truncation markers and monitor filtering/deduplication still apply: this is not a lossless stdout/RPC channel.
90
+ - Defaults: wait 30 seconds, watch 5 seconds; each accepts `timeoutMs` from 1 to 300000. Ready evidence returns immediately. Neither timeout nor cancellation stops or renews the task. Store shutdown rejects pending observations and removes their subscriptions.
91
+ - No polling, inference, or extra wakeups are performed by wait/watch. Ordinary background tasks and wake-enabled monitors retain their existing notification behavior. Main usually yields for those notifications; a controller can use UI-only monitors and wait/watch without a model turn per event.
92
+ - A detached task belongs to the Pi session, not the observing Jev program. Stopping that program cancels its pending wait/watch, not the task. Preserve IDs, set finite process deadlines, and explicitly call `tasks.stop` when required.
93
+
94
+ ## Opt-in monitors
95
+
96
+ ```ts
97
+ return await pi.bash({
98
+ cmd: "./scripts/watch-ci.sh", // emits a line only when something interesting changes
99
+ description: "Watch CI",
100
+ monitor: {
101
+ delivery: "wake", // REQUIRED: "ui" or "wake"
102
+ match: "CI:", // optional case-sensitive literal substring, not regex
103
+ timeoutMs: 300000,
104
+ intervalMs: 5000,
105
+ },
106
+ });
107
+ ```
108
+
109
+ A monitor implies background execution; `background: false` is rejected. The
110
+ ordinary shell runner, extension hooks, middleware filters, approvals and explicit
111
+ shell timeout still apply. `delivery: "ui"` only updates task inspection, including
112
+ completion; it never wakes the model. `"wake"` additionally delivers coalesced line
113
+ events and completion to the owning agent. Main configures/starts/stops/renews the
114
+ watch, while the process does the polling or subscribes to an external source.
115
+ Unchanged polls require **zero LLM turns** when the script emits nothing.
116
+
117
+ Limits:
118
+
119
+ - Five-minute default lifetime; 1 second minimum, 30 minutes maximum. Expiration
120
+ stops the command and produces one terminal outcome. Renewal is a new explicit
121
+ call; there is no automatic restart or hidden supervisor LLM.
122
+ - At most eight concurrent monitors per session. Output batches are spaced by
123
+ `intervalMs` (1–60 seconds, default 5 seconds). This is a **delivery** interval,
124
+ not the script's polling interval.
125
+ - UTF-8 chunks are framed incrementally. Lines retain their first 2048 characters;
126
+ matching applies to that bounded prefix. Empty lines and adjacent duplicate
127
+ matching lines are suppressed. Events keep at most eight 500-character previews
128
+ per batch; overflow is disclosed. A busy owner receives the newest batch per
129
+ task, not every historical line. Retained raw output is available in the log.
130
+ - Main interruption cancels monitors and suppresses automatic wakeups. Ordinary
131
+ detached commands retain their existing lifetime; their outcomes wait for input.
132
+ - Events and output are untrusted data. `wake` can incur model turns; use `ui` for
133
+ human-only observation and emit only meaningful changes for agent-facing watches.
134
+
135
+ Opaque captured shell overrides do not gain Fabric monitors: Fabric must not bypass
136
+ an SSH backend or security gate. Compatible [bash middleware](shell-middleware.md)
137
+ keeps its filtering/protection. PowerShell monitors require the host's tracked shell
138
+ operations API. The tasks provider is installed with the native Pi provider in full
139
+ code mode (and schema enforce, whose authorization rules still apply), not in
140
+ orchestration-only mode or closed-world managed hosts.
@@ -64,18 +64,18 @@ defers overflow and manual compactions.
64
64
  5. **Serialization is deterministic and bounded.** Identical branch entries and instructions produce byte-identical output. The rendered result is at most 32 KiB in UTF-8.
65
65
  6. **The nominal model window is the safety boundary.** Fabric never treats it as a target to fill. Fabric calibrates Pi's structural token estimate against `preparation.tokensBefore`, retains the largest closure-safe suffix within Pi's bounded `keepRecentTokens` continuity budget, and treats the configured occupancy ratio, Pi response reserve, estimator-error margin, and pre-compaction size as hard ceilings. Undocumented provider headroom never enters the budget.
66
66
 
67
- These invariants prevent summary-chain drift and deterministic
67
+ These invariants prevent compounding summary-chain drift, not all semantic
68
68
  forgetting. Pi replaces the previous rendered summary on each compaction.
69
- Fabric still re-derives the original goal, cumulative successful file
70
- addresses, error state, and user scope changes from raw branch history every
71
- time.
69
+ Fabric re-derives recent dialogue, historical requests, cumulative successful
70
+ file addresses, and error state from raw branch history every time. The
71
+ protected dialogue window is bounded continuity, not permanent decision memory.
72
72
 
73
73
  ## Loss model and memory
74
74
 
75
75
  Fabric compaction is **source-lossless and addressably lossless**. The model's bounded continuation view does not stay byte-for-byte lossless:
76
76
 
77
77
  - Compaction appends a marker. It never deletes or rewrites raw session JSONL. The active parent-linked session branch remains ground truth.
78
- - The model receives a bounded deterministic projection plus the recent raw continuity tail. Fabric preserves typed goals, declared Fabric run intent paired with aggregate outcomes, file operations, failures, status, and stable addresses through mechanical rules. Arbitrary old prose, tool-output bodies, and thinking may fall out of the inline view.
78
+ - The model receives a bounded deterministic projection plus the recent raw continuity tail. Fabric preserves role-labelled recent dialogue, historical requests, declared Fabric run intent paired with aggregate outcomes, file operations, failures, status, and stable addresses through mechanical rules. Arbitrary old prose, tool-output bodies, and thinking may fall out of the inline view.
79
79
  - Every sampled omission records a count and source entry-id range. `memory.expand` can re-read exact untruncated source by stable entry ID or operation address with source-hash and lineage checks.
80
80
  - The memory index remains derived and disposable. Compaction works without successful indexing, and it never treats an incomplete index as ground truth. Exact expansion reads session JSONL.
81
81
 
@@ -92,7 +92,8 @@ active branch entries ─┬─► live window ─► calibrated token budget
92
92
  ```
93
93
 
94
94
  - `normalize.ts` converts raw message and top-level `custom_message` entries to typed events. It selects custom content only from typed string or text parts, keeps JSON details depth/node/collection/string/byte bounded, and omits malformed details while otherwise valid content stays. Assistant thinking parts count as deliberation, so normalization never turns them into events. Summaries carry side effects and state, and truncated scratchpad text that could read as fact stays out. The compactor records how many thinking blocks it erased, so the omission stays auditable. Only `toolCallId` pairs each tool call with its result. A completed `fabric_exec` with a non-empty typed `display.name` contributes a bounded declared-intent event that carries its optional `display.description`, aggregate outcome, and call address. A `fabric_exec` result contributes nested events only through a valid `details.trace` V1 guard, or through the separate strict legacy `details.audits` adapter when no `trace` field exists.
95
- - `projections.ts` computes goal, file, operation-state, turn, status, and transcript views.
95
+ - `dialogue.ts` selects the last three eligible user exchanges and their preceding text-bearing assistant responses, independent of tool-event volume. Fully raw exchanges are excluded before the three-exchange limit; summarized and crossing exchanges remain eligible. It joins text parts from the same assistant entry, excludes thinking, and bounds complete multiline excerpts with explicit omitted-byte markers. It never infers acceptance or supersession from prose.
96
+ - `projections.ts` computes protected dialogue, historical request, file, operation-state, turn, status, and transcript views.
96
97
  - `enrichers.ts` permits deterministic optional annotations. Fabric ships no built-in enrichers.
97
98
  - `render.ts` independently bounds every rendered block and enforces the global UTF-8 limit.
98
99
  - `hook.ts` computes the live cut, selects cumulative source, emits v2 details, and implements Pi/pi-vcc precedence.
@@ -126,25 +127,61 @@ boundary fits, Fabric uses compact-all (`firstKeptEntryId: ""`), and no kept
126
127
  side remains to orphan either half. If the rendered deterministic summary
127
128
  itself would push the calibrated projection over the target, Fabric cancels
128
129
  the compaction to avoid persisting an expanding or over-budget result. If
129
- model metadata is unavailable, the legacy latest-turn closure-safe cut remains
130
- as a compatibility fallback.
130
+ model metadata is unavailable, Fabric keeps the legacy closure-safe whole-turn
131
+ cut only when that tail fits `keepRecentTokens` (20,000 by default). Oversized
132
+ turns use the same bounded suffix selector, including assistant boundaries;
133
+ if no legal suffix fits, Fabric compacts everything. Preparation settings
134
+ still apply without a model window. This fallback emits no fabricated model
135
+ window or calibrated budget metadata. Its bound is on structural raw-tail
136
+ estimates plus the bounded summary, not unknown fixed provider overhead.
131
137
 
132
138
  The live cut determines only what Pi keeps. The summary source is the raw
133
139
  active-branch prefix before that new boundary. Normalization skips earlier
134
- compaction and branch-summary prose within that prefix.
140
+ compaction and branch-summary prose within that prefix. For dialogue selection
141
+ only, Fabric also reads user/assistant text in the kept tail. If an exchange
142
+ crosses the cut, its summarized assistant response stays inline and its user
143
+ reply is addressed as `retained raw`, without duplicating the reply. Fully raw
144
+ exchanges need no summary copy and do not consume protected-window slots.
145
+ Newer raw instructions still take precedence over earlier summarized context.
146
+ This does not change cut selection.
147
+
148
+ Compacted trajectory handoffs use the resolved destination model window,
149
+ Fabric occupancy ceiling, and Pi's destination-specific compaction settings
150
+ when available. Settings are read at handoff use, respecting project trust.
151
+ Source-model usage does not calibrate a new executor; its budget uses structural
152
+ estimates until target usage exists. The finalized outer tool result and any
153
+ thinking-transfer digest enter the child log before compaction, so neither
154
+ escapes the cut and the outer call/result pair remains closure-safe. A failed
155
+ requested handoff compaction rejects the handoff and prevents the
156
+ uncompacted fork from launching. Without destination metadata, the bounded fallback applies.
135
157
 
136
158
  ## Bounded sections
137
159
 
138
- Fabric emits the original first user goal first. Later user scope changes and
139
- the potentially large file, operation-state, and earlier-turn collections use
140
- deterministic earliest-plus-latest sampling. Every omission records a count
141
- and a source entry-id range. File lines also carry the source call entry id.
142
-
143
- Rendered block limits include their headers:
144
-
145
- | Block | UTF-8 limit |
160
+ Fabric leads with protected recent dialogue, then explicit compaction requests
161
+ and historical requests. Each of the last three eligible summarized or
162
+ cross-boundary user exchanges gets up to 3968 bytes including role/address
163
+ headings. User text gets at least half the available text budget when needed;
164
+ short replies leave room for the preceding assistant response. Complete
165
+ multiline text survives whenever the exchange fits. Assistant replies are
166
+ labelled **Historical assistant response (not a verified outcome)**: they may
167
+ contain proposals, explanations, or old progress reports, not necessarily
168
+ current state or accepted instructions. New eligible exchanges can age an
169
+ exchange out; fully raw exchanges and more tool events alone cannot. There is
170
+ no reset keyword detector or task ledger.
171
+
172
+ Historical requests, files, operation-state, and earlier-turn collections still
173
+ use deterministic earliest-plus-latest sampling. Sampled omissions record a
174
+ count and source entry-id range. Protected excerpts instead report omitted
175
+ UTF-8 bytes alongside their entry addresses. Historical requests are evidence
176
+ of earlier instructions, not a reconstructed active mandate.
177
+
178
+ Rendered block ceilings include their headers. Historical blocks may receive
179
+ less under shared-budget pressure:
180
+
181
+ | Block | UTF-8 ceiling |
146
182
  | --- | ---: |
147
- | `[Session Goal]` | 4096 bytes |
183
+ | `[Recent user directions and discussion]` | 12288 bytes |
184
+ | `[Historical requests]` | 4096 bytes |
148
185
  | `[Compaction Request]` | 3072 bytes |
149
186
  | `[Files And Changes]` | 4608 bytes |
150
187
  | `[Fabric Activity]` | 2048 bytes |
@@ -154,16 +191,25 @@ Rendered block limits include their headers:
154
191
  | collapsed transcript | 5120 bytes |
155
192
  | footer | 1536 bytes |
156
193
 
157
- The limits sum below 32 KiB, leaving room for separators. A final UTF-8 guard
158
- enforces the global limit. Projection limits stay finite: 24 later goals, 24
159
- file addresses per operation kind, 32 operation-state records, 48 Fabric
160
- activity records, 32 earlier turns, and 40 transcript events. Omitted source
194
+ These ceilings are not simultaneous reservations. Fabric renders protected
195
+ dialogue and explicit requests first, then subtracts their actual UTF-8 size,
196
+ the footer, separators, and final newline from the unchanged 32 KiB ceiling.
197
+ Historical blocks keep their former ceilings whenever their capped content
198
+ fits the remaining space. Only under pressure are they reduced proportionally
199
+ to demand, reserving headers/omission markers or complete single-line blocks; sampling
200
+ slack passes to later blocks. Small or absent dialogue therefore does not
201
+ unconditionally shrink operational history. The raw-tail budget is unchanged,
202
+ and a final UTF-8 guard remains in place. Projection limits stay finite: three
203
+ eligible recent exchanges, 24 historical requests, 24 file addresses per
204
+ operation kind, 32 operation-state records, 48 Fabric activity records, 32
205
+ earlier turns, and 40 transcript events. Omitted source
161
206
  remains executable-addressable through entry-id ranges and the footer recall
162
207
  pointer.
163
208
 
164
209
  ## Sections
165
210
 
166
- - **Session Goal**: up to three bounded lines from the original first user message, followed by sampled later user scope changes.
211
+ - **Recent user directions and discussion**: complete bounded user/preceding-assistant exchanges, with roles and entry IDs. This is source evidence, not an inferred current-goal declaration.
212
+ - **Historical requests**: sampled older user requests, including the original objective once it leaves the recent window. The internal `goal` omission key remains for v2 compatibility.
167
213
  - **Compaction Request**: canonicalized, bounded custom instructions. See below.
168
214
  - **Files And Changes**: successful typed file-tool addresses grouped as Created, Written, Modified, or Read. `edit` counts as Modified. `write` counts as Written unless a typed result explicitly proves creation.
169
215
  - **Fabric Activity**: completed named `fabric_exec` runs as bounded `name → outcome` records that place an em dash between the name and the optional description, followed in source order by phases and significant non-file nested operations, including bash, agents, workflow, mesh, state, MCP, and extension refs. Named runs expose the exact assistant call entry ID while sourced raw, and their typed fact address after branch rehydration. Nested phases and operations expose stable `entryId/subordinal` addresses. The name and outcome are mandatory for a rendered run. The optional description decays first under tighter views.
@@ -183,7 +229,7 @@ through a valid typed `preserve` item or another typed state transition.
183
229
  The clean core retains only these mechanical text operations:
184
230
 
185
231
  - select text from typed user, assistant, top-level custom-message, tool-result, Fabric display-name/description, command-argument, error, phase, ref, and path fields.
186
- - split user text on literal newlines for bounded goal lines, or select the first line for one-line views.
232
+ - join text parts belonging to one assistant entry; retain multiline dialogue text or select the first line for historical one-line views.
187
233
  - trim/collapse whitespace and truncate by fixed character or UTF-8 byte limits.
188
234
  - quote bounded user/custom/assistant/tool/error text without interpreting its content.
189
235
  - compare typed action/path, action/command, or ref/JSON-arguments identities exactly for resolution.
@@ -224,6 +270,14 @@ validates scalar grammar and surrogate pairing. It checks the preserve count
224
270
  before it iterates or canonicalizes values. Plain Pi and manual instructions
225
271
  stay explicit bounded text and never run through the typed protocol parser.
226
272
 
273
+ Request rendering preserves complete items when they fit the 3 KiB block; it
274
+ does not apply the historical 1024-byte line cap or drop middle items. If the
275
+ block overflows, every item receives a bounded excerpt and explicit byte-loss
276
+ marker. `instructionPolicy.truncated` includes rendering loss, and
277
+ `renderedOmittedBytes` measures it separately from decoder truncation.
278
+ `preserve` remains one-shot input to that compaction, not a durable pin.
279
+ Neither `state.goal` nor state transitions are consulted to infer task intent.
280
+
227
281
  ## Compaction details v2
228
282
 
229
283
  New summaries emit `details.compactor: "fabric"` and `details.version: 2` with:
@@ -232,7 +286,8 @@ New summaries emit `details.compactor: "fabric"` and `details.version: 2` with:
232
286
  - branch, source-entry, event, and live-cut counts.
233
287
  - prior recognized Fabric v1/v2 marker counts.
234
288
  - per-projection omission counts, the typed preserve count (valid v1 requests cannot exceed the preserve limit), and the structural count of erased assistant thinking blocks.
235
- - instruction mode, canonicalization, source size, truncation, and preserve counts.
289
+ - instruction mode, canonicalization, source size, decoder/rendering truncation, rendered omitted bytes, and preserve counts.
290
+ - `omittedCounts.dialogueBytes` for protected dialogue clipping (UTF-8 bytes, not event count). These additive fields are optional when reading older v2 records.
236
291
  - stable kept/source entry-id addresses and the source timestamp.
237
292
  - when continuity budgeting is active: effective window, occupancy ceiling ratio/tokens, continuity target, reserve and reduction ceilings, the binding constraint, Pi reserve/recent settings, raw estimate, calibration scale, fixed overhead, raw-tail budget, retained raw tokens, and Fabric's `projectedTokensAfter`. Pi core independently recomputes its own `estimatedTokensAfter` after persisting the compaction. Legacy v2 records with `strategy: "adaptive"` remain recognized.
238
293
 
@@ -304,7 +359,10 @@ never reads branch summary prose. Later compaction can then resolve
304
359
  abandoned-branch failures against later exact successes, and custom context, files, and
305
360
  activity survive navigation or forks without any prose parsing. Pi supplies
306
361
  only the active path or the abandoned `entriesToSummarize` path to each
307
- compiler, so sibling branches cannot contaminate one another.
362
+ compiler, so sibling branches cannot contaminate one another. Branch rendering
363
+ also protects dialogue available in that supplied path, but the existing typed
364
+ branch envelope does not carry arbitrary assistant responses. This patch does
365
+ not extend decision retention across abandoned branches lacking raw dialogue.
308
366
 
309
367
  ## pi-vcc precedence
310
368
 
@@ -336,10 +394,15 @@ from rendered sections. QA probes follow the same bounded sampling policy as
336
394
  projections. The report checks directly rendered samples for content, and it
337
395
  validates omitted collections for count and range addressability. Mutation tests
338
396
  remove file, error, turn, latest Fabric run intent/outcome/address, and footer
339
- information to verify that the report detects loss.
397
+ information to verify that the report detects loss. Additional source-derived
398
+ probes require complete bounded, role-labelled recent dialogue excerpts: losing
399
+ a later architecture paragraph, constraint, estimate, or user selection fails
400
+ QA even when historical activity and recall pointers survive. When checking a
401
+ split exchange, pass all normalized events and the summarized-prefix cut index
402
+ so QA can see the retained user reply as well.
340
403
 
341
404
  Run:
342
405
 
343
406
  ```sh
344
- pnpm vitest run tests/compaction-qa.test.ts
407
+ bunx vitest run tests/compaction-qa.test.ts tests/compaction-dialogue.test.ts
345
408
  ```
@@ -140,6 +140,10 @@ Declare instances at the root of `fabric.json`:
140
140
 
141
141
  A definition may arrive after the configuration that references it. The unresolved instance stays `waiting` and lists `component:<name>` in `missing`. Component discovery activates the instance later. Once the runtime is active, trusted configuration edits reconcile automatically; `/fabric reload` is not required. When a later activation fails during a multi-entry reconciliation, Fabric rolls back the additions and replacements from that pass. Two live component records may never declare the same provider name. Fabric rejects the insertion or replacement before it disturbs either fiber.
142
142
 
143
+ ### External connectors
144
+
145
+ Connector packages own their component definitions, provider schemas, transports, credentials, and model-facing guidance. Fabric has no connector-specific registration table or required UI action vocabulary. Install the connector's ordinary Pi extension: it registers through `FABRIC_COMPONENT_REGISTER_EVENT` and answers `FABRIC_COMPONENT_DISCOVER_EVENT`. Configure it with the same generic `components.describe` / `plan` / `apply` surface used by every other component. A configured but undiscovered definition remains `waiting`; configuration never imports arbitrary modules on its own. These generic extension contracts remain available, but existing browser/macOS CLIs do not require a component bridge; see [harness CLI composition and migration](harnesses.md).
146
+
143
147
  ### Live configuration control
144
148
 
145
149
  Components are generic host primitives. Connector packages own browser, desktop, application, and transport behavior; neither component management nor Jev needs a built-in tool for each integration. Register the definition through the ordinary extension protocol, then configure instances through the same live control plane.
@@ -162,7 +166,7 @@ await components.apply({ ...plan.request, expectedRevision: plan.revision });
162
166
  - Apply runs the loader transaction before persistence. A failed activation leaves disk untouched. A failed compare-before-write triggers runtime compensation, without overwriting the external edit. Failed compensation is reported, never claimed successful. This is not an atomic transaction across multiple processes, files, or remote effects.
163
167
  - `components.reconcile()` re-reads trusted files without reinitializing Fabric. The active runtime also watches both file paths (250 ms stat interval, 50 ms debounce), including file creation, deletion, and atomic replacement. Content revisions suppress redundant reconciliation. The watcher reads only trusted layers and never repairs or quarantines malformed live files. Invalid edits retain the last applied state and appear in `components.list().configuration.error` and the UI. Its watchers and timers stop with the owning runtime.
164
168
  - Before first use, bootstrap stays idle: no watcher imports optional engines or starts connectors. First use rereads component configuration. Activation does not imply that a connector has connected or requested OS permissions; connector packages own explicit, lazy acquisition and health reporting.
165
- - `components.list().configuration` reports source paths, trust, selected layers, session override IDs, and warnings. An untrusted project file is reported as ignored without parsing it. Diagnostics report provenance rather than raw configuration documents; activation errors remain author-supplied.
169
+ - `components.list().configuration` reports source paths, trust, selected layers, session override IDs, and warnings. An untrusted project file is reported as ignored without parsing it. Diagnostics report provenance, not raw configuration documents; activation errors remain author-supplied.
166
170
  - Apply/reconcile are host-control operations, unavailable to committed guest views and in managed hosts or Schema enforce mode. Existing approval and schema policy gates still apply. Built-in `fabric.provider.*` components cannot be changed by this configuration API; their existing reload control remains separate.
167
171
 
168
172
  Replacement uses the existing retire-before-activate path, not zero-downtime migration. New calls resolve the new generation after commit; unrelated providers and Jev runs are not restarted. Existing committed views may continue using the retired generation until release. Removal uses the same **drain** policy, not immediate security revocation. Owners must retain supporting connections/processes until provider `close()`. Connector session IDs and observed handles must not be silently moved between generations. Cancellation after activation begins does not abandon commit/compensation and cannot undo already-issued external effects.
@@ -203,13 +203,13 @@ where absent values do not participate. Orchestration programs (`agents.run` / `
203
203
 
204
204
  `jev` configures TypeSafe typed judgments and session-owned foreground/background programs. It is enabled by default but makes no inference requests until called. `/login jev` stores API-key credentials through Pi; `TYPESAFE_API_KEY` and an explicitly configured `jev.credentialCommand` argv are also supported. Bare `jev.model` aliases use TypeSafe; `typesafe/...` or `~typesafe/...` model IDs use OpenRouter's decisions endpoint with the existing `openrouter` credential (`/login openrouter`, `OPENROUTER_API_KEY`, or `TYPESAFE_OPENROUTER_API_KEY`); `typesafe-ai/...` model IDs use Vercel AI Gateway's TypeSafe-compatible endpoint with the existing `vercel-ai-gateway` credential (`/login vercel-ai-gateway` or `AI_GATEWAY_API_KEY`). Never store the resolved secret in `fabric.json`.
205
205
 
206
- Host ceilings include `maxDurationMs`, `maxEvaluations`, `maxToolCalls`, `maxTokens`, `maxConcurrentRuns`, and `maxRetainedRuns`. Request controls are `model`, `requestTimeoutMs`, and `maxRequestBytes`. Per-program limits cannot raise these ceilings. See [Jev programs](jev.md) for defaults, typed schemas, cancellation, and the optional `browser-harness` component. Jev is unavailable in Schema enforce and managed-host modes.
206
+ Host ceilings include `maxDurationMs`, `maxEvaluations`, `maxToolCalls`, `maxTokens`, `maxConcurrentRuns`, and `maxRetainedRuns`. Request controls are `model`, `requestTimeoutMs`, and `maxRequestBytes`. Per-program limits cannot raise these ceilings. Per-program `maxEvaluations: 0` disables program inference for deterministic shell orchestration. See [Jev programs](jev.md) for typed decisions, shell/task composition, and cancellation; harness CLIs need no component configuration. Jev is unavailable in Schema enforce and managed-host modes.
207
207
 
208
208
  ## Components
209
209
 
210
210
  `components` is a root array of declarative supervised instances. Each `id` gives one instance a stable identity, and `component` names its definition in the versioned protocol. Fabric passes `config` to `activate(context, config)`. The `disabled` field removes an instance from the active graph and preserves its declaration. An empty array is the default, with a limit of 256 valid entries. The runtime installs enabled first-party providers as pinned `fabric.provider.*` components whose reserved IDs sit outside this array.
211
211
 
212
- Unknown definitions stay visible as waiting. They do not fail the Fabric runtime. Late discovery activates them. Once the runtime is active, trusted file edits reconcile automatically without `/fabric reload`; idle bootstrap remains lazy and first use rereads the component configuration. Invalid live edits keep the last working state and are never repaired or renamed by the watcher. `components.describe`, `components.plan`, `components.apply`, and `components.reconcile` provide the same control plane to programs. Changes default to session scope; global/project persistence is explicit, and untrusted project writes are rejected rather than redirected. Project component arrays replace global arrays; session overrides apply by ID on top. Definitions may declare `configSchema` for pre-activation validation. When a definition re-registers with `overwrite: true`, Fabric uses the same rollback-capable replacement path. See [components, effects, and committed capabilities](components.md#live-configuration-control).
212
+ Unknown definitions stay visible as waiting. They do not fail the Fabric runtime. Late discovery activates them. Once the runtime is active, trusted file edits reconcile automatically without `/fabric reload`; idle bootstrap remains lazy and first use rereads the component configuration. Invalid live edits keep the last working state and are never repaired or renamed by the watcher. `components.describe`, `components.plan`, `components.apply`, and `components.reconcile` provide the same control plane to programs. Changes default to session scope; global/project persistence is explicit, and untrusted project writes are rejected, never redirected. Project component arrays replace global arrays; session overrides apply by ID on top. Definitions may declare `configSchema` for pre-activation validation. When a definition re-registers with `overwrite: true`, Fabric uses the same rollback-capable replacement path. See [components, effects, and committed capabilities](components.md#live-configuration-control).
213
213
 
214
214
  ## Speculation
215
215
 
@@ -239,7 +239,7 @@ Unknown definitions stay visible as waiting. They do not fail the Fabric runtime
239
239
 
240
240
  `prewalk.thinking` sets the optional reasoning effort for the trajectory child executor. Its values are `off` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`, clamped to each model's supported levels. When you leave it unset, the executor inherits `agents.thinking`. In-place mode keeps Main's session level.
241
241
 
242
- `prewalk.alwaysRearm` defaults to `false`. When enabled, prewalk returns to an armed, taskless state after each completed handoff (in-place return or trajectory completion); a failed in-place return drops the arm instead of completing it. Every Main session then starts armed automatically, non-interactively from `prewalk.model`, and `/fabric reload` re-arms Main as well. Child agents and actors never auto-arm from inherited settings; explicit arming is unaffected. `/fabric prewalk --off` cancels the armed state until the next session start or reload. Turns that settle without a handoff never disarm prewalk, regardless of this setting. The settings UI labels an unset model **Ask each time**. Non-interactive sessions must configure a model. In-place mode does not require child agents. Trajectory mode requires `agents.enabled`. It shows child spawn, progress, nested tools, metrics, and completion in Main's Fabric activity UI.
242
+ `prewalk.alwaysRearm` defaults to `false`. When enabled, prewalk returns to an armed, taskless state after each completed handoff (in-place return or trajectory completion); a failed in-place return drops the arm without completing it. Every Main session then starts armed automatically, non-interactively from `prewalk.model`, and `/fabric reload` re-arms Main as well. Child agents and actors never auto-arm from inherited settings; explicit arming is unaffected. `/fabric prewalk --off` cancels the armed state until the next session start or reload. Turns that settle without a handoff never disarm prewalk, regardless of this setting. The settings UI labels an unset model **Ask each time**. Non-interactive sessions must configure a model. In-place mode does not require child agents. Trajectory mode requires `agents.enabled`. It shows child spawn, progress, nested tools, metrics, and completion in Main's Fabric activity UI.
243
243
 
244
244
  `prewalk.detectShellWrites` defaults to `true`. When armed, a `fabric_exec` boundary that ran a successful `pi.bash` or `pi.powershell` without an audited `pi.edit` / `pi.write` / `schema.commit` claims the handoff if file size or mtime stats drifted from the arm-time baseline. This routes shell heredocs and formatter binaries to the executor as well. The report's `trigger.files` lists the bounded drifted paths. An audited mutation consumes the shell-write drift window, so earlier edits cannot re-fire on a later read-only shell boundary. Fabric's own state directory never registers and does not consume the tracked-file cap. Other tool directories follow the project's ignore rules, so a Git work tree excludes them through `.gitignore`. Set this option to `false` to accept audited mutations only.
245
245
 
@@ -247,7 +247,7 @@ Unknown definitions stay visible as waiting. They do not fail the Fabric runtime
247
247
 
248
248
  `prewalk.compactOnReturn` defaults to `true`. When an in-place continuation settles, Fabric requests a compaction with the configured `compaction.engine` and commits it while the executor is still the active model. Main's restored model receives the compacted transcript. Set this option to `false` when Main must receive the complete transcript.
249
249
 
250
- Each in-place handoff captures Main's active model at the boundary and restores it when the continuation settles, when a new session is still on the executor, and when prewalk is cancelled (`/fabric prewalk --off` / `--disable`) or reloaded. A process that restarts while a continuation is still pending restores that captured model from the persisted continuation at the next session start, before the session auto-arms. Pi's public `setModel` extension API may also update the session model that a later session inherits, so restoring the captured Main model repairs that too. When the return itself fails, the arm is dropped instead of re-armed and the failure is reported: the captured Main model is preserved so a later session start or `/fabric reload` retries the return, auto-arm is skipped while Main is still on the executor, and an explicit `/fabric prewalk` arm overrides.
250
+ Each in-place handoff captures Main's active model at the boundary and restores it when the continuation settles, when a new session is still on the executor, and when prewalk is cancelled (`/fabric prewalk --off` / `--disable`) or reloaded. A process that restarts while a continuation is still pending restores that captured model from the persisted continuation at the next session start, before the session auto-arms. Pi's public `setModel` extension API may also update the session model that a later session inherits, so restoring the captured Main model repairs that too. When the return itself fails, the arm is dropped, not re-armed and the failure is reported: the captured Main model is preserved so a later session start or `/fabric reload` retries the return, auto-arm is skipped while Main is still on the executor, and an explicit `/fabric prewalk` arm overrides.
251
251
 
252
252
  ## Models
253
253
 
@@ -410,7 +410,7 @@ The host asks four typed Noul questions in one request: whether the exact action
410
410
 
411
411
  Lower thresholds permit more actions. **0 allows every valid judgment whose secrets and destructive verdicts are clean**, while 1 requires a safety probability of 1; a secrets or destructive probability at or above 0.5 escalates regardless of threshold, and so do missing user text, malformed answers, and errors. Reasons report the four numeric judgments and the effective threshold, not generated explanations. This is a policy cutoff, **not a calibrated security guarantee**. Use `ask` or `deny` when a probabilistic advisor is inappropriate.
412
412
 
413
- Jev receives the exact bounded arguments, the **latest user message and subsequent assistant tool calls**, and a bounded projection of earlier session actions - direct tool calls and nested Fabric actions with their arguments, host-recorded failures marked `"ok":false`. Earlier turns' prose, thinking, images, and tool outputs are excluded, so vague follow-ups cannot borrow authority from omitted history and retrieved content cannot instruct the classifier. Missing user text still requires explicit approval without inference. Oversized arguments, transcript clipping, and projection limits are disclosed to Jev as `evidence`/`session.truncated` facts instead of aborting classification (16,000 argument characters, 6,000 per user message/tool-call batch, 24,000 total evidence characters, 12,000 session-projection characters). Starting a new explicit user turn resets the conversational evidence window; the session-action projection spans the session.
413
+ Jev receives the exact bounded arguments, the **latest user message and subsequent assistant tool calls**, and a bounded projection of earlier session actions - direct tool calls and nested Fabric actions with their arguments, host-recorded failures marked `"ok":false`. Earlier turns' prose, thinking, images, and tool outputs are excluded, so vague follow-ups cannot borrow authority from omitted history and retrieved content cannot instruct the classifier. Missing user text still requires explicit approval without inference. Oversized arguments, transcript clipping, and projection limits are disclosed to Jev as `evidence`/`session.truncated` facts without aborting classification (16,000 argument characters, 6,000 per user message/tool-call batch, 24,000 total evidence characters, 12,000 session-projection characters). Starting a new explicit user turn resets the conversational evidence window; the session-action projection spans the session.
414
414
 
415
415
  Selecting this remote classifier authorizes sending that evidence to TypeSafe; it can contain private paths, code, or values from tool arguments. Do not select it for data that must stay local. Classification is a host-side request, not a recursive `jev.evaluate` tool call, so it does not recursively invoke the network approval policy. Normal tool permissions still apply after classification. Missing auth, malformed answers, HTTP errors, cancellation and timeouts never fall back to another model or auto-allow. They use the existing explicit approval flow (or deny in headless mode).
416
416
 
@@ -428,7 +428,7 @@ Run housekeeping begins on actual agent storage use (not manager startup), conti
428
428
 
429
429
  ### Temporary output and reader scratch
430
430
 
431
- New model-output spills and shell logs use private directories with a versioned `.fabric-scratch.json` ownership marker. They expire 24 hours after completion; oldest eligible caches may be removed sooner above **128 MiB or 256 items**, pooled across these two classes. Completed output is protected for its first hour. These aggregate limits are **soft** while files are active/recent or cannot be safely attributed. Model-output artifacts remain complete (not truncated), but their links are temporary.
431
+ New model-output spills and shell logs use private directories with a versioned `.fabric-scratch.json` ownership marker. They expire 24 hours after completion; oldest eligible caches may be removed sooner above **128 MiB or 256 items**, pooled across these two classes. Completed output is protected for its first hour. These aggregate limits are **soft** while files are active/recent or cannot be safely attributed. Model-output artifacts remain complete (not truncated). Their links are temporary.
432
432
 
433
433
  Shell hang tracking keeps a **1 MiB RAM tail per running command**, then releases it on finish. Completed handles are capped at **256** and expire after 24 hours on subsequent store access. Each shell log is capped at **8 MiB including notices**; it starts with the retained pre-spill tail, not necessarily the command's beginning. The returned notice and log header explicitly say this is bounded, **not a full-output archive**; reaching the disk cap appends a truncation notice. Further output continues to the normal shell consumer but not the log. PID files are retired on finish; logs remain subject to the cache policy. A disk write error also stops logging without interrupting command execution; bounded logs never promise completeness.
434
434
 
package/docs/foreman.md CHANGED
@@ -13,12 +13,12 @@ Fabric already has the required primitives for **session-bound, lifecycle-driven
13
13
  | Independent long-running controller with local state | `jev.spawn`, `JevProgramManager` in `src/jev/manager.ts` | One persistent QuickJS program; Main does not wait. Session-owned, not restart-durable. |
14
14
  | Observe coding progress at a decision point | `observe.events`, `program.nextEvent()`, `JevObservationHost` in `src/jev/observation.ts` | `turn_end` and `agent_settled` are the same local event names used by actors; no polling required. |
15
15
  | Bounded observation, history, and instruction evidence | Explicit `observe.include`, queue/age/character bounds; schema-bounded program input and local history | Settlement itself carries no transcript. Cache opted-in turn evidence; never assume hidden history access. Repository instructions are an explicitly supplied snapshot. |
16
- | Ten parallel semantic questions | One `jev.evaluate` request with ten `noul` questions; `src/jev/client.ts` validates answers | Implementation, tests, requirements, verification, readiness, progress, stuck, off-track, instruction drift, and human need. Code—not Jev—selects actions. |
16
+ | Ten parallel semantic questions | One `jev.evaluate` request with ten `noul` questions; `src/jev/client.ts` validates answers | Implementation, tests, requirements, verification, readiness, progress, stuck, off-track, instruction drift, and human need. Code selects actions; Jev does not. |
17
17
  | Continue, steer, or request another pass | `program.advise` / `jev.advise` with `steer` or `followUp` and explicit `triggerTurn` | Same delivery semantics as actors, with additional Jev freshness and feedback gates. Advice is asynchronous, not a pre-tool veto. |
18
18
  | Coding workers and independent verifiers | Existing `agents.spawn` / `agents.run`, tool allowlists, worktrees, status/log/wait | Main is the worker in this profile. Main can launch a verifier and execute approved targeted checks; the observer does not acquire worker-launch authority. |
19
19
  | Stop/retry an owned child | Existing `agents.stop`, then an explicitly bounded fresh `agents.spawn` | Stop is not rollback; retries are policy, not a primitive. The default sidecar does not stop Main or retry workers automatically. |
20
20
  | Structured progress and inspection | `program.emit`, `jev.status`, terminal envelopes | Latest 64 events in memory, not Foreman's atomic state file and append-only durable run store. |
21
- | Persistent coordination when actually needed | Existing `mesh.put` CAS state, `mesh.publish`, durable actors and participant subscriptions | Requires explicit capabilities and trusted mesh configuration. A Jev run is not a mesh participant or a durable subscription target. |
21
+ | Persistent coordination when needed | Existing `mesh.put` CAS state, `mesh.publish`, durable actors and participant subscriptions | Requires explicit capabilities and trusted mesh configuration. A Jev run is not a mesh participant or a durable subscription target. |
22
22
  | Bounded cost and interruption | Program limits, host ceilings, `jev.stop`, shared Main halt path | Main abort/Escape, tree navigation, and provider retirement cancel observers. Token usage is post-request, not a hard dollar cap. |
23
23
 
24
24
  `FabricRuntimeState.dispatchHostEvent` feeds both actors and Jev from the same lifecycle, while `haltAdvisors` stops both. Jev is available with mesh disabled. Normal reasoning actors may receive a sanitized recent transcript and use broader host events; Jev deliberately requires an explicit text projection and exposes a smaller event allowlist. That difference is an authorization boundary, not a reason to add implicit transcript access.
@@ -35,7 +35,7 @@ The skill ships an executable starter in both kernel trees. The Python entry poi
35
35
  4. `FINISH_REVIEW` is only a candidate for Main's acceptance review. Main must inspect independent verifier findings and actual targeted test/build results before claiming completion. Semantic scores and verifier prose are not passing checks.
36
36
  5. The observer retires on new input, escalation, a finish-review candidate, inference failure, or its budgets. Terminal `completed` means the program returned valid output, not that the software job is complete. Main inspects `result.outcome`.
37
37
 
38
- Requested limits are 15 minutes, 20 assessments, 600 host calls, 40,000 reported tokens, and 120 consumed events, clamped to trusted host ceilings. Inference failure ends the profile with a labeled escalation rather than spinning on 429/529 or guessing an answer. Read [Jev's budget and auth rules](jev.md) before launch. No live API test is necessary to install or verify the skill.
38
+ Requested limits are 15 minutes, 20 assessments, 600 host calls, 40,000 reported tokens, and 120 consumed events, clamped to trusted host ceilings. Inference failure ends the profile with a labeled escalation, without spinning on 429/529 or guessing an answer. Read [Jev's budget and auth rules](jev.md) before launch. No live API test is necessary to install or verify the skill.
39
39
 
40
40
  ### Delivery is deliberately bounded
41
41
 
@@ -47,7 +47,7 @@ Escalation and limit outcomes stop the observer, not Main. Even an accepted paus
47
47
 
48
48
  - Main replaces the Codex App Server worker. Existing Pi/Claude runners can be composed separately; no new Codex App Server transport is implied.
49
49
  - Turn/settlement boundaries replace streamed subprocess output and periodic observations, as requested. Silence causes no inference.
50
- - Bounded selected evidence replaces automatic Git/shell observation. The program has no shell authority and no secret/history access. If the instruction snapshot changes, review and explicitly replace the observer rather than assume it refreshed.
50
+ - Bounded selected evidence replaces automatic Git/shell observation. The program has no shell authority and no secret/history access. If the instruction snapshot changes, review and explicitly replace the observer; do not assume it refreshed.
51
51
  - Jev programs do not survive host restarts. In-memory status is not durable recovery. Existing mesh primitives can store explicit checkpoints, but they do not resume a lost QuickJS context or make effects exactly once.
52
52
  - The skill does not weaken feedback prevention to reproduce an unbounded factory loop. Use a reasoning actor when persistent conversational supervision with its different context/lifecycle contract is desired.
53
53
 
@@ -0,0 +1,95 @@
1
+ # Harness CLI composition
2
+
3
+ Fabric follows `jev-fabric`'s shell-first boundary: compose existing programs,
4
+ not application-specific tool bridges. Browser Harness JS and macOS Harness own
5
+ their connections, persistent state, native APIs, permission checks, and guarded
6
+ interaction. Fabric supplies its existing shell and task supervision; Jev is an
7
+ optional typed decision-maker. No harness-specific Fabric extension, SDK module
8
+ path, component entry, or provider registration is required.
9
+
10
+ ## Browser Harness JS
11
+
12
+ Load the harness-owned `cdp` skill. After the user authorizes a browser scope,
13
+ use its normal CLI through `pi.bash`, with `--no-auto-allow` so Fabric does not
14
+ silently approve a browser debugging prompt. For a reviewed snippet saved by
15
+ `pi.write`, the command shape is:
16
+
17
+ ```ts
18
+ return await pi.bash({cmd:"browser-harness-js --no-auto-allow < ./observe-browser.js",timeout:15,settle:true});
19
+ ```
20
+
21
+ This is a composition pattern, not permission to connect or scan. The CLI owns a
22
+ persistent daemon, session, and explicit target routing; Fabric does not import
23
+ the SDK or create a second connection. Use the harness's authorized connection
24
+ setup and guarded controller at unknown UI boundaries. Preserve explicit target
25
+ scope and fresh observation handles. The CLI prints raw results, not a Fabric
26
+ provider envelope: validate the documented result, exit status, and size before
27
+ parsing. Empty output is not automatically valid JSON or proof of success.
28
+
29
+ A short CLI process exiting does not stop its daemon. Follow the harness's own
30
+ cleanup contract; stopping a Fabric task is not rollback or daemon shutdown.
31
+ Do not stop a shared daemon owned by another workflow.
32
+
33
+ ## macOS Harness
34
+
35
+ Load the harness-owned `macos-harness` skill. Native access needs separately
36
+ approved OS permissions and explicit already-running app scope. The guarded
37
+ server is an ordinary command:
38
+
39
+ ```sh
40
+ macos-harness serve --app com.apple.TextEdit
41
+ ```
42
+
43
+ Keep **one** process alive for a multi-step workflow. Its stdin/stdout protocol
44
+ is newline-terminated UTF-8 JSON, `{id,method,args}` to `{id,result}` or
45
+ `{id,error}`; stderr contains diagnostics. A reviewed task-specific native script
46
+ can own the child, serialize requests, validate response IDs/errors, enforce
47
+ bounds/deadlines, and close stdin/terminate it during cleanup. Run that script
48
+ through the authorized shell, e.g. `pi.bash({cmd:"node ./desktop-task.mjs"})`.
49
+ This does not change Fabric's configured kernel or grant an unrestricted fallback.
50
+
51
+ `pi.bash` is not an interactive stdin handle. Do not launch `serve` as an isolated
52
+ background command and expect `tasks.watch` to become RPC. Monitors and log tails
53
+ are bounded observations and may omit/truncate data. Do not restart the server
54
+ between observe and act: native controller handles do not survive process exit.
55
+ For one-shot deterministic work, the harness's ordinary CLI/library can keep the
56
+ whole observe/act/check sequence in one invocation.
57
+
58
+ ## Supervision and decisions
59
+
60
+ Use [background tasks](background-tasks.md) for finite shell deadlines,
61
+ `tasks.wait`, literal-filtered `tasks.watch`, and `tasks.stop`. UI-only monitors
62
+ never wake Main or invoke Jev. A program may explicitly evaluate a remaining
63
+ semantic question over minimized output; see [Jev](jev.md). Validate exact status
64
+ and protocol facts first, map typed answers to code-owned branches, and verify
65
+ postconditions after effects. Never run a model answer as shell code.
66
+
67
+ Preserve the harness's guards:
68
+
69
+ - `executed` means dispatched, not goal success; check fresh authoritative state.
70
+ - `stale` means re-observe; never reuse stale handles.
71
+ - `blocked` means resolve permission/scope or stop; raw APIs cannot bypass it.
72
+ - `outcome_unknown` means inspect, never blindly replay.
73
+ - Never approve permission dialogs, activate apps, or move the physical cursor
74
+ as a workaround. Keep secrets and unrelated private data out of model state.
75
+
76
+ Shell execution runs with host privileges. QuickJS program isolation is not a
77
+ sandbox around the shell or a substitute for the harness's authorization rules.
78
+ Cancellation is not rollback; detached processes/daemons have separate lifetimes.
79
+
80
+ ## Migration
81
+
82
+ Remove unneeded `browser-harness` / `macos-harness` entries from your Fabric
83
+ configuration and stop loading their optional `pi/` extensions when switching
84
+ to CLI composition. Do this deliberately after stopping their work: no automatic
85
+ configuration rewrite or cleanup is performed. Replace `browser.*` / `macos.*`
86
+ program grants with only the shell/task actions actually needed.
87
+
88
+ There are no concrete harness exports in `pi-fabric/jev` and no compatibility
89
+ bridge to maintain. The generic [component protocol](components.md) remains
90
+ available for independently installed providers; this change does not remove it
91
+ or modify the sibling harness repositories. Harness-specific docs/skills in those
92
+ packages remain authoritative for their standalone CLIs.
93
+
94
+ Offline checks use local fixture processes and mocked judgments. They do not
95
+ connect to a personal browser, control apps, install tools, or spend API credits.