pi-fabric 0.130.2 → 0.131.0

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 (225) hide show
  1. package/dist/activity/store.d.ts +2 -1
  2. package/dist/activity/store.d.ts.map +1 -1
  3. package/dist/actors/directory.d.ts.map +1 -1
  4. package/dist/actors/global-registry.d.ts.map +1 -1
  5. package/dist/actors/manager.d.ts +4 -3
  6. package/dist/actors/manager.d.ts.map +1 -1
  7. package/dist/actors/mesh-monitor.d.ts +2 -0
  8. package/dist/actors/mesh-monitor.d.ts.map +1 -1
  9. package/dist/actors/name-policy.d.ts +3 -0
  10. package/dist/actors/name-policy.d.ts.map +1 -0
  11. package/dist/actors/registry-store.d.ts +1 -1
  12. package/dist/actors/registry-store.d.ts.map +1 -1
  13. package/dist/agents/agent-files.d.ts +8 -0
  14. package/dist/agents/agent-files.d.ts.map +1 -1
  15. package/dist/agents/agent-files.js +48 -3
  16. package/dist/agents/agent-files.js.map +2 -2
  17. package/dist/agents/child-skills.d.ts +60 -0
  18. package/dist/agents/child-skills.d.ts.map +1 -0
  19. package/dist/agents/child-skills.js +94 -0
  20. package/dist/agents/child-skills.js.map +7 -0
  21. package/dist/agents/clone-first-worktree.d.ts +6 -0
  22. package/dist/agents/clone-first-worktree.d.ts.map +1 -1
  23. package/dist/agents/cow-clone.d.ts.map +1 -1
  24. package/dist/agents/handoff.d.ts +12 -2
  25. package/dist/agents/handoff.d.ts.map +1 -1
  26. package/dist/agents/manager.d.ts +4 -1
  27. package/dist/agents/manager.d.ts.map +1 -1
  28. package/dist/agents/model-pin-guard.d.ts +27 -0
  29. package/dist/agents/model-pin-guard.d.ts.map +1 -0
  30. package/dist/agents/model-pin-guard.js +86 -0
  31. package/dist/agents/model-pin-guard.js.map +7 -0
  32. package/dist/agents/model-pin.d.ts +25 -0
  33. package/dist/agents/model-pin.d.ts.map +1 -0
  34. package/dist/agents/provider-bridge.d.ts +5 -4
  35. package/dist/agents/provider-bridge.d.ts.map +1 -1
  36. package/dist/agents/provider-bridge.js +32 -4
  37. package/dist/agents/provider-bridge.js.map +3 -3
  38. package/dist/agents/request.d.ts.map +1 -1
  39. package/dist/agents/service-schema.d.ts.map +1 -1
  40. package/dist/agents/types.d.ts +25 -0
  41. package/dist/agents/types.d.ts.map +1 -1
  42. package/dist/agents/worktree-manager.d.ts.map +1 -1
  43. package/dist/agents.js +6 -5
  44. package/dist/agents.js.map +2 -2
  45. package/dist/audit/details.d.ts +4 -0
  46. package/dist/audit/details.d.ts.map +1 -1
  47. package/dist/chunks/{chunk-SBAROA4Y.js → chunk-2RWNVCFD.js} +17 -1
  48. package/dist/chunks/{chunk-SBAROA4Y.js.map → chunk-2RWNVCFD.js.map} +2 -2
  49. package/dist/chunks/{chunk-6O6UWMBO.js → chunk-36XQFTEN.js} +2 -2
  50. package/dist/chunks/chunk-3PKZSIRA.js +1312 -0
  51. package/dist/chunks/chunk-3PKZSIRA.js.map +7 -0
  52. package/dist/chunks/{chunk-JJXUOXI5.js → chunk-4KX6BIPL.js} +17 -2
  53. package/dist/chunks/chunk-4KX6BIPL.js.map +7 -0
  54. package/dist/chunks/{chunk-EYHTTMSM.js → chunk-4PBW54I2.js} +5 -5
  55. package/dist/chunks/{chunk-WTIF3MIM.js → chunk-56NMRVTV.js} +8 -8
  56. package/dist/chunks/{chunk-WQFG7ZVC.js → chunk-5BOTHX47.js} +48 -13
  57. package/dist/chunks/chunk-5BOTHX47.js.map +7 -0
  58. package/dist/chunks/chunk-5QJFDKPN.js +179 -0
  59. package/dist/chunks/chunk-5QJFDKPN.js.map +7 -0
  60. package/dist/chunks/chunk-6HO2IUQ5.js +104 -0
  61. package/dist/chunks/chunk-6HO2IUQ5.js.map +7 -0
  62. package/dist/chunks/{chunk-NF6W327N.js → chunk-7CIES6X2.js} +9 -2
  63. package/dist/chunks/chunk-7CIES6X2.js.map +7 -0
  64. package/dist/chunks/{chunk-KDX3762L.js → chunk-DGERP4VL.js} +4 -4
  65. package/dist/chunks/{chunk-K3ZWBUUL.js → chunk-IOGDTIGN.js} +13 -13
  66. package/dist/chunks/chunk-IOGDTIGN.js.map +7 -0
  67. package/dist/chunks/{chunk-UXIBKMUM.js → chunk-KIFOEBYJ.js} +4 -4
  68. package/dist/chunks/{chunk-D5224P2R.js → chunk-LKYLD5SN.js} +7 -7
  69. package/dist/chunks/chunk-NENQZCGW.js +45 -0
  70. package/dist/chunks/chunk-NENQZCGW.js.map +7 -0
  71. package/dist/chunks/{chunk-YTYLKL3Z.js → chunk-OJ4HAALD.js} +8 -8
  72. package/dist/chunks/{chunk-TBB7F7WS.js → chunk-PQVUMJ5J.js} +84 -18
  73. package/dist/chunks/chunk-PQVUMJ5J.js.map +7 -0
  74. package/dist/chunks/chunk-UD7LFV43.js +28 -0
  75. package/dist/chunks/chunk-UD7LFV43.js.map +7 -0
  76. package/dist/chunks/{chunk-CH2QMORW.js → chunk-UFMYN5TA.js} +2 -2
  77. package/dist/chunks/chunk-V4OW2ULC.js +422 -0
  78. package/dist/chunks/chunk-V4OW2ULC.js.map +7 -0
  79. package/dist/chunks/{chunk-6C2DMTQC.js → chunk-VNWQIGQL.js} +552 -145
  80. package/dist/chunks/chunk-VNWQIGQL.js.map +7 -0
  81. package/dist/chunks/{chunk-OA5SJT2T.js → chunk-WGMCNCP6.js} +183 -82
  82. package/dist/chunks/chunk-WGMCNCP6.js.map +7 -0
  83. package/dist/chunks/{chunk-HAHRJMWY.js → chunk-WWTGWGH7.js} +6 -6
  84. package/dist/chunks/{chunk-F4HL6KJR.js → chunk-X7QETPBC.js} +7 -7
  85. package/dist/chunks/{chunk-SSRSCT2M.js → chunk-XFOSUGLU.js} +4 -4
  86. package/dist/chunks/{chunk-4VGB6HMU.js → chunk-ZFWICFNJ.js} +23 -18
  87. package/dist/chunks/{chunk-4VGB6HMU.js.map → chunk-ZFWICFNJ.js.map} +2 -2
  88. package/dist/commands/fabric-handler.d.ts.map +1 -1
  89. package/dist/commands/fabric-handler.js +43 -7
  90. package/dist/commands/fabric-handler.js.map +2 -2
  91. package/dist/compaction/claim-events.js +2 -2
  92. package/dist/components/configuration.js +3 -3
  93. package/dist/config.d.ts +9 -1
  94. package/dist/config.d.ts.map +1 -1
  95. package/dist/core/action-registry.js +4 -4
  96. package/dist/core/model-aliases.d.ts +22 -0
  97. package/dist/core/model-aliases.d.ts.map +1 -0
  98. package/dist/core/model-resolution.d.ts +41 -20
  99. package/dist/core/model-resolution.d.ts.map +1 -1
  100. package/dist/core/prompt-guidance.js +9 -4
  101. package/dist/core/prompt-guidance.js.map +2 -2
  102. package/dist/core/system-guidance.d.ts.map +1 -1
  103. package/dist/decisions/command.d.ts +2 -1
  104. package/dist/decisions/command.d.ts.map +1 -1
  105. package/dist/decisions/command.js +31 -11
  106. package/dist/decisions/command.js.map +2 -2
  107. package/dist/decisions/events.js +2 -1
  108. package/dist/decisions/events.js.map +1 -1
  109. package/dist/decisions/host.d.ts +8 -0
  110. package/dist/decisions/host.d.ts.map +1 -1
  111. package/dist/decisions/render.d.ts +44 -0
  112. package/dist/decisions/render.d.ts.map +1 -0
  113. package/dist/durable/agent.d.ts +6 -0
  114. package/dist/durable/agent.d.ts.map +1 -1
  115. package/dist/durable/worker-host.d.ts.map +1 -1
  116. package/dist/durable/worker-host.js +7 -1283
  117. package/dist/durable/worker-host.js.map +4 -4
  118. package/dist/durable/worker-options.d.ts +2 -0
  119. package/dist/durable/worker-options.d.ts.map +1 -1
  120. package/dist/durable/worker-role-seed.d.ts +82 -0
  121. package/dist/durable/worker-role-seed.d.ts.map +1 -0
  122. package/dist/durable/worker.js +10 -1
  123. package/dist/durable/worker.js.map +2 -2
  124. package/dist/durable-extension.d.ts +1 -1
  125. package/dist/durable-extension.js +1 -1
  126. package/dist/durable-extension.js.map +1 -1
  127. package/dist/durable-host.d.ts +8 -0
  128. package/dist/durable-host.d.ts.map +1 -0
  129. package/dist/durable-host.js +20 -0
  130. package/dist/durable-host.js.map +7 -0
  131. package/dist/entropy/index.js +1 -1
  132. package/dist/execution-service.d.ts.map +1 -1
  133. package/dist/extension-bootstrap.d.ts.map +1 -1
  134. package/dist/extension-bootstrap.js +16 -16
  135. package/dist/extension.d.ts.map +1 -1
  136. package/dist/fabric-exec-tool.d.ts.map +1 -1
  137. package/dist/fabric-runtime-state.d.ts +2 -0
  138. package/dist/fabric-runtime-state.d.ts.map +1 -1
  139. package/dist/fabric-runtime-state.js +203 -124
  140. package/dist/fabric-runtime-state.js.map +2 -2
  141. package/dist/fabric-state.d.ts +26 -1
  142. package/dist/fabric-state.d.ts.map +1 -1
  143. package/dist/index.js +20 -16
  144. package/dist/index.js.map +1 -1
  145. package/dist/jev/client.js +2 -2
  146. package/dist/jev/observation.js +3 -3
  147. package/dist/jev.js +7 -7
  148. package/dist/protocol.d.ts +84 -0
  149. package/dist/protocol.d.ts.map +1 -1
  150. package/dist/protocol.js +5 -1
  151. package/dist/providers/agents-actions.d.ts.map +1 -1
  152. package/dist/providers/agents-provider.d.ts +3 -0
  153. package/dist/providers/agents-provider.d.ts.map +1 -1
  154. package/dist/providers/jev-provider.js +7 -7
  155. package/dist/residency/host.d.ts.map +1 -1
  156. package/dist/residency/host.js +13 -10
  157. package/dist/residency/pi-entry.js +13 -10
  158. package/dist/residency/pi-entry.js.map +1 -1
  159. package/dist/runtime/core-override-guest-types.js +2 -2
  160. package/dist/runtime/cpython-runtime.js +3 -3
  161. package/dist/runtime/exec-journal.js +3 -3
  162. package/dist/runtime/guest-types.d.ts +1 -1
  163. package/dist/runtime/guest-types.d.ts.map +1 -1
  164. package/dist/runtime/guest-types.js +1 -1
  165. package/dist/runtime/monty-runtime.js +6 -6
  166. package/dist/runtime/node-process-runtime.js +5 -5
  167. package/dist/runtime/quickjs-runtime.js +3 -3
  168. package/dist/runtime/typescript-kernel.js +11 -11
  169. package/dist/storage/retention.d.ts.map +1 -1
  170. package/dist/type-error-guidance.js +1 -1
  171. package/dist/ui/conversation-chrome.js +2 -2
  172. package/dist/ui/conversation.js +10 -10
  173. package/dist/ui/dashboard.d.ts.map +1 -1
  174. package/dist/ui/dashboard.js +14 -12
  175. package/dist/ui/dashboard.js.map +2 -2
  176. package/dist/ui/settings-sections-presentation.d.ts.map +1 -1
  177. package/dist/ui/settings.js +12 -9
  178. package/dist/ui/settings.js.map +2 -2
  179. package/dist/ui/widget.d.ts.map +1 -1
  180. package/dist/verified/generated/actor-name.d.ts +4 -0
  181. package/dist/verified/generated/actor-name.js +17 -0
  182. package/dist/verified/generated/manifest.json +11 -3
  183. package/dist/worker/options.d.ts.map +1 -1
  184. package/dist/worker/options.js +20 -0
  185. package/dist/worker/options.js.map +2 -2
  186. package/dist/worker.js +57 -8
  187. package/dist/worker.js.map +2 -2
  188. package/docs/actor-name-policy-handoff.md +5 -0
  189. package/docs/agents.md +64 -5
  190. package/docs/audit-trace.md +2 -1
  191. package/docs/components.md +1 -1
  192. package/docs/configuration.md +7 -4
  193. package/docs/decisions.md +47 -2
  194. package/docs/durable-pi.md +162 -2
  195. package/docs/interface.md +1 -1
  196. package/docs/providers.md +1 -1
  197. package/docs/verified-kernels.md +1 -0
  198. package/package.json +5 -1
  199. package/proofs/actor-name.ts +27 -0
  200. package/proofs/index.ts +2 -0
  201. package/scripts/verified-kernels.ts +1 -1
  202. package/skillsets/python/fabric-exec/references/agents.md +6 -4
  203. package/skillsets/typescript/fabric-exec/references/agents.md +6 -3
  204. package/dist/chunks/chunk-6C2DMTQC.js.map +0 -7
  205. package/dist/chunks/chunk-JJXUOXI5.js.map +0 -7
  206. package/dist/chunks/chunk-K3ZWBUUL.js.map +0 -7
  207. package/dist/chunks/chunk-KJZAOENY.js +0 -212
  208. package/dist/chunks/chunk-KJZAOENY.js.map +0 -7
  209. package/dist/chunks/chunk-NF6W327N.js.map +0 -7
  210. package/dist/chunks/chunk-OA5SJT2T.js.map +0 -7
  211. package/dist/chunks/chunk-TBB7F7WS.js.map +0 -7
  212. package/dist/chunks/chunk-WQFG7ZVC.js.map +0 -7
  213. package/dist/chunks/chunk-ZLNJDTCN.js +0 -226
  214. package/dist/chunks/chunk-ZLNJDTCN.js.map +0 -7
  215. /package/dist/chunks/{chunk-6O6UWMBO.js.map → chunk-36XQFTEN.js.map} +0 -0
  216. /package/dist/chunks/{chunk-EYHTTMSM.js.map → chunk-4PBW54I2.js.map} +0 -0
  217. /package/dist/chunks/{chunk-WTIF3MIM.js.map → chunk-56NMRVTV.js.map} +0 -0
  218. /package/dist/chunks/{chunk-KDX3762L.js.map → chunk-DGERP4VL.js.map} +0 -0
  219. /package/dist/chunks/{chunk-UXIBKMUM.js.map → chunk-KIFOEBYJ.js.map} +0 -0
  220. /package/dist/chunks/{chunk-D5224P2R.js.map → chunk-LKYLD5SN.js.map} +0 -0
  221. /package/dist/chunks/{chunk-YTYLKL3Z.js.map → chunk-OJ4HAALD.js.map} +0 -0
  222. /package/dist/chunks/{chunk-CH2QMORW.js.map → chunk-UFMYN5TA.js.map} +0 -0
  223. /package/dist/chunks/{chunk-HAHRJMWY.js.map → chunk-WWTGWGH7.js.map} +0 -0
  224. /package/dist/chunks/{chunk-F4HL6KJR.js.map → chunk-X7QETPBC.js.map} +0 -0
  225. /package/dist/chunks/{chunk-SSRSCT2M.js.map → chunk-XFOSUGLU.js.map} +0 -0
package/docs/agents.md CHANGED
@@ -32,13 +32,24 @@ You can give `fabric_exec` optional `agentBudget` and `tokenBudget` limits. Conf
32
32
 
33
33
  `agents.wait`/`join`, terminal `agents.status`, and cleanup acknowledge the result and retract any pending notification, including completion that arrived before the wait. Running status and UI/list polling do not acknowledge results. Acknowledgment means the Fabric program received the result: return the relevant outcome to Main when it needs to reason about it. Prefer `wait` over a polling loop.
34
34
 
35
+ ### Queued spawns
36
+
37
+ By default `agents.spawn` waits inside the call for a free `agents.maxConcurrent` slot. A program that spawns more children than the limit blocks there, and if its deadline passes first, the waiting spawns never launch and the program cannot return the ids of the runs that did.
38
+
39
+ `agents.spawn({ ..., queue: true })` returns at once with `status: "queued"` and the run's `id`. The run starts when a slot frees, first come first served, even after the program that spawned it has ended. Its `timeoutMs` counts from its start, not from the spawn call. Meanwhile `agents.wait`, `agents.status`, and `agents.list` accept the id and report `queued`; `wait` resolves with the final result once the run starts and finishes. `agents.stop` on a queued run cancels it without launching and returns a `stopped` result. `agents.cleanup` removes a cancelled queued run; a queued run must be stopped first. `agents.steer`, `agents.followUp`, and `agents.log` need a started run and throw until then. If the launch fails after admission (an unavailable model, a worktree error), the run ends `failed` with that error and a detached run reports it like any other completion. Request validation errors still reject the `spawn` call itself. `queue` is not available with `residency: "durable"`. A [background program](background-tasks.md) (`fabric_exec` with `background: true`) is the other way to keep a long spawn loop from blocking Main, but each spawn in it still waits for a slot.
40
+
41
+ ```ts
42
+ const handles = await Promise.all(tasks.map((task) => agents.spawn({ task, queue: true })));
43
+ return handles.map((handle) => handle.id);
44
+ ```
45
+
35
46
  Durable spawns use the same inbox. Undelivered envelopes survive disconnects; receipts survive reconnects. Escape or an errored Main turn parks pending results until new input; Main does not restart immediately. Explicit lifecycle subscriptions, actor messages, and trajectory handoffs retain their separate delivery policies. A terminal run can still report incomplete work; Main must inspect its result.
36
47
 
37
48
  ### Stalled Pi error recovery
38
49
 
39
50
  After a failed or aborted assistant response (including `Error: Terminated`), Fabric allows Pi's own retries to recover. If no recovery output arrives for 60 seconds, the worker fails the run with the original error and terminates the child, escalating from SIGTERM to SIGKILL after another 5 seconds. Repeated retry announcements, errors, or lifecycle events do not extend this deadline. Nonempty text/thinking/tool-call deltas refresh it; a successful assistant response clears it. Healthy inference and tool execution are not subject to this recovery timer, and the overall run deadline still applies.
40
51
 
41
- Fabric handles exhausted retries explicitly without waiting forever on an earlier `willRetry` flag. Child shutdown after RPC stdin closes is also bounded: 5 seconds for graceful exit, then SIGTERM and a further 5 seconds before SIGKILL. These failures settle `agents.wait`/`join` and notify detached callers normally; they do not automatically replay potentially side-effecting work. Already-running workers must be stopped and respawned to use the fix.
52
+ Fabric handles exhausted retries explicitly without waiting forever on an earlier `willRetry` flag. Child shutdown after RPC stdin closes is also bounded: 5 seconds for graceful exit, then SIGTERM and a further 5 seconds before SIGKILL. When the child already gave its final answer, a slow exit does not fail the run: it stays `completed` with that answer, and the run log records a `fabric_exit_warning` event. Without a final answer (an error, or a last message that stopped on a tool call), the run fails. These failures settle `agents.wait`/`join` and notify detached callers normally; they do not automatically replay potentially side-effecting work. Already-running workers must be stopped and respawned to use the fix.
42
53
 
43
54
  ### Stalled Pi stream
44
55
 
@@ -64,7 +75,36 @@ The 4,194,304-character guard still applies to other event data, including a sin
64
75
 
65
76
  Use `agents.models({ runner: "pi" })` and copy the returned `key` verbatim, or use an explicitly configured `models.aliases` name. Reuse the `model` returned by a successful spawn. Do not reconstruct it from an agent's display name. For example, an agent named “Sol” need not share the version number of one named “Astra”. Prior success with one key does not validate a different key.
66
77
 
67
- `provider/model` selectors prefer an exact visible match. A near-miss ID resolves to the closest available model on the **same provider**, using Fabric's existing similarity ranking; ties prefer recent usage, then canonical key order. For example, `openai-codex/gpt-6-sol` resolves to `openai-codex/gpt-5.6-sol` when that is the closest visible model. The returned handle's `model` and the worker's `requestedModel` contain the canonical selection. Unknown providers and names without sufficient resemblance still fail before launch. Model IDs containing `/` stay provider-scoped. Configured aliases keep their ordered, exact-target fallback chains.
78
+ To check one known key without reading the whole list, pass it as `model`: `agents.models({ runner: "pi", model: "provider/id" })` returns only the entries whose `key` equals that string exactly and case-sensitively, so a missing model gives `[]`. This lookup does not resolve aliases or near matches, and it filters the Claude, Veda, and registered-runner lists the same way.
79
+
80
+ `provider/model` selectors prefer an exact visible match. A near-miss ID resolves to the closest available model on the **same provider**, using Fabric's existing similarity ranking; ties prefer recent usage, then canonical key order. For example, `openai-codex/gpt-6-sol` resolves to `openai-codex/gpt-5.6-sol` when that is the closest visible model. The returned handle's `model` and the worker's `requestedModel` contain the canonical selection. Unknown providers and names without sufficient resemblance still fail before launch. Model IDs containing `/` stay provider-scoped. Configured aliases keep their ordered, exact-target fallback chains. To turn the alias and near-miss steps off, see [exact model match](#exact-model-match).
81
+
82
+ ### Exact model match
83
+
84
+ Set `modelMatch: "exact"` on `agents.run` or `agents.spawn` to select a named model without fallback. **This is not a security guarantee or final-dispatch enforcement.** Later hooks, unknown API payloads, providers, and extension-made calls can route data elsewhere; attribution may detect drift only after a call. Do not rely on this mode to prevent data disclosure. `model` is then required and must be a `provider/id` that `agents.models({ runner: "pi" })` lists. Fabric skips the `models.aliases` step (an alias named like the model is ignored), the closest-match step, and the fuzzy step, and it applies no alias `thinking` level. Matching ignores case, as it does for other exact lookups, and the handle reports the registry's own spelling. When two registry entries differ only by case, the identical spelling wins, and Fabric authenticates that same entry. Without `modelMatch`, resolution is unchanged.
85
+
86
+ Fabric refuses these requests before any child starts:
87
+
88
+ - `model` is missing or not in `provider/id` form: `modelMatch "exact" requires model in provider/id form, as listed by agents.models({ runner: "pi" }).`
89
+ - The model is not in the visible registry: the usual `Model "<selector>" is not available to this Pi session.` error, which names `agents.models({ runner: "pi" })`.
90
+ - The runner is not `pi` or `pi-durable`: `modelMatch "exact" is supported only by the pi and pi-durable runners.` Claude, Veda, and registered runners forward `model` to a backend that can apply its own aliases, so Fabric cannot promise that model and refuses the request.
91
+ - The value is not `"exact"`: the input schema rejects it, and a direct request fails with `Invalid Fabric agent modelMatch`.
92
+
93
+ The mode holds on every launch path, including a retry or resume of the same run and `residency: "durable"`, where the resident host resolves the model again with the same mode. It is not accepted by `agents.handoff`, `agents.create`, actor activations, or the hosted `AgentService`; their schemas reject it.
94
+
95
+ What `modelMatch: "exact"` does (subject to the limitations above):
96
+
97
+ 1. **Fabric picks the listed `provider/id` and nothing else.** There is no alias, closest-match or fuzzy step, and no `thinking` level comes from an alias. A model that `agents.models({ runner: "pi" })` does not list is refused before any child starts.
98
+ 2. **Admission is strict.** An exact request always uses strict model admission, whatever `agents.modelAdmission` says. This covers the first launch, a startup retry, a resume, and the resident host. Permissive admission accepts a child that reports a different model after selection, and an exact run never does.
99
+ 3. **The guard checks observable model changes and requests.** When it detects a different session model or a known payload model mismatch, it stops the child at that check and the run fails with `Fabric exact model pin violated: only <pin> may run, but <actual> was about to run. The provider call was stopped before any request was sent.` The worker loads the `model-pin-guard` Pi extension into the child with `-e`, the same way it loads the write guard, and it loads even with `extensions: false`. The guard knows the pinned `provider/id` and checks three things:
100
+ - **Model switches.** On the `model_select` event, any model other than the pin ends the run. This detects emitted switches and stops the child, including when Pi's own compaction or branch summaries use the changed session model; independent calls and provider routing remain outside the guard. Pi emits `model_select` only when the model changes. The launch with `--model <pin>`, Fabric's startup `set_model` to the same pin, and a different default model in settings never reach the guard as a switch.
101
+ - **The current model before each request.** The `context`, `context_with_system` and `before_provider_request` events must show the pin as Pi's current model.
102
+ - **The outgoing payload.** In `before_provider_request`, the guard compares the model id inside the payload with the registry `id` of the pin, which is the value Pi sends. It does this only for APIs whose payload shape carries the model id in a known field: `model` for `openai-completions`, `openai-responses`, `openai-codex-responses`, `anthropic-messages`, `mistral-conversations`, `google-generative-ai`, `google-vertex` and `pi-messages`, and `modelId` for `bedrock-converse-stream`. It skips Azure OpenAI Responses, whose payload names a deployment, virtual models, APIs that extensions register, and any payload without a string in that field. A rewrite made by a handler that is loaded before the guard is caught. A rewrite made by a handler that runs after the guard is not.
103
+
104
+ On a detected violation the guard writes one `[pi-fabric] model-pin-violation` line to stderr and ends the child process with status 71 at that check. The error's pre-send wording refers to the intercepted request, not to prior calls or undetected rerouting. Pi ignores an exception thrown by an extension handler. `ctx.abort()` also stopped the call in Pi 1.0.4 probes, because credential lookup ahead of the provider honours the aborted signal, but the run would then fail as a plain abort with no fixed reason. Ending the process depends on neither behaviour. A pin failure is final: Fabric neither retries nor resumes it, whatever words the model ids contain.
105
+ 4. **The guard is not final-dispatch enforcement.** A guard inside the child process cannot stop extension code in that process from calling another model. This covers nested model calls from tools, custom compaction that summarizes with another model, a provider that an extension re-registers under the pinned name so that it forwards to another model, and a payload rewrite by a handler that runs after the guard. The strict attribution check on assistant messages stays as a second line of defence: it fails the run afterwards where a reply names another model, after the call has been made.
106
+
107
+ A project extension that emits a detected model switch at `before_agent_start`, between turns, inside a tool, or inside a `context` handler causes the guard to end the run; this does not rule out other calls or later rerouting. This also holds at `session_start`: an extension that switches the model there and relied on Fabric to switch it back now fails an exact run, because the guard cannot tell that switch from one that is followed by a summary on the other model. Run such an extension with a default request, or set `extensions: false` for the exact run.
68
108
 
69
109
  For independent launches, await `Promise.allSettled` and inspect every result. An uncaught `Promise.all` rejection ends the Fabric program and can abort sibling calls still in flight; it does not prove every requested model was unavailable. Already completed calls are not rolled back, so retain successful handles and retry only failed launches.
70
110
 
@@ -79,6 +119,21 @@ return results.map(result => result.status === "fulfilled"
79
119
 
80
120
  `systemPrompt` on `agents.run` or `agents.spawn` adds text to the child's system prompt. Fabric joins it ahead of any [component model guidance](components.md), and Pi and Claude children append the result to their system prompt with `--append-system-prompt`. A Veda child receives it as a `<system_instructions>` block in its prompt. A blank value is ignored, and durable `agents.spawn` refuses it.
81
121
 
122
+ ### Child skills
123
+
124
+ `skills` on `agents.run` or `agents.spawn` chooses the child's Pi skills by name. Fabric looks up each name among the skills this session has loaded, as Pi lists them in its `skill:` commands. A child never gets a skill this session does not have, and a path in place of a name is refused.
125
+
126
+ | Value | The child gets |
127
+ | --- | --- |
128
+ | omitted | Pi's own skill discovery, as before. |
129
+ | `false` | No skills. |
130
+ | `["writing", "review"]` | Those skills preloaded in full, plus this session's other skills in its skill list. |
131
+ | `{ preload: ["writing"], inherit: false }` | Only the preloaded skills. |
132
+
133
+ A preloaded skill is placed in the child's system prompt in full, in the `<skill>` block Pi uses for `/skill:name`, after any `systemPrompt` and ahead of component model guidance. Fabric starts the child with `--no-skills` and one `--skill` for each skill it may still list, so it does not run its own discovery. Fabric's bundled skills come from the parent's list too; a child with `skills: false` has none of them.
134
+
135
+ An unknown name fails before any child starts. The error lists this session's skill names and suggests the closest one. A listed skill whose file cannot be read also fails. Only the `pi` and `pi-durable` runners accept `skills`; Claude and Veda children refuse it before launch, including `skills: false`. `extensions: false` children accept it, because Pi loads skills without extensions. Durable `agents.spawn` refuses it, like `systemPrompt`.
136
+
82
137
  ### Named agent files
83
138
 
84
139
  A named agent file saves the settings of a child agent in a Markdown file with YAML frontmatter. Pass its name as `agent` to `agents.run` or `agents.spawn` and Fabric fills the request from the file. Files written for Claude Code subagents and for Pi agent profiles load unchanged.
@@ -123,9 +178,11 @@ A project file shadows a user file with the same `name`. Fabric reads the projec
123
178
  | `model` | `model` | Resolved like a call's `model`, so `models.aliases` names and their thinking levels apply. `inherit` or no value sets nothing. |
124
179
  | `tools` | `tools` | A YAML list or a comma-separated string. Claude Code names map to Pi names without regard to case: `Read` to `read`, `Grep` to `grep`, `Glob` to `find`, `LS` to `ls`, `Bash` to `bash`, `Edit`, `MultiEdit` to `edit`, `Write` to `write`. Other names stay as written. No value means the default allowlist. |
125
180
  | `thinking` or `effort` | `thinking` | One of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Writing both is an error. |
181
+ | `skills` | `skills` | Skill names to preload (see [Child skills](#child-skills)), as a YAML list or a comma-separated string. An entry can also be `{ name, required }`; a missing skill with `required: false` is skipped with a warning. `source` and `version` load with a warning and are not used. A path is an error. An empty list preloads nothing. |
182
+ | `context.skills` | `skills.inherit` | `true` (the default) keeps this session's other skills in the child's skill list; `false` leaves only the preloaded ones. Other `context` keys are ignored with a warning. |
126
183
  | `runtimes.fabric` | request fields | Fabric-only settings under their request field names: `runner`, `kernel`, `model`, `thinking`, `tools`, `timeoutMs`, `readOnly`. They win over the shared fields above. An unknown key is an error. |
127
184
 
128
- Any other top-level field, such as `color`, `skills`, `delegate` or `permissionMode`, is ignored. Fabric reports each one as a warning in `agents.definitions()` and in the run's progress notice. It never fails the run, so a file written for another tool keeps loading. Pi agent profiles accept only seven keys, so a file in `.pi/agents` that you share with that tool must keep to them. Put Fabric-only settings under `runtimes.fabric` only in a folder that tool does not read.
185
+ Any other top-level field, such as `color`, `delegate` or `permissionMode`, is ignored. Fabric reports each one as a warning in `agents.definitions()` and in the run's progress notice. It never fails the run, so a file written for another tool keeps loading. Pi agent profiles accept only seven keys, so a file in `.pi/agents` that you share with that tool must keep to them. Put Fabric-only settings under `runtimes.fabric` only in a folder that tool does not read.
129
186
 
130
187
  **Override rule.** Fabric fills a request field from the file only when the call leaves it out. A field passed on the call, including an empty list, always wins. `agents.spawn` with `residency: "durable"` refuses a file that has a body, because a durable spawn does not accept `systemPrompt`.
131
188
 
@@ -133,7 +190,7 @@ Any other top-level field, such as `color`, `skills`, `delegate` or `permissionM
133
190
 
134
191
  **Listing.** `agents.definitions()` returns `{ name, description, path, scope, shadows?, warnings, error? }[]` with `scope` set to `"user"` or `"project"`. `shadows` is the path of the user file a project file replaces. A file that cannot be read appears with an `error`. The call reads the folders each time and starts no child.
135
192
 
136
- Fabric does not read actor templates from files (they stay in `global-actors.json`), does not look in `.claude/agents`, and does not preload skills. Fabric loads the file reader and its YAML parser on first use, so a session that never names an agent does not pay for them.
193
+ Fabric does not read actor templates from files (they stay in `global-actors.json`), and does not look in `.claude/agents`. Fabric loads the file reader and its YAML parser on first use, so a session that never names an agent does not pay for them.
137
194
 
138
195
  ### Requested models are authoritative
139
196
 
@@ -145,7 +202,7 @@ Startup waits for a correlated RPC readiness response. Startup, model admission,
145
202
 
146
203
  Selectors with no available match, rejected/malformed RPC responses, or a remaining model mismatch fail the run without sending its task. A startup or admission stall exhausts the overall deadline with `timed_out`, also without sending the task. Queued controls wait for admission too. After parent-side selector resolution, the worker must use that canonical model: it does not substitute an MRU model or fall back during admission. Standalone `AgentManager` callers can also supply a unique exact bare model ID; ambiguous IDs must be provider-qualified.
147
204
 
148
- `requestedModel` preserves launch intent in run records; `model` follows verified child state and actual assistant attribution. The manager and participant UI preserve that observed value; the launch label cannot overwrite it. If assistant attribution drifts after admission, Fabric terminates the child and reports both requested and observed models in the failure. This verifies Pi's local provider/model identity, not a remote provider's internal routing.
205
+ `requestedModel` in run records is the model Fabric selected at launch, after alias and near-miss resolution, not the caller's selector (with `modelMatch: "exact"` the two name the same model); `model` follows verified child state and actual assistant attribution. The manager and participant UI preserve that observed value; the launch label cannot overwrite it. If assistant attribution drifts after admission, Fabric terminates the child and reports both requested and observed models in the failure. This verifies Pi's local provider/model identity, not a remote provider's internal routing.
149
206
 
150
207
  Existing workers are not retroactively changed by rebuilding or reloading the parent. Stop and respawn affected workers to apply model admission.
151
208
 
@@ -713,6 +770,8 @@ A project-scoped actor stores one definition for the project. Select storage per
713
770
  - **Session binding.** A mode-`0600` file stores only `model` and `thinking` for one Pi session ID. It survives a resume of that session and does not rewrite `actors.json`.
714
771
  - **Runtime.** One owner keeps the stable actor identity, serial mailbox, and runner session. Other sessions send direct work to that owner.
715
772
 
773
+ Creation rejects names already present in the visible project or session scope, including stopped actors. Creating a stopped actor's namesake is refused; automatic replacement is disabled. To reuse the name, explicitly remove the stopped actor first with `agents.remove({ id })`; removal deletes its retained actor session and history. This is a compatibility change from automatic replacement. The refusal does not provide distributed ownership or execution fencing between independent hosts.
774
+
716
775
  Fabric resolves each activation in this order:
717
776
 
718
777
  ```text
@@ -14,6 +14,7 @@ interface FabricPersistedExecutionDetailsV1 {
14
14
  audits: FabricLegacyRenderAudit[];
15
15
  phases: string[];
16
16
  error?: string;
17
+ omittedCalls?: { count: number; done: number }; // audits the size bound dropped
17
18
  }
18
19
 
19
20
  interface FabricExecutionTraceV1 {
@@ -150,4 +151,4 @@ An invalid or unknown trace, when present, blocks semantic legacy reinterpretati
150
151
 
151
152
  ## Limitations
152
153
 
153
- Persisted audits are verbatim. Resumed final rendering shows read bodies, edit diffs, write bodies, bash output, agent tasks, and provider results. Durable traces still store bounded projections. Bash command text stays in the trace, and arbitrary argument or result content never enters it. That exclusion covers discovery queries, workflow descriptions and data, external and MCP arguments, and provider results. When arguments are omitted from the trace, generic failure resolution keeps only the ref identity. The envelope stays bounded. Past 512 KiB, display-only audits trim first. Trace-only cards, old or trimmed, render `not retained across reload` markers for content the session record does not hold. Workflow activity content stays available only while the live execution result or activity store remains in memory.
154
+ Persisted audits are verbatim. Resumed final rendering shows read bodies, edit diffs, write bodies, bash output, agent tasks, and provider results. Durable traces still store bounded projections. Bash command text stays in the trace, and arbitrary argument or result content never enters it. That exclusion covers discovery queries, workflow descriptions and data, external and MCP arguments, and provider results. When arguments are omitted from the trace, generic failure resolution keeps only the ref identity. The envelope stays bounded. Past 512 KiB, display-only audits trim first, and `omittedCalls` counts the dropped audits so the resumed card still reports every call. Trace-only cards, old or trimmed, render `not retained across reload` markers for content the session record does not hold. Workflow activity content stays available only while the live execution result or activity store remains in memory.
@@ -255,7 +255,7 @@ Append contributions are ordered by component ID and label, not activation timin
255
255
 
256
256
  [Prompt-cache observations and scoped warming](prompt-cache.md) expose runtime interest separately from the stable prompt projection described here.
257
257
 
258
- With an unchanged host prompt, skill catalog, model, target, Fabric mode, core-override catalog, and committed component projection, Fabric emits a byte-identical system prompt. Slot order is fixed, append entries sort by component ID and label, and no component revision, timestamp, run ID, message ID, or projection hash enters the model-visible text. Fabric appends its stable sections in this order: kernel, resolved slots, Schema notice, core-override guidance, and component appends. Turn-derived skill dependency guidance comes last. A turn that adds such guidance therefore retains the ordinary turn's complete system prompt as its cacheable prefix. Turn-derived guidance stays in a transcript message and does not mutate that system prefix.
258
+ With an unchanged host prompt, skill catalog, model, target, Fabric mode, core-override catalog, and committed component projection, Fabric emits a byte-identical system prompt. Slot order is fixed, append entries sort by component ID and label, and no component revision, timestamp, run ID, message ID, or projection hash enters the model-visible text. Fabric joins its stable guidance in this order: kernel, resolved slots, Schema notice, core-override guidance, and component appends. On a Pi host with structured prompt sections, Fabric puts that guidance in its own `fabric` section and its skill catalog in the `skills` section, and leaves other sections to Pi and other extensions. Pi then sends a later change as an update to that section, and the rest of the prompt stays cached. On an older host, or when an earlier extension has already replaced the whole prompt, Fabric appends the guidance to the prompt text. Turn-derived skill dependency guidance comes last. A turn that adds such guidance therefore retains the ordinary turn's complete system prompt as its cacheable prefix. Turn-derived guidance stays in a transcript message and does not mutate that system prefix.
259
259
 
260
260
  Participant task text and actor message envelopes remain user content. They are not interpolated into component guidance. Direct runs with the same role prompt, selected model, and committed guidance receive the same Fabric append-system prompt even when their tasks differ. Persistent actors keep a stable actor system prompt across mailbox activations; an actor identity or binding change intentionally creates a different prefix.
261
261
 
@@ -181,6 +181,7 @@ where absent values do not participate, and time spent inside a `humanWaitRefs`
181
181
  "defaultTools": ["read", "bash", "edit", "write", "grep", "find", "ls"],
182
182
  "retainRuns": false,
183
183
  "durableWorkerRecovery": false,
184
+ "durableWorkerSession": false,
184
185
  "notifyOnComplete": true,
185
186
  "budgetUsd": 0,
186
187
  "maxTokensPerChild": 0,
@@ -331,7 +332,7 @@ Each in-place handoff captures Main's active model at the boundary and restores
331
332
 
332
333
  ## Models
333
334
 
334
- `models.aliases` names model selectors for `agents.switchModel` and for Pi-runner `model` arguments on `agents.run`, `agents.spawn`, `agents.create`, and `agents.handoff` (see [Agents](agents.md#switching-mains-session-model)). Each alias is either one `provider/model` target, an ordered fallback chain, or an object `{"model": <target or chain>, "thinking": <level>}`. Resolution walks the chain and uses the first authenticated target. Alias names match case-insensitively and take priority over bare model ids and fuzzy matching. Aliases live in normal Fabric configuration, so a project `.pi/fabric.json` can extend the agent-level `fabric.json`; entries with malformed names or targets are ignored at load, and an unrecognized `thinking` level is dropped while the alias survives. An alias `thinking` level is the default effort for every run that selects it: an explicit `thinking` on the call or actor wins, and `agents.thinking` applies only when the alias sets none. `agents.switchModel` changes only the session model, so an alias thinking level does not apply there.
335
+ `models.aliases` names model selectors for `agents.switchModel` and for Pi-runner `model` arguments on `agents.run`, `agents.spawn`, `agents.create`, and `agents.handoff` (see [Agents](agents.md#switching-mains-session-model)). Each alias is either one `provider/model` target, an ordered fallback chain, or an object `{"model": <target or chain>, "thinking": <level>}`. Resolution walks the chain and uses the first authenticated target. Alias names match case-insensitively and take priority over bare model ids and fuzzy matching. Aliases live in normal Fabric configuration, so a project `.pi/fabric.json` can extend the agent-level `fabric.json`; entries with malformed names or targets are ignored at load, and an unrecognized `thinking` level is dropped while the alias survives. An alias `thinking` level is the default effort for every run that selects it: an explicit `thinking` on the call or actor wins, and `agents.thinking` applies only when the alias sets none. `agents.switchModel` changes only the session model, so an alias thinking level does not apply there. A request with `modelMatch: "exact"` ignores aliases and their thinking levels (see [exact model match](agents.md#exact-model-match)).
335
336
 
336
337
  ```json
337
338
  {
@@ -486,7 +487,7 @@ A compatible exact-name core override is an additive extension of its existing `
486
487
  Fabric risk classes are `read`, `write`, `execute`, `network`, and `agent`. Approval policy values are `allow`, `ask`, `auto`, or `deny`. Policies cover actions invoked inside `fabric_exec` and top-level model-requested tools left on Pi's native path. Native calls keep Pi's original implementation, result shape, and renderer. Fabric adds only the supported interception hook that runs before execution. The native-path check starts with the session, before Fabric's runtime activates on first use, so the same direct call gets the same answer before and after the first `fabric_exec`. `/fabric settings` and `/fabric reload` are commands, not tool calls, so a restrictive policy can always be changed in-session.
487
488
 
488
489
  - Captured and directly registered tools default to the conservative `execute` risk because Pi tool definitions do not declare effects. Add exact tool-name overrides under `capture.risks`. Fovea's verified graph-navigation tools (`fovea_sketch`, `fovea_focus`, `fovea_dwell`, and `fovea_impact`) are read-only exceptions that default to `read`.
489
- - `capture.hideFromModel` and `capture.keepVisible` remain accepted legacy preferences, but cannot override exclusive full-code or Schema enforce mode. Native active tools stay registered/callable while their declarations are hidden.
490
+ - `capture.hideFromModel` and `capture.keepVisible` remain accepted legacy preferences, but cannot override exclusive full-code or Schema enforce mode. Native active tools stay registered/callable while their declarations are hidden. When `keepVisible` names a tool other than `fabric_exec` (or a declared foreground tool) in one of those modes, Fabric shows one warning per session (or logs it without a UI). To declare a tool beside `fabric_exec` in full code mode, use [`foreground.tools`](#foreground-tools).
490
491
  - In orchestration-only mode, Pi's active set and each tool's native exposure govern model visibility.
491
492
  - 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.
492
493
  - 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.
@@ -635,7 +636,7 @@ Reader checkpoints are lossless live state: they are **never pressure-evicted**.
635
636
 
636
637
  ## Agents
637
638
 
638
- `agents.runner` selects the default harness: `"pi-durable"` (default, [isolated durable Pi host](durable-pi.md)), `"pi"` (legacy Pi CLI), `"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-durable"`. Explicit existing runner settings are preserved. `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.
639
+ `agents.runner` selects the default harness: `"pi-durable"` (default, [isolated durable Pi host](durable-pi.md)), `"pi"` (legacy Pi CLI), `"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-durable"`. Explicit existing runner settings are preserved. `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. A request with `modelMatch: "exact"` ignores this setting and always uses strict admission; the worker also loads a guard that ends the child when the session's model changes or a conversation request is about to go out on another model. The guarantee excludes model calls that extension code makes itself, such as nested calls from tools and custom compaction with another model (see [exact model match](agents.md#exact-model-match)).
639
640
 
640
641
  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.
641
642
 
@@ -655,6 +656,7 @@ Other agent settings:
655
656
  - `budgetUsd`: shared append-only cost ledger across a recursion tree (0 disables).
656
657
  - `maxTokensPerChild`: cumulative token bound per child (0 disables).
657
658
  - `durableWorkerRecovery` (default `false`): let a restarted resident host re-attach, or relaunch on its journal, an unfinished `pi-durable` run launched with `residency: "durable"` on the `process` transport. A run it cannot recover settles with `outcome: "indeterminate"`. See [durable-pi.md](durable-pi.md#opt-in-reattach-after-a-resident-host-restart).
659
+ - `durableWorkerSession` (default `false`): give a `pi-durable` child without a seeded session a private Pi session file in its run directory, and put a worker-role entry at the root of its session (fork and handoff seeds too). A relaunch then keeps what extensions saved in the session. With it off, the child runs with `--no-session` as before. See [durable-pi.md](durable-pi.md#opt-in-a-session-file-for-pi-durable-workers).
658
660
  - `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.
659
661
  - `sessionExport`: export each agent run's usage as an attributed pi-format session file (on by default).
660
662
  - `sessionExportDir`: override the export store root (default `~/.pi-fabric/agent`, with `PI_FABRIC_AGENT_DIR` taking precedence).
@@ -665,7 +667,7 @@ Other agent settings:
665
667
 
666
668
  ### Usage tracking with external tools
667
669
 
668
- Fabric children run with `--no-session`, so token trackers that scrape session files (tokscale, ccusage, …) cannot see subagent token usage or cost. With `sessionExport` enabled (the default), every child writes one usage-only session file (tokens and cost, never transcript content) to:
670
+ Fabric children run with `--no-session` (a `pi-durable` child with `agents.durableWorkerSession` keeps its session file inside the run directory), so token trackers that scrape session files (tokscale, ccusage, …) cannot see subagent token usage or cost. With `sessionExport` enabled (the default), every child writes one usage-only session file (tokens and cost, never transcript content) to:
669
671
 
670
672
  ```text
671
673
  ~/.pi/agent/sessions/.fabric/<encoded-cwd>/<run>.jsonl
@@ -734,6 +736,7 @@ See the [TypeScript MCP reference](../skillsets/typescript/fabric-exec/reference
734
736
  - `ui.showAgentToolPreview` defaults to `true` and controls the child-agent and actor tool rows in both the parent `fabric_exec` card and the widget. Recursive agents render their full descendant tree, bounded by the preview depth/node budget. The version 2 config migration renamed this key from `ui.showNestedToolCalls`.
735
737
  - `ui.toolDisplay` is `"compact"` (default) or `"full"`. Compact elevates the declared display name and description and keeps bounded nested tool detail visible; full retains the outer Fabric program transcript. Pi's tool-expand keybinding (`ctrl+o` by default) expands a compact card to the full transcript and collapses it again. Invalid values fall back to `"compact"`. If configuration fails to load, rendering falls back to full so a degraded startup never hides the transcript. Change it under `/fabric settings` → **UI**; successful changes apply immediately to live and completed cards.
736
738
  - `ui.terminalTitle` defaults to `true`. The terminal window/tab title shows the declared `fabric_exec` display name (for example `record release evidence`) and nothing else; nested call detail stays in the transcript. The title holds until the next declared name, survives the program that set it, and is adopted again on resume, because Fabric records it as a session entry. Pi's `app - session - cwd` shape only shows before the first declared name in a session. A call without a declared name leaves the current title alone. Headless and RPC hosts never receive it, and it requires `ui.enabled`; turn it off under `/fabric settings` → **UI**.
739
+ - `ui.questionRenderers` (default off) lets an extension show routed child questions and `/fabric decisions` in its own interface. Any value except `true` keeps Fabric's own dialogs. See [question renderers](decisions.md#question-renderers).
737
740
  - `ui.updateDebounceMs` defaults to `100`. It applies one execution-wide coalescing interval to every live `fabric_exec` card update: nested calls, progress text, and agent tool previews. Continuous streams emit at most once per interval, so a long call no longer postpones every render until completion. Set it to `0` to emit every update. Accepted values clamp to `0..2000`. The version 3 config migration renamed this key from `ui.nestedToolDebounceMs`.
738
741
  - `ui.sessionLabel` controls where a root Pi session shows its Fabric [peer label](agents.md#peer-labels-and-queue-gates), such as `FAB-3`. Child agents and actors never show one.
739
742
  - `footer` defaults to `true` and shows the label. In the TUI the label sits on the editor's top border and heads the Fabric widget (`● FAB-3`), and the footer stays empty. The footer shows `Fabric FAB-3` instead when `ui.widget` is `hidden` or `ui.enabled` is `false`, and RPC clients always receive it as the `fabric-label` status. `false` hides the label everywhere; the widget header then reads `Fabric`. Independently of this setting, a root session records its label once as a `pi-fabric-peer` session entry (`FABRIC_PEER_ENTRY_TYPE` in `pi-fabric/protocol`) holding `{ version: 1, sequence, participantId, label }`, which headless hosts read with Pi's RPC `get_entries`. A session takes its label at its first Fabric use, or at once when it resumes with a recorded one; see [peer labels](agents.md#peer-labels-and-queue-gates).
package/docs/decisions.md CHANGED
@@ -6,7 +6,7 @@ Four sources raise decisions:
6
6
 
7
7
  - programs, through `decisions.raise`;
8
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 or the child is a durable run;
9
+ - routed child dialogs, when `agents.childQuestions` is `"route"` and the parent session has no interactive UI, the child is a durable run, or a [question renderer](#question-renderers) is active;
10
10
  - other extensions, through the [extension question events](#extension-questions).
11
11
 
12
12
  ## Record
@@ -160,9 +160,53 @@ Fabric copies only those question fields. The decision is always held by `"user"
160
160
 
161
161
  `source` names the asking extension, for example its package name. The record stores it as `raisedBy.participantId: "extension:<source>"` next to the session id, so a person can see who asked. It must match `[A-Za-z0-9@][A-Za-z0-9@._/-]{0,63}`; any other value is refused before a decision is raised. Without `source`, the session is the raiser.
162
162
 
163
+ ## Question renderers
164
+
165
+ By default Fabric shows a routed child question and the decision picked in `/fabric decisions` with its own `ctx.ui` dialogs. An extension with a richer question interface can show them in its own interface. Fabric consults renderers only when `ui.questionRenderers` is `true`; any other value leaves both surfaces exactly as they are.
166
+
167
+ ```json
168
+ {
169
+ "ui": {
170
+ "questionRenderers": true
171
+ }
172
+ }
173
+ ```
174
+
175
+ Register a renderer over `pi.events`. Registration is accepted whether or not the setting is on. A second registration under the same `name` replaces the first and keeps its place in registration order:
176
+
177
+ ```ts
178
+ import { FABRIC_QUESTION_RENDERER_REGISTER_EVENT } from "pi-fabric/protocol";
179
+
180
+ let unregister: (() => void) | undefined;
181
+ pi.events.emit(FABRIC_QUESTION_RENDERER_REGISTER_EVENT, {
182
+ version: 1,
183
+ name: "my-question-ui",
184
+ render: async ({ surface, ui, decision, signal }) => {
185
+ const optionId = await showMyQuestionUi(ui, decision, signal);
186
+ return optionId
187
+ ? { status: "answered", decisionId: decision.id, answer: { optionId } }
188
+ : { status: "dismissed", decisionId: decision.id };
189
+ },
190
+ respond: (result) => { if (result.ok) unregister = result.unregister; },
191
+ });
192
+ ```
193
+
194
+ The renderer receives `surface` (`"child-question"` or `"decisions-command"`), the session `ui`, a private copy of the `decision` (`id`, `kind`, `title`, `body?`, `input`, `options?`, `holder`, `raisedBy`, `createdAt`, `deadline?`), and a `signal`. It returns one of:
195
+
196
+ | Result | Effect |
197
+ |---|---|
198
+ | `{ status: "answered", decisionId, answer: { optionId?, text? } }` | Fabric records the answer. |
199
+ | `{ status: "cancelled", decisionId }` | Fabric cancels the decision. |
200
+ | `{ status: "dismissed", decisionId }` | The person closed the renderer without deciding. A child question is cancelled; a decision picked in `/fabric decisions` stays open. |
201
+ | `undefined` | The renderer declines; Fabric asks the next renderer, then shows its own dialog. |
202
+
203
+ Fabric asks renderers one at a time in registration order. It writes the result to the store itself, with `via: "tui"` and the OS user as `answeredBy`, and copies only `optionId` and `text`, so a renderer cannot change the holder, the raiser, the deadline, or who is recorded as answering. A result whose `decisionId` names another decision, a malformed result, an answer the store refuses (an unknown option, text over the limit), a throw, or a rejection falls back to Fabric's own dialog. `signal` aborts when the decision is answered, cancelled, or expires elsewhere, or when the asking child run settles; Fabric then uses what the record says.
204
+
205
+ With an active renderer and a decision store, a routed child question that would use the parent's UI is recorded first as a root-held `kind: "question"` decision with the question's own deadline, so the renderer and Fabric's fallback dialog show the same record. `/fabric decisions` and `pi-fabric decisions answer` can answer it too; the first answer wins and the child gets what the record says. A `select` with more than 12 options keeps Fabric's direct dialog and is not recorded. A [held question](#holding-a-question-for-a-person) keeps the hold path and is not offered to renderers. Only the main session consults renderers; a child session's UI forwards to its parent.
206
+
163
207
  ## Human surfaces
164
208
 
165
- - `/fabric decisions [id]` lists open decisions, then answers the picked one through native dialogs (`select` for options, and `input` or `editor` for text). Both kinds offer a "Cancel this decision" entry. A text or editor decision first asks "Answer this question" or "Cancel this decision", so an empty answer and a cancel never look the same. Answers and cancels record `via: "tui"`.
209
+ - `/fabric decisions [id]` lists open decisions, then answers the picked one through native dialogs (`select` for options, and `input` or `editor` for text). Both kinds offer a "Cancel this decision" entry. A text or editor decision first asks "Answer this question" or "Cancel this decision", so an empty answer and a cancel never look the same. Answers and cancels record `via: "tui"`. With an active [question renderer](#question-renderers), the picked decision goes to the renderer first.
166
210
  - `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.
167
211
  - `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.
168
212
  - `pi-fabric decisions cancel --root <meshRoot> <id> [--json]` cancels one open decision with `via: "cli"` and the OS user name as `answeredBy`. Use it to clear a decision whose asker has gone away, such as a `pi -p` run stopped with Ctrl+C. Cancelling a decision that is not open exits 1, like answering one twice.
@@ -175,6 +219,7 @@ Fabric copies only those question fields. The decision is always held by `"user"
175
219
  | `approvals.headlessTimeoutMs` | `300000` | headless approval deadline (1 s to 24 h) |
176
220
  | `approvals.policyHooks` | off | consult [extension action policy hooks](configuration.md#extension-action-policy-hooks); a `hold` uses the headless path above |
177
221
  | `agents.childQuestions` | `"cancel"` | `"route"` forwards child dialogs to the parent |
222
+ | `ui.questionRenderers` | off | offer decisions shown at this terminal to [question renderers](#question-renderers) |
178
223
  | `agents.childQuestionTimeoutMs` | `600000` | default routed dialog deadline (1 s to 24 h) |
179
224
  | `agents.childQuestionTools` | `["ask"]` | tools a routed Pi child gets for asking; `[]` grants none |
180
225
 
@@ -69,8 +69,8 @@ recorded order, before the program sees their result. `compact.request` and
69
69
  `compact.cancel` are always redone. `prewalk.plan` is redone when the
70
70
  restarted session's prewalk arm owes a plan, and skipped otherwise.
71
71
  `compact.carry`, `thinking.set`, and `thinking.reset` are redone only when
72
- the session entry they wrote did not survive, as in a worker without a session
73
- file, so a surviving session never gets a second entry. A redo runs the
72
+ the session entry they wrote did not survive, as with an explicit Pi runner
73
+ started with `--no-session`, so a surviving session never gets a second entry. A redo runs the
74
74
  provider again under the current policy, without asking for approval again. If
75
75
  a redo fails, the program stops, reports that call and its error, and runs
76
76
  nothing after it. State, mesh, saved programs, and cache releases are already on
@@ -119,6 +119,111 @@ observers from memory after that commit. The journal grows with the transcript,
119
119
  not with the square of each streamed message. Run retention removes `durable/`
120
120
  with its run, and unknown or linked files inside it still preserve the run.
121
121
 
122
+ ### Opt-in: a session file for pi-durable workers
123
+
124
+ By default a `pi-durable` child without a seeded session runs with
125
+ `--no-session`. Set `agents.durableWorkerSession: true` to have it keep a
126
+ private Pi session file at `durable-session/session.jsonl` in its run directory
127
+ (mode `0600`, folder `0700`). The journal restores messages only; the session
128
+ file restores what extensions saved in the session, such as custom entries,
129
+ context edits, and compaction, when a relaunched attempt reopens it. This
130
+ includes the relaunch described in [Opt-in: reattach after a resident host
131
+ restart](#opt-in-reattach-after-a-resident-host-restart): it reuses the run
132
+ directory, so the relaunched worker reopens the same session file. Without the
133
+ file, the redo rules above rebuild extension state from the journal, and only
134
+ some calls can be redone. With the option on, the manager also creates run
135
+ directories with mode `0700`. Explicit `pi` children keep `--no-session`
136
+ either way. Run retention removes `durable-session/` with its run; see
137
+ "Retention" below for what it accepts.
138
+
139
+ With the option off, nothing below applies: there is no session file, no
140
+ worker-role entry, and fork and handoff seeds are written as before.
141
+
142
+ ### Worker role
143
+
144
+ With `agents.durableWorkerSession`, a `pi-durable` child's session carries a worker-role entry, so a context-aware
145
+ extension in the child knows it is a worker. The entry is one custom entry in the Pi
146
+ session file:
147
+
148
+ ```json
149
+ { "type": "custom", "customType": "context-aware.policy.v1",
150
+ "data": { "schemaVersion": 1, "layer": "host", "declaredBy": "pi-fabric/durable-worker",
151
+ "values": { "sessionRole": "worker" } } }
152
+ ```
153
+
154
+ Delegation extensions write the same entry for their workers. Without it, such an
155
+ extension acts as a session with a user at a terminal: it can send a compaction seed as a new
156
+ user message, rewrite it with a model, add the cache listing, and compact in the
157
+ middle of a reply. Fabric does not import any such extension; without one
158
+ the entry is one unread line.
159
+
160
+ **Create complete, never edit.** Fabric writes the entry only into a session file
161
+ it creates, in the same write that creates the file. The worker never appends to,
162
+ rewrites, or parses an existing session file, so a file that exists already (a
163
+ relaunch, or a `sessionFile` the caller supplies) is used exactly as it is.
164
+
165
+ The entry is the **root** of the tree: the first entry after the header, with
166
+ `parentId: null`. Every entry Pi appends, and every branch a later navigation or
167
+ Pi fork reaches, then descends from it. That is why the entry does not depend on
168
+ which entry Pi treats as the leaf.
169
+
170
+ - **New `durable-session/session.jsonl`.** Line 1 is a Pi session header (version
171
+ 3), line 2 is the entry with `parentId: null`. The worker writes both to
172
+ `tmp-<uuid>.jsonl` in the same folder (exclusive create, no link following,
173
+ `0600`), syncs it, hard-links it to `session.jsonl` and unlinks the temp name.
174
+ Exactly one of two concurrent attempts wins the link; the other keeps the
175
+ winner's file. On relaunch an existing `session.jsonl` is reused untouched, and
176
+ a leftover `tmp-<uuid>.jsonl` that is a second name of it is removed.
177
+ - **Fork and handoff seeds.** For a `pi-durable` child with the option on, the manager passes the seed
178
+ writers (`writeForkSession`, `writeHandoffSession`) `{ workerRole: true }`.
179
+ The file they return has the header, then the entry as the root, then the seed's
180
+ entries unchanged except that the seed's former root has `parentId` set to the
181
+ entry's id. The inherited messages are identical. A seed Pi's own
182
+ `createBranchedSession` writes is rewritten once by the writer, before it
183
+ returns the path and before any worker can open the file.
184
+ - **Plain `pi`, other runners, and the option off.** No option is passed. Seeds are byte for byte
185
+ what the writers always produced, there is no entry, and a child with no seed
186
+ keeps `--no-session`.
187
+ - **Caller-supplied `sessionFile`.** Never written. Such a child keeps whatever role
188
+ that file already declares.
189
+ - **A later explicit declaration wins.** A context-aware extension replays policy entries in
190
+ order and a later entry wins per path, so a later host policy that declares another
191
+ `sessionRole` overrides the seeded one; Fabric does not fight it.
192
+
193
+ #### Threat model
194
+
195
+ A process running as the same user is trusted, because it can already write every
196
+ session file. Same-user races (swapping a folder for a symlink, adding a hard link
197
+ between a check and a write) are therefore out of scope. The worker guards against
198
+ other users and against accidental links:
199
+
200
+ - Before it creates anything, the worker `lstat`s the run directory. It must be a
201
+ real directory (not a link) owned by the worker's user; otherwise the launch fails
202
+ with a clear error before any write. If group or others can write it
203
+ (`mode & 0o022`), the worker removes that write itself through a descriptor opened
204
+ without following links and checked to be the same directory, then confirms the bit
205
+ is gone. A run directory from an earlier Fabric or a test harness may have mode
206
+ `0775`; with the option on, the manager creates run directories with mode `0700`. After the
207
+ tightening no other user can add or swap entries in the run directory, and
208
+ anything already there is refused by the owner and link checks on
209
+ `durable-session/` and by `O_EXCL | O_NOFOLLOW` on the temp file.
210
+ - `durable-session/` is created without `recursive` (so the run directory must
211
+ already exist), with mode `0700`; an existing one must be a real directory owned by
212
+ the worker's user.
213
+ - The temp file is created with `O_CREAT | O_EXCL | O_NOFOLLOW`.
214
+
215
+ #### Retention
216
+
217
+ Run retention accepts only `session.jsonl` and `tmp-<lowercase uuid v4>.jsonl` in
218
+ `durable-session/`, each a regular file owned by this user. A file with two names is
219
+ accepted only as the crash leftover between the worker's link and unlink: the folder
220
+ holds exactly `session.jsonl` and one `tmp-<uuid>.jsonl` that share a device and
221
+ inode. A link that leaves the run, an unknown name (including an uppercase or
222
+ all-zero uuid), a symlink, or another owner keeps the run.
223
+
224
+ Fabric does not read the `context-aware.worker-compaction.v1` advisories a worker
225
+ writes.
226
+
122
227
  Durability **does not restore arbitrary JavaScript continuations**, promise
123
228
  general exactly-once external effects, or restart failed workers indefinitely.
124
229
  The standard process/actor lifecycle controls stop/retry/retention. A new run is
@@ -447,6 +552,61 @@ Full-host coverage is in `tests/durable-agent.test.ts`,
447
552
  `tests/durable-worker-e2e.test.ts`, `tests/durable-fabric-exec.test.ts`,
448
553
  `tests/handoff-continuation-worker.test.ts`, and `tests/durable-actors.test.ts`.
449
554
 
555
+ ## Embedding a durable session: `pi-fabric/durable-host`
556
+
557
+ A host process that runs one long-lived durable `AgentSession` of its own (a
558
+ daemon, not a Fabric-managed worker) imports `pi-fabric/durable-host`. The host
559
+ supplies the Pi SDK (`@earendil-works/pi-coding-agent`, `pi-ai`, `pi-agent-core`)
560
+ as peers, as for the extension. Fabric's registration graph never loads this
561
+ entry, and it does not read `agents.durableWorkerSession` or any other Fabric
562
+ setting: the embedder chooses its own session file.
563
+
564
+ Exports: `createDurableAgentSession` (the session), `DurableAgent`,
565
+ `openDurableWorkerStorage` (exclusive, fsync'd JSONL storage with a lease),
566
+ `createDurableWorkerRuntime` and `DurableWorkerOptions` (the full native runtime
567
+ with `/new`, `/fork` and `/resume`), `declareWorkerSessionRole` and
568
+ `DURABLE_WORKER_POLICY_ENTRY_TYPE`.
569
+
570
+ ```ts
571
+ import {
572
+ createDurableAgentSession, declareWorkerSessionRole, openDurableWorkerStorage,
573
+ } from "pi-fabric/durable-host";
574
+ import { SessionManager } from "@earendil-works/pi-coding-agent";
575
+ import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
576
+
577
+ const lease = await openDurableWorkerStorage("/absolute/private/run-dir"); // throws if another process owns it
578
+ const sessionManager = SessionManager.open(sessionFile, undefined, cwd); // or create(...)
579
+ declareWorkerSessionRole(sessionManager); // before the first prompt; "already-seeded" on resume
580
+ const host = await createDurableAgentSession({
581
+ cwd, sessionManager, storage: lease.storage, runId: "my-daemon:main", // stable across restarts
582
+ // modelRuntime, model, tools, customTools, resourceLoader: as for createAgentSession
583
+ });
584
+ await host.session.bindExtensions({}); // not done for you; bind your own mode/UI/error hooks
585
+ await host.session.prompt("...");
586
+ // Shutdown: await host.close(); await lease.storage.close(BACKGROUND_CONTEXT); await lease.release();
587
+ ```
588
+
589
+ **Worker role.** `declareWorkerSessionRole(sessionManager)` appends the same
590
+ worker-role entry described under "Worker role" above to a session you already
591
+ opened. It returns `"seeded"` when it wrote the entry and `"already-seeded"`
592
+ when the latest host role declaration on the active branch is worker, so a restart
593
+ loop does not grow the file. A sibling branch does not count, and a later host
594
+ role override causes the helper to append a fresh worker declaration. Call it before the first prompt and before `bindExtensions`.
595
+ Unlike a Fabric child, whose entry is the tree root, this one is appended after
596
+ whatever the session already holds. Without it the session counts as a
597
+ foreground session with a user at a terminal.
598
+
599
+ **Supervision is the host's job.** An embedder gets journal resume through
600
+ `createDurableWorkerRuntime` and `createDurableAgentSession`, but not Fabric's
601
+ opt-in worker recovery (`agents.durableWorkerRecovery` and
602
+ `worker-recovery.json`), which only Fabric's agent manager performs. Nothing in
603
+ this entry restarts a process. After a crash, the host starts a new process,
604
+ reopens the same storage directory and session file, and calls
605
+ `createDurableAgentSession` again with the **same `runId`**, then
606
+ `host.agent.continue()` to finish interrupted work. Do not replay the original
607
+ prompt. The host also owns backoff, a restart budget, and releasing the storage
608
+ lease before another process takes over.
609
+
450
610
  ## Evidence
451
611
 
452
612
  `tests/durable-runner.test.ts` exercises the real published packages with offline
package/docs/interface.md CHANGED
@@ -155,7 +155,7 @@ Fabric ships a general-purpose, theme-aware activity surface that works with any
155
155
  - The graph renders status-coloured node shapes, orthogonal connectors, animated traffic, an optional fixed-width selected-node inspector, and directional off-canvas summaries. Traffic follows the same structural branches through the source/target lowest common ancestor. It never draws direct lines through unrelated subtrees. A large or deeply recursive graph opens around the attention-priority node. When you move between nodes, a damped spring camera retargets smoothly and the viewport does not snap. Live and replay animation drives renders only while the dashboard is open. Narrow terminals keep the centred graph and drop the inspector.
156
156
  - Retained-run selection works as a lens over the same topology. Pressing `[` or `]` changes the highlighted run and its phase context, and live actors and remote project participants stay visible. Route records remain selectable, and they aggregate repeated traffic by source, target, topic, and kind. The recent event feed is a bounded live window. It does not replace audit history.
157
157
  - **Inspection and control** work the same way in both views. Agent detail includes Markdown-rendered tasks and results, highlighted YAML values, model, current tool, usage, worktree, and attach metadata. Tool-call details show highlighted command, file, and edit inputs, with Markdown or YAML outputs. Persisted bash calls keep their command text. Space peeks at an agent or actor transcript. `t` toggles between summary and transcript detail. The initial bounded tail is paged directly from Pi RPC, Pi session, and Claude stream-JSON logs. At the loaded top, `k` or Up fetches one older page, `g` loads and jumps to the true beginning, and `G` jumps to the growing tail and resumes follow mode. Assistant text uses native Markdown. Tool calls retain structured arguments and results, so they get the same read, bash, search, edit, and write previews as the parent card. Credential and token redaction applies before rendering. You can steer Main and active one-shot agents or queue them a follow-up, and one-shot agents can also be stopped safely. Persistent actors accept `s` mailbox messages. Where configured, they expose model (`m`), thinking (`e`), the complete session-bound Pi host-event catalog (`v`), instructions (`i`), mailbox clearing (`c`), and export (`x`). Remote participants expose only their advertised capabilities. Control resolves their owner and reports success after acknowledgement. From Activity, global templates stay available for import (`p`), instruction editing (`i`), and deletion (`d`).
158
- - `/fabric settings` opens an inline settings view that mirrors Pi core's `/settings`, with top and bottom borders, fuzzy search, and section submenus, and it writes changes to `fabric.json`. Trusted projects default to `<project>/.pi/fabric.json`. Pressing **Ctrl+G** anywhere in the view switches both the displayed configuration layer and the save destination between project and global `~/.pi/agent/fabric.json`. The global view keeps global edits visible even when a project override remains effective, and its scope banner states that precedence explicitly. Untrusted sessions stay global-only. In RPC hosts, the same hierarchy is exposed through recursive select/input dialogs; a root save-scope action replaces the Ctrl+G shortcut, while Back returns one section at a time. Full code mode, capture, executor, approvals, and UI changes apply immediately when they change the effective configuration. Mesh, agent, retention, and MCP changes persist and take effect on the next `/fabric reload`. The UI section includes **Tool display** (`full` by default or `compact`), a default-on **Agent tool preview** toggle, and a global **Update debounce** (`0`/Off through `1000ms`, default `100ms`); all apply immediately. Compact display makes the declared Fabric display name/description the card header, hides outer TypeScript at every expansion level, and retains bounded nested tool details. The Agents section selects the default runner, keeps independent Pi and runtime-enumerated Claude model pickers, and exposes free-text Veda backend, persona, and model fields for the Veda runner. List editors for `agents.defaultTools` and `capture.keepVisible` toggle known tools on and off. The `keepVisible` candidates include `fabric_exec` plus every captured extension tool; this legacy preference cannot override full-code or Schema enforce mode's sole `fabric_exec` model declaration on Pi 0.99.
158
+ - `/fabric settings` opens an inline settings view that mirrors Pi core's `/settings`, with top and bottom borders, fuzzy search, and section submenus, and it writes changes to `fabric.json`. Trusted projects default to `<project>/.pi/fabric.json`. Pressing **Ctrl+G** anywhere in the view switches both the displayed configuration layer and the save destination between project and global `~/.pi/agent/fabric.json`. The global view keeps global edits visible even when a project override remains effective, and its scope banner states that precedence explicitly. Untrusted sessions stay global-only. In RPC hosts, the same hierarchy is exposed through recursive select/input dialogs; a root save-scope action replaces the Ctrl+G shortcut, while Back returns one section at a time. Full code mode, capture, executor, approvals, and UI changes apply immediately when they change the effective configuration. Mesh, agent, retention, and MCP changes persist and take effect on the next `/fabric reload`. The UI section includes **Tool display** (`full` by default or `compact`), a default-on **Agent tool preview** toggle, and a global **Update debounce** (`0`/Off through `1000ms`, default `100ms`); all apply immediately. Compact display makes the declared Fabric display name/description the card header, hides outer TypeScript at every expansion level, and retains bounded nested tool details. The Agents section selects the default runner, keeps independent Pi and runtime-enumerated Claude model pickers, and exposes free-text Veda backend, persona, and model fields for the Veda runner. List editors for `agents.defaultTools` and `capture.keepVisible` toggle known tools on and off. The `keepVisible` candidates include `fabric_exec` plus every captured extension tool; this legacy preference cannot override full-code or Schema enforce mode's sole `fabric_exec` model declaration on Pi 0.99, so in those modes the row reads `(no effect)` and points to `foreground.tools`.
159
159
 
160
160
  ### Keybindings
161
161
 
package/docs/providers.md CHANGED
@@ -213,7 +213,7 @@ The run has the same semantics as `/fabric run`: the session's root capability v
213
213
 
214
214
  ## Decision request events
215
215
 
216
- An extension with no screen to ask on, such as a question tool in a headless session, can hand a question to a person. `pi-fabric:decisions:capability:v1` (`FABRIC_DECISIONS_CAPABILITY_EVENT`) reports whether user-held decisions are available and their limits. `pi-fabric:decisions:request:v1` (`FABRIC_DECISION_REQUEST_EVENT`) raises a `kind: "question"` decision held by `"user"` and responds once a person answers or cancels it, or it expires. Both use the claim/respond shape and are exported from `pi-fabric/protocol`. See [Extension questions](decisions.md#extension-questions) for the fields and guarantees.
216
+ An extension with no screen to ask on, such as a question tool in a headless session, can hand a question to a person. `pi-fabric:decisions:capability:v1` (`FABRIC_DECISIONS_CAPABILITY_EVENT`) reports whether user-held decisions are available and their limits. `pi-fabric:decisions:request:v1` (`FABRIC_DECISION_REQUEST_EVENT`) raises a `kind: "question"` decision held by `"user"` and responds once a person answers or cancels it, or it expires. Both use the claim/respond shape and are exported from `pi-fabric/protocol`. See [Extension questions](decisions.md#extension-questions) for the fields and guarantees. An extension with a richer question interface can also show Fabric's own decisions: register it with `pi-fabric:question-renderer:register:v1` (`FABRIC_QUESTION_RENDERER_REGISTER_EVENT`); see [Question renderers](decisions.md#question-renderers).
217
217
 
218
218
  ## Managed embedded hosts
219
219
 
@@ -34,6 +34,7 @@ a set of small policy kernels, **not a proof of every subsystem invariant**.
34
34
  | State and Schema | `policy.ts`: `headReadable`, `certificateAccepted`, `consume` | `state/store.ts`, `schema/controller.ts` | `head_sound`, `pending_without_marker_hidden`, `committed_head_visible`, `pending_head_visible`, `certificate_sound`, `certificate_complete`, `consume_once`, `consume_retires` |
35
35
  | External mesh grants | `grants.ts`: `meshGrantTake` | `verified/grants.ts`, `mesh/grants.ts` | Exact scoped admission, expiry/refusal precedence, exact decrement, refusal preservation and kind/topic forwarding |
36
36
  | Speculation bookkeeping | `speculation.ts`: `speculationAdmission`, `speculationCheck`, `speculationAccounting`; `policy.ts`: `consume` | `verified/speculation.ts`, `speculation/store.ts` | Exact admission caps, checkpoint refusal precedence, one-use entry reservation, exact event counters and epoch successor |
37
+ | Actor name decision | `actor-name.ts`: `actorName` | `actors/name-policy.ts`, `actors/manager.ts`, `actors/directory.ts` | Active dominates stopped, stopped is refused absent active, neither is available; host snapshot only, not a reservation |
37
38
  | Agent budget admission | `budget.ts`: `budgetAdmission` | `verified/budget.ts`, `agents/manager.ts` | Strict threshold safety/completeness, equality refusal, invalid observations refused |
38
39
  | Effect diagnostics | `policy.ts`: `unknownConflict`, `knownConflict` | `components/effect-policy.ts` | `unknown_conflict_exact`, `unknown_conflict_symmetric`, `known_conflict_exact` |
39
40
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-fabric",
3
- "version": "0.130.2",
3
+ "version": "0.131.0",
4
4
  "description": "A programmable tool and agent runtime for Pi",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -29,6 +29,10 @@
29
29
  "types": "./dist/durable.d.ts",
30
30
  "import": "./dist/durable.js"
31
31
  },
32
+ "./durable-host": {
33
+ "types": "./dist/durable-host.d.ts",
34
+ "import": "./dist/durable-host.js"
35
+ },
32
36
  "./durable-extension": {
33
37
  "types": "./dist/durable-extension.d.ts",
34
38
  "import": "./dist/durable-extension.js"