pi-fabric 0.44.13 → 0.44.15

package/docs/capability-combustion.md

@@ -121,29 +121,42 @@ With the default fixture terms, "query the results table please" scores
 $s = 1.333$ (weak band): the EWMA crosses $0.9$ only on the second tidy prompt,
 and cool-off while the user edits code delays the fire as intended.
 
-## Ash: permanent suppression with provenance
-
-Fired namespaces are burned. The record (ash) is append-only and machine-global,
-persisted at `<agent-dir>/fabric/capability-advisories.json`:
+## Ash: session-scoped suppression — the transcript is the ledger
+
+Fired namespaces are burned, and the burn record lives in the session's own
+transcript — there is no side store:
+
+- `fired` — the hint itself is the record: every advisory is emitted as a
+  `pi-fabric-capability` custom-message entry whose `details` name the
+  namespaces shown. Burning happened *when the paper entered the fire*, and
+  the transcript is the fire.
+- `organic` — the model invoked a captured tool from that namespace *without
+  a hint*. The tool call is already a transcript entry; the capability's
+  information potential was spent by discovery, so we burn it preemptively
+  (organic-discovery poisoning: the same one-way door, entered from the other
+  side).
+
+Ash is *derived*, never stored: on `session_start` and on every branch switch
+(`session_tree`) the advisor replays the current branch's entries
+(`ctx.sessionManager.getBranch()`) and re-marks both burn kinds, with
+provenance (`origin`) and wall time (`at`, taken from the entry's own
+timestamp) rebuilt from the transcript:
 
 ```json
-{ "format": 2, "burned": [
-    { "namespace": "extension:pi-websearch", "origin": "fired", "at": "2026-08-10T16:00:00.000Z" },
-    { "namespace": "extension:pi-fovea",    "origin": "organic" } ] }
+{ "namespace": "extension:pi-websearch", "origin": "fired", "at": "2026-08-10T16:00:00.000Z" }
+{ "namespace": "extension:pi-fovea",    "origin": "organic", "at": "2026-08-10T16:12:11.000Z" }
 ```
 
-Provenance is in `origin`:
-
-- `fired` — a hint was emitted for this capability.
-- `organic` — the model invoked a captured tool from that namespace *without a
-  hint*. The capability's information potential is already spent; a hint would
-  be redundant, so we burn it preemptively. This is organic-discovery poisoning:
-  the same one-way door as a fire, entered from the other side.
-
-You don't unburn paper. Ash is never reclaimed: no expires, no release path, no
-defrost knob. `reset()` clears things that are inherently session-local (warmth,
-smoke streak, per-session cap) but never ash; `hydrate()` loads it on session
-start.
+Thermodynamic consequence: the ash set is exactly "burns that happened up to
+the current point in this branch's history." Fork a session and the fork
+replays ashes up to the fork point; rewind with `/tree` and capabilities whose
+burns live only in the abandoned future burn *back into paper* — you don't
+unburn paper, but undoing time restores what hadn't happened yet. A new
+session is a fresh urn: nothing carries across sessions, because the learner
+the hint was meant for (the model's context) doesn't either. Within a session
+there's still no release path: no expires, no defrost knob — `reset()` clears
+only what is inherently transient (warmth, smoke streak, per-session cap),
+never ash.
 
 ## Furnace feedback
 
@@ -162,15 +175,15 @@ zero — clean combustion keeps the furnace responsive. Smoke feedback only rais
 the *weak-band* ignition bar; strong matches still ignite instantly, because if
 the evidence is that unambiguous the furnace's skepticism isn't invited.
 
-Transient feedback lives session-locally too: smoke is lifted by the first clean
-burn, and unlike ash it doesn't persist across sessions (organic poisoning
-covers the durable learning).
+Transient feedback lives session-locally too: smoke is lifted by the first
+clean burn. Like everything else in this model, it does not cross sessions —
+the new session brings a fresh transcript, hence a fresh urn.
 
 ## Per-session cap
 
 $\leq$ `maxPerSession` fires per session regardless of model behavior (default
 3). Unchanged from the pre-combustion design; the cap guards against prompt
-storms in a single session, ash guards against repetition across sessions.
+storms in a single session, and ash guards against repetition within it.
 
 ## Summary
 

package/docs/configuration.md

@@ -234,7 +234,7 @@ Fabric risk classes are `read`, `write`, `execute`, `network`, and `agent`; appr
 - 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 and default to `read`.
 - Set `capture.hideFromModel` to `false` to index non-core extension tools without hiding them from the model's active set.
 - `capture.keepVisible` names stay in both Fabric and Pi's model-facing active set, except that Pi core names are always Fabric-owned in full code mode.
-- `capture.advisory` injects a capability hint at `before_agent_start` when the prompt's terms match a captured source's tf-idf fingerprint (names + descriptions grouped by source namespace, no manifest declarations needed). `mode: "enabled"` (default) renders the hint in the transcript, `"hidden"` delivers it to the model only, and `"disabled"` turns it off. Each capability fires at most once — the fired set persists in `<agent-dir>/fabric/capability-advisories.json` across session restarts; `maxPerSession` (default 3) caps hints within a session, `threshold` (default 0.9) tunes sensitivity, `maxPerSession` (default 3) caps hints within a session, `threshold` (default 0.9) tunes sensitivity, and `budget` (default 512, clamped 128–8192 — same range as [pi-fovea](https://github.com/monotykamary/pi-fovea)'s `sync.budget`) caps the advisory text in tokens (estimated as chars/4; rendering walks a degradation ladder — indented tool tree with descriptions → names-only tree → flat per-source lines → `header + steer` — until a rung fits; the ladder keeps leftover tool names in a `+N more:` leaf so they stay addressable). The matcher follows a combustion model: 1/df-weighted term scoring, strong matches fire instantly, weak matches accumulate warmth ($W \leftarrow \frac{1}{2}W + \frac{1}{2}s$; ignites at $W \geq$ threshold), each namespace's fire-set is durable *ash* (`fired` or `organic` — organic covers tools you used without a hint) persisted in `<agent-dir>/fabric/capability-advisories.json` across restarts, and ignored fires push smoke streaks that raise the weak-band ignition point by $\theta/\tau^2$ per streak ($0.25\theta$ at the internal memory scale $\tau = 2$ — every internal constant projects from $\tau$ and the score quantum $q = 1$). See [docs/capability-combustion.md](docs/capability-combustion.md) for the full math. Skill markup pi expands into the prompt (`<available_skills>`/`<skill>` blocks) is stripped before matching so a loaded skill cannot trigger its own hint. The hint follows fovea's structured shape: headline, `Candidates:` refs grouped by source, a `Next:` schema/action line for the top ref, and a `Steer:` directive.
+- `capture.advisory` injects a capability hint at `before_agent_start` when the prompt's terms match a captured source's tf-idf fingerprint (names + descriptions grouped by source namespace, no manifest declarations needed). `mode: "enabled"` (default) renders the hint in the transcript, `"hidden"` delivers it to the model only, and `"disabled"` turns it off. Each capability fires at most once per session — ash is derived from the session transcript itself (a fired hint is its own custom-message entry; organic use is its own tool call), so reloads and `/tree` branch rewinds replay ashes exactly up to the current point, and a brand-new session starts with a clean urn; `maxPerSession` (default 3) caps hints within a session, `threshold` (default 0.9) tunes sensitivity, `maxPerSession` (default 3) caps hints within a session, `threshold` (default 0.9) tunes sensitivity, and `budget` (default 512, clamped 128–8192 — same range as [pi-fovea](https://github.com/monotykamary/pi-fovea)'s `sync.budget`) caps the advisory text in tokens (estimated as chars/4; rendering walks a degradation ladder — indented tool tree with descriptions → names-only tree → flat per-source lines → `header + steer` — until a rung fits; the ladder keeps leftover tool names in a `+N more:` leaf so they stay addressable). The matcher follows a combustion model: 1/df-weighted term scoring, strong matches fire instantly, weak matches accumulate warmth ($W \leftarrow \frac{1}{2}W + \frac{1}{2}s$; ignites at $W \geq$ threshold), each namespace's fire-set is durable *ash* (`fired` or `organic` — organic covers tools you used without a hint) persisted in `<agent-dir>/fabric/capability-advisories.json` across restarts, and ignored fires push smoke streaks that raise the weak-band ignition point by $\theta/\tau^2$ per streak ($0.25\theta$ at the internal memory scale $\tau = 2$ — every internal constant projects from $\tau$ and the score quantum $q = 1$). See [docs/capability-combustion.md](docs/capability-combustion.md) for the full math. Skill markup pi expands into the prompt (`<available_skills>`/`<skill>` blocks) is stripped before matching so a loaded skill cannot trigger its own hint. The hint follows fovea's structured shape: headline, `Candidates:` refs grouped by source, a `Next:` schema/action line for the top ref, and a `Steer:` directive.
 - An `ask` policy emits a warning notification and opens an explicit **Allow once** / **Allow for this session** / **Deny** permission prompt, matching Claude-style approval scopes. **Allow once** authorizes only the requested action. **Allow for this session** authorizes that risk class until the current Pi session ends. The TUI uses an inline wizard; RPC clients receive the equivalent `select` dialog.
 - Concurrent requests are serialized so a one-time approval never silently widens to sibling calls. Session-wide grants are shared between native calls and `fabric_exec`. Escape, dismissal, unavailable interactive UI, and session restart all fail closed.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fabric",
-  "version": "0.44.13",
+  "version": "0.44.15",
   "description": "A programmable tool and agent runtime for Pi",
   "type": "module",
   "main": "./dist/index.js",

package/dist/core/capability-advisory-store.d.ts

@@ -1,4 +0,0 @@
-import type { CapabilityBurn } from "./capability-advisory.js";
-export declare const loadCapabilityAdvisoryState: (filePath?: string) => CapabilityBurn[];
-export declare const saveCapabilityAdvisoryState: (burned: Iterable<CapabilityBurn>, filePath?: string) => void;
-//# sourceMappingURL=capability-advisory-store.d.ts.map

package/dist/core/capability-advisory-store.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"capability-advisory-store.d.ts","sourceRoot":"","sources":["../../src/core/capability-advisory-store.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAyB/D,eAAO,MAAM,2BAA2B,GAAI,WAAW,MAAM,KAAG,cAAc,EA2B7E,CAAC;AAEF,eAAO,MAAM,2BAA2B,GACtC,QAAQ,QAAQ,CAAC,cAAc,CAAC,EAChC,WAAW,MAAM,KAChB,IAGF,CAAC"}

package/dist/core/capability-advisory-store.js

@@ -1,46 +0,0 @@
-import { randomUUID } from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-const ADVISORY_STATE_FILENAME = "capability-advisories.json";
-const defaultStatePath = () => 
-// Sits beside the global actor registry: fired capability hints belong to
-// the user's machine-global agent dir so once-fired advisories stay quiet
-// across session restarts in every project.
-path.join(getAgentDir(), "fabric", ADVISORY_STATE_FILENAME);
-const atomicWriteJson = (filePath, value) => {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
-    const temporaryPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
-    fs.writeFileSync(temporaryPath, JSON.stringify(value, null, 2), {
-        encoding: "utf8",
-        mode: 0o600,
-    });
-    fs.renameSync(temporaryPath, filePath);
-};
-export const loadCapabilityAdvisoryState = (filePath) => {
-    try {
-        const raw = JSON.parse(fs.readFileSync(filePath ?? defaultStatePath(), "utf8"));
-        if (raw.format === 2 && Array.isArray(raw.burned)) {
-            return raw.burned.filter((entry) => typeof entry === "object" &&
-                entry !== null &&
-                typeof entry.namespace === "string" &&
-                (entry.origin === "fired" ||
-                    entry.origin === "organic"));
-        }
-        if (raw.format === 1 && Array.isArray(raw.fired)) {
-            return raw.fired
-                .filter((entry) => typeof entry === "string")
-                .map((namespace) => ({ namespace, origin: "fired" }));
-        }
-        return [];
-    }
-    catch {
-        // Missing or corrupt state means nothing has burned yet.
-        return [];
-    }
-};
-export const saveCapabilityAdvisoryState = (burned, filePath) => {
-    const document = { format: 2, burned: [...burned] };
-    atomicWriteJson(filePath ?? defaultStatePath(), document);
-};
-//# sourceMappingURL=capability-advisory-store.js.map

package/dist/core/capability-advisory-store.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"capability-advisory-store.js","sourceRoot":"","sources":["../../src/core/capability-advisory-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAE9D,MAAM,uBAAuB,GAAG,4BAA4B,CAAC;AAW7D,MAAM,gBAAgB,GAAG,GAAW,EAAE;AACpC,0EAA0E;AAC1E,0EAA0E;AAC1E,4CAA4C;AAC5C,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,uBAAuB,CAAC,CAAC;AAE9D,MAAM,eAAe,GAAG,CAAC,QAAgB,EAAE,KAAc,EAAQ,EAAE;IACjE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACvE,MAAM,aAAa,GAAG,GAAG,QAAQ,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,MAAM,CAAC;IACvE,EAAE,CAAC,aAAa,CAAC,aAAa,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;QAC9D,QAAQ,EAAE,MAAM;QAChB,IAAI,EAAE,KAAK;KACZ,CAAC,CAAC;IACH,EAAE,CAAC,UAAU,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;AACzC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,QAAiB,EAAoB,EAAE;IACjF,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,IAAI,gBAAgB,EAAE,EAAE,MAAM,CAAC,CAI7E,CAAC;QACF,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,OAAO,GAAG,CAAC,MAAM,CAAC,MAAM,CACtB,CAAC,KAAK,EAA2B,EAAE,CACjC,OAAO,KAAK,KAAK,QAAQ;gBACzB,KAAK,KAAK,IAAI;gBACd,OAAQ,KAAwB,CAAC,SAAS,KAAK,QAAQ;gBACvD,CAAE,KAAwB,CAAC,MAAM,KAAK,OAAO;oBAC1C,KAAwB,CAAC,MAAM,KAAK,SAAS,CAAC,CACpD,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,OAAO,GAAG,CAAC,KAAK;iBACb,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC;iBAC7D,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,OAAgB,EAAE,CAAC,CAAC,CAAC;QACnE,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,yDAAyD;QACzD,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAG,CACzC,MAAgC,EAChC,QAAiB,EACX,EAAE;IACR,MAAM,QAAQ,GAA2B,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC;IAC5E,eAAe,CAAC,QAAQ,IAAI,gBAAgB,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC5D,CAAC,CAAC"}