pi-background-tasks 2.5.0 → 2.6.0

package/docs/api/eventbus-v1.md

@@ -10,6 +10,8 @@ covers_sources: [src/core/extension-api.ts]
 # EventBus API v1
 
 <!-- pi-docs:begin name="eventbus-contract" generator="scripts/docs/generate.mjs" -->
+Availability: `always`; available by default: **yes**.
+
 | Channel purpose | Channel | Schema |
 | --- | --- | --- |
 | Request | `pi-background-tasks:request:v1` | `pi-background-tasks.extension-request.v1` |
@@ -35,6 +37,12 @@ Operations: `capabilities`, `kill`, `logs`, `run`, `status`.
 
 Primary source: `src/core/extension-api.ts`. Code is authoritative.
 
+## Initialized-host SDK requirement
+
+The service accepts requests only after `session_start` supplies its session context. Normal Pi TUI, RPC, print, and JSON modes provide counted lifecycle bindings. An SDK embedder must call `bindExtensions()` with at least one counted UI/command/shutdown/error binding so reload emits `session_start`; an empty or mode-only host must explicitly bind again after every reload.
+
+Bare `createAgentSession()` does not initialize this context, and an empty or mode-only binding does not preserve post-bind initialization across `reload()`. Calls before initialization fail as unavailable; consumers must not fabricate context. This public-host limitation remains a `BLOCKED_SCOPE` SDK compatibility blocker. The generated API availability describes the initialized-host contract and is not a pre-bind availability guarantee.
+
 ## Channels and schema ids
 
 | Purpose | Channel | `schema_version` |
@@ -59,7 +67,7 @@ Closed object; unknown keys fail.
 Payloads:
 
 - `capabilities`: `{}` only.
-- `run`: `{ name, command, isAgent, notifyOnCompletion, triggerOnCompletion, timeoutSeconds? }`; strings are non-empty, booleans are booleans, `timeoutSeconds` is a positive integer when present.
+- `run`: `{ name, command, isAgent, notifyOnCompletion, triggerOnCompletion, timeoutSeconds? }`; strings are non-empty, booleans are booleans, `timeoutSeconds` is a positive integer when present. V1 cannot request reload survival: `surviveReload` remains an unknown-key error and every v1 run uses the compatible default `false`.
 - `status`: `{ taskId? }`; `taskId` is non-empty when present.
 - `logs`: `{ taskId, maxBytes?, tail? }`; `maxBytes` is positive when present and is still bounded by runtime log caps.
 - `kill`: `{ taskId }`.
@@ -90,7 +98,7 @@ Closed by construction through the exported union:
 }
 ```
 
-Duplicate `request_id` values are rejected. The service rejects requests before `session_start` and while shutting down. Calling `close()` unsubscribes the request listener, so later requests are not handled and receive no service response.
+Duplicate `request_id` values are rejected. The service rejects requests before `session_start` and while shutting down. The installed service exposes typed state `open | closed`. Calling `close()` is idempotent, transitions it permanently to `closed`, unsubscribes the request listener, and disposes registry publication, so requests first emitted after close are not handled and receive no service response. A request already accepted before close may receive one error response, but never a post-close success. Direct publication after close throws `BackgroundTaskExtensionServiceClosedError` with code `pi_background_tasks_eventbus_closed`; callers must not infer closure from message text.
 
 ## Capabilities
 
@@ -120,17 +128,25 @@ Terminal events are emitted on `pi-background-tasks:terminal:v1`:
 }
 ```
 
-The terminal event carries no request id; consumers correlate by `task.id` returned from `run`/`kill`/`status`.
+The terminal event carries no request id; consumers correlate by `task.id` returned from `run`/`kill`/`status`. The additive task snapshot can include `surviveReload` and `reloadSurvival` when a task was launched through `bg_run` or `/bg`; the request side remains unchanged. A fresh activation may emit that survivor's pending terminal on this same v1 channel.
 
 ## Ordering and durability barrier
 
 For `run` and `kill` requests, the service installs a terminal-publication gate. After the response is emitted, the gate waits one microtask before releasing terminal publication, so immediate-exit tasks cannot publish terminal before the caller has observed the task id.
 
-The registry publishes terminal snapshots only after the output stream has finished/closed and durable terminal metadata has been written. Successful publication is latched and not emitted again. If `EventBus.emit` throws, the failure is loud and the registry retries; because one listener may have received a frame before another listener threw, delivery is **at least once under emission failure**. Consumers must deduplicate by `task.id`.
+The registry publishes terminal snapshots only after the output stream has finished/closed and durable terminal metadata has been written. Publication state is tracked separately as `pending`, `delivered`, or `abandoned`; successful publication is latched and not emitted again, while abandonment is never represented as delivery.
+
+If `EventBus.emit` throws, the registry retries after 100 ms for at most three total emit attempts. Persistent failure then becomes `abandoned` with bounded diagnostics. Because one listener may have received a frame before a later listener threw, delivery is **at least once under emission failure** and the same task can be observed up to the attempt bound. Consumers must deduplicate by `task.id`.
+
+Shutdown, service disposal, a rejected publication gate, retry exhaustion, retention-limit eviction, or reload-handoff expiry can abandon the terminal frame without changing durable task metadata, waiter completion, or notification truth. Shutdown/service disposal clears pending retry timers and races any gate wait against one-way activation closure. Retention eviction abandons and releases an oldest pending publication before deleting that old task, so a newer notified result remains retrievable and finished-task retention stays bounded. After either gate resolution or rejection, lifecycle is checked again, so a late gate cannot emit or re-arm an old activation. Tasks made terminal by ordinary session shutdown intentionally do not publish onto the disposed activation's EventBus.
+
+A valid opted reload handoff removes the survivor before old publication closure, clears only old physical gate/retry handles, and retains its logical state plus cumulative attempt count. Completion in the gap queues for the fresh service. The three-attempt cap and typed closed-service handling do not reset across reload; physical delivery remains at-least-once and consumers still deduplicate by task id.
+
+If a synchronous terminal listener calls `close()` while emission is on the stack, queued publication work is disposed but that emission settles only when the emitter returns or throws. A normal return is delivered without an abandonment diagnostic; a non-handoff throw is abandoned once with truthful diagnostics. If the listener synchronously transferred reload ownership before throwing, the old publisher first observes that its exact task/lease binding is gone, leaves publication pending with the attempt consumed, and schedules no old retry; the fresh activation resumes at the next cumulative attempt. Closure never records both outcomes.
 
 ## Operations
 
-- `run` starts a background task through the registry and returns a `BgTaskSnapshot`.
+- `run` starts a background task through the registry and returns a `BgTaskSnapshot`. Task admission is one-way closed at shutdown; each accepted admission has cancellation plus an overall bounded preflight deadline, and shutdown drains its owned cleanup before taking the running-task snapshot. A request crossing closure cannot insert/spawn or return success.
 - `status` returns `{ tasks }`; with `taskId`, the array has one resolved task or errors loudly.
 - `logs` returns bounded log details plus `text`; full bytes stay in `.pi/tasks/...output`.
 - `kill` stops a running task and returns `{ task, message }` after the stop path.

package/docs/choose-a-workflow.md

@@ -9,6 +9,8 @@ covers_sources: []
 ---
 # Choose a workflow
 
+The complete table is available by default. Operators can remove advanced registrations with strict `PI_BG_FEATURES`; a workflow whose capability is disabled is absent rather than executable under a hidden/stale name. See [Configuration](operations/configuration.md). `bg_result` appears only when delegate or Fusion is enabled.
+
 ## Quick decision tree
 
 1. **Is the work short and interactive?** Use ordinary foreground Pi work.

package/docs/commands/bg-clear.md

@@ -10,9 +10,9 @@ covers_sources: []
 # `/bg-clear`
 
 <!-- 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:559` |
+| Command | Availability | Default | Description | Provenance |
+| --- | --- | --- | --- | --- |
+| `/bg-clear` | `always` | yes | Clear finished background task footer notices | `src/extension.ts:793` |
 <!-- pi-docs:end name="command-contract-bg-clear" -->
 
 Clear finished background task footer notices.

package/docs/commands/bg-update.md

@@ -10,9 +10,9 @@ covers_sources: []
 # `/bg-update`
 
 <!-- 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:567` |
+| Command | Availability | Default | Description | Provenance |
+| --- | --- | --- | --- | --- |
+| `/bg-update` | `always` | yes | Show how to update pi-background-tasks to the latest published version | `src/extension.ts:801` |
 <!-- pi-docs:end name="command-contract-bg-update" -->
 
 Show update instructions for `pi-background-tasks`.

package/docs/commands/bg.md

@@ -10,9 +10,9 @@ covers_sources: []
 # `/bg`
 
 <!-- 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:517` |
+| Command | Availability | Default | Description | Provenance |
+| --- | --- | --- | --- | --- |
+| `/bg` | `always` | yes | Start a tracked shell command: /bg [--survive-reload] [--agent] [--name "Task name"] <command> | `src/extension.ts:750` |
 <!-- pi-docs:end name="command-contract-bg" -->
 
 Start a shell command as a tracked background task from the command line.
@@ -20,7 +20,7 @@ Start a shell command as a tracked background task from the command line.
 ## Synopsis
 
 
-`/bg [--agent|--llm-agent] [--script|--no-agent] [--name <name>|-n <name>] [--] <command>`
+`/bg [--survive-reload] [--agent|--llm-agent] [--script|--no-agent] [--name <name>|-n <name>] [--] <command>`
 
 `--name=<name>` and `-n=<name>` are also accepted. Quoted names are parsed by the extension before the remaining bytes become the shell command.
 
@@ -34,11 +34,18 @@ Use `/bg` for user-driven long-running commands where you want a footer entry, o
 - `--script`/`--no-agent`: forces `isAgent:false` after earlier flags.
 - `notifyOnCompletion`: `true`.
 - `triggerOnCompletion`: `false` for `/bg`, so completion is display-only by default.
+- `surviveReload`: `false`; one bare leading `--survive-reload` opts an ordinary `isAgent:false` shell execution into supported same-process real reload handoff.
 - Task name: explicit `--name` if present, otherwise derived from the command.
 
+## Shell selection
+
+`/bg` uses the same activation-stable policy and agent-visible guidance as `bg_run`. The compatible non-Windows default remains non-empty `SHELL`, otherwise `/bin/sh`, with `-c`; it never silently switches existing users to Bash or loads login-shell startup. Set `PI_BG_POSIX_SHELL=bash` or `sh` before startup or `/reload` for deliberate automation syntax, with optional validated absolute `PI_BG_POSIX_SHELL_PATH`. See [Configuration](../operations/configuration.md) for search and validation details.
+
+Inherited Nu, fish, csh, and unknown names are reported as `user-non-posix`, not POSIX/Bash. Task metadata records the exact executable, argument prefix, and dialect used. Windows remains controlled only by its existing `PI_BG_SHELL`/`PI_BG_SHELL_PATH`/`ComSpec` policy.
+
 ## Lifecycle
 
-The command returns after the child process is spawned and reports task id, output path, and command. Terminal statuses are exactly `running`, `completed`, `failed`, or `killed`. A finished footer badge remains visible until that task's detail view is opened or [`/bg-clear`](bg-clear.md) marks unseen finished tasks seen.
+The command returns after the child process is spawned and reports task id, output path, and command. Terminal statuses are exactly `running`, `completed`, `failed`, or `killed`. By default reload kills it. With `--survive-reload`, a real same-process reload claims the same live child/PID/id/nonce/path and keeps output, status, kill, absolute timeout, cumulative output cap, and one completion delivery working. New/resume/fork/clone/quit, extension removal without a claimant, crash, and process restart do not survive. A finished footer badge remains visible until that task's detail view is opened or [`/bg-clear`](bg-clear.md) marks unseen finished tasks seen.
 
 ## Examples
 
@@ -46,6 +53,7 @@ The command returns after the child process is spawned and reports task id, outp
 /bg --name "Docs build" npm run docs
 /bg --agent --name "Child Pi" pi -p "summarize this repo"
 /bg --name="Server" -- npm run dev -- --host 127.0.0.1
+/bg --survive-reload --name "Reload-safe watcher" npm run watch
 ```
 
 ## Output/result
@@ -64,12 +72,16 @@ Completion is delivered as a durable `background-task-notification` custom messa
 
 - Empty command: `Background command is empty`.
 - Missing or unterminated `--name`: `requires a task name`.
+- Duplicate or assignment-form survival flags: `pi_bg_survive_reload_invalid`; `--` makes a later `--survive-reload` literal command text.
+- `--agent`/`--llm-agent` with survival: `pi_bg_survive_reload_requires_non_agent` before files or spawn.
+- A lifecycle without a bound owner (including the empty-binding SDK reload limitation): `pi_bg_reload_owner_unavailable`.
 - Shell/spawn errors fail the task loudly and write failure metadata.
+- Invalid or unavailable explicit POSIX Bash/sh selection rejects the launch without fallback.
 - Unknown shell policy on Windows can reject the launch before a task is created.
 
 ## Runtime artifacts
 
-Outputs and metadata are written under `.pi/tasks/<session-id>-<pid>/` as `<task-id>.output` and `<task-id>.json`. Model-visible log reads are bounded; the full output path is preserved in notices.
+Outputs and metadata are written under `.pi/tasks/<session-id>-<pid>/` as `<task-id>.output` and `<task-id>.json`. Ordinary-task metadata includes the non-secret resolved shell policy. Model-visible log reads are bounded; the full output path is preserved in notices.
 
 ## Safety boundaries
 

package/docs/commands/claude-cache.md

@@ -10,12 +10,12 @@ covers_sources: []
 # `/claude-cache`
 
 <!-- pi-docs:begin name="command-contract-claude-cache" generator="scripts/docs/generate.mjs" -->
-| Command | Description | Provenance |
-| --- | --- | --- |
-| `/claude-cache` | Show or set Claude cache retention for this session (short, long, default) | `src/core/anthropic-attribution.ts:3026` |
+| Command | Availability | Default | Description | Provenance |
+| --- | --- | --- | --- | --- |
+| `/claude-cache` | `feature:attribution` | yes | Show or set Claude cache retention for this session (short, long, default) | `src/core/anthropic-attribution.ts:3206` |
 <!-- pi-docs:end name="command-contract-claude-cache" -->
 
-Show or change the Anthropic cache-retention preference for the current session.
+Show or change the Anthropic cache-retention preference for the current session. Under the initialized-host contract, the command is registered only when `PI_BG_FEATURES` includes the ambient `attribution` capability (enabled by default); disabling that capability removes the command together with the parent provider/hooks. Its generated default availability is not a pre-bind availability guarantee: bare SDK sessions and empty/mode-only reloads require the explicit binding described in [Anthropic attribution](../subsystems/anthropic-attribution.md#initialized-host-sdk-contract-and-blocker).
 
 ## Synopsis
 

package/docs/commands/fusion-models.md

@@ -10,9 +10,9 @@ covers_sources: []
 # `/fusion-models`
 
 <!-- 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:1029` |
+| Command | Availability | Default | Description | Provenance |
+| --- | --- | --- | --- | --- |
+| `/fusion-models` | `feature:fusion` | yes | Open the five-slot global fusion model selector. | `src/fusion-extension.ts:1123` |
 <!-- pi-docs:end name="command-contract-fusion-models" -->
 
 Open the global Fusion model selector.
@@ -33,6 +33,45 @@ The selector edits exactly five global slots:
 
 Duplicate model selections are allowed. `$current` is the default for every slot and resolves at run time to Pi's current model; it is available only when a current model exists and is available to child Pi. Slash-containing model ids are stored as `provider/model-id` strings.
 
+## What each role does
+
+Fusion follows one fixed pipeline: preflight, three candidates in parallel, an evaluator, an optional evaluator repair, then a merger.
+
+### Candidate 1, Candidate 2, and Candidate 3
+
+The candidates are three independent attempts over the same canonical input, with the same workflow instruction and fixed workflow tools. They are not assigned specialties: Candidate 1 is not inherently a researcher, Candidate 2 a critic, or Candidate 3 a writer. A tool-enabled workflow lets every candidate use that workflow's same allowlist; `reason` gives all three no tools.
+
+The candidate wave must finish before evaluation, so the slowest candidate controls successful wave latency. Choosing different capable routes can improve answer diversity, but route diversity does not guarantee different reasoning or coverage. Repeating one route is valid and can still produce useful independent attempts, but the answers may be similar—especially when that route behaves deterministically.
+
+### Evaluator
+
+The evaluator starts after all candidates complete. It receives the original canonical input and the three anonymous answers labeled A, B, and C, with no provider, model, slot, or completion-order identity. It has no tools. It compares strengths, limitations, agreements, conflicts, risks, and useful contributions, then emits closed JSON containing a constrained `synthesis_plan`; it does not select a winner or write the user-facing answer.
+
+If that JSON is invalid or schema-invalid, Fusion makes exactly one repair attempt using the same evaluator slot and resolved model. The repair receives the original blind input, the invalid output, and bounded validation errors. A second invalid result fails the run; Fusion does not switch models or add another repair.
+
+### Merger
+
+The merger starts only after a valid evaluation. It receives the original canonical input, all three candidate outputs, and the validated evaluation. It has no tools and the merge stage produces the sole final user-facing answer; candidates and evaluator output are never returned as the answer. For `fusion_validate`, the host renders the final report from validated finding accounting after the no-tool merger rather than forwarding unverified merger prose.
+
+This is the final sequential stage and normally has the greatest synthesis burden: it must reconcile all upstream material rather than retrieve new facts.
+
+## Choosing models
+
+There is no universally best assignment. Use only routes currently listed as available by the selector, and account for both capability and context capacity.
+
+| Goal | Candidates | Evaluator | Merger |
+| --- | --- | --- | --- |
+| **Quality-first** | Choose three strong task-capable routes; use different routes when their genuine differences are useful, while remembering that diversity is not guaranteed. | Prefer strong comparison and schema reliability. It must absorb the input plus all three answers, and one failed schema attempt adds repair latency. | Prefer the strongest available synthesis route with enough context for every upstream answer and the evaluation. |
+| **Speed-first** | Choose fast routes for all three; one slow outlier delays the whole parallel wave. Repeating one fast route is allowed. | Choose a fast, schema-reliable route so the sequential stage is short and the optional repair is unlikely. | Choose a capable fast synthesizer; its latency is added after the complete candidate and evaluator stages. |
+
+Context capacity can outweigh nominal model strength. Each candidate sees the canonical input; the evaluator fans in that input plus three bounded candidate outputs; the merger additionally receives the validated evaluation. Conditional repair has the widest evaluator input because it also includes the invalid evaluation and validation errors. Fusion measures each rendered stage against that slot's route before launch, so a stronger small-context route can still be unusable. See [Fusion runtime limits](../operations/configuration.md#fusion-runtime-limits) and [budget behavior](../subsystems/fusion.md#budgets-and-output-contracts).
+
+For frontier models, every role must remain on Pi's Anthropic or Codex subscription OAuth channel. Here “expensive” can mean latency, subscription quota, and token/context use; it is not permission to move a role to a metered API route.
+
+## Slots are not calls
+
+Five role slots do not promise five distinct models or five provider calls. `$current` and explicit selections may be duplicated across any slots. An ordinary success without repair uses five child invocations: three candidates, one evaluator, and one merger. A successful evaluator repair makes six child invocations. A preflight rejection creates zero children. Failed or cancelled runs can stop with fewer completed children, transient pre-creation spawn failures can change launch attempts, and each child Pi process can make multiple provider requests within its runtime limits.
+
 ## UI behavior
 
 The selector starts from the loaded config or the default all-`$current` config. It lists:
@@ -45,7 +84,11 @@ In the five-slot view, arrow keys move, Enter opens the model list, `r` resets t
 
 ## Persistence and conflicts
 
-The config file is `fusion-models.json` in Pi's agent directory (`fusionModelConfigPath()`). Its schema is closed:
+The config file is `fusion-models.json` in Pi's agent directory (`fusionModelConfigPath()`). Its schema is closed.
+
+### Valid repeated-route example
+
+This is both a valid configuration and the missing-file default. It deliberately demonstrates `$current` and duplicates; at run time the current route must still be available and pass admission for child Pi.
 
 ```json
 {
@@ -56,6 +99,8 @@ The config file is `fusion-models.json` in Pi's agent directory (`fusionModelCon
 }
 ```
 
+For explicit selections, save only exact `provider/model-id` keys shown as available by `/fusion-models`; no model aliases are implied by the quality-first or speed-first recipes above. Reusing the same exact key in multiple slots is valid.
+
 Loads reject invalid JSON, unknown keys, wrong schema version, blank selections, surrounding whitespace, unqualified configured selections, and candidate arrays that do not contain exactly three entries.
 
 Saves are durable and revision-safe: the parent captures the file revision hash on load, takes a lock next to the config, verifies the on-disk revision still matches, then atomically replaces the file. If another process changes the file first, the save fails with a config-conflict error shown inside the selector; it does not overwrite concurrent work. Lock acquisition times out loudly after 10 seconds.

package/docs/commands/fusion.md

@@ -10,9 +10,9 @@ covers_sources: []
 # `/fusion`
 
 <!-- pi-docs:begin name="command-contract-fusion" generator="scripts/docs/generate.mjs" -->
-| Command | Description | Provenance |
-| --- | --- | --- |
-| `/fusion` | Start fixed-purpose Fusion reason in the background and return immediately. | `src/fusion-extension.ts:996` |
+| Command | Availability | Default | Description | Provenance |
+| --- | --- | --- | --- | --- |
+| `/fusion` | `feature:fusion` | yes | Start fixed-purpose Fusion reason in the background and return immediately. | `src/fusion-extension.ts:1083` |
 <!-- pi-docs:end name="command-contract-fusion" -->
 
 Run the fixed-purpose Fusion **reason** workflow from the command line.

package/docs/commands/jobs.md

@@ -10,9 +10,9 @@ covers_sources: []
 # `/jobs`
 
 <!-- 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:605` |
+| Command | Availability | Default | Description | Provenance |
+| --- | --- | --- | --- | --- |
+| `/jobs` | `always` | yes | List running and recent background tasks | `src/extension.ts:850` |
 <!-- pi-docs:end name="command-contract-jobs" -->
 
 List running and recent background tasks.

package/docs/commands/kill.md

@@ -10,9 +10,9 @@ covers_sources: []
 # `/kill`
 
 <!-- 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:649` |
+| Command | Availability | Default | Description | Provenance |
+| --- | --- | --- | --- | --- |
+| `/kill` | `always` | yes | Stop a running background task: /kill <id> | `src/extension.ts:894` |
 <!-- pi-docs:end name="command-contract-kill" -->
 
 Stop a running background task.

package/docs/commands/logs.md

@@ -10,9 +10,9 @@ covers_sources: []
 # `/logs`
 
 <!-- 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:618` |
+| Command | Availability | Default | Description | Provenance |
+| --- | --- | --- | --- | --- |
+| `/logs` | `always` | yes | Show bounded output from a background task: /logs <id> [maxBytes] | `src/extension.ts:863` |
 <!-- pi-docs:end name="command-contract-logs" -->
 
 Show bounded output from a background task.

package/docs/commands/task-manager.md

@@ -10,10 +10,10 @@ covers_sources: []
 # `/tasks` and `/bg-tasks`
 
 <!-- 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:543` |
-| `/bg-tasks` | Open the background task manager UI | `src/extension.ts:551` |
+| Command | Availability | Default | Description | Provenance |
+| --- | --- | --- | --- | --- |
+| `/tasks` | `always` | yes | Open the Claude-like background task manager UI | `src/extension.ts:777` |
+| `/bg-tasks` | `always` | yes | Open the background task manager UI | `src/extension.ts:785` |
 <!-- pi-docs:end name="command-contract-tasks-bg-tasks" -->
 
 Open the interactive background task manager. `/tasks` and `/bg-tasks` are aliases.
@@ -37,7 +37,7 @@ Use the task manager when you want the host UI: select tasks, inspect a live out
 
 ## Lifecycle
 
-The manager is an overlay dock. Opening it sets the footer hint to `focused` and temporarily hides the `/bg-clear` hint; closing returns the footer to the normal `Shift↓` hint. Opening a finished task's detail view marks that task seen. Merely opening the list or closing the dock does **not** clear other finished badges; use [`/bg-clear`](bg-clear.md) to clear them together.
+The manager is an overlay dock. Opening it sets the footer hint to `focused` and temporarily hides the `/bg-clear` hint; closing returns the footer to the configured `Shift↓`, `CtrlAltB`, or `/tasks` hint. `PI_BG_DOCK_SHORTCUT=off` disables only the key registration—both commands on this page continue to work. Opening a finished task's detail view marks that task seen. Merely opening the list or closing the dock does **not** clear other finished badges; use [`/bg-clear`](bg-clear.md) to clear them together.
 
 List view sorts tasks as running, failed, killed, then completed; within a status, newest terminal/start time appears first. Status labels shown in the UI are `running`, `error` for `failed`, `stopped` for `killed`, and `done` for `completed`.
 

package/docs/concepts/completion-delivery.md

@@ -26,7 +26,7 @@ Background tasks can finish silently, notify the terminal, or notify and wake th
 - `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.
+- A received `<background-task-notification>` is metadata-backed terminal-status truth. The output stream has finished/closed; after a requested POSIX tree stop, the originally owned process group has also been observed gone, while a force/proof failure is delivered as `failed` rather than a successful kill. 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
 
@@ -51,7 +51,11 @@ If either completion flag was intentionally disabled, manual inspection is allow
 
 ## Failures and suppression
 
-If notification send fails, the task resets `notified:false` and logs the error; it does not silently pretend delivery happened. During Pi session shutdown/reload, notifications are suppressed while running tasks are killed.
+Completion notification receipt and terminal EventBus publication are independent facts. EventBus publication can be pending, delivered, or abandoned without changing durable task status or `notified`. At the retention boundary, an oldest pending publication is abandoned and disposed before that old task is pruned; it cannot evict a newer notified Fusion result before `bg_result` retrieval. If the EventBus service alone is disposed, an otherwise enabled notification may still be sent. During ordinary Pi shutdown, notifications are suppressed and old publication is abandoned.
+
+A live opted ordinary reload survivor is different: detach transfers its logical publication ledger and notification latch without sending through the old host. Completion during the gap queues. The fresh activation resumes at the same cumulative EventBus attempt count and sends at most one successful host notification; a reload never resets `notified`. Physical EventBus delivery remains at-least-once under listener failure and consumers still deduplicate by task id.
+
+If notification send fails, the task resets `notified:false` and logs the error; it does not silently pretend delivery happened. Likewise, EventBus abandonment—including `reload_handoff_expired` when no fresh activation claims an owner—never becomes successful publication or rewrites the real terminal status.
 
 ## Related docs
 

package/docs/getting-started.md

@@ -36,6 +36,12 @@ pi install .
 pi install . -l
 ```
 
+## SDK embedding requirement
+
+**Initialized-host contract:** package resources that require post-bind initialization are available in normal Pi TUI, RPC, print, and JSON modes. An SDK embedder must call `bindExtensions()` with at least one counted binding for lifecycle restoration—such as `onError`, UI/command actions, or shutdown handling—so `session_start` is emitted again by `reload()`. If the embedder uses an empty or mode-only binding, it must explicitly call `bindExtensions()` again after every reload.
+
+Bare `createAgentSession()` does not emit `session_start`; `{}` or `{ mode: "print" }` binds once but does not make a later reload emit it. Post-bind resources such as ambient Anthropic attribution, `/claude-cache`, and session-context EventBus readiness are therefore unavailable on those bare/reloaded paths until an explicit bind. This is a current public Pi SDK blocker, not supported package behavior. The generated availability tables describe this initialized-host contract; they are not a pre-bind availability guarantee.
+
 ## 2. Start your first `/bg` task
 
 Inside a project, run:
@@ -55,7 +61,7 @@ Use the footer dock or commands:
 /logs <task id> 20000
 ```
 
-Press **Shift↓** to open the dock when the `bg ...` footer appears. `/bg-clear` acknowledges finished-task footer notices.
+Press the configured dock key (**Shift↓** by default, or **Ctrl+Alt+B**) when the `bg ...` footer appears. With `PI_BG_DOCK_SHORTCUT=off`, use `/tasks` or `/bg-tasks`. `/bg-clear` acknowledges finished-task footer notices.
 
 ## 4. Start an agent-launched background task