pi-background-tasks 0.7.0 → 0.7.3

package/PUBLISHING.md

@@ -1,6 +1,6 @@
 # Publishing pi-background-tasks
 
-Release checklist for npm publishing and standalone git publishing. Version 0.7.0 adds 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.0 --offline --no-tools --no-session -p "/jobs"
-pi install npm:pi-background-tasks@0.7.0
+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.0
-git push origin v0.7.0
+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.0 --offline --no-tools --no-session -p "/jobs"
-pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.7.0
+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.0
+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.0
+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.0
+pi install -l npm:pi-background-tasks@0.7.3
 ```
 
 ## Commands
@@ -33,7 +33,7 @@ pi install -l npm:pi-background-tasks@0.7.0
 - `/tasks` or `/bg-tasks` — fallback command to open the task manager UI.
 - `/bg-clear` — clear finished background-task footer notices.
 - `/bg-update` — print update instructions when a newer published version exists (instruct-only; never self-installs).
-- `/fusion <prompt>` — run three candidate child Pi JSON-mode calls, one blind evaluator, and one merger, then append the merged answer directly as a visible `fusion-result` custom message without asking the parent model to rewrite it. Running `/fusion` without arguments opens a multiline editor in UI-capable modes; cancelling the editor does not spawn children.
+- `/fusion <prompt>` — run three candidate child Pi final-text calls, one blind evaluator, and one merger, then append the merged answer directly as a visible `fusion-result` custom message without asking the parent model to rewrite it. Running `/fusion` without arguments opens a multiline editor in UI-capable modes; cancelling the editor does not spawn children.
 - `/fusion-models` — TUI-only five-slot global model selector (`Candidate 1`, `Candidate 2`, `Candidate 3`, `Evaluator`, `Merger`). It supports duplicate selections, `$current` defaults, slash-containing model ids, atomic saves to `fusion-models.json`, and rejects non-TUI modes immediately.
 
 ## Footer dock UX
@@ -95,16 +95,20 @@ 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 to `triggerOnCompletion: true`, so completion notifications trigger a follow-up agent turn. Tasks marked with `isAgent: true` that launch print/json child Pi agents through the normal shell command name are telemetry-wrapped; set `PI_BG_DISABLE_PI_TELEMETRY=1` only when raw Pi stdout is required. The task snapshot and metadata expose `isAgent`, `contextUsage` (latest reported child assistant turn), cumulative `tokenUsage` (`input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`), cumulative `toolUsage` (`total`, `failed`, `byName`), and `model` (the LLM identifier reported by the child assistant turns, preferring the fully-qualified `provider/model` form) when reported by the child task. User-launched `/bg` jobs are display-only by default unless `--agent` is provided; UI reruns preserve the original task's `isAgent` value.
+`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.
+
+Tasks marked with `isAgent: true` that launch print/json child Pi agents through the normal shell command name are telemetry-wrapped; set `PI_BG_DISABLE_PI_TELEMETRY=1` only when raw Pi stdout is required. The task snapshot and metadata expose `isAgent`, `contextUsage` (latest reported child assistant turn), cumulative `tokenUsage` (`input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`), cumulative `toolUsage` (`total`, `failed`, `byName`), and `model` (the LLM identifier reported by the child assistant turns, preferring the fully-qualified `provider/model` form) when reported by the child task. User-launched `/bg` jobs are display-only by default unless `--agent` is provided; UI reruns preserve the original task's `isAgent` value.
 
 `bg_run_pi_attested` is separate from `bg_run` and never accepts a shell command. It takes structured `provider`, `model`, `prompt`, optional literal extra Pi argv, and a relative `reportPath`; launches exactly one direct `pi --mode json` child; records raw Pi JSON events, separate stderr, exact argv/cwd, prompt/report hashes, observed Pi session/provider/model, and `ModelRegistry.isUsingOAuth` credential class. It forbids direct API-key/auth-file launch arguments and emits no partial attestation: failures remain ordinary failed tasks with no sidecar.
 
 
 ## Fusion workflow
 
-Fusion runs direct child `pi --mode json` 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. The prompt travels over stdin, not a shell or positional argument.
+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, 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:
 
@@ -158,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:
 
@@ -174,7 +178,7 @@ The attestation sidecar uses `schema_version: "phase2.pi_task_attestation.v1"` a
 ## Safety model
 
 - Commands are spawned and tracked with `child_process.spawn`; the package does not rely on shell `&`.
-- Fusion inference is isolated to direct child `pi --mode json` invocations with tools/extensions/skills/session/context files disabled; no direct completion API, API-key argument, or model fallback is used.
+- Fusion inference is isolated to direct child `pi --mode text` invocations with tools/skills/session/context files disabled and only the package-owned compact metadata extension explicitly loaded; no direct completion API, API-key argument, or model fallback is used.
 - Attested Pi tasks are a local, unsigned, same-user-writable attestation path for downstream gates. They bind source bytes and observed Pi/ModelRegistry facts; they are not cryptographic proof against a malicious local user, compromised Pi binary, or compromised provider.
 - stdout/stderr are captured to task output files.
 - Model-visible logs are bounded and point to full output files.

package/TESTING.md

@@ -77,23 +77,23 @@ 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 json` calls 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
 
 Implemented coverage includes:
 
-- tools: `bg_run`, `bg_run_pi_attested`, `bg_status`, `bg_logs`, `bg_kill`, `fusion_brainstorm`, including required `isAgent` schema/runtime validation, attested direct Pi spawn validation, Fusion exact merged tool result delivery/progress/details/context exclusion, text-transcript image omission markers with raw image data excluded from child prompts, unknown/ambiguous IDs, completed-kill failure, legacy no-name preparation, head/tail truncation, and notification on/off behavior
+- tools: `bg_run`, `bg_run_pi_attested`, `bg_status`, `bg_logs`, `bg_kill`, `fusion_brainstorm`, including required `isAgent` schema/runtime validation, the event-driven no-sleep/no-poll system-prompt contract, truthful launch receipts for all four notification/wake combinations, non-terminating `bg_run` compatibility, point-in-time status/log guidance, durable terminal-notification authority, attested direct Pi spawn validation, Fusion exact merged tool result delivery/progress/details/context exclusion, text-transcript image omission markers with raw image data excluded from child prompts, unknown/ambiguous IDs, completed-kill failure, legacy no-name preparation, head/tail truncation, and notification on/off behavior
 - 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, split/large telemetry ingestion, metadata after completion/failure, 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 for actual `bg_run` completion follow-up turns, `/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
+- 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, 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
 
@@ -45,18 +45,18 @@ This package follows:
 | Show bounded logs | `/logs <id> [maxBytes]` | yes |  | yes |  |  |  |  | Unit covers bounded reads; RPC verifies output/path. |
 | Kill running task | `/kill <id>` |  | yes | yes |  |  |  |  | SDK tool and RPC slash command. |
 | Open task manager fallback | `/tasks`, `/bg-tasks` |  |  | discovery | yes | yes |  |  | Component covers dock; PTY covers `/tasks` and `/bg-tasks`. |
-| Start background command from LLM tool | `bg_run` | yes | yes |  |  |  |  | yes | SDK starts named commands, verifies required `isAgent` schema/runtime behavior, and scripted provider verifies agent-loop tool calls with `isAgent:false` for scripts. |
+| Start background command from LLM tool | `bg_run` | yes | yes |  |  |  |  | yes | Unit derives all notification/wake modes from one typed helper. SDK exercises the registered tool's effective system prompt, descriptions, non-terminating behavior, and all four launch-receipt combinations. The scripted provider verifies a default launch yields without sleep/status/log polling before one terminal-event follow-up. |
 | Attested direct Pi producer | `bg_run_pi_attested` | yes | yes |  |  |  | type/schema |  | Unit covers 128-bit ids, exact direct argv, raw events/stderr, provider/model/session capture from Pi JSON, OAuth observation via ModelRegistry, prompt/report/source hash laws, completion visibility only after durable sidecar creation, malformed-event rejection, and no sidecar for ordinary tasks. SDK runs a fake Pi CLI through the public tool and verifies one complete flat attestation. |
-| Inspect task status | `bg_status` |  | yes |  |  |  |  |  | SDK polls exact IDs and validates shutdown state. |
-| Read task logs | `bg_logs` | yes | yes |  |  |  |  |  | SDK verifies content. |
+| Inspect task status | `bg_status` |  | yes |  |  |  |  | yes | SDK uses exact IDs for deterministic lifecycle observations and verifies the model-facing contract calls status a point-in-time inspection rather than a wait primitive. Scripted-provider ordinary waiting makes zero status calls. |
+| 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 child argv/stdin/event parsing, artifacts, pre-abort handling, and orchestration. SDK runs real `/fusion` against a fake child `pi`, verifies exactly five child JSON-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 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 |  |  | 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 json`, shutdown cleanup, `.pi/fusion` artifacts | yes | yes | yes |  |  | yes |  | Unit covers argv, env cleanup, stdin transport, LF JSONL parser, stdin failure, stdout/stderr output caps, timeout/abort/process-group kill, abort-during-spawn race, cleanup failure surfacing, no-close-after-SIGKILL failure, manifest transitions, atomic artifact writes, failed-run usage persistence, aggregate manifest usage exactly matching successful plus observed failed/cancelled attempt usage for candidate/evaluator/repair/merger failures, failed-attempt response artifact references, transient spawn retry, candidate sibling cancellation, concurrent workflows, and orchestrator cancellation. SDK/RPC verify actual public command/tool 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 | Unit covers duplicate/failing notification paths; SDK verifies XML/details; scripted provider verifies real follow-up turns, display-only `/bg`, `notifyOnCompletion:false`, and failed-task error fields. |
+| 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. |
 | Footer status | `ctx.ui.setStatus` |  | load path + clear command/shortcut + mixed states/focused label |  | render semantics | yes |  |  | SDK verifies `/bg-clear` hint, failed/stopped/done combinations, running combinations, and focused label; PTY verifies Shift+Down dock path after footer-visible task. |
 | Explicit agent classification | required `bg_run.isAgent`, `/bg --agent`, task metadata | yes | yes |  |  |  |  | yes | `isAgent:true` is required only for LLM/agent tasks and enables Pi-agent telemetry wrapping when the command invokes plain `pi`; `isAgent:false` is required for scripts/non-agents and prevents wrapping even if the command text looks like `pi -p ...`. |
 | Per-task context usage | task row/detail + `bg_status`/metadata/notification snapshots | yes | yes |  | yes |  |  |  | SDK verifies task-owned telemetry is captured, explicitly marked background `pi` invocations are wrapped to emit telemetry, and parent `ctx.getContextUsage()` is not used; component verifies list/detail rendering plus `ctx —` placeholder. |
@@ -93,7 +93,7 @@ Lane A residual hardening is now covered by automated tests. No remaining harden
 | Process lifecycle/races | Unit tests cover duplicate error/close finalization, output-cap races, duplicate-notification prevention, waiter resolution via stop paths, metadata failure logging, and notification failure reset. |
 | Process-tree kill safety | Unit tests cover POSIX process-group kill, child fallback, both-fail loud errors, SIGTERM idempotency, SIGKILL escalation, and Windows child-kill/shell invocation. |
 | Pruning | Unit tests cover oldest-finished pruning while preserving running tasks. |
-| Completion follow-up turns | `test:agent-loop` registers a deterministic scripted provider and verifies `bg_run` wakeup default, `/bg` display-only default, `notifyOnCompletion:false`, failed notification error fields, and real follow-up provider calls. |
+| Completion follow-up turns | `test:agent-loop` registers a deterministic scripted provider against the shipped extension path and verifies event-driven `bg_run` yielding with no sleep/status/log polling, exactly one default wakeup, notification-only `triggerOnCompletion:false`, `/bg` display-only behavior, `notifyOnCompletion:false`, and failed notification error fields. |
 | PTY secondary keys | `test:pty` covers arrows, page keys, `a`/`K`, `R`, `c`, `/bg-tasks`, failed/unread badges, multiple-task ordering, and rerun paths for running/completed/failed/killed tasks. |
 | Footer/status combinations | SDK tests cover failed/stopped/done/running combinations, explicit clear, and focused label. |
 

package/extensions/fusion-child.ts

@@ -0,0 +1 @@
+export { default } from '../src/fusion-child-extension.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-background-tasks",
-  "version": "0.7.0",
+  "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/common.ts

@@ -102,6 +102,66 @@ export interface BgTask extends Omit<BgTaskSnapshot, 'name'> {
   waiters: Array<() => void>;
 }
 
+export type CompletionDeliveryMode =
+  | 'notification-and-wake'
+  | 'notification-only'
+  | 'manual-monitoring';
+
+export interface CompletionDeliveryGuidance {
+  readonly mode: CompletionDeliveryMode;
+  readonly notificationEnabled: boolean;
+  readonly automaticWakeEnabled: boolean;
+  readonly text: string;
+}
+
+/**
+ * Describe the actual parent-agent completion path for one bg_run launch.
+ * A wake request cannot take effect without the notification that carries it.
+ */
+export function deriveCompletionDeliveryGuidance(
+  notifyOnCompletion: boolean,
+  triggerOnCompletion: boolean,
+): CompletionDeliveryGuidance {
+  if (notifyOnCompletion && triggerOnCompletion) {
+    return {
+      mode: 'notification-and-wake',
+      notificationEnabled: true,
+      automaticWakeEnabled: true,
+      text: [
+        'Terminal notification: enabled.',
+        'Automatic follow-up turn: enabled.',
+        'Next action: do not poll or sleep merely to wait; continue only independent useful work, otherwise end this turn and wait for <background-task-notification>.',
+      ].join('\n'),
+    };
+  }
+
+  if (notifyOnCompletion) {
+    return {
+      mode: 'notification-only',
+      notificationEnabled: true,
+      automaticWakeEnabled: false,
+      text: [
+        'Terminal notification: enabled.',
+        'Automatic follow-up turn: disabled. The terminal notification will be delivered, but it will not start an agent turn.',
+        'Next action: automatic wake-up was explicitly disabled; use bg_status/bg_logs only when deliberate monitoring is required, without tight polling.',
+      ].join('\n'),
+    };
+  }
+
+  return {
+    mode: 'manual-monitoring',
+    notificationEnabled: false,
+    automaticWakeEnabled: false,
+    text: [
+      'Terminal notification: disabled.',
+      triggerOnCompletion
+        ? 'Automatic follow-up turn: disabled because terminal notifications are disabled. triggerOnCompletion has no effect while notifyOnCompletion is false.'
+        : 'Automatic follow-up turn: disabled.',
+      'Next action: completion delivery was explicitly disabled; use bg_status/bg_logs only for deliberate manual monitoring, without tight polling.',
+    ].join('\n'),
+  };
+}
+
 export interface BgRunDetails {
   task: BgTaskSnapshot;
 }

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,
@@ -67,7 +68,8 @@ export interface RecordFusionFailedAttemptInput {
   slot?: 1 | 2 | 3;
   attempt: number;
   prompt: string;
-  stdout: Buffer;
+  events: Buffer;
+  partialResponse: Buffer;
   stderr: Buffer;
   error: string;
   status: 'failed' | 'cancelled';
@@ -82,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;
@@ -195,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 },
   };
@@ -259,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: {},
     };
@@ -315,7 +305,7 @@ export class FusionArtifactStore {
 
   async setUsage(usage: FusionUsage): Promise<void> {
     await this.updateManifest((manifest) => {
-      manifest.usage = usageClone(usage);
+      manifest.usage = cloneFusionUsage(usage);
     });
   }
 
@@ -353,7 +343,7 @@ export class FusionArtifactStore {
   async recordChildAttempt(input: RecordFusionChildAttemptInput): Promise<void> {
     const prefix = attemptPrefix(input.result.stage, input.result.slot, input.result.attempt);
     const promptRef = await this.writeArtifact(`${prefix}.prompt.txt`, input.prompt);
-    const eventsRef = await this.writeArtifact(`${prefix}.events.jsonl`, input.result.stdout);
+    const eventsRef = await this.writeArtifact(`${prefix}.events.jsonl`, input.result.events);
     const stderrRef = await this.writeArtifact(`${prefix}.stderr.txt`, input.result.stderr);
     const responseRef = await this.writeArtifact(
       responseName(prefix, input.responseKind),
@@ -371,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);
@@ -381,9 +371,16 @@ export class FusionArtifactStore {
   async recordFailedAttempt(input: RecordFusionFailedAttemptInput): Promise<void> {
     const prefix = attemptPrefix(input.stage, input.slot, input.attempt);
     const promptRef = await this.writeArtifact(`${prefix}.prompt.txt`, input.prompt);
-    const eventsRef = await this.writeArtifact(`${prefix}.events.jsonl`, input.stdout);
+    const eventsRef = await this.writeArtifact(`${prefix}.events.jsonl`, input.events);
     const stderrRef = await this.writeArtifact(`${prefix}.stderr.txt`, input.stderr);
     const responseRef = await this.writeArtifact(responseName(prefix, input.responseKind), '');
+    const partialResponseRef =
+      input.partialResponse.length === 0
+        ? undefined
+        : await this.writeArtifact(
+            `${prefix}.response.partial.${input.responseKind}`,
+            input.partialResponse,
+          );
     await this.updateManifest((manifest) => {
       const record: FusionAttemptArtifactRecord = {
         stage: input.stage,
@@ -395,10 +392,11 @@ export class FusionArtifactStore {
         response_path: responseRef.path,
         error: input.error,
       };
+      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 {
@@ -143,7 +132,8 @@ function recordFailureInput(
       stage,
       attempt,
       prompt,
-      stdout: error.stdout,
+      events: error.events,
+      partialResponse: error.response,
       stderr: error.stderr,
       error: error.message,
       status: error.code === 'child_cancelled' ? 'cancelled' : 'failed',
@@ -160,7 +150,8 @@ function recordFailureInput(
     stage,
     attempt,
     prompt,
-    stdout: Buffer.alloc(0),
+    events: Buffer.alloc(0),
+    partialResponse: Buffer.alloc(0),
     stderr: Buffer.alloc(0),
     error: errorText(error),
     status:
@@ -338,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');
@@ -376,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);
@@ -463,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 };
@@ -543,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);