pi-background-tasks 1.0.7 → 2.0.0

package/README.md

@@ -26,7 +26,7 @@
 | Fact | Value |
 | --- | --- |
 | Package | `pi-background-tasks` |
-| Version | `1.0.7` |
+| Version | `2.0.0` |
 | Node engine | `>=22.19.0` |
 | Pi entrypoint | `./extensions/background-tasks.ts` |
 | Package image | [logo.png](https://raw.githubusercontent.com/ismailsaleekh/pi-background-tasks/main/logo.png) |
@@ -123,13 +123,13 @@ Local paths are loaded from disk without copying; use the path to this package f
 
    Call this with `bg_result`. Retrieval is hash-verified and never silently truncated.
 
-6. For a self-contained synthesis, ask Fusion:
+6. For a self-contained synthesis, start Fusion in the background:
 
    ```json
    {"prompt":"Compare the tradeoffs between a watcher, a one-shot build, and a delegated repo inspection for a large refactor."}
    ```
 
-   Call this with `fusion_reason`, or use `/fusion <prompt>` interactively.
+   Call this with `fusion_reason`, or use `/fusion <prompt>` interactively. The launch returns after durable preflight; wait for its terminal notification, then retrieve the verified result with `bg_result`.
 
 More walkthrough detail: [Getting started](docs/getting-started.md).
 
@@ -142,10 +142,10 @@ More walkthrough detail: [Getting started](docs/getting-started.md).
 | `bg_run` | No | No model child unless command starts one | Runs your shell command; **not sandboxed** | Agent-started long commands | Returns task id/output path; defaults to notification plus automatic follow-up wake. |
 | `bg_delegate` + `bg_result` | No launch; retrieval is point-in-time | Frozen visible conversation projection | Inspect-only child: read, grep, find, ls, artifact read; no shell, writes, network, recursion | Context-aware read-only investigation while parent continues | Launch returns immediately; result is committed by child and hash-verified by retrieval. |
 | `bg_run_pi_attested` | No | Prompt passed to one direct child Pi run | Direct `pi --mode json`; no shell command; writes requested report path | Evidence-oriented direct Pi task | Emits local attestation sidecar only after successful completion. |
-| `/fusion` / `fusion_reason` | Synchronous | Versioned conversation projection plus prompt | Candidates/evaluator/repair/merger run with no tools | Self-contained reasoning and synthesis | Three candidates → blind evaluator → optional bounded repair if evaluator JSON is invalid → merger. |
-| `fusion_investigate` | Synchronous | Clean task input only | Candidate read-only repo tools; evaluator/repair/merger no tools | Independent repo investigation | Restate all needed facts in fields; parent hidden/tool context is not visible. |
-| `fusion_research` | Synchronous | Clean task input only | Candidate read-only repo tools plus targeted fetch of caller-supplied public URLs only | URL-backed synthesis | Targeted URL retrieval, **not web search**. |
-| `fusion_validate` | Synchronous | Clean task input only | Advisory read-only validation review | Second-opinion review of completed work | Not a replacement for tests, builds, linters, security scans, or human review. |
+| `/fusion` / `fusion_reason` | Background launch; point-in-time `bg_result` retrieval | Versioned conversation projection plus prompt | Candidates/evaluator/repair/merger run with no tools | Self-contained reasoning and synthesis | Returns after durable preflight; three candidates → blind evaluator → optional bounded repair → merger. |
+| `fusion_investigate` | Background launch; point-in-time `bg_result` retrieval | Clean task input only | Candidate read-only repo tools; evaluator/repair/merger no tools | Independent repo investigation | Restate needed facts; continue only independent work while the live repository is inspected. |
+| `fusion_research` | Background launch; point-in-time `bg_result` retrieval | Clean task input only | Candidate read-only repo tools plus targeted fetch of caller-supplied public URLs only | URL-backed synthesis | Targeted URL retrieval, **not web search**. |
+| `fusion_validate` | Background launch; point-in-time `bg_result` retrieval | Clean task input only | Advisory read-only validation review | Second-opinion review of completed work | Do not mutate the reviewed scope while it runs; not a substitute for mechanical gates. |
 
 See [Choose a workflow](docs/choose-a-workflow.md) for a decision tree and tradeoffs.
 

package/TESTING.md

@@ -186,14 +186,14 @@ 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 v1 public-surface coverage asserts exactly four tools (`fusion_reason`, `fusion_investigate`, `fusion_research`, `fusion_validate`), no public capability argument, retired-tool active-tool removal, `/fusion` mapping to reason/no-tool candidates, closed schemas with Google-compatible enum status, targeted URL fetch not search, URL exfiltration warnings, strict validation verification rules, historical v4 rendering without old-tool activation, and actionable migration errors for `fusion_validate({prompt})`. Fusion context coverage covers both reason conversation projection and clean-task non-interference invariants, including parent-sentinel absence from every clean downstream prompt/artifact and byte-identical clean inputs across unrelated parent sessions. `tests/unit/fusion-context-prompts.test.ts` verifies that a synthetic session carrying more than 1 MB of tool arguments/results still yields a small canonical input, that user and assistant text survive verbatim, that thinking and tool payloads never appear (including no head/tail/preview sentinel), that omission counts, byte totals, and hashes are exact and stable, that repeated construction is byte-identical, that the active Fusion tool leaf and sibling calls stay scope-excluded, that images remain marker-only or ledger-only with no raw base64 in child prompts, and that every retained source block receives exactly one disposition. `tests/unit/fusion-high-cardinality.test.ts` covers the receipt-cardinality regression: a session of many short interleaved tool events (rather than a few enormous results) pins per-receipt cost, proves the compact `omitted_activity` fields are the only model-facing ones, reconciles every receipt against the ledger through `projection_map`, and proves the whole workflow fits a real route budget. `tests/unit/fusion-budget.test.ts` covers stage budgets: each route reserves the larger of Fusion's output contract and the model's declared maximum output, the limiting model is selected by conservative byte capacity (including when it is the evaluator rather than a candidate), unknown or too-small capacities fail before spawn, boundary prompts pass at exactly the limit and fail one byte past it, the child system prompt counts as input, dense multi-byte UTF-8 cannot bypass byte accounting, and candidate, evaluator, evaluation-repair, and merger expansions are each rejected before their child is spawned with zero partial launches. `tests/unit/fusion-pi-child.test.ts` covers the post-launch `fusion-runtime-guard.v1` protocol, exact final-payload measurement, 128-request/192-tool limits, malformed or duplicate evidence rejection, typed parent errors, and failed audit sealing. `tests/unit/fusion-claude-cache.test.ts` pins default one-hour Claude retention, explicit short/none/long policy, model compatibility fallback, non-mutation, no-marker compaction preservation, the four-breakpoint ceiling, and malformed-control refusal, and distinct `child_cache_policy_invalid` parent errors. Child metadata binds each requested/effective cache observation in `fusion-child-result.v3`. Terminal `fusion-child-settlement.v2` is published only at `agent_settled`; recovered non-final provider errors must be zero-content/zero-usage retry markers named by that settlement, and missing/duplicate/tampered/failed settlements or substantive error records remain fatal. `tests/scripted-provider/fusion-runtime-guard.test.ts` drives a real Pi agent loop through Pi's `openai-codex-responses` adapter against local HTTP and proves provider-payload transforms chain in load order and the governor's `ctx.abort()` prevents network transport. `tests/package/typebox-compat.test.ts` pins the TypeBox posture and compiles nullable-array schemas. 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, verifies `/fusion-models` rejects non-TUI mode, requires each supported Pi line to declare terminal `agent_settled` and `before_provider_request`, verifies the installed Anthropic adapter exposes cache breakpoints plus long/tool compatibility controls, asserts the resolved `typebox` is Pi's bundled peer rather than a private or nested copy, and scans the installed package bytes for TypeBox APIs removed in the 1.3.x line. Pi 0.75.5 is intentionally unsupported because it lacks the terminal event required to seal a Fusion audit after retries and compaction. It then drives the current host Pi through a real RPC `fusion_reason` 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.
+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. SDK coverage proves the Fusion tools return after durable no-child preflight without waiting for delayed children, transfer cancellation ownership away from the completed tool call, remain tracked through status/dock/kill/notification, verify manifest-bound `result.json` plus `merged.md`, and attach complete usage on the first `bg_result` retrieval exactly once. The scripted provider proves launch → no-poll parent response → terminal wake → `bg_result` → verified answer. `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 v1 public-surface coverage asserts exactly four tools (`fusion_reason`, `fusion_investigate`, `fusion_research`, `fusion_validate`), no public capability argument, retired-tool active-tool removal, `/fusion` mapping to reason/no-tool candidates, closed schemas with Google-compatible enum status, targeted URL fetch not search, URL exfiltration warnings, strict validation verification rules, historical v4 rendering without old-tool activation, and actionable migration errors for `fusion_validate({prompt})`. Fusion context coverage covers both reason conversation projection and clean-task non-interference invariants, including parent-sentinel absence from every clean downstream prompt/artifact and byte-identical clean inputs across unrelated parent sessions. `tests/unit/fusion-context-prompts.test.ts` verifies that a synthetic session carrying more than 1 MB of tool arguments/results still yields a small canonical input, that user and assistant text survive verbatim, that thinking and tool payloads never appear (including no head/tail/preview sentinel), that omission counts, byte totals, and hashes are exact and stable, that repeated construction is byte-identical, that the active Fusion tool leaf and sibling calls stay scope-excluded, that images remain marker-only or ledger-only with no raw base64 in child prompts, and that every retained source block receives exactly one disposition. `tests/unit/fusion-high-cardinality.test.ts` covers the receipt-cardinality regression: a session of many short interleaved tool events (rather than a few enormous results) pins per-receipt cost, proves the compact `omitted_activity` fields are the only model-facing ones, reconciles every receipt against the ledger through `projection_map`, and proves the whole workflow fits a real route budget. `tests/unit/fusion-budget.test.ts` covers stage budgets: each route reserves the larger of Fusion's output contract and the model's declared maximum output, the limiting model is selected by conservative byte capacity (including when it is the evaluator rather than a candidate), unknown or too-small capacities fail before spawn, boundary prompts pass at exactly the limit and fail one byte past it, the child system prompt counts as input, dense multi-byte UTF-8 cannot bypass byte accounting, and candidate, evaluator, evaluation-repair, and merger expansions are each rejected before their child is spawned with zero partial launches. `tests/unit/fusion-pi-child.test.ts` covers the post-launch `fusion-runtime-guard.v1` protocol, exact final-payload measurement, 128-request/192-tool limits, malformed or duplicate evidence rejection, typed parent errors, and failed audit sealing. `tests/unit/fusion-claude-cache.test.ts` pins default one-hour Claude retention, explicit short/none/long policy, model compatibility fallback, non-mutation, no-marker compaction preservation, the four-breakpoint ceiling, and malformed-control refusal, and distinct `child_cache_policy_invalid` parent errors. Child metadata binds each requested/effective cache observation in `fusion-child-result.v3`. Terminal `fusion-child-settlement.v2` is published only at `agent_settled`; recovered non-final provider errors must be zero-content/zero-usage retry markers named by that settlement, and missing/duplicate/tampered/failed settlements or substantive error records remain fatal. `tests/scripted-provider/fusion-runtime-guard.test.ts` drives a real Pi agent loop through Pi's `openai-codex-responses` adapter against local HTTP and proves provider-payload transforms chain in load order and the governor's `ctx.abort()` prevents network transport. `tests/package/typebox-compat.test.ts` pins the TypeBox posture and compiles nullable-array schemas. 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, verifies `/fusion-models` rejects non-TUI mode, requires each supported Pi line to declare terminal `agent_settled` and `before_provider_request`, verifies the installed Anthropic adapter exposes cache breakpoints plus long/tool compatibility controls, asserts the resolved `typebox` is Pi's bundled peer rather than a private or nested copy, and scans the installed package bytes for TypeBox APIs removed in the 1.3.x line. Pi 0.75.5 is intentionally unsupported because it lacks the terminal event required to seal a Fusion audit after retries and compaction. It then drives the current host Pi through a real RPC `fusion_reason` 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_reason`, `fusion_investigate`, `fusion_research`, `fusion_validate`, 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, reason versioned conversation projection with explicit hash-accounted tool/thinking omissions, clean-task context isolation, pre-spawn stage budget rejection for all four expansion stages, 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
+- tools: `bg_run`, `bg_run_pi_attested`, `bg_status`, `bg_logs`, `bg_kill`, `fusion_reason`, `fusion_investigate`, `fusion_research`, `fusion_validate`, 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 immediate launch receipts, managed progress, hash-verified `bg_result` delivery, exactly-once usage, and context exclusion, reason versioned conversation projection with explicit hash-accounted tool/thinking omissions, clean-task context isolation, pre-spawn stage budget rejection for all four expansion stages, 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` non-blocking managed-task launch and terminal notification, `/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 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

package/TEST_PLAN.md

@@ -74,8 +74,8 @@ SDK/RPC/scripted-provider/package/compatibility coverage asserts exactly four to
 | 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 v2 conversation-projection 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 v1 tool result | `fusion_reason`, `fusion_investigate`, `fusion_research`, `fusion_validate` | yes | yes |  |  | current-host stats/replay | yes | yes | Exactly four tools are registered/activated; `fusion_brainstorm` is removed from active tools. No public `capability` exists. BUG-182 coverage pins the exact host `Usage` contract, complete cost-component aggregation, v4 result rendering, exact merged text, progress, context exclusion, and final details. The compatibility gate drives a real current-host RPC agent through `fusion_reason`, verifies persisted tool usage, invokes the same session-stat path used by the footer, then reopens the durable session and verifies identical stats. |
+| Fusion command background launch | `/fusion`, managed task, terminal notification, `bg_result` | yes | yes | yes |  | yes | yes |  | Core unit covers deterministic projection, child argv/stdin/metadata parsing, artifacts, pre-abort handling, and orchestration. SDK verifies `/fusion` returns after durable preflight, all five child invocations continue in the managed task, terminal notification is emitted without a parent rewrite, editor/cancel behavior remains correct, and malformed config launches zero children. RPC verifies command discovery, Unicode request preservation, background terminal delivery, no parent `agent_start`, editor protocol, malformed-config admission failure, child failure notification, and child isolation flags. |
+| Fusion v1 background result | `fusion_reason`, `fusion_investigate`, `fusion_research`, `fusion_validate`, `bg_result` | yes | yes |  |  | current-host stats/replay | yes | yes | Exactly four workflow tools remain registered; each returns a managed-task receipt after durable no-child preflight. `bg_result` verifies manifest-bound `result.json`/`merged.md`, never truncates, and attaches complete `Usage` exactly once. SDK pins non-blocking launch under delayed children, tool-signal ownership handoff, clean-context isolation, failure coordinates, shutdown cancellation, and repeated-retrieval no-double-counting. Scripted-provider coverage proves no polling between launch and terminal wake. |
 | Fusion Anthropic child sanitization | `@ravshansbox/pi-anthropic-sps` dependency, child `--extension` argv | yes |  |  |  |  | yes |  | Unit proves a Claude route receives exactly two `--extension` paths with the sanitizer first and the package runtime governor/metadata extension second, so final provider-payload measurement occurs after sanitization; every non-Anthropic provider still receives exactly one and never resolves the sanitizer at all, and that the real installed package resolves to an existing file through its manifest `pi.extensions[0]`. Resolution failures are each pinned as loud errors: package unresolvable, manifest unreadable, manifest not JSON, missing `pi` section, empty `pi.extensions`, blank entry, and a declared file that does not exist. Package guards require the sanitizer to be a declared dependency and require the provider gate so non-Anthropic child argv cannot drift. |
 | Fusion validation workflow | structured `fusion_validate`, workflow profiles, `fusion-manifest.v4`, `fusion-result.v5` | yes | yes |  |  |  | yes |  | Public validation rejects legacy `{prompt}` with a migration error, enforces non-empty `scope`/`acceptanceCriteria`, and loudly validates `verification` cross-fields (`provided` ↔ evidence, `not_run` ↔ reason). Core validate orchestration is clean/read-only/advisory, enforces source-finding accounting including singleton, duplicate, exclusion, and merger add/drop cases, and remains no build/test substitute claim. |
 | Fusion context boundaries | canonical input `fusion-input.v5`, reason `context-omission-ledger.json`, clean-task inputs | yes | yes | yes |  |  | yes |  | Unit covers reason/session projection for a >1 MB synthetic tool-heavy session, verbatim user/assistant text, thinking exclusion, zero tool-payload preview bytes, exact and stable omission counts/byte totals/hashes, compact tuple round-trip, receipt-to-ledger reconciliation, active-tool-call-leaf and sibling-call exclusion, and byte-identical repeated construction. Clean-task tests assert investigate/research/validate inputs omit parent system prompt, conversation projection, and omission ledger, stay byte-identical across unrelated parent sessions, and keep parent sentinels out of every clean downstream prompt and artifact. SDK/RPC verify clean validate stdin has no `conversation_projection` or transcript while `/fusion`/reason preserve the projected-conversation path. |

package/docs/INDEX.md

@@ -125,31 +125,31 @@ Generated navigation for every package-local documentation page. This index inte
 
 | Kind | Name | ID | Provenance |
 | --- | --- | --- | --- |
-| command | `bg` | `command:bg` | `src/extension.ts:506` |
-| command | `bg-clear` | `command:bg-clear` | `src/extension.ts:548` |
-| command | `bg-tasks` | `command:bg-tasks` | `src/extension.ts:540` |
-| command | `bg-update` | `command:bg-update` | `src/extension.ts:556` |
-| command | `fusion` | `command:fusion` | `src/fusion-extension.ts:891` |
-| command | `fusion-models` | `command:fusion-models` | `src/fusion-extension.ts:914` |
-| command | `jobs` | `command:jobs` | `src/extension.ts:594` |
-| command | `kill` | `command:kill` | `src/extension.ts:638` |
-| command | `logs` | `command:logs` | `src/extension.ts:607` |
-| command | `tasks` | `command:tasks` | `src/extension.ts:532` |
-| tool | `bg_delegate` | `tool:bg_delegate` | `src/delegate-extension.ts:265` |
-| tool | `bg_kill` | `tool:bg_kill` | `src/extension.ts:897` |
-| tool | `bg_logs` | `tool:bg_logs` | `src/extension.ts:852` |
-| tool | `bg_result` | `tool:bg_result` | `src/delegate-extension.ts:428` |
-| tool | `bg_run` | `tool:bg_run` | `src/extension.ts:671` |
-| tool | `bg_run_pi_attested` | `tool:bg_run_pi_attested` | `src/extension.ts:756` |
-| tool | `bg_status` | `tool:bg_status` | `src/extension.ts:821` |
-| tool | `fusion_investigate` | `tool:fusion_investigate` | `src/fusion-extension.ts:1049` |
-| tool | `fusion_reason` | `tool:fusion_reason` | `src/fusion-extension.ts:1032` |
-| tool | `fusion_research` | `tool:fusion_research` | `src/fusion-extension.ts:1066` |
-| tool | `fusion_validate` | `tool:fusion_validate` | `src/fusion-extension.ts:1084` |
-| shortcut | `ctrl+alt+c` | `shortcut:ctrl+alt+c` | `src/extension.ts:586` |
-| shortcut | `shift+down` | `shortcut:shift+down` | `src/extension.ts:579` |
-| renderer | `background-task-notification` | `renderer:background-task-notification` | `src/extension.ts:415` |
-| renderer | `fusion-result` | `renderer:fusion-result` | `src/fusion-extension.ts:875` |
+| command | `bg` | `command:bg` | `src/extension.ts:517` |
+| command | `bg-clear` | `command:bg-clear` | `src/extension.ts:559` |
+| command | `bg-tasks` | `command:bg-tasks` | `src/extension.ts:551` |
+| command | `bg-update` | `command:bg-update` | `src/extension.ts:567` |
+| command | `fusion` | `command:fusion` | `src/fusion-extension.ts:996` |
+| command | `fusion-models` | `command:fusion-models` | `src/fusion-extension.ts:1029` |
+| command | `jobs` | `command:jobs` | `src/extension.ts:605` |
+| command | `kill` | `command:kill` | `src/extension.ts:649` |
+| command | `logs` | `command:logs` | `src/extension.ts:618` |
+| command | `tasks` | `command:tasks` | `src/extension.ts:543` |
+| tool | `bg_delegate` | `tool:bg_delegate` | `src/delegate-extension.ts:292` |
+| tool | `bg_kill` | `tool:bg_kill` | `src/extension.ts:908` |
+| tool | `bg_logs` | `tool:bg_logs` | `src/extension.ts:863` |
+| tool | `bg_result` | `tool:bg_result` | `src/delegate-extension.ts:453` |
+| tool | `bg_run` | `tool:bg_run` | `src/extension.ts:682` |
+| tool | `bg_run_pi_attested` | `tool:bg_run_pi_attested` | `src/extension.ts:767` |
+| tool | `bg_status` | `tool:bg_status` | `src/extension.ts:832` |
+| tool | `fusion_investigate` | `tool:fusion_investigate` | `src/fusion-extension.ts:1197` |
+| tool | `fusion_reason` | `tool:fusion_reason` | `src/fusion-extension.ts:1179` |
+| tool | `fusion_research` | `tool:fusion_research` | `src/fusion-extension.ts:1216` |
+| tool | `fusion_validate` | `tool:fusion_validate` | `src/fusion-extension.ts:1236` |
+| shortcut | `ctrl+alt+c` | `shortcut:ctrl+alt+c` | `src/extension.ts:597` |
+| shortcut | `shift+down` | `shortcut:shift+down` | `src/extension.ts:590` |
+| renderer | `background-task-notification` | `renderer:background-task-notification` | `src/extension.ts:426` |
+| renderer | `fusion-result` | `renderer:fusion-result` | `src/fusion-extension.ts:980` |
 | eventbus | `background-task-v1` | `eventbus:background-task-v1` | `src/core/extension-api.ts` |
 | workflow | `investigate` | `workflow:investigate` | `src/core/fusion/workflows.ts:80` |
 | workflow | `reason` | `workflow:reason` | `src/core/fusion/workflows.ts:61` |

package/docs/choose-a-workflow.md

@@ -26,10 +26,10 @@ covers_sources: []
 | `bg_run` | Async | None by package | Command decides | Command decides | Command decides | Not a model route unless command invokes one | Pi should launch a long command and resume later. |
 | `bg_delegate` + `bg_result` | Async launch, point-in-time retrieval | Frozen visible conversation projection | Yes, inspect-only | No | No | Pinned at launch; no substitution | Context-aware read-only investigation. |
 | `bg_run_pi_attested` | Async | Prompt only | Child Pi decides from prompt/tools | Child Pi route/tools decide | Report path requested | Structured provider/model; OAuth observed for supported subscription routes | Local evidence-producing Pi run. |
-| `fusion_reason` / `/fusion` | Synchronous | Versioned conversation projection plus prompt | No | No | No | Configured Fusion slots; no silent fallback | Self-contained reasoning/synthesis. |
-| `fusion_investigate` | Synchronous | Clean task input only | Candidate read-only tools | No | No | Configured Fusion slots; no silent fallback | Independent repository investigation. |
-| `fusion_research` | Synchronous | Clean task input only | Candidate read-only tools | Only declared public URLs | No | Configured Fusion slots; no silent fallback | Targeted URL-backed synthesis, not search. |
-| `fusion_validate` | Synchronous | Clean task input only | Candidate read-only tools | No | No | Configured Fusion slots; no silent fallback | Advisory review of completed work. |
+| `fusion_reason` / `/fusion` | Async launch, point-in-time `bg_result` retrieval | Versioned conversation projection plus prompt | No | No | No | Configured Fusion slots; no silent fallback | Self-contained reasoning/synthesis. |
+| `fusion_investigate` | Async launch, point-in-time `bg_result` retrieval | Clean task input only | Candidate read-only tools | No | No | Configured Fusion slots; no silent fallback | Independent repository investigation. |
+| `fusion_research` | Async launch, point-in-time `bg_result` retrieval | Clean task input only | Candidate read-only tools | Only declared public URLs | No | Configured Fusion slots; no silent fallback | Targeted URL-backed synthesis, not search. |
+| `fusion_validate` | Async launch, point-in-time `bg_result` retrieval | Clean task input only | Candidate read-only tools | No | No | Configured Fusion slots; no silent fallback | Advisory review of completed work. |
 
 ## Tradeoffs and boundaries
 

package/docs/commands/bg-clear.md

@@ -12,7 +12,7 @@ covers_sources: []
 <!-- pi-docs:begin name="command-contract-bg-clear" generator="scripts/docs/generate.mjs" -->
 | Command | Description | Provenance |
 | --- | --- | --- |
-| `/bg-clear` | Clear finished background task footer notices | `src/extension.ts:548` |
+| `/bg-clear` | Clear finished background task footer notices | `src/extension.ts:559` |
 <!-- pi-docs:end name="command-contract-bg-clear" -->
 
 Clear finished background task footer notices.

package/docs/commands/bg-update.md

@@ -12,7 +12,7 @@ covers_sources: []
 <!-- pi-docs:begin name="command-contract-bg-update" generator="scripts/docs/generate.mjs" -->
 | Command | Description | Provenance |
 | --- | --- | --- |
-| `/bg-update` | Show how to update pi-background-tasks to the latest published version | `src/extension.ts:556` |
+| `/bg-update` | Show how to update pi-background-tasks to the latest published version | `src/extension.ts:567` |
 <!-- pi-docs:end name="command-contract-bg-update" -->
 
 Show update instructions for `pi-background-tasks`.

package/docs/commands/bg.md

@@ -12,7 +12,7 @@ covers_sources: []
 <!-- pi-docs:begin name="command-contract-bg" generator="scripts/docs/generate.mjs" -->
 | Command | Description | Provenance |
 | --- | --- | --- |
-| `/bg` | Start a shell command as a tracked background task: /bg [--agent] [--name "Task name"] <command> | `src/extension.ts:506` |
+| `/bg` | Start a shell command as a tracked background task: /bg [--agent] [--name "Task name"] <command> | `src/extension.ts:517` |
 <!-- pi-docs:end name="command-contract-bg" -->
 
 Start a shell command as a tracked background task from the command line.

package/docs/commands/fusion-models.md

@@ -12,7 +12,7 @@ covers_sources: []
 <!-- pi-docs:begin name="command-contract-fusion-models" generator="scripts/docs/generate.mjs" -->
 | Command | Description | Provenance |
 | --- | --- | --- |
-| `/fusion-models` | Open the five-slot global fusion model selector. | `src/fusion-extension.ts:914` |
+| `/fusion-models` | Open the five-slot global fusion model selector. | `src/fusion-extension.ts:1029` |
 <!-- pi-docs:end name="command-contract-fusion-models" -->
 
 Open the global Fusion model selector.

package/docs/commands/fusion.md

@@ -12,7 +12,7 @@ covers_sources: []
 <!-- pi-docs:begin name="command-contract-fusion" generator="scripts/docs/generate.mjs" -->
 | Command | Description | Provenance |
 | --- | --- | --- |
-| `/fusion` | Run fixed-purpose Fusion reason (no candidate tools) and append the merged result directly. | `src/fusion-extension.ts:891` |
+| `/fusion` | Start fixed-purpose Fusion reason in the background and return immediately. | `src/fusion-extension.ts:996` |
 <!-- pi-docs:end name="command-contract-fusion" -->
 
 Run the fixed-purpose Fusion **reason** workflow from the command line.
@@ -47,20 +47,17 @@ Reason/session-projection input uses schema `pi-background-tasks.fusion-input.v5
 
 Omitted payload bytes are not summarized or previewed for the children. If a fact exists only inside omitted tool output, restate it in the prompt.
 
-## Result delivery
+## Background result delivery
 
-After a successful run, `/fusion` appends two custom messages without asking the parent model to rewrite the answer:
+`/fusion` freezes its reason input, completes durable no-child preflight, registers a managed background task, and returns control immediately. It does not hold a loader open or append a premature result message. The footer dock, `/jobs`, `bg_status`, `bg_logs`, and `bg_kill` operate on the tracked run.
 
-1. a hidden `fusion-request` record for the command request/run id;
-2. a visible `fusion-result` record whose content is the merger's exact text and whose details include run id, artifact directory, model summary, usage/cost, evaluator-attempt count, and budget metadata.
-
-In TUI mode `/fusion` uses a cancellable loader. Cancelling aborts the active child process tree and records a cancelled run when a run directory exists.
+On terminal state the command emits the standard background-task notification without automatically starting a model turn. Retrieve the verified answer with `bg_result({taskId})`; running retrieval is non-blocking, and oversized results become artifact references rather than truncation.
 
 ## Calls and failure shape
 
 A successful run uses three candidate children, one blind evaluator, and one merger. If the first evaluator response is invalid JSON or violates the closed evaluation schema, Fusion performs exactly one evaluator-repair attempt before failing or continuing. Therefore a successful run may have five or six child invocations; preflight failures launch zero children, and candidate/evaluator/merge failures stop the workflow rather than substituting another model.
 
-Failures are reported as `Fusion failed: ...`; tool/stage errors include the artifact directory when one exists. Prompt-budget forecast failures happen before child creation. Child cancellation, timeout, output caps, model-route admission failures, invalid evaluator JSON after repair, invalid compact child metadata, and invalid tool-call audits are loud failures.
+Admission failures are reported immediately as `Fusion failed: ...`; prompt-budget forecast failures happen before child creation. Failures after the receipt become terminal failed tasks whose notification and `bg_result` error preserve stage coordinates and artifact directory. Child cancellation, timeout, output caps, model-route admission failures, invalid evaluator JSON after repair, invalid compact child metadata, and invalid tool-call audits remain loud failures.
 
 ## Related
 

package/docs/commands/jobs.md

@@ -12,7 +12,7 @@ covers_sources: []
 <!-- pi-docs:begin name="command-contract-jobs" generator="scripts/docs/generate.mjs" -->
 | Command | Description | Provenance |
 | --- | --- | --- |
-| `/jobs` | List running and recent background tasks | `src/extension.ts:594` |
+| `/jobs` | List running and recent background tasks | `src/extension.ts:605` |
 <!-- pi-docs:end name="command-contract-jobs" -->
 
 List running and recent background tasks.

package/docs/commands/kill.md

@@ -12,7 +12,7 @@ covers_sources: []
 <!-- pi-docs:begin name="command-contract-kill" generator="scripts/docs/generate.mjs" -->
 | Command | Description | Provenance |
 | --- | --- | --- |
-| `/kill` | Stop a running background task: /kill <id> | `src/extension.ts:638` |
+| `/kill` | Stop a running background task: /kill <id> | `src/extension.ts:649` |
 <!-- pi-docs:end name="command-contract-kill" -->
 
 Stop a running background task.

package/docs/commands/logs.md

@@ -12,7 +12,7 @@ covers_sources: []
 <!-- pi-docs:begin name="command-contract-logs" generator="scripts/docs/generate.mjs" -->
 | Command | Description | Provenance |
 | --- | --- | --- |
-| `/logs` | Show bounded output from a background task: /logs <id> [maxBytes] | `src/extension.ts:607` |
+| `/logs` | Show bounded output from a background task: /logs <id> [maxBytes] | `src/extension.ts:618` |
 <!-- pi-docs:end name="command-contract-logs" -->
 
 Show bounded output from a background task.

package/docs/commands/task-manager.md

@@ -12,8 +12,8 @@ covers_sources: []
 <!-- pi-docs:begin name="command-contract-tasks-bg-tasks" generator="scripts/docs/generate.mjs" -->
 | Command | Description | Provenance |
 | --- | --- | --- |
-| `/tasks` | Open the Claude-like background task manager UI | `src/extension.ts:532` |
-| `/bg-tasks` | Open the background task manager UI | `src/extension.ts:540` |
+| `/tasks` | Open the Claude-like background task manager UI | `src/extension.ts:543` |
+| `/bg-tasks` | Open the background task manager UI | `src/extension.ts:551` |
 <!-- pi-docs:end name="command-contract-tasks-bg-tasks" -->
 
 Open the interactive background task manager. `/tasks` and `/bg-tasks` are aliases.

package/docs/concepts/completion-delivery.md

@@ -25,6 +25,7 @@ Background tasks can finish silently, notify the terminal, or notify and wake th
 - `/bg` is display-only by default: it sets `notifyOnCompletion:true` and `triggerOnCompletion:false`.
 - `bg_run` defaults to durable notification plus follow-up turn: `notifyOnCompletion:true` and `triggerOnCompletion:true`.
 - `bg_status` and `bg_logs` are point-in-time inspection tools, not polling primitives.
+- Tool-launched Fusion tasks default to notification plus follow-up wake and are retrieved once with `bg_result`; `/fusion` uses notification-only.
 - A received `<background-task-notification>` is metadata-backed terminal-status truth. The output stream has finished/closed, but ordinary `.output` bytes are not explicitly fsynced. Do not call `bg_status` only to reconfirm status; call `bg_logs` only if output bytes are needed.
 
 ## Notification payload

package/docs/getting-started.md

@@ -113,7 +113,7 @@ Call this with `fusion_reason`, or use:
 /fusion Compare a foreground command, bg_run, and bg_delegate for a ten-minute repository audit.
 ```
 
-Fusion runs three candidates, blind evaluation, optional bounded repair only if evaluator JSON is invalid, and merger. `/fusion` and `fusion_reason` receive a versioned conversation projection; investigate/research/validate receive clean task input only.
+Fusion returns a tracked background-task receipt after durable no-child preflight. It then runs three candidates, blind evaluation, optional bounded repair only if evaluator JSON is invalid, and merger. Wait for the terminal notification and call `bg_result` once; do not poll. `/fusion` and `fusion_reason` receive a versioned conversation projection; investigate/research/validate receive clean task input only.
 
 ## Next links