pi-background-tasks 2.5.0 → 2.6.0

package/docs/subsystems/fusion.md

@@ -5,25 +5,25 @@ mode: mixed
 review_policy: behavioral
 stability: stable
 covers_surfaces: [renderer:fusion-result, workflow:investigate, workflow:reason, workflow:research, workflow:validate]
-covers_sources: [extensions/fusion-child.ts, src/core/fusion/artifacts.ts, src/core/fusion/budget.ts, src/core/fusion/child-protocol.ts, src/core/fusion/claude-cache.ts, src/core/fusion/clean-context.ts, src/core/fusion/config.ts, src/core/fusion/context.ts, src/core/fusion/evaluation.ts, src/core/fusion/orchestrator.ts, src/core/fusion/output-contract.ts, src/core/fusion/pi-child.ts, src/core/fusion/prompts.ts, src/core/fusion/result-package.ts, src/core/fusion/source-policy.ts, src/core/fusion/types.ts, src/core/fusion/web-fetch.ts, src/core/fusion/workflows.ts, src/fusion-child-extension.ts, src/fusion-extension.ts, src/ui/fusion-model-selector.ts]
+covers_sources: [extensions/fusion-child.ts, src/core/fusion/artifacts.ts, src/core/fusion/budget.ts, src/core/fusion/child-protocol.ts, src/core/fusion/claude-cache.ts, src/core/fusion/clean-context.ts, src/core/fusion/config.ts, src/core/fusion/context.ts, src/core/fusion/evaluation.ts, src/core/fusion/facade-contract.ts, src/core/fusion/orchestrator.ts, src/core/fusion/output-contract.ts, src/core/fusion/pi-child.ts, src/core/fusion/prompts.ts, src/core/fusion/result-package.ts, src/core/fusion/source-policy.ts, src/core/fusion/types.ts, src/core/fusion/web-fetch.ts, src/core/fusion/workflows.ts, src/fusion-child-extension.ts, src/fusion-extension.ts, src/ui/fusion-model-selector.ts]
 ---
 
 # Fusion subsystem
 
 <!-- pi-docs:begin name="fusion-workflows" generator="scripts/docs/generate.mjs" -->
-| Workflow | Tool | Context | Candidate capability | Candidate tools | Evaluator/merger tools | Provenance |
-| --- | --- | --- | --- | --- | --- | --- |
-| `investigate` | `fusion_investigate` | `clean_task` | `inspect` | `read`, `grep`, `find`, `ls` | none | `src/core/fusion/workflows.ts:80` |
-| `reason` | `fusion_reason` | `session_projection` | `reason` | none | none | `src/core/fusion/workflows.ts:61` |
-| `research` | `fusion_research` | `clean_task` | `research` | `read`, `grep`, `find`, `ls`, `fusion_web_fetch` | none | `src/core/fusion/workflows.ts:99` |
-| `validate` | `fusion_validate` | `clean_task` | `inspect` | `read`, `grep`, `find`, `ls` | none | `src/core/fusion/workflows.ts:118` |
+| Workflow | Availability | Default | Tool | Context | Candidate capability | Candidate tools | Evaluator/merger tools | Provenance |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `investigate` | `feature:fusion` | yes | `fusion_investigate` | `clean_task` | `inspect` | `read`, `grep`, `find`, `ls` | none | `src/core/fusion/workflows.ts:80` |
+| `reason` | `feature:fusion` | yes | `fusion_reason` | `session_projection` | `reason` | none | none | `src/core/fusion/workflows.ts:61` |
+| `research` | `feature:fusion` | yes | `fusion_research` | `clean_task` | `research` | `read`, `grep`, `find`, `ls`, `fusion_web_fetch` | none | `src/core/fusion/workflows.ts:99` |
+| `validate` | `feature:fusion` | yes | `fusion_validate` | `clean_task` | `inspect` | `read`, `grep`, `find`, `ls` | none | `src/core/fusion/workflows.ts:118` |
 <!-- pi-docs:end name="fusion-workflows" -->
 
 This document is the primary behavioral owner for Fusion's package-owned source files listed in frontmatter. Shared parent-context and token-budget modules are referenced here only as dependencies; their behavior is not owned by this document.
 
 ## Public v1 surface
 
-Fusion v1 exposes exactly two commands and exactly four public tools:
+When `PI_BG_FEATURES` includes `fusion`, Fusion v1 exposes exactly two commands and exactly four public tools; all are absent otherwise:
 
 - `/fusion` — command shorthand for fixed-purpose `reason`.
 - `/fusion-models` — TUI-only global five-slot model selector.
@@ -34,6 +34,10 @@ Fusion v1 exposes exactly two commands and exactly four public tools:
 
 Every public tool schema is closed and has no public capability/mode switch. The retired `fusion_brainstorm` surface is never registered; session start removes it from active tools while preserving rendering of historical completed v4 result messages.
 
+Fusion's facade registers those schemas, commands, fixed workflow metadata, and the `fusion-result` renderer immediately. Context projection, clean-context construction, model configuration/resolution, and the orchestrator are loaded as one activation-local single-flight module on the first workflow invocation. `/fusion-models` has a separate config/selector loader, so opening the selector does not preload the orchestrator, and cancelling an empty `/fusion` editor does not load either lane. Concurrent cold calls share module loading only; every workflow keeps its own controller, readiness gate, managed task, and orchestrator run.
+
+A deferred import failure is bounded, names the failed lane, and is retained for that activation. Fusion joins the package-wide synchronous close fence, so both lanes close, lifecycle generation advances, and every active controller aborts in the same first shutdown handler that closes delegate/result/core lanes, before active-run cleanup can pause sequential Pi dispatch. Retained tools reject before loader or host effects. Retained `/fusion` and `/fusion-models` commands assert activation before editor, idle wait, mode/UI handling, selector loading, or notification; once closure is detected their error paths do not notify the old context. A real reload creates fresh loaders rather than reviving the old instance. The shared state-machine and conditional compiled-startup details are documented in [Delegation](delegation.md#lazy-facade-activation).
+
 ## Commands
 
 `/fusion <prompt>` trims the command text and starts the reason workflow as a managed background task. `/fusion` with no arguments opens the multiline editor when UI is available; editor cancellation or blank edited text returns without child spawn. Durable preflight and task registration finish before the command returns; no loader remains open and no premature result message is appended. Terminal state uses the standard background notification, and `bg_result` verifies and retrieves the committed result.
@@ -59,7 +63,7 @@ All workflows use the same orchestrator shape:
 7. run a no-tool merger;
 8. durably commit `merged.md` plus manifest-bound `result.json`, then publish terminal task state.
 
-Do not describe Fusion as unconditionally exactly five model calls. A completed run may use five or six child invocations, while preflight failures use zero; candidate failures, cancellation, spawn retry, output caps, or invalid repair alter observed attempts.
+The five slots are role assignments, not a guarantee of five distinct models or of five provider calls. An ordinary success uses five child invocations (three candidates, one evaluator, one merger); the one permitted evaluator repair makes six. Fatal preflight launches zero children. Failed or cancelled waves may create or complete fewer children, a transient pre-creation spawn failure may be retried once, and a child agent loop may make multiple provider requests. Attempt and provider-request counts therefore remain runtime facts, not values inferred from the slot count.
 
 Candidate tool policies are fixed by workflow:
 
@@ -72,6 +76,27 @@ Candidate tool policies are fixed by workflow:
 
 Evaluator, evaluator-repair, and merger always use capability `reason` and empty tool lists. Tool-enabled children run with built-in tools disabled and an explicit allowlist plus a denylist that includes shell/write/edit, Fusion recursion, and background/delegate tools.
 
+### Model roles, fan-in, and latency
+
+Candidate 1/2/3 are independent child attempts, not assigned specialties. The orchestrator gives all three the same canonical input, candidate system instruction, workflow capability, and fixed candidate-tool policy, then starts their promises as one parallel wave. Tool-enabled candidates can make different investigative choices, but no slot is pre-designated as researcher, critic, or writer. Different capable routes may improve diversity without guaranteeing it; duplicate routes are valid but can yield similar answers. On a successful wave, evaluation cannot start until all three settle, so the slowest candidate determines wave latency.
+
+The evaluator receives the canonical input plus all three completed responses after their slot identities have been randomly mapped to anonymous A/B/C labels. It has no tools and must emit the closed `pi-background-tasks.fusion-evaluation.v1` structure: exactly three assessments plus agreements, conflicts, and a constrained synthesis plan (with validation accounting only for `fusion_validate`). It neither ranks a winner nor emits the final answer. If parsing or schema validation fails, the evaluation repair uses the same configured and resolved evaluator model. That single repair receives the complete original blind input, the invalid evaluator output, and bounded validation errors; another invalid result terminates the run.
+
+The merger receives the canonical input, all three anonymous candidate responses, and the validated evaluation. It has no tools and is the last model stage. For reason, investigate, and research, its output is the sole final answer; candidate and evaluator responses are never returned directly. For `fusion_validate`, the host subsequently renders the final report from the validated finding accounting, preventing raw merger prose from adding or dropping findings.
+
+The normal-path critical path is `preflight → max(candidate 1, candidate 2, candidate 3) → evaluator → merger`; repair inserts another evaluator-model stage before merger. Its stage fan-in is:
+
+| Stage | Prompt fan-in | Route/timing consequence |
+| --- | --- | --- |
+| Candidate | Candidate system prompt + canonical input | Three parallel routes; the slowest successful candidate gates evaluation. |
+| Evaluator | Evaluator system prompt + canonical input + all three bounded candidate outputs | First sequential stage; schema reliability matters because invalid output triggers the sole repair. |
+| Evaluation repair | Repair system prompt + original blind evaluator input + invalid evaluator output + bounded errors | Conditional, same evaluator route, and potentially the largest prompt. |
+| Merger | Merger system prompt + canonical input + all three candidate outputs + validated evaluation | Final sequential stage and normally the greatest synthesis/context burden. |
+
+Budget planning reserves upstream output contracts for every fan-in stage and records worst-case reservation pressure as warnings; immediately before each child launch, the exact rendered prompt must fit that role's route. A nominally stronger model with a smaller usable context window can therefore be an invalid choice. Quality-first routing favors capable, genuinely diverse candidates, a strong schema-following evaluator, and the strongest available long-context synthesizer for merger. Speed-first routing avoids a slow candidate outlier, uses a fast schema-reliable evaluator to avoid repair, and keeps the sequential merger fast. In both cases frontier routes remain subscription OAuth only; duplicates and `$current` are valid, and metered APIs are not a tradeoff option.
+
+See the user-facing [model-selection guide](../commands/fusion-models.md), [budgets and output contracts](#budgets-and-output-contracts), and the configured [Fusion runtime limits](../operations/configuration.md#fusion-runtime-limits).
+
 ## Validation specifics
 
 `fusion_validate` enforces a strict public verification contract: `provided` requires non-empty evidence and no reason; `not_run` requires a reason and empty/omitted evidence. Reviewers return exactly one bare, closed candidate-report JSON object. The host keeps its shared JSON parser strict; a single complete `json` fence can be removed only by the validation-specific audited recovery path, which writes a contract-event artifact and surfaces a limitation. One irrecoverable minority report is also recorded and surfaced as a limitation, while two invalid reports fail the workflow. The host assigns stable finding ids after anonymization, the evaluator must account for every source finding exactly once, and the host renders the final report from validated accounting after the merger. Validation is advisory and read-only: it never edits files, runs tests, gates a release, or replaces builds, linters, scanners, or human review.
@@ -88,7 +113,7 @@ Inspect/research candidates write sealed tool-call audit logs. The log contains
 
 ## Child process isolation
 
-Fusion never calls direct completion APIs. It launches direct child `pi --mode text` processes and writes the prompt over stdin. Child argv includes `--no-session`, `--no-extensions`, `--no-skills`, `--no-prompt-templates`, `--no-themes`, and `--no-context-files`; explicit extensions still load. Non-Anthropic children receive only the package-owned compact metadata/runtime-governor extension. Anthropic children receive, in fixed order, the package-wide attribution/sanitization extension and the runtime governor. The same attribution implementation is globally loaded for ordinary package sessions; Fusion supplies its public extension entrypoint explicitly because ambient discovery is disabled. Attribution adds the Claude Code OAuth session header, linked account/device/session metadata, model-policy beta headers, system identity, beta-resource transport, cache surfaces, and model-aware cache usage pricing. It reads `userID` and `oauthAccount.accountUuid` from `~/.claude.json` without writing the file and fails loudly when required attribution data is absent or malformed. Its internal sanitizer removes all reviewed exact-match rejected prompt lines while preserving unrelated text and cache controls; no external sanitizer package is resolved.
+Fusion never calls direct completion APIs. It launches direct child `pi --mode text` processes and writes the prompt over stdin. Child argv includes `--no-session`, `--no-extensions`, `--no-skills`, `--no-prompt-templates`, `--no-themes`, and `--no-context-files`; explicit extensions still load. Non-Anthropic children receive only the package-owned compact metadata/runtime-governor extension. Anthropic children receive, in fixed order, the always-on `extensions/anthropic-attribution-child.ts` attribution/sanitization entrypoint and the runtime governor. Ordinary parent sessions use the separate feature-aware ambient entrypoint; disabling that ambient capability cannot disable explicit child safety. Attribution adds the Claude Code OAuth session header, linked account/device/session metadata, model-policy beta headers, system identity, beta-resource transport, cache surfaces, and model-aware cache usage pricing. It reads `userID` and `oauthAccount.accountUuid` from `~/.claude.json` without writing the file and fails loudly when required attribution data is absent or malformed. Its internal sanitizer removes all reviewed exact-match rejected prompt lines while preserving unrelated text and cache controls; no external sanitizer package is resolved.
 
 Child text mode writes the final full answer to stdout. The private child extension emits compact reasoning-free metadata frames to stderr for finalized assistant messages: provider/model, stop reason, text block byte counts and hashes, aggregate text hash, the complete Pi `Usage` object (including Anthropic `cacheWrite1h` and provider-reported reasoning subsets), and a closed cache-policy observation. It governs every final `before_provider_request` payload after attribution and sanitization. For Anthropic routes, the child environment defaults `PI_CACHE_RETENTION` to `long` before provider serialization, so the attribution/Pi adapter creates system, final-tool, and final-conversation breakpoints with `ttl: "1h"`; inherited `PI_CACHE_RETENTION=short|none|long` remains explicit, and call-level `cacheRetention="none"` still wins for compaction. The final governor validates and normalizes those upstream-selected breakpoints, falls back to short when model compatibility rejects long retention, preserves no-marker compaction payloads, enforces Anthropic's four-breakpoint ceiling, and appends the subscription prompt-caching-scope beta idempotently. Its `effective_retention` field describes the final payload, not provider acceptance. Provider usage is preserved verbatim: `cacheWrite1h > 0` proves a one-hour write, but zero is inconclusive on subscription OAuth. Live normal-spawn and exact Fusion-child controls each observed a unique cache read after 370 idle seconds despite `cacheWrite1h = 0`; therefore payload observations prove request intent and `cacheRead` proves reuse, while neither zero telemetry nor a six-minute hit alone proves the full one-hour lifetime. Malformed controls or policy values abort before transport. Non-Anthropic payloads and child environments remain unchanged apart from the governor's existing JSON normalization.
 
@@ -118,7 +143,7 @@ Artifact writes use durable private temp-file/fsync/rename. Manifests enforce le
 
 For tool-enabled children, the private audit journal remains open across every low-level `agent_end`, because Pi may still retry, compact and retry, or process a queued continuation. Only terminal `agent_settled` can exclusively publish the complete hash/count/byte seal. Runtime-guard refusal latches process failure, makes that seal incomplete, and forces the result settlement to failed. The child emits one closed `pi-background-tasks.fusion-runtime-guard.v2` stderr frame for malformed provider payloads, malformed Claude cache policy, provider-request loops, or tool-call loops. The frame contains the refusal code, route, request/tool ordinals, bounded payload byte/hash evidence where applicable, and a bounded message; it never emits the payload itself. The parent validates this frame and reports typed `child_runtime_limit_exceeded`, `child_runtime_payload_invalid`, or `child_cache_policy_invalid` instead of accepting a later clean-looking result or reducing it to an unexplained exit code. Tool activity after finalization, duplicate settlement, pre-settlement shutdown, extension diagnostics, malformed/duplicate runtime-guard frames, and missing/failed/stale seals are fatal. This lifecycle requires Pi 0.81.1 or newer; older Pi lines do not expose the required terminal event and are not claimed as compatible.
 
-The four public Fusion tools return a background launch receipt after the readiness barrier. Tool-launched runs default to terminal notification plus follow-up wake; `/fusion` uses notification-only. The first successful `bg_result` retrieval durably claims and attaches complete Fusion usage exactly once; repeated retrieval returns the answer without duplicating session accounting. Running retrieval never waits.
+The four public Fusion tools return a background launch receipt after the readiness barrier. Tool-launched runs default to terminal notification plus follow-up wake; `/fusion` uses notification-only. The first successful `bg_result` retrieval durably claims and attaches complete Fusion usage exactly once; repeated retrieval returns the answer without duplicating session accounting. Verification, delivery checks, and usage cloning finish before the claim starts. That durable claim is the retrieval settlement point: closure before it prevents a claim, while closure during its metadata write lets the already-started invocation finish and return the usage without any later host effect. Metadata failure remains loud and is not silently reset. Running retrieval never waits.
 
 Cancellation and shutdown are loud and durable when a run store exists. The extension tracks active runs, managed tasks own their abort controllers, `bg_kill` and session shutdown abort them, and terminal task publication waits for workflow settlement. Child processes have a 50 minute wall timeout, 35 minute idle watchdog, SIGTERM grace, SIGKILL wait, process-group kill on POSIX, bounded stdout/stderr, and cleanup-error propagation.
 

package/docs/subsystems/host-ui-and-telemetry.md

@@ -5,7 +5,7 @@ mode: authored
 review_policy: behavioral
 stability: stable
 covers_surfaces: []
-covers_sources: [extensions/background-tasks.ts, src/core/update-check.ts, src/extension.ts, src/ui/background-tasks-manager.ts]
+covers_sources: [extensions/background-tasks.ts, src/core/config.ts, src/core/update-check.ts, src/extension.ts, src/ui/background-tasks-manager.ts]
 ---
 # Host UI and telemetry
 
@@ -13,12 +13,21 @@ This subsystem owns the extension entrypoint, command/tool registration, footer
 
 ## Entrypoint and registration
 
-`extensions/background-tasks.ts` re-exports `src/extension.ts`. The extension registers:
+The published `dist/extensions/background-tasks.js` entrypoint is compiled from `extensions/background-tasks.ts`, which re-exports the authoritative `src/extension.ts`. Before creating the registry or registering a surface, the extension strictly parses the shared capability/shortcut configuration. It dynamically imports delegate/Fusion facade registration only for enabled capabilities; the dock component is imported only when an interactive manager is opened. `process` is mandatory and registers:
 
 - commands: `/bg`, `/tasks`, `/bg-tasks`, `/bg-clear`, `/bg-update`, `/jobs`, `/logs`, `/kill`;
-- tools: `bg_run`, `bg_status`, `bg_logs`, `bg_kill` plus package-owned advanced tools documented elsewhere;
-- shortcuts: `shift+down` and `ctrl+alt+c`;
-- renderer: `background-task-notification`.
+- tools: `bg_run`, `bg_status`, `bg_logs`, `bg_kill`;
+- shortcut: the selected dock key (`shift+down`, `ctrl+alt+b`, or none for `off`) plus unconditional `ctrl+alt+c`;
+- renderer: `background-task-notification`;
+- the task UI and EventBus service.
+
+Delegate, Fusion, attested-run, and ambient attribution registrations are independently selected by `PI_BG_FEATURES`. `bg_result` is derived and registered once iff delegate or Fusion is enabled. Disabled facade/attribution modules are absent from the process-only static startup graph rather than merely inactive. Active-tool cleanup is delegated to Pi's registration rebuild: a stale package name with no current definition is dropped, while an active definition from another extension remains active even when it uses a disabled package capability name such as `bg_delegate` or the retired `fusion_brainstorm`. The package does not perform name-wide subtraction. The default selection preserves the complete historical surface. Capability flags alone make no startup-performance claim.
+
+## Agent-visible shell guidance
+
+A dedicated `before_agent_start` hook adds the activation's actual background-shell executable, dialect, and `-c`/cmd argument shape before the model generates a command. The hook uses an independently replaceable prompt section when the host supports structured sections and a chained, idempotent section on older supported hosts. It preserves guidance added by other background-feature hooks in either registration order.
+
+An inherited Nu, fish, csh, or unknown shell is explicitly described as `user-non-posix`, with instructions not to assume Bash syntax and remediation to set `PI_BG_POSIX_SHELL=bash` before startup or `/reload`. The guidance contains only resolved launch facts, not the process environment or credentials. The registry receives the same immutable selection; task snapshots and metadata make that match observable.
 
 ## Footer status
 
@@ -30,7 +39,7 @@ When visible, the footer label includes counts in this order:
 2. failed,
 3. stopped (`killed`),
 4. done (`completed`),
-5. entry hint (`focused` while the dock is open, otherwise `Shift↓`),
+5. entry hint (`focused` while the dock is open, otherwise `Shift↓`, `CtrlAltB`, or `/tasks` from the parsed dock setting),
 6. `/bg-clear` hint when there are unseen finished tasks **and the dock is closed**,
 7. optional update segment.
 
@@ -38,9 +47,9 @@ A finished badge is cleared when that task's detail view is opened, or when `/bg
 
 ## Task manager UI
 
-`/tasks`, `/bg-tasks`, and `Shift+Down` open the same overlay. Non-interactive contexts receive an error notification directing users to `/jobs`, `/logs`, `bg_status`, or `bg_logs`.
+`/tasks`, `/bg-tasks`, and the configured dock shortcut (when not `off`) open the same overlay. The two commands are unconditional process surfaces, including when the shortcut is disabled. Non-interactive contexts receive an error notification directing users to `/jobs`, `/logs`, `bg_status`, or `bg_logs`.
 
-The list view supports selection, paging, stop, confirmed stop-all, history toggle, rerun, output path, and close. Rerun is shell-task-only: typed delegate and Fusion tasks fail with guidance to relaunch through their owning tool rather than executing their display command as a shell command. The detail view shows task identity, status, runtime, output path, description, task-owned model/context/tokens/tools when reported, command, error, and an output tail.
+The list view supports selection, paging, stop, confirmed stop-all, history toggle, rerun, output path, and close. Rerun is shell-task-only: typed delegate and Fusion tasks fail with guidance to relaunch through their owning tool rather than executing their display command as a shell command. Rerunning an opted survivor preserves `surviveReload:true`, but it is a new execution with a new id/nonce and the current activation's shell policy, timeout, and output cap. The detail view shows task identity, status, runtime, output path, description, task-owned model/context/tokens/tools when reported, command, error, and an output tail.
 
 Detail output semantics:
 
@@ -67,7 +76,11 @@ The host UI displays telemetry only from task snapshots: context, model, token t
 
 ## Shutdown
 
-On session shutdown, the extension marks the registry as shutting down, clears the status interval, kills running tasks with reason `Killed during Pi session shutdown/reload`, reports cleanup failures through the UI when possible, and closes the event service.
+On session shutdown, one early synchronous lifecycle fence permanently closes the activation. Only `reason:"reload"` may first detach admission-committed `surviveReload:true`, `isAgent:false` ordinary executions; detachment removes the old host adapter before any await while preserving logical publication and notification state. The same call stack then closes admissions, aborts admission-owned cancellation scopes, closes registry publication and the EventBus service, clears pending retry/status handles, suppresses old-host notifications, closes every enabled Fusion/delegate/result lazy lane, aborts Fusion controllers, and aborts delegate preparation. The entrypoint registers this shared fence before any facade asynchronous cleanup, so sequential Pi dispatch cannot pause with another old lane still open. Later handlers drain workflow/preparation/admission-owned subprocess, file, and managed cleanup; kill every remaining registry-owned task with the specific lifecycle reason; and report cleanup failures through the UI when possible. Preflight that crosses closure cannot insert, spawn, or return EventBus success.
+
+The first fresh `session_start` callback synchronously claims the exact `(process.pid, session id, canonical cwd)` slot, imports/durably audits the same task records, commits the fresh adapter, then allows existing UI/status/update setup. Completion during the gap queues for that adapter. Status, logs, kill, commands, and dock therefore use the same id/PID/path/nonce/execution after reload. A malformed new activation or removed extension cannot steal the owner; its fixed handoff deadline cleans up.
+
+Shutdown terminal metadata and task waiters remain truthful even when old-activation EventBus publication is abandoned. Shutdown is idempotent, including handle cleanup on repeated calls. `session_start` rechecks activation after runtime-directory setup and before status interval/update-check creation, so an overlapping late continuation cannot recreate old resources. Pi `AgentSession.reload()` replaces the extension runner; `AgentSessionRuntime` new/switch/fork/clone/dispose flows do not claim reload handoffs and kill opted work. Kill-on-reload remains the default unless an ordinary task explicitly opts in. Hard crash/restart survival is not supported.
 
 ## Related docs
 

package/docs/tools/bg_delegate.md

@@ -11,7 +11,9 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-bg_delegate" generator="scripts/docs/generate.mjs" -->
 - Label: **Background Delegate**
-- Source: `src/delegate-extension.ts:340`
+- Source: `src/delegate-extension.ts:500`
+- Availability: `feature:delegate`
+- Available by default: **yes**
 - Description: Launch one background Pi agent seeded with a frozen projection of the current conversation, then return a launch receipt immediately. The child has its own session, a route pinned at launch that is never substituted, and read-only tools. Extension discovery is isolated by default; ambient mode supports extension-registered providers but executes arbitrary discovered extension code. Retrieve its verified answer with bg_result.
 - Root schema: `object`; additionalProperties: `false`
 

package/docs/tools/bg_kill.md

@@ -11,7 +11,9 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-bg_kill" generator="scripts/docs/generate.mjs" -->
 - Label: **Background Kill**
-- Source: `src/extension.ts:908`
+- Source: `src/extension.ts:1181`
+- Availability: `always`
+- Available by default: **yes**
 - Description: Stop a running background task by ID. Fails loudly if the task is unknown or already finished.
 - Root schema: `object`
 

package/docs/tools/bg_logs.md

@@ -11,7 +11,9 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-bg_logs" generator="scripts/docs/generate.mjs" -->
 - Label: **Background Logs**
-- Source: `src/extension.ts:863`
+- Source: `src/extension.ts:1136`
+- Availability: `always`
+- Available by default: **yes**
 - Description: Read bounded output from a background task for deliberate inspection; this is not a waiting primitive. Output is capped at 50.0KB for model safety and points to the full output file when truncated.
 - Root schema: `object`
 

package/docs/tools/bg_result.md

@@ -11,7 +11,9 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-bg_result" generator="scripts/docs/generate.mjs" -->
 - Label: **Background Result**
-- Source: `src/delegate-extension.ts:516`
+- Source: `src/delegate-extension.ts:757`
+- Availability: `any(feature:delegate,feature:fusion)`
+- Available by default: **yes**
 - Description: Retrieve a hash-verified result from a bg_delegate or background Fusion task. Never blocks: a running task returns a typed not-ready result. Oversized answers are never truncated.
 - Root schema: `object`; additionalProperties: `false`
 
@@ -47,7 +49,7 @@ covers_sources: []
 </details>
 <!-- pi-docs:end name="tool-contract-bg_result" -->
 
-`bg_result` retrieves the result of a `bg_delegate` or background Fusion task. It never blocks: a running task returns a typed not-ready view, and a terminal task is verified before any answer bytes are returned.
+`bg_result` retrieves the result of a `bg_delegate` or background Fusion task. It is a derived surface: registered exactly once when `PI_BG_FEATURES` includes `delegate` or `fusion`, and absent when both producers are disabled. Delegate-only and Fusion-only configurations use the same verifier and retain their respective producer path. It never blocks: a running task returns a typed not-ready view, and a terminal task is verified before any answer bytes are returned.
 
 ## Public arguments
 
@@ -92,7 +94,7 @@ The returned text is decoded from the same aggregate buffer that was hashed. Cor
 
 ## Fusion retrieval
 
-A completed Fusion task is accepted only when `manifest.json` is terminal `completed`, its `result.json` and `merged.md` fixed references match, both files match manifest-bound byte lengths and SHA-256 values, run/workflow/artifact identity matches the task, result details carry the current schema, usage is complete, and merged bytes are well-formed UTF-8. The first successful retrieval attaches complete Fusion usage exactly once; later retrievals omit usage to prevent double-counting.
+A completed Fusion task is accepted only when `manifest.json` is terminal `completed`, its `result.json` and `merged.md` fixed references match, both files match manifest-bound byte lengths and SHA-256 values, run/workflow/artifact identity matches the task, result details carry the current schema, usage is complete, and merged bytes are well-formed UTF-8. The first successful retrieval attaches complete Fusion usage exactly once; later retrievals omit usage to prevent double-counting. Verification and delivery checks precede the durable claim. If shutdown begins after that claim starts, the in-flight retrieval finishes with usage and performs no later host effect; closure before the claim leaves it available to a fresh retrieval. A metadata-write failure remains loud and is not silently reset.
 
 ## Fusion failed/cancelled terminal view
 

package/docs/tools/bg_run.md

@@ -11,7 +11,9 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-bg_run" generator="scripts/docs/generate.mjs" -->
 - Label: **Background Run**
-- Source: `src/extension.ts:682`
+- Source: `src/extension.ts:927`
+- Availability: `always`
+- Available by default: **yes**
 - Description: Start a named long-running shell command in the background and return immediately with a task ID and output path. By default, completed, failed, or killed terminal state is delivered automatically as <background-task-notification> and starts a follow-up agent turn; do not sleep or poll merely to wait. Output is written to .pi/tasks and model-visible logs are bounded to 50.0KB.
 - Root schema: `object`
 
@@ -22,6 +24,7 @@ covers_sources: []
 | `isAgent` | yes | `boolean` | Required. Set true only when this background task launches an LLM/agent process, such as a child `pi -p ...` or `pi --mode json ...`, so Pi-agent telemetry can be collected. Set false for scripts, tests, servers, sleeps, and ordinary shell commands. |  |
 | `name` | yes | `string` | Short human-readable task name shown in the bg footer dock. Required; use 2-6 words, not the raw command. |  |
 | `notifyOnCompletion` | no | `boolean` | Whether to deliver the durable terminal notification. Default: true; disable only when deliberately taking over completion monitoring. |  |
+| `surviveReload` | no | `boolean` | Opt in to retaining this exact ordinary isAgent:false shell execution across a real same-process Pi reload. Default: false. Unsupported for agent, managed, delegate, Fusion, and attested tasks. |  |
 | `timeoutSeconds` | no | `number` | Optional timeout; task is failed and killed when exceeded |  |
 | `triggerOnCompletion` | no | `boolean` | Whether that notification should automatically trigger a follow-up agent turn. Default: true for bg_run; requires notifyOnCompletion. |  |
 
@@ -52,6 +55,10 @@ covers_sources: []
       "description": "Whether to deliver the durable terminal notification. Default: true; disable only when deliberately taking over completion monitoring.",
       "type": "boolean"
     },
+    "surviveReload": {
+      "description": "Opt in to retaining this exact ordinary isAgent:false shell execution across a real same-process Pi reload. Default: false. Unsupported for agent, managed, delegate, Fusion, and attested tasks.",
+      "type": "boolean"
+    },
     "timeoutSeconds": {
       "description": "Optional timeout; task is failed and killed when exceeded",
       "type": "number"
@@ -90,6 +97,7 @@ Optional fields:
 - `timeoutSeconds: number`
 - `notifyOnCompletion: boolean`
 - `triggerOnCompletion: boolean`
+- `surviveReload: boolean` — opt in only for ordinary `isAgent:false` shell work that must keep the same live execution across a supported real reload.
 
 Legacy argument preparation can derive a missing `name` from `description` or `command`, but the public schema remains strict and requires `name`, `command`, and `isAgent`.
 
@@ -97,7 +105,7 @@ Legacy argument preparation can derive a missing `name` from `description` or `c
 
 Use for long-running tests, builds, servers, watchers, sleeps, and child agent work. Do not use normal foreground shell tools for commands expected to outlive the current turn.
 
-For an Anthropic child `pi`, keep normal extension discovery enabled. Do not pass `--no-extensions` unless the command also explicitly loads this package's `extensions/anthropic-attribution.ts` with `-e`/`--extension`.
+For an Anthropic child `pi`, keep normal extension discovery enabled when parent ambient attribution is enabled. Do not pass `--no-extensions` unless the command also explicitly loads this package's always-on `extensions/anthropic-attribution-child.ts` with `-e`/`--extension`.
 
 ## Defaults
 
@@ -105,10 +113,21 @@ For an Anthropic child `pi`, keep normal extension discovery enabled. Do not pas
 - `triggerOnCompletion`: `true`.
 - `timeoutSeconds`: absent means no timeout.
 - `isAgent`: no default in the tool contract; callers must provide a boolean. It is not inferred from command text.
+- `surviveReload`: `false`. True is valid only with `isAgent:false` and never changes the default for other launches.
+
+## Shell selection and guidance
+
+The extension resolves one immutable shell selection per activation. Before the model generates a command, agent guidance states the exact executable, dialect, and argument shape used by `bg_run`. The same facts appear in the returned task's `shellPolicy` and durable metadata. Guidance never includes the full environment.
+
+The compatible POSIX default is `PI_BG_POSIX_SHELL=inherit`: use non-empty `SHELL`, otherwise `/bin/sh`, with `-c`. To deliberately request the Bash syntax models commonly generate, set `PI_BG_POSIX_SHELL=bash` before starting or reloading Pi. `PI_BG_POSIX_SHELL=sh` selects portable sh. An optional `PI_BG_POSIX_SHELL_PATH` is valid only for explicit Bash/sh and must be an absolute regular executable. Bash/sh use `-c`, not a login shell. See [Configuration](../operations/configuration.md) for exact `/bin`-then-`PATH` search and validation.
+
+Inherited Nu, fish, csh, and unknown shells remain the default when selected through `SHELL`, but are labeled `user-non-posix`, not POSIX or Bash. Their guidance says not to generate Bash syntax and gives explicit Bash remediation. Windows keeps its separate `PI_BG_SHELL` policy and ignores the POSIX variables.
 
 ## Lifecycle
 
-The tool returns a task id, current `running` status, pid if known, output path, and completion-delivery guidance. Terminal statuses are exactly `completed`, `failed`, or `killed`. With default delivery, terminal state is sent as `<background-task-notification>` and starts a follow-up agent turn; after launching, do not sleep or poll merely to wait.
+The tool returns a task id, current `running` status, pid if known, output path, completion-delivery guidance, and structured task details including the actual shell policy. Terminal statuses are exactly `completed`, `failed`, or `killed`. With default delivery, terminal state is sent as `<background-task-notification>` and starts a follow-up agent turn; after launching, do not sleep or poll merely to wait.
+
+An opted ordinary task crosses a supported real same-process reload as the same living child, task id, PID, launch nonce, completion id, output path/stream, shell policy, absolute timeout, launch-time cap, cumulative byte count, and tree authority. Completion in the hostless gap queues for the fresh activation. Status/logs/kill/commands/dock continue against that same object. Hard crash/process restart, new/resume/fork/clone/quit, and SDK reload without a fresh counted binding are not survival paths.
 
 ## Examples
 
@@ -124,6 +143,10 @@ The tool returns a task id, current `running` status, pid if known, output path,
 {"name":"Manual server","command":"npm run dev","isAgent":false,"notifyOnCompletion":false,"triggerOnCompletion":false}
 ```
 
+```json
+{"name":"Reload-safe watcher","command":"npm run watch","isAgent":false,"surviveReload":true}
+```
+
 ## Output/result
 
 Text result:
@@ -138,7 +161,7 @@ Automatic follow-up turn: enabled.
 ...
 ```
 
-Structured details include `task`, a snapshot with command, status, output path, cwd, timing, pid, byte count, `isAgent`, delivery flags, telemetry fields when available, and error when present.
+Structured details include `task`, a snapshot with command, status, output path, cwd, timing, pid, byte count, `isAgent`, `surviveReload`, optional non-authoritative `reloadSurvival` audit facts, delivery flags, the non-secret `shellPolicy` (`policy`, `executable`, `argvPrefix`, `dialect`) for ordinary shell tasks, telemetry fields when available, and error when present.
 
 ## Errors
 
@@ -146,11 +169,14 @@ Structured details include `task`, a snapshot with command, status, output path,
 - Missing command: `bg_run requires command string`.
 - Missing `isAgent`: loud error explaining true/false use.
 - Empty command at execution: `Background command is empty`.
+- Invalid explicit POSIX shell mode/path or an unavailable requested Bash/sh route fails loudly without fallback.
+- A malformed survival value fails as `pi_bg_survive_reload_invalid`; true with `isAgent:true` fails as `pi_bg_survive_reload_requires_non_agent`, both before side effects.
+- Missing/stale/conflicting/incompatible activation ownership fails with a stable `pi_bg_reload_owner_*` code. A handoff that receives no compatible claimant reaches fixed-deadline cleanup as `pi_bg_reload_handoff_expired`.
 - Shell/spawn/timeout/output-cap failures become loud task failures.
 
 ## Runtime artifacts
 
-Creates `.pi/tasks/<session-id>-<pid>/<task-id>.output` and `.json`. If `isAgent:true` and the command matches an interceptable POSIX `pi -p`, `pi --print`, or `pi --mode json` invocation, a temporary telemetry wrapper file is also written in the task directory.
+Creates `.pi/tasks/<session-id>-<pid>/<task-id>.output` and `.json`; the JSON records the actual ordinary-task shell policy. If `isAgent:true`, the command matches an interceptable `pi -p`, `pi --print`, or `pi --mode json` invocation, and the resolved shell supports POSIX function syntax, a temporary telemetry wrapper file is also written in the task directory. Unknown/non-POSIX inherited shells are left unwrapped with a diagnostic.
 
 ## Safety boundaries
 

package/docs/tools/bg_run_pi_attested.md

@@ -11,7 +11,9 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-bg_run_pi_attested" generator="scripts/docs/generate.mjs" -->
 - Label: **Attested Pi Run**
-- Source: `src/extension.ts:767`
+- Source: `src/extension.ts:1036`
+- Availability: `feature:attested`
+- Available by default: **yes**
 - Description: Opt-in evidence-oriented direct Pi spawn. Launches exactly one `pi --mode json` child, records raw Pi events/stderr, hashes prompt/report/output, observes OAuth through ModelRegistry, and emits a strict attestation sidecar only after successful completion.
 - Root schema: `object`
 

package/docs/tools/bg_status.md

@@ -11,7 +11,9 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-bg_status" generator="scripts/docs/generate.mjs" -->
 - Label: **Background Status**
-- Source: `src/extension.ts:832`
+- Source: `src/extension.ts:1105`
+- Availability: `always`
+- Available by default: **yes**
 - Description: Inspect one background task or list all running/recent background tasks. This is a point-in-time inspection tool, not a waiting primitive.
 - Root schema: `object`
 

package/docs/tools/fusion_investigate.md

@@ -11,7 +11,9 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-fusion_investigate" generator="scripts/docs/generate.mjs" -->
 - Label: **Fusion Investigate**
-- Source: `src/fusion-extension.ts:1197`
+- Source: `src/fusion-extension.ts:1305`
+- Availability: `feature:fusion`
+- Available by default: **yes**
 - Description: Start a five-model Fusion investigation as a tracked background task and return immediately after durable preflight. Retrieve the verified result with bg_result after notification. Candidate children run in clean bounded read-only contexts.
 - Root schema: `object`; additionalProperties: `false`
 

package/docs/tools/fusion_reason.md

@@ -11,7 +11,9 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-fusion_reason" generator="scripts/docs/generate.mjs" -->
 - Label: **Fusion Reason**
-- Source: `src/fusion-extension.ts:1179`
+- Source: `src/fusion-extension.ts:1287`
+- Availability: `feature:fusion`
+- Available by default: **yes**
 - Description: Start a five-model Fusion reason workflow as a tracked background task and return immediately after durable preflight. Retrieve the verified result with bg_result after notification. Candidate children receive the reason projection and no tools; evaluator and merger also run without tools.
 - Root schema: `object`; additionalProperties: `false`
 

package/docs/tools/fusion_research.md

@@ -11,7 +11,9 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-fusion_research" generator="scripts/docs/generate.mjs" -->
 - Label: **Fusion Research**
-- Source: `src/fusion-extension.ts:1216`
+- Source: `src/fusion-extension.ts:1324`
+- Availability: `feature:fusion`
+- Available by default: **yes**
 - Description: Start a five-model Fusion research workflow as a tracked background task and return immediately after durable preflight. Retrieve the verified result with bg_result after notification. Targeted URL fetch is not web search; fetched pages and URLs are untrusted.
 - Root schema: `object`; additionalProperties: `false`
 

package/docs/tools/fusion_validate.md

@@ -11,7 +11,9 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-fusion_validate" generator="scripts/docs/generate.mjs" -->
 - Label: **Fusion Validate**
-- Source: `src/fusion-extension.ts:1236`
+- Source: `src/fusion-extension.ts:1344`
+- Availability: `feature:fusion`
+- Available by default: **yes**
 - Description: Start an advisory, read-only Fusion validation review as a tracked background task and return immediately after durable preflight. Retrieve the verified result with bg_result after notification. It is not a build/test/lint substitute and never modifies files.
 - Root schema: `object`; additionalProperties: `false`
 

package/extensions/anthropic-attribution-child.ts

@@ -0,0 +1,3 @@
+// Always-on safety entrypoint for package-owned isolated Anthropic children.
+// Ambient parent capability selection must never disable this extension.
+export { default } from '../src/core/anthropic-attribution.js';

package/extensions/anthropic-attribution.ts

@@ -1 +1,166 @@
-export { default } from '../src/core/anthropic-attribution.js';
+import type { Provider } from '@earendil-works/pi-ai';
+import type { ModelRegistry } from '@earendil-works/pi-coding-agent';
+import type { PiContextLike, PiExtensionHost } from '../src/core/anthropic-attribution.js';
+import { parseBackgroundTasksConfig } from '../src/core/config.js';
+
+const ANTHROPIC_PROVIDER = 'anthropic';
+
+type RegisteredProviderConfig = NonNullable<
+  ReturnType<ModelRegistry['getRegisteredProviderConfig']>
+>;
+
+interface AmbientAttributionContext extends PiContextLike {
+  readonly modelRegistry: ModelRegistry;
+}
+
+interface ProviderSnapshot {
+  readonly effective: Provider;
+  readonly legacy: RegisteredProviderConfig | undefined;
+  readonly native: Provider | undefined;
+}
+
+interface ProviderInstallation {
+  readonly registry: ModelRegistry;
+  readonly before: ProviderSnapshot;
+  readonly token: RegisteredProviderConfig;
+}
+
+function captureProviderSnapshot(registry: ModelRegistry): ProviderSnapshot {
+  const effective = registry.getProvider(ANTHROPIC_PROVIDER);
+  if (effective === undefined) {
+    throw new Error(
+      'pi_anthropic_attribution_unsupported: the host exposes no effective anthropic provider to preserve',
+    );
+  }
+  return {
+    effective,
+    legacy: registry.getRegisteredProviderConfig(ANTHROPIC_PROVIDER),
+    native: registry.getRegisteredNativeProvider(ANTHROPIC_PROVIDER),
+  };
+}
+
+function confirmProviderInstallation(
+  registry: ModelRegistry,
+  before: ProviderSnapshot,
+): ProviderInstallation | undefined {
+  const token = registry.getRegisteredProviderConfig(ANTHROPIC_PROVIDER);
+  const native = registry.getRegisteredNativeProvider(ANTHROPIC_PROVIDER);
+  const effective = registry.getProvider(ANTHROPIC_PROVIDER);
+
+  // The accepted duplicate-owner protocol returned without registering anything.
+  if (token === before.legacy && native === before.native && effective === before.effective) {
+    return undefined;
+  }
+
+  if (
+    token === undefined ||
+    token === before.legacy ||
+    native !== undefined ||
+    effective === undefined ||
+    effective === before.effective ||
+    token.streamSimple === before.legacy?.streamSimple
+  ) {
+    throw new Error(
+      'pi_anthropic_attribution_install_failed: host provider registration did not install the package transport atomically',
+    );
+  }
+
+  return { registry, before, token };
+}
+
+function sameConfigValues(
+  left: RegisteredProviderConfig,
+  right: RegisteredProviderConfig,
+): boolean {
+  const leftKeys = Object.keys(left).sort();
+  const rightKeys = Object.keys(right).sort();
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every(
+      (key, index) =>
+        key === rightKeys[index] && Object.is(Reflect.get(left, key), Reflect.get(right, key)),
+    )
+  );
+}
+
+function restoreProviderInstallation(installation: ProviderInstallation): void {
+  const { registry, before, token } = installation;
+  if (
+    registry.getRegisteredProviderConfig(ANTHROPIC_PROVIDER) !== token ||
+    registry.getRegisteredNativeProvider(ANTHROPIC_PROVIDER) !== undefined
+  ) {
+    // A later owner replaced this exact installation. It owns teardown now.
+    return;
+  }
+
+  if (before.native !== undefined) {
+    registry.registerProvider(before.native);
+  } else if (before.legacy !== undefined) {
+    // Native replacement removes only the still-current package legacy layer. Reapplying
+    // the prior legacy snapshot then starts from an empty legacy layer, so package-only
+    // fields cannot leak through ModelRuntime's documented merge semantics.
+    registry.registerProvider(before.effective);
+    registry.registerProvider(ANTHROPIC_PROVIDER, before.legacy);
+  } else {
+    // The exact package token and absence of a later native owner were proven above.
+    // Public unregister is therefore owner-conditional here: it removes only this
+    // still-current package layer and restores the captured built-in source absence.
+    registry.unregisterProvider(ANTHROPIC_PROVIDER);
+  }
+
+  const restoredConfig = registry.getRegisteredProviderConfig(ANTHROPIC_PROVIDER);
+  const restoredNative = registry.getRegisteredNativeProvider(ANTHROPIC_PROVIDER);
+  const restoredEffective = registry.getProvider(ANTHROPIC_PROVIDER);
+  const restoredIds = registry.getRegisteredProviderIds();
+  const registrationRestored =
+    before.legacy !== undefined
+      ? restoredNative === undefined &&
+        restoredConfig !== undefined &&
+        sameConfigValues(restoredConfig, before.legacy)
+      : restoredConfig === undefined &&
+        (before.native !== undefined
+          ? restoredNative === before.native
+          : restoredNative === undefined);
+  const streamIdentityRestored =
+    before.legacy !== undefined
+      ? restoredConfig?.streamSimple === before.legacy.streamSimple
+      : restoredEffective?.streamSimple === before.effective.streamSimple;
+  const effectiveIdentityRestored =
+    before.legacy !== undefined || restoredEffective === before.effective;
+  const registeredIdRestored =
+    before.legacy !== undefined || before.native !== undefined
+      ? restoredIds.includes(ANTHROPIC_PROVIDER)
+      : !restoredIds.includes(ANTHROPIC_PROVIDER);
+  if (
+    !registrationRestored ||
+    restoredEffective === undefined ||
+    !streamIdentityRestored ||
+    !effectiveIdentityRestored ||
+    !registeredIdRestored
+  ) {
+    throw new Error(
+      'pi_anthropic_attribution_restore_failed: the preexisting host provider was not restored by identity',
+    );
+  }
+}
+
+export default async function ambientAnthropicAttribution(pi: PiExtensionHost): Promise<void> {
+  const config = parseBackgroundTasksConfig();
+  if (config.features.attribution) {
+    const { default: spawnAnthropicAttribution } = await import(
+      '../src/core/anthropic-attribution.js'
+    );
+    let installation: ProviderInstallation | undefined;
+    pi.on('session_start', (_event, context) => {
+      const registry = (context as AmbientAttributionContext).modelRegistry;
+      const before = captureProviderSnapshot(registry);
+      spawnAnthropicAttribution(pi);
+      installation = confirmProviderInstallation(registry, before) ?? installation;
+    });
+    pi.on('session_shutdown', () => {
+      const current = installation;
+      installation = undefined;
+      if (current !== undefined) restoreProviderInstallation(current);
+    });
+  }
+}