pi-background-tasks 0.7.2 → 0.7.3

package/PUBLISHING.md

@@ -1,6 +1,6 @@
 # Publishing pi-background-tasks
 
-Release checklist for npm publishing and standalone git publishing. The current release candidate is 0.7.2; version 0.7.0 introduced the Fusion public surfaces (`/fusion`, `/fusion-models`, `fusion_brainstorm`) in addition to the background-task surfaces. Do not advertise the GitHub install target until the standalone repository has the exact release commit and tag.
+Release checklist for npm publishing and standalone git publishing. The current release candidate is 0.7.3; version 0.7.0 introduced the Fusion public surfaces (`/fusion`, `/fusion-models`, `fusion_brainstorm`) in addition to the background-task surfaces. Do not advertise the GitHub install target until the standalone repository has the exact release commit and tag.
 
 ## Preconditions
 
@@ -34,8 +34,8 @@ npm publish --access public
 Pi install smoke after publish:
 
 ```bash
-PI_CODING_AGENT_DIR=$(mktemp -d) pi -e npm:pi-background-tasks@0.7.2 --offline --no-tools --no-session -p "/jobs"
-pi install npm:pi-background-tasks@0.7.2
+PI_CODING_AGENT_DIR=$(mktemp -d) pi -e npm:pi-background-tasks@0.7.3 --offline --no-tools --no-session -p "/jobs"
+pi install npm:pi-background-tasks@0.7.3
 ```
 
 ## Publish to git
@@ -48,15 +48,15 @@ git status --short --branch
 git log --oneline -3
 git remote -v
 git push origin main
-git tag v0.7.2
-git push origin v0.7.2
+git tag v0.7.3
+git push origin v0.7.3
 ```
 
 Pi install smoke after git tag, using an isolated Pi agent directory so no local checkout or user `~/.pi` state is involved:
 
 ```bash
-PI_CODING_AGENT_DIR=$(mktemp -d) pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.7.2 --offline --no-tools --no-session -p "/jobs"
-pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.7.2
+PI_CODING_AGENT_DIR=$(mktemp -d) pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.7.3 --offline --no-tools --no-session -p "/jobs"
+pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.7.3
 ```
 
 ## pi.dev/packages

package/README.md

@@ -9,19 +9,19 @@ This package adds named, tracked background shell jobs with durable output files
 From npm after publish:
 
 ```bash
-pi install npm:pi-background-tasks@0.7.2
+pi install npm:pi-background-tasks@0.7.3
 ```
 
 From git after pushing this package to its standalone repository and tagging:
 
 ```bash
-pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.7.2
+pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.7.3
 ```
 
 For project-local install:
 
 ```bash
-pi install -l npm:pi-background-tasks@0.7.2
+pi install -l npm:pi-background-tasks@0.7.3
 ```
 
 ## Commands
@@ -95,7 +95,7 @@ The lookup runs at most once per session on `session_start`, is time-boxed, and
 - `bg_status` — inspect one task or all recent tasks.
 - `bg_logs` — read bounded task output.
 - `bg_kill` — stop a running task.
-- `fusion_brainstorm({prompt})` — always-active tool that runs the Fusion workflow and returns the exact merged text as the tool result for the parent agent to consume, with standard nested usage attached when the host Pi supports tool-result usage. Its closed public schema has exactly one required parameter, `prompt`; extra keys are rejected. It has no eligibility, quota, routine, or justification gate. Tool context capture excludes the current assistant tool-call leaf when Pi is executing that `fusion_brainstorm` call, so the nested children do not see the in-progress tool call or sibling calls.
+- `fusion_brainstorm({prompt})` — always-active tool that runs the Fusion workflow and returns the exact merged text as the tool result for the parent agent to consume, with the exact Pi `Usage` shape attached when the host supports tool-result usage: token fields plus complete `cost.input`, `cost.output`, `cost.cacheRead`, `cost.cacheWrite`, and `cost.total`. Its closed public schema has exactly one required parameter, `prompt`; extra keys are rejected. It has no eligibility, quota, routine, or justification gate. Tool context capture excludes the current assistant tool-call leaf when Pi is executing that `fusion_brainstorm` call, so the nested children do not see the in-progress tool call or sibling calls.
 
 `bg_run` requires a concise `name` for the footer dock, the shell `command`, and required `isAgent: boolean`. Set `isAgent: true` only when the background task launches an LLM/agent process (for example `pi -p ...` or `pi --mode json ...`); set `isAgent: false` for scripts, tests, dev servers, sleeps, and ordinary shell commands. It defaults both `notifyOnCompletion` and `triggerOnCompletion` to `true`. With those defaults, `bg_run` returns immediately, the agent continues only independent useful work or ends its current turn instead of sleeping or polling, and a durable `background-task-notification` for completed, failed, or killed state automatically starts a follow-up turn. The launch receipt states the effective notification/wake behavior explicitly. `bg_status` and `bg_logs` remain available for user-requested inspection, deliberately disabled completion delivery, concrete hang diagnosis, or reading output after the terminal event; they are not waiting primitives, and the terminal notification does not need status reconfirmation. Setting `triggerOnCompletion: false` keeps the notification but prevents it from starting an agent turn. Setting `notifyOnCompletion: false` suppresses both notification and wake-up even if `triggerOnCompletion` is true.
 
@@ -108,7 +108,7 @@ Tasks marked with `isAgent: true` that launch print/json child Pi agents through
 
 Fusion runs direct child `pi --mode text` processes only; it never calls `pi-ai` completion APIs. Each child is launched with `--no-session`, `--no-tools`, `--no-extensions`, `--no-skills`, `--no-prompt-templates`, `--no-themes`, and `--no-context-files`, plus the resolved provider/model/thinking level and the package-owned private `extensions/fusion-child.ts` metadata extension. The prompt travels over stdin, not a shell or positional argument.
 
-Pi text mode writes the final full answer exactly once instead of serializing cumulative reasoning/partial-message events on every token delta. The private child extension emits one compact, reasoning-free metadata record per finalized assistant message for provider/model, stop reason, usage, and response byte/hash validation. Fusion persists those compact records in `*.events.jsonl`; the complete answer remains in the stage response artifact. The 32 MiB child stdout cap therefore applies to one final response, not amplified JSON telemetry. Failed attempts keep the authoritative response artifact empty and, when any stdout was captured, persist it separately as an explicitly incomplete `*.response.partial.*` artifact.
+Pi text mode writes the final full answer exactly once instead of serializing cumulative reasoning/partial-message events on every token delta. The private child extension emits one compact, reasoning-free metadata record per finalized assistant message for provider/model, stop reason, the complete Pi token/cost `Usage` object, and response byte/hash validation. Fusion persists those compact records in `*.events.jsonl`; the complete answer remains in the stage response artifact. The 32 MiB child stdout cap therefore applies to one final response, not amplified JSON telemetry. Failed attempts keep the authoritative response artifact empty and, when any stdout was captured, persist it separately as an explicitly incomplete `*.response.partial.*` artifact.
 
 Model configuration is global under the Pi agent directory:
 
@@ -162,7 +162,7 @@ Fusion writes private debugging artifacts under:
 .pi/fusion/<session-id>-<pid>/<run-id>/
 ```
 
-Each run contains `manifest.json`, `canonical-input.json`, candidate/evaluation/merge prompts, raw child JSONL events, stderr, responses, `blind-candidates.json`, `evaluation.json`, `merged.md`, and `error.json` for failed/cancelled runs. Artifact files are written by private temp-file/fsync/rename, and manifests persist cumulative child usage plus per-attempt observed usage/model data for successful, failed, and cancelled child attempts. These artifacts are local evidence only; they are not shown in `/jobs` or the background-task dock.
+Each run contains `manifest.json`, `canonical-input.json`, candidate/evaluation/merge prompts, raw child JSONL events, stderr, responses, `blind-candidates.json`, `evaluation.json`, `merged.md`, and `error.json` for failed/cancelled runs. Artifact files are written by private temp-file/fsync/rename, and v2 manifests persist cumulative child usage plus per-attempt observed usage/model data for successful, failed, and cancelled child attempts. Every usage record preserves the complete Pi cost breakdown; the same exact shape is cloned into `fusion_brainstorm` tool results so newer Pi hosts can calculate and replay footer/session statistics safely. These artifacts are local evidence only; they are not shown in `/jobs` or the background-task dock.
 
 For attested Pi tasks only, the task id is `b` plus 32 random hex characters (128 bits) and additional flat siblings are written in the same directory:
 

package/TESTING.md

@@ -77,7 +77,7 @@ npm run test:rpc
 npm run test:agent-loop
 ```
 
-The Fusion SDK/RPC/scripted-provider tests install a deterministic fake child `pi` in a temp `PATH` from `tests/helpers/fusion-fake-pi.ts`. Parent Pi remains the real SDK/RPC runtime; only direct child `pi --mode text` calls with the package-owned private compact metadata extension are intercepted. `PI_CODING_AGENT_DIR` is pointed at the temp agent directory so `fusion-models.json` is never read from the user's real global Pi directory. Fusion context coverage is intentionally text-transcript coverage: tests verify long text is not summarization-truncated and image-containing session entries are represented by `[Image omitted from fusion text transcript: <mime-type>]` markers without forwarding raw image bytes/base64 to child Pi prompts. The release-only `npm run test:compat` packs the package, installs exact supported Pi versions, runs `/jobs`, runs `/fusion` through the installed package entrypoint with the fake child Pi, verifies five child invocations, and verifies `/fusion-models` rejects non-TUI mode.
+The Fusion SDK/RPC/scripted-provider tests install a deterministic fake child `pi` in a temp `PATH` from `tests/helpers/fusion-fake-pi.ts`. Parent Pi remains the real SDK/RPC runtime; only direct child `pi --mode text` calls with the package-owned private compact metadata extension are intercepted. `PI_CODING_AGENT_DIR` is pointed at the temp agent directory so `fusion-models.json` is never read from the user's real global Pi directory. Fusion context coverage is intentionally text-transcript coverage: tests verify long text is not summarization-truncated and image-containing session entries are represented by `[Image omitted from fusion text transcript: <mime-type>]` markers without forwarding raw image bytes/base64 to child Pi prompts. The release-only `npm run test:compat` packs the package, installs exact supported Pi versions, runs `/jobs`, runs `/fusion` through the installed package entrypoint with the fake child Pi, verifies five child invocations, and verifies `/fusion-models` rejects non-TUI mode. It then drives the current host Pi through a real RPC `fusion_brainstorm` parent-agent loop, checks the persisted tool result carries the complete Pi `Usage.cost` object, invokes `get_session_stats` (the same aggregation boundary used by the TUI footer), reopens the durable session, and verifies identical token/cost totals. All parent and child inference remains deterministic and local.
 
 ## Coverage summary
 
@@ -87,13 +87,13 @@ Implemented coverage includes:
 - commands: `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks`, `/bg-clear`, `/bg-update`, `/fusion`, `/fusion-models` discovery, happy paths, `/fusion` direct custom-message delivery, `/fusion` editor/cancel flow, `/fusion-models` TUI save and non-TUI rejection, `/bg --agent` parsing, finished-notice clearing, malformed `/bg`, unknown/ambiguous IDs, completed-task `/kill`, byte-limit normalization, and RPC no-hang fallback behavior
 - update-available notice: semver parse/compare/precedence, `formatUpdateSegment`, npm/`package.json` payload narrowing, and injected-fetch success/404/throw/timeout (unit); localhost-registry footer segment (idle + appended to an active footer), `/bg-update` non-installing instructions, and opt-out/offline/already-current/registry-failure no-segment-and-no-throw paths (SDK); `/bg-update` discovery and offline instructions (RPC). The check is one-shot on `session_start`, time-boxed, offline-safe, gated by `PI_OFFLINE`/`PI_BG_DISABLE_UPDATE_CHECK`, and `PI_BG_REGISTRY_URL` overrides the registry endpoint
 - shortcut/UI: component coverage for focused dock list/detail/key handling, detail output-tail scrolling (arrow/page scroll, follow-pause-on-scroll, `lines X–Y of N` position indicator, resume-follow-at-bottom, and no-scroll when output fits), empty/history/unread states, paging, close aliases, stop/stop-all/rerun/path actions, missing output files; SDK coverage for explicit `/bg-clear` finished-notice clearing, `/bg-clear` footer hinting, optional `Ctrl+Alt+C` fallback shortcut registration, and mixed failed/stopped/done/focused footer status; RPC coverage that `/bg-clear` works as a terminal-independent clear path; and PTY coverage for `/tasks`, `/bg-tasks`, real `Shift+Down`, arrows, page keys, detail/back/history/stop/stop-all/rerun/path/close, failed unread badges, and running/completed/failed/killed rerun paths
-- runtime files: output and metadata files under `.pi/tasks/`, Fusion private `.pi/fusion/<session-id>-<pid>/<run-id>/` artifacts plus global `fusion-models.json`, persisted `isAgent` classification, task-owned context-window telemetry snapshots, cumulative background Pi-agent token usage, tool-use counts, agent model identifier (preferring the fully-qualified `provider/model` form), explicit `isAgent:true` telemetry wrapping for background `pi` agents, `isAgent:false` non-wrapping for scripts, attested Pi flat siblings (`.pi-events.jsonl`, `.stderr`, `.pi-telemetry-wrapper.cjs`, `.attestation.json`), real child `pi --mode json` tool-event parsing for background-agent telemetry, split/large telemetry ingestion, metadata after completion/failure, Fusion compact final-only child metadata and explicitly marked partial-response artifacts, Fusion manifest aggregate usage equal to the sum of successful plus observed failed/cancelled child attempt usage, local tarball install contents
+- runtime files: output and metadata files under `.pi/tasks/`, Fusion private `.pi/fusion/<session-id>-<pid>/<run-id>/` artifacts plus global `fusion-models.json`, persisted `isAgent` classification, task-owned context-window telemetry snapshots, cumulative background Pi-agent token usage, tool-use counts, agent model identifier (preferring the fully-qualified `provider/model` form), explicit `isAgent:true` telemetry wrapping for background `pi` agents, `isAgent:false` non-wrapping for scripts, attested Pi flat siblings (`.pi-events.jsonl`, `.stderr`, `.pi-telemetry-wrapper.cjs`, `.attestation.json`), real child `pi --mode json` tool-event parsing for background-agent telemetry, split/large telemetry ingestion, metadata after completion/failure, Fusion v2 compact final-only metadata and explicitly marked partial-response artifacts, and Fusion manifest token plus complete cost-component aggregates equal to the sum of successful and observed failed/cancelled attempts
 - extension EventBus API: unit coverage for `pi-background-tasks:request:v1`/`response:v1` closed-frame validation, exact capability handshake, malformed payload rejection, unknown keys, unknown operations, duplicate request IDs, missing `session_start`, shutdown refusal, unsubscribe, strict terminal frame shape, and response-barrier ordering; registry coverage for exactly-one terminal publication after durable metadata plus loud/retriable terminal delivery failure; SDK coverage with a shared real `createEventBus()` loading the actual extension, starting `printf api-ok`, reading bounded logs, observing exactly one terminal event after the run response, and killing a real sleep task without model/provider calls
 - attested Pi producer: unit/SDK coverage for 128-bit attested task ids, exact direct argv/cwd, ModelRegistry OAuth observation without secrets, raw Pi session/message events, separate stderr, prompt/report/source hashes, authority start/finish commit/tree/clean checks, atomic metadata serialization, completion visibility only after the sidecar is durable, malformed event rejection, and no attestation sidecar for ordinary tasks
 - agent activity transcript: pure `parseAgentActivity`/`formatAgentActivityLine` coverage (assistant text, reasoning, tool start with arg summary, silent successful tool end, `✗ tool failed` errors, truncation, invalid/non-activity narrowing); registry-unit coverage that wrapped-agent stdout is reconstructed across split chunks into the human-readable transcript while telemetry/activity control JSON is stripped from the output file (telemetry fields still updated), stderr passes through, and the trailing partial line is flushed on finalize; SDK coverage that fake and real child `pi --mode json` runs surface `→ tool`/`✗ tool failed`/assistant text in `bg_logs` with no control JSON leaking into the visible output
 - safety: kill, already-finished kill failure, timeout failure, spawn failure, low output-cap failure, multi-task shutdown cleanup, process-group kill fallback, Windows child-kill behavior, SIGKILL escalation, duplicate finalization/notification races, metadata/notification failure handling, and pruning
 - agent loop: deterministic scripted-provider coverage against `extensions/background-tasks.ts` for actual event-driven `bg_run` behavior. The provider observes the effective system prompt, public tool descriptions, and real launch receipt and deliberately emits the pre-fix `bg_status` poll if any contract layer is absent; the passing path proves one launch, no sleep/status/log polling, one durable terminal notification, and exactly one follow-up turn. It also covers notification-only `triggerOnCompletion:false`, `/bg` display-only behavior, `notifyOnCompletion:false`, failed-task notification error fields, and parent-model `fusion_brainstorm` tool use followed by normal parent response
-- package: manifest, docs, `pi.extensions`, exported `src/core/extension-api.ts`, peer dependency/import parity, packed runtime files, tarball-install smoke, direct-completion import bans, test/helper/script/artifact exclusion, and isolated offline npm install environment for default package tests
+- package: manifest, docs, `pi.extensions`, exported `src/core/extension-api.ts`, peer dependency/import parity, packed runtime files, tarball-install smoke, direct-completion import bans, test/helper/script/artifact exclusion, isolated offline npm installation, exact-version compatibility, and current-host persisted/replayed tool-usage safety
 
 ## PTY notes
 

package/TEST_PLAN.md

@@ -34,7 +34,7 @@ This package follows:
 | Scripted provider | `npm run test:agent-loop` | full gate | implemented |
 | Pack dry run | `npm run pack:dry-run` | release gate | implemented |
 | Smoke | `npm run smoke` | no | implemented; isolated load-only |
-| Compatibility | `npm run test:compat` | release gate | implemented; exact Pi `0.75.5`, `0.81.1`, `0.82.1` pack/install plus `/jobs`, `/fusion`, and `/fusion-models` surfaces |
+| Compatibility | `npm run test:compat` | release gate | implemented; exact Pi `0.75.5`, `0.81.1`, `0.82.1` pack/install plus `/jobs`, `/fusion`, and `/fusion-models` surfaces, followed by a current-host real `fusion_brainstorm` session-stat and replay witness |
 
 ## Feature coverage matrix
 
@@ -51,9 +51,9 @@ This package follows:
 | Read task logs | `bg_logs` | yes | yes |  |  |  |  | yes | SDK verifies bounded content and the model-facing no-wait-loop contract. Scripted-provider ordinary waiting makes zero log calls. |
 | Stop task from LLM tool | `bg_kill` |  | yes |  |  |  |  |  | Covers running kill and already-finished loud failure. |
 | Fusion command direct result | `/fusion`, `fusion-result` custom message | yes | yes | yes |  | yes | yes |  | Core unit covers deterministic full text-transcript context construction, explicit image omission markers without raw image data, direct final-text child argv/stdin/compact-metadata parsing, exact multi-block answer reconstruction, artifacts, pre-abort handling, and orchestration. SDK runs real `/fusion` against a fake child `pi`, verifies exactly five child text-mode invocations, hidden prompt persistence, visible exact merged custom message, no parent assistant rewrite, renderer output, progress/status behavior, no-argument editor flow, editor cancellation, and malformed config causing zero children. RPC verifies command discovery, `/fusion <prompt>` with U+2028/U+2029 content, custom-message result emission, no parent `agent_start`, no-argument editor protocol, malformed config/child failure visibility, and child isolation flags. PTY verifies `/fusion` renders the exact merged answer directly in a real TUI. Compatibility smoke runs `/fusion` through every supported Pi version with the installed package entrypoint. |
-| Fusion tool result | `fusion_brainstorm({prompt})` | yes | yes |  |  |  | yes | yes | Tool is registered at load and re-added on `session_start`; no eligibility/quota/routine/justification gates are implemented. Unit/SDK cover closed one-parameter schema, extra-key rejection, active tool-call leaf exclusion before asynchronous config/model work, sibling-call exclusion, exact merged text delivery, image-containing session context serialized as text omission markers with raw image bytes/base64 absent from child stdin, standard nested usage when supported, progress updates, final details with usage/artifact/model snapshot, and invalid config zero-child failure. Scripted-provider coverage proves a deterministic parent model calls `fusion_brainstorm`, receives the exact merged tool result, exercises one evaluator schema-repair child after invalid first evaluator JSON, then responds normally. |
+| Fusion tool result | `fusion_brainstorm({prompt})` | yes | yes |  |  | current-host stats/replay | yes | yes | Tool is registered at load and re-added on `session_start`; no eligibility/quota/routine/justification gates are implemented. BUG-182 unit/SDK coverage pins the exact host `Usage` contract, complete cost-component aggregation, rejection of legacy `costTotal`, v2 child/result/manifest schemas, exact merged text, progress, context exclusion, and final details. The release compatibility gate drives a real current-host RPC agent through the tool, verifies persisted tool usage, invokes the same session-stat path used by the footer, then reopens the durable session and verifies identical stats. Scripted-provider coverage proves normal parent consumption and evaluator schema repair. |
 | Fusion model selector | `/fusion-models`, `fusion-models.json`, `FusionModelSelector` | yes | yes | yes | yes | yes | yes |  | Unit covers strict config parsing, duplicates, slash-containing model IDs, stale model failures, `$current`, atomic save, inter-process lock/revision compare-and-swap, and deterministic concurrent-save conflict. Component covers all five slots, duplicate selection, searchable model list, stale display, reset/save/cancel, persistence errors, and width safety. SDK drives the real command in a synthetic TUI context without `ctx.mode` to cover old Pi compatibility and verifies duplicate `$current`/explicit model persistence; SDK also verifies headless no-UI rejection. RPC verifies non-TUI notification without hanging, PTY verifies the real selector opens in a TUI, and compatibility smoke verifies print-mode rejection for every supported Pi version. |
-| Fusion child isolation/lifecycle | child `pi --mode text`, private compact metadata extension, shutdown cleanup, `.pi/fusion` artifacts | yes | yes | yes |  |  | yes |  | BUG-180 unit coverage proves reasoning and full response text are absent from compact metadata, text mode emits the complete final answer once, exact text-block byte/hash reconstruction preserves the unmodified answer, malformed metadata/model/stop/hash/newline states fail loudly, and the unchanged 32 MiB cap now bounds one semantic response. Unit coverage also covers argv, package-owned extension resolution, env cleanup, stdin failure, stdout/stderr caps, timeout/abort/process-group kill, abort-during-spawn race, cleanup failure surfacing, no-close-after-SIGKILL failure, manifest transitions, compact event artifacts, explicit incomplete partial-response artifacts, failed-run usage persistence, aggregate usage, transient spawn retry, sibling cancellation, concurrent workflows, and orchestrator cancellation. SDK/RPC verify actual public consumers launch direct child `pi` with all isolation flags. Session shutdown tracks initializing and live Fusion runs through the extension active-run set. |
+| Fusion child isolation/lifecycle | child `pi --mode text`, private compact metadata extension, shutdown cleanup, `.pi/fusion` artifacts | yes | yes | yes |  | current-host stats/replay | yes |  | BUG-180 coverage proves final-text transport, reasoning exclusion, strict response reconstruction, unchanged caps, isolation, process cleanup, failure artifacts, and lifecycle semantics. BUG-182 upgrades the private compact metadata and artifact manifest to v2, preserves all token and cost components, centralizes clone/add/empty operations, rejects missing/legacy/unknown/non-finite cost shapes, and proves successful plus failed/cancelled attempt costs aggregate exactly once. SDK/RPC verify public child isolation; session shutdown tracks initializing and live runs. |
 | Extension request/response service | `pi-background-tasks:request:v1` → `pi-background-tasks:response:v1` | yes | yes |  |  |  | yes |  | Unit covers closed-frame validation, capability handshake, unknown keys, unknown operation, duplicate request IDs, missing `session_start`, shutdown refusal, strict `run.payload`, strict malformed frames, and unsubscribe. SDK loads the real extension with a shared `createEventBus()`, starts `printf api-ok`, reads bounded logs, lists status, starts and kills a real sleep task, and checks malformed/unknown/duplicate controls without model/provider calls. Package tests assert `src/core/extension-api.ts` ships. |
 | Terminal EventBus publication | `pi-background-tasks:terminal:v1` | yes | yes |  |  |  | yes |  | Registry unit proves exactly-one terminal snapshot after durable metadata and loud/retriable EventBus delivery failure; extension API unit proves one strict terminal frame correlated by task id after the run response for immediate, normal, failed, timeout, and killed tasks; SDK observes one terminal event for a completed task and one for a killed task through the real extension service. |
 | Completion notification | custom message `background-task-notification` | yes | yes |  | renderer via typecheck |  |  | yes | BUG-181 unit/SDK coverage pins the durable-terminal guidance and truthful effective delivery receipts. Scripted provider loads the shipped extension, conditionally attempts the old `bg_status` poll when the real system prompt/descriptions/receipt are incomplete, and proves the fixed contract instead yields with exactly one `bg_run`, one terminal notification, and one default follow-up. Notification-only, notification-disabled, failed-task, and display-only `/bg` paths remain covered. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-background-tasks",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Pi extension package for background shell tasks plus five-model fusion brainstorming: bg_run tools, /bg commands, /fusion, fusion_brainstorm, model selector UI, bounded logs, kill/timeout safety, and completion wakeups.",
   "type": "module",
   "license": "ISC",

package/src/core/fusion/artifacts.ts

@@ -8,6 +8,7 @@ import {
   EMPTY_FUSION_USAGE,
   FUSION_MANIFEST_SCHEMA_VERSION,
   FusionError,
+  cloneFusionUsage,
   type FusionArtifactManifest,
   type FusionArtifactRef,
   type FusionAttemptArtifactRecord,
@@ -83,18 +84,6 @@ function makeRunId(): string {
   return `f${randomBytes(16).toString('hex')}`;
 }
 
-function usageClone(usage: FusionUsage): FusionUsage {
-  const out: FusionUsage = {
-    input: usage.input,
-    output: usage.output,
-    cacheRead: usage.cacheRead,
-    cacheWrite: usage.cacheWrite,
-    totalTokens: usage.totalTokens,
-  };
-  if (usage.costTotal !== undefined) out.costTotal = usage.costTotal;
-  return out;
-}
-
 function modelsForManifest(models: ResolvedFusionModels): MutableFusionArtifactManifest['models'] {
   const first = models.candidates[0].qualifiedId;
   const second = models.candidates[1].qualifiedId;
@@ -196,7 +185,7 @@ function publicManifest(manifest: MutableFusionArtifactManifest): FusionArtifact
     cwd: manifest.cwd,
     config: manifest.config,
     models: manifest.models,
-    usage: usageClone(manifest.usage),
+    usage: cloneFusionUsage(manifest.usage),
     attempts: [...manifest.attempts],
     artifacts: { ...manifest.artifacts },
   };
@@ -260,7 +249,7 @@ export class FusionArtifactStore {
       cwd: options.cwd,
       config: options.config,
       models: modelsForManifest(options.models),
-      usage: usageClone(EMPTY_FUSION_USAGE),
+      usage: cloneFusionUsage(EMPTY_FUSION_USAGE),
       attempts: [],
       artifacts: {},
     };
@@ -316,7 +305,7 @@ export class FusionArtifactStore {
 
   async setUsage(usage: FusionUsage): Promise<void> {
     await this.updateManifest((manifest) => {
-      manifest.usage = usageClone(usage);
+      manifest.usage = cloneFusionUsage(usage);
     });
   }
 
@@ -372,7 +361,7 @@ export class FusionArtifactStore {
         provider: input.result.provider,
         model: input.result.model,
         qualifiedId: input.result.qualifiedId,
-        usage: usageClone(input.result.usage),
+        usage: cloneFusionUsage(input.result.usage),
       };
       if (input.result.slot !== undefined) record.slot = input.result.slot;
       manifest.attempts.push(record);
@@ -403,12 +392,11 @@ export class FusionArtifactStore {
         response_path: responseRef.path,
         error: input.error,
       };
-      if (partialResponseRef !== undefined)
-        record.partial_response_path = partialResponseRef.path;
+      if (partialResponseRef !== undefined) record.partial_response_path = partialResponseRef.path;
       if (input.provider !== undefined) record.provider = input.provider;
       if (input.model !== undefined) record.model = input.model;
       if (input.qualifiedId !== undefined) record.qualifiedId = input.qualifiedId;
-      if (input.usage !== undefined) record.usage = usageClone(input.usage);
+      if (input.usage !== undefined) record.usage = cloneFusionUsage(input.usage);
       if (input.slot !== undefined) record.slot = input.slot;
       manifest.attempts.push(record);
     });

package/src/core/fusion/orchestrator.ts

@@ -27,6 +27,8 @@ import {
 import {
   FUSION_RESULT_SCHEMA_VERSION,
   FusionError,
+  addFusionUsage,
+  createEmptyFusionUsage,
   type FusionCanonicalInputV1,
   type FusionCandidateId,
   type FusionChildRunResult,
@@ -80,21 +82,8 @@ interface EvaluationAttemptResult {
   errors: readonly string[];
 }
 
-function emptyUsage(): FusionUsage {
-  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 };
-}
-
-function addUsage(target: FusionUsage, delta: FusionUsage): void {
-  target.input += delta.input;
-  target.output += delta.output;
-  target.cacheRead += delta.cacheRead;
-  target.cacheWrite += delta.cacheWrite;
-  target.totalTokens += delta.totalTokens;
-  if (delta.costTotal !== undefined) target.costTotal = (target.costTotal ?? 0) + delta.costTotal;
-}
-
 function addFailedChildUsage(target: FusionUsage, error: unknown): void {
-  if (error instanceof FusionChildRunError) addUsage(target, error.usage);
+  if (error instanceof FusionChildRunError) addFusionUsage(target, error.usage);
 }
 
 function errorText(error: unknown): string {
@@ -340,7 +329,7 @@ export class FusionOrchestrator {
     if (this.now !== undefined) storeOptions.now = this.now;
     const store = await this.createArtifactStore(storeOptions);
     input.onProgress?.({ type: 'state', state: 'initializing' });
-    const usage = emptyUsage();
+    const usage = createEmptyFusionUsage();
     try {
       await store.writeCanonicalInput(input.canonicalInputSerialized);
       await store.transition('candidates_running');
@@ -378,7 +367,7 @@ export class FusionOrchestrator {
         undefined,
         'md',
       );
-      addUsage(usage, merged.usage);
+      addFusionUsage(usage, merged.usage);
       await store.recordChildAttempt({ result: merged, prompt: mergePrompt, responseKind: 'md' });
       await store.writeMerged(merged.text);
       await store.setUsage(usage);
@@ -465,7 +454,7 @@ export class FusionOrchestrator {
         ).then(async (result) => {
           await store.recordChildAttempt({ result, prompt, responseKind: 'md' });
           completed += 1;
-          addUsage(usage, result.usage);
+          addFusionUsage(usage, result.usage);
           await store.setUsage(usage);
           input.onProgress?.({ type: 'candidate_completed', slot, completed, total: 3 });
           return { slot, result };
@@ -545,7 +534,7 @@ export class FusionOrchestrator {
       'txt',
       attempt,
     );
-    addUsage(usage, result.usage);
+    addFusionUsage(usage, result.usage);
     await store.recordChildAttempt({ result, prompt, responseKind: 'txt' });
     await store.setUsage(usage);
     const parsed = parseEvaluationAttempt(result.text);

package/src/core/fusion/pi-child.ts

@@ -8,13 +8,16 @@ import {
   FUSION_CHILD_RESULT_SCHEMA_VERSION,
   type FusionChildResultMetadata,
 } from '../../fusion-child-extension.js';
-import type { ResolvedFusionModel } from './types.js';
 import {
   FusionError,
+  addFusionUsage,
+  cloneFusionUsage,
+  createEmptyFusionUsage,
   type FusionChildRunResult,
   type FusionErrorDetails,
   type FusionStage,
   type FusionUsage,
+  type ResolvedFusionModel,
 } from './types.js';
 import { isJsonObject, parseJsonText } from '../common.js';
 
@@ -149,7 +152,7 @@ export class FusionChildRunError extends FusionError {
     this.stderr = stderr;
     this.exitCode = close.code;
     this.signalName = close.signal;
-    this.usage = { ...observed.usage };
+    this.usage = cloneFusionUsage(observed.usage);
     this.provider = observed.provider;
     this.modelName = observed.model;
     this.qualifiedId = observed.qualifiedId;
@@ -204,15 +207,6 @@ export function buildFusionPiChildArgv(
   ];
 }
 
-function addUsage(target: FusionUsage, delta: FusionUsage): void {
-  target.input += delta.input;
-  target.output += delta.output;
-  target.cacheRead += delta.cacheRead;
-  target.cacheWrite += delta.cacheWrite;
-  target.totalTokens += delta.totalTokens;
-  if (delta.costTotal !== undefined) target.costTotal = (target.costTotal ?? 0) + delta.costTotal;
-}
-
 const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
 const FUSION_CHILD_RESULT_PREFIX_BYTES = Buffer.from(FUSION_CHILD_RESULT_PREFIX, 'utf8');
 
@@ -265,32 +259,42 @@ function requireUsageInteger(
   return value;
 }
 
+function requireCostNumber(
+  record: Record<PropertyKey, unknown>,
+  key: string,
+  label: string,
+): number {
+  const value = record[key];
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+    throw new Error(`${label}.${key} must be a non-negative finite number`);
+  return value;
+}
+
 function parseCompactUsage(value: unknown): FusionUsage {
-  if (!isJsonObject(value) || Array.isArray(value))
-    throw new Error('fusion child usage must be an object');
-  const allowed = new Set(['input', 'output', 'cacheRead', 'cacheWrite', 'totalTokens', 'costTotal']);
-  for (const key of Object.keys(value)) {
-    if (!allowed.has(key)) throw new Error(`fusion child usage contains unknown key ${key}`);
-  }
-  for (const key of ['input', 'output', 'cacheRead', 'cacheWrite', 'totalTokens']) {
-    if (!Object.prototype.hasOwnProperty.call(value, key))
-      throw new Error(`fusion child usage is missing key ${key}`);
-  }
-  const record = value;
-  const usage: FusionUsage = {
+  const record = assertClosedRecord(
+    value,
+    ['input', 'output', 'cacheRead', 'cacheWrite', 'totalTokens', 'cost'],
+    'fusion child usage',
+  );
+  const cost = assertClosedRecord(
+    record['cost'],
+    ['input', 'output', 'cacheRead', 'cacheWrite', 'total'],
+    'fusion child usage.cost',
+  );
+  return {
     input: requireUsageInteger(record, 'input', 'fusion child usage'),
     output: requireUsageInteger(record, 'output', 'fusion child usage'),
     cacheRead: requireUsageInteger(record, 'cacheRead', 'fusion child usage'),
     cacheWrite: requireUsageInteger(record, 'cacheWrite', 'fusion child usage'),
     totalTokens: requireUsageInteger(record, 'totalTokens', 'fusion child usage'),
+    cost: {
+      input: requireCostNumber(cost, 'input', 'fusion child usage.cost'),
+      output: requireCostNumber(cost, 'output', 'fusion child usage.cost'),
+      cacheRead: requireCostNumber(cost, 'cacheRead', 'fusion child usage.cost'),
+      cacheWrite: requireCostNumber(cost, 'cacheWrite', 'fusion child usage.cost'),
+      total: requireCostNumber(cost, 'total', 'fusion child usage.cost'),
+    },
   };
-  const costTotal = record['costTotal'];
-  if (costTotal !== undefined) {
-    if (typeof costTotal !== 'number' || !Number.isFinite(costTotal) || costTotal < 0)
-      throw new Error('fusion child usage.costTotal must be a non-negative finite number');
-    usage.costTotal = costTotal;
-  }
-  return usage;
 }
 
 function parseChildResultMetadata(value: unknown): FusionChildResultMetadata {
@@ -385,7 +389,8 @@ function reconstructFinalText(response: Buffer, record: FusionChildResultMetadat
   if (sha256Buffer(joined) !== record.text_sha256)
     throw new Error('Pi final text aggregate hash mismatch');
   const text = joined.toString('utf8');
-  if (!Buffer.from(text, 'utf8').equals(joined)) throw new Error('Pi final text is not valid UTF-8');
+  if (!Buffer.from(text, 'utf8').equals(joined))
+    throw new Error('Pi final text is not valid UTF-8');
   if (text.trim().length === 0) throw new Error('Pi assistant response is empty');
   return text;
 }
@@ -404,11 +409,14 @@ export class FusionPiCompactResultParser {
       const parsed = parseFusionChildStderr(stderr);
       return this.observedFromRecords(parsed.records);
     } catch {
-      return { usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 } };
+      return { usage: createEmptyFusionUsage() };
     }
   }
 
-  finish(response: Buffer, stderr: Buffer): {
+  finish(
+    response: Buffer,
+    stderr: Buffer,
+  ): {
     text: string;
     usage: FusionUsage;
     provider: string;
@@ -443,15 +451,11 @@ export class FusionPiCompactResultParser {
     }
   }
 
-  private observedFromRecords(records: readonly FusionChildResultMetadata[]): ObservedChildSnapshot {
-    const usage: FusionUsage = {
-      input: 0,
-      output: 0,
-      cacheRead: 0,
-      cacheWrite: 0,
-      totalTokens: 0,
-    };
-    for (const record of records) addUsage(usage, record.usage);
+  private observedFromRecords(
+    records: readonly FusionChildResultMetadata[],
+  ): ObservedChildSnapshot {
+    const usage = createEmptyFusionUsage();
+    for (const record of records) addFusionUsage(usage, record.usage);
     const final = records.at(-1);
     if (final === undefined) return { usage };
     return {

package/src/core/fusion/types.ts

@@ -1,10 +1,12 @@
+import type { Usage } from '@earendil-works/pi-ai';
+
 export type FusionThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 
 export const FUSION_MODEL_CONFIG_SCHEMA_VERSION = 'pi-background-tasks.fusion-models.v1';
 export const FUSION_INPUT_SCHEMA_VERSION = 'pi-background-tasks.fusion-input.v1';
 export const FUSION_EVALUATION_SCHEMA_VERSION = 'pi-background-tasks.fusion-evaluation.v1';
-export const FUSION_RESULT_SCHEMA_VERSION = 'pi-background-tasks.fusion-result.v1';
-export const FUSION_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.fusion-manifest.v1';
+export const FUSION_RESULT_SCHEMA_VERSION = 'pi-background-tasks.fusion-result.v2';
+export const FUSION_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.fusion-manifest.v2';
 
 export const FUSION_CANDIDATE_IDS = ['A', 'B', 'C'] as const;
 export type FusionCandidateId = (typeof FUSION_CANDIDATE_IDS)[number];
@@ -124,14 +126,16 @@ export interface FusionEvaluationV1 {
   synthesis_plan: FusionSynthesisPlan;
 }
 
-export interface FusionUsage {
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheWrite: number;
-  totalTokens: number;
-  costTotal?: number;
-}
+/** Exact Pi usage contract used at the child, artifact, and host tool-result boundaries. */
+export type FusionUsage = Usage;
+
+const EMPTY_FUSION_COST: Usage['cost'] = Object.freeze({
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  total: 0,
+});
 
 export const EMPTY_FUSION_USAGE: FusionUsage = Object.freeze({
   input: 0,
@@ -139,8 +143,43 @@ export const EMPTY_FUSION_USAGE: FusionUsage = Object.freeze({
   cacheRead: 0,
   cacheWrite: 0,
   totalTokens: 0,
+  cost: EMPTY_FUSION_COST,
 });
 
+export function createEmptyFusionUsage(): FusionUsage {
+  return cloneFusionUsage(EMPTY_FUSION_USAGE);
+}
+
+export function cloneFusionUsage(usage: FusionUsage): FusionUsage {
+  return {
+    input: usage.input,
+    output: usage.output,
+    cacheRead: usage.cacheRead,
+    cacheWrite: usage.cacheWrite,
+    totalTokens: usage.totalTokens,
+    cost: {
+      input: usage.cost.input,
+      output: usage.cost.output,
+      cacheRead: usage.cost.cacheRead,
+      cacheWrite: usage.cost.cacheWrite,
+      total: usage.cost.total,
+    },
+  };
+}
+
+export function addFusionUsage(target: FusionUsage, delta: FusionUsage): void {
+  target.input += delta.input;
+  target.output += delta.output;
+  target.cacheRead += delta.cacheRead;
+  target.cacheWrite += delta.cacheWrite;
+  target.totalTokens += delta.totalTokens;
+  target.cost.input += delta.cost.input;
+  target.cost.output += delta.cost.output;
+  target.cost.cacheRead += delta.cost.cacheRead;
+  target.cost.cacheWrite += delta.cost.cacheWrite;
+  target.cost.total += delta.cost.total;
+}
+
 export interface FusionResultDetails {
   schema_version: typeof FUSION_RESULT_SCHEMA_VERSION;
   run_id: string;

package/src/fusion-child-extension.ts

@@ -1,8 +1,9 @@
 import { createHash } from 'node:crypto';
+import type { Usage } from '@earendil-works/pi-ai';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 
 export const FUSION_CHILD_RESULT_SCHEMA_VERSION =
-  'pi-background-tasks.fusion-child-result.v1' as const;
+  'pi-background-tasks.fusion-child-result.v2' as const;
 export const FUSION_CHILD_RESULT_PREFIX = '\u001ePI_FUSION_CHILD_RESULT ';
 
 export interface FusionChildTextBlockMetadata {
@@ -10,14 +11,7 @@ export interface FusionChildTextBlockMetadata {
   sha256: string;
 }
 
-export interface FusionChildResultUsageMetadata {
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheWrite: number;
-  totalTokens: number;
-  costTotal?: number;
-}
+export type FusionChildResultUsageMetadata = Usage;
 
 export interface FusionChildResultMetadata {
   schema_version: typeof FUSION_CHILD_RESULT_SCHEMA_VERSION;
@@ -38,14 +32,7 @@ export function buildFusionChildResultMetadata(message: {
   model: string;
   stopReason: string;
   content: ReadonlyArray<{ type: string; text?: string }>;
-  usage: {
-    input: number;
-    output: number;
-    cacheRead: number;
-    cacheWrite: number;
-    totalTokens: number;
-    cost: { total: number };
-  };
+  usage: Usage;
 }): FusionChildResultMetadata {
   const textBlocks = message.content.flatMap((part) =>
     part.type === 'text' && typeof part.text === 'string' ? [part.text] : [],
@@ -56,10 +43,14 @@ export function buildFusionChildResultMetadata(message: {
     cacheRead: message.usage.cacheRead,
     cacheWrite: message.usage.cacheWrite,
     totalTokens: message.usage.totalTokens,
+    cost: {
+      input: message.usage.cost.input,
+      output: message.usage.cost.output,
+      cacheRead: message.usage.cost.cacheRead,
+      cacheWrite: message.usage.cost.cacheWrite,
+      total: message.usage.cost.total,
+    },
   };
-  if (Number.isFinite(message.usage.cost.total) && message.usage.cost.total >= 0) {
-    usage.costTotal = message.usage.cost.total;
-  }
   return {
     schema_version: FUSION_CHILD_RESULT_SCHEMA_VERSION,
     provider: message.provider,

package/src/fusion-extension.ts

@@ -1,3 +1,4 @@
+import type { Usage } from '@earendil-works/pi-ai';
 import type {
   AgentToolResult,
   ExtensionAPI,
@@ -26,6 +27,7 @@ import { FusionOrchestrator } from './core/fusion/orchestrator.js';
 import {
   FUSION_RESULT_SCHEMA_VERSION,
   FusionError,
+  cloneFusionUsage,
   type FusionModelConfigV1,
   type FusionModelSelection,
   type FusionProgressEvent,
@@ -49,7 +51,7 @@ const FUSION_MODEL_COMMAND_NAME = 'fusion-models';
 
 type FusionToolDetails = FusionResultDetails | FusionProgressDetails;
 type FusionToolResultWithUsage = AgentToolResult<FusionToolDetails> & {
-  usage: FusionResultDetails['usage'];
+  usage: Usage;
 };
 
 type CommandDialogResult =
@@ -160,8 +162,7 @@ function makeProgressDetails(event: FusionProgressEvent): FusionProgressDetails
 
 function usageSummary(details: FusionResultDetails): string {
   const tokens = details.usage.totalTokens;
-  const cost =
-    details.usage.costTotal === undefined ? '' : ` · $${details.usage.costTotal.toFixed(4)}`;
+  const cost = ` · $${details.usage.cost.total.toFixed(4)}`;
   return `${String(tokens)} tokens${cost}`;
 }
 
@@ -578,7 +579,7 @@ export function registerFusionExtension(pi: ExtensionAPI): void {
       const toolResult: FusionToolResultWithUsage = {
         content: textContent(result.mergedText),
         details: result.details,
-        usage: result.details.usage,
+        usage: cloneFusionUsage(result.details.usage),
       };
       return toolResult;
     },