pi-background-tasks 0.9.0 → 1.0.4

package/docs/api/eventbus-v1.md

@@ -0,0 +1,166 @@
+---
+doc_id: api/eventbus-v1
+audience: maintainer
+mode: mixed
+review_policy: behavioral
+stability: evolving
+covers_surfaces: [eventbus:background-task-v1]
+covers_sources: [src/core/extension-api.ts]
+---
+# EventBus API v1
+
+<!-- pi-docs:begin name="eventbus-contract" generator="scripts/docs/generate.mjs" -->
+| Channel purpose | Channel | Schema |
+| --- | --- | --- |
+| Request | `pi-background-tasks:request:v1` | `pi-background-tasks.extension-request.v1` |
+| Response | `pi-background-tasks:response:v1` | `pi-background-tasks.extension-response.v1` |
+| Terminal | `pi-background-tasks:terminal:v1` | `pi-background-tasks.extension-terminal.v1` |
+
+Operations: `capabilities`, `kill`, `logs`, `run`, `status`.
+
+
+```json
+{
+  "api_version": 1,
+  "kill": true,
+  "logs": true,
+  "logs_bounded": true,
+  "run": true,
+  "run_completion_trigger": true,
+  "run_is_agent": true,
+  "status": true
+}
+```
+<!-- pi-docs:end name="eventbus-contract" -->
+
+Primary source: `src/core/extension-api.ts`. Code is authoritative.
+
+## Channels and schema ids
+
+| Purpose | Channel | `schema_version` |
+|---|---|---|
+| Requests | `pi-background-tasks:request:v1` | `pi-background-tasks.extension-request.v1` |
+| Responses | `pi-background-tasks:response:v1` | `pi-background-tasks.extension-response.v1` |
+| Terminal events | `pi-background-tasks:terminal:v1` | `pi-background-tasks.extension-terminal.v1` |
+
+## Request frame
+
+Closed object; unknown keys fail.
+
+```ts
+{
+  schema_version: 'pi-background-tasks.extension-request.v1',
+  request_id: string,        // non-empty, max 200 chars
+  operation: 'capabilities' | 'run' | 'status' | 'logs' | 'kill',
+  payload: object            // operation-specific closed object
+}
+```
+
+Payloads:
+
+- `capabilities`: `{}` only.
+- `run`: `{ name, command, isAgent, notifyOnCompletion, triggerOnCompletion, timeoutSeconds? }`; strings are non-empty, booleans are booleans, `timeoutSeconds` is a positive integer when present.
+- `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 }`.
+
+Malformed frames still receive a response where possible: `request_id` and `operation` echo valid non-empty input strings, otherwise `malformed`.
+
+## Response frame
+
+Closed by construction through the exported union:
+
+```ts
+// success
+{
+  schema_version: 'pi-background-tasks.extension-response.v1',
+  request_id: string,
+  operation: string,
+  ok: true,
+  result: BackgroundTaskExtensionResult
+}
+
+// error
+{
+  schema_version: 'pi-background-tasks.extension-response.v1',
+  request_id: string,
+  operation: string,
+  ok: false,
+  error: string             // whitespace-compacted, max 240 chars
+}
+```
+
+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.
+
+## Capabilities
+
+`capabilities` returns exactly:
+
+```json
+{
+  "api_version": 1,
+  "run": true,
+  "run_is_agent": true,
+  "run_completion_trigger": true,
+  "status": true,
+  "logs": true,
+  "logs_bounded": true,
+  "kill": true
+}
+```
+
+## Terminal frames
+
+Terminal events are emitted on `pi-background-tasks:terminal:v1`:
+
+```ts
+{
+  schema_version: 'pi-background-tasks.extension-terminal.v1',
+  task: BgTaskSnapshot
+}
+```
+
+The terminal event carries no request id; consumers correlate by `task.id` returned from `run`/`kill`/`status`.
+
+## 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`.
+
+## Operations
+
+- `run` starts a background task through the registry and returns a `BgTaskSnapshot`.
+- `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.
+- `capabilities` is pure and does not require a task.
+
+## Integration example
+
+```ts
+const requestId = crypto.randomUUID();
+const terminal = new Promise((resolve) => {
+  const off = events.on('pi-background-tasks:terminal:v1', (frame) => {
+    if (frame?.schema_version === 'pi-background-tasks.extension-terminal.v1') {
+      off();
+      resolve(frame.task);
+    }
+  });
+});
+
+events.emit('pi-background-tasks:request:v1', {
+  schema_version: 'pi-background-tasks.extension-request.v1',
+  request_id: requestId,
+  operation: 'run',
+  payload: {
+    name: 'Example',
+    command: 'printf eventbus-ok',
+    isAgent: false,
+    notifyOnCompletion: true,
+    triggerOnCompletion: true
+  }
+});
+```
+
+Listen for the matching response on `pi-background-tasks:response:v1`, deduplicate terminal frames by `task.id`, and treat the frame's metadata-backed status as terminal truth; do not poll status merely to reconfirm it.

package/docs/assets/architecture.svg

@@ -0,0 +1,78 @@
+<svg xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc" viewBox="0 0 1200 820">
+  <title id="title">pi-background-tasks architecture</title>
+  <desc id="desc">Pi session routes to a background registry, delegate child process, and Fusion candidates that flow through blind evaluation, optional repair, and merger.</desc>
+  <defs>
+    <linearGradient id="panel" x1="0" x2="1">
+      <stop offset="0" stop-color="#071a33"/>
+      <stop offset="1" stop-color="#0e3157"/>
+    </linearGradient>
+    <linearGradient id="cyan" x1="0" x2="1">
+      <stop offset="0" stop-color="#77f5ff"/>
+      <stop offset="1" stop-color="#18bde7"/>
+    </linearGradient>
+    <linearGradient id="amber" x1="0" x2="1">
+      <stop offset="0" stop-color="#ffd987"/>
+      <stop offset="1" stop-color="#ffa51f"/>
+    </linearGradient>
+    <marker id="arrowCyan" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto">
+      <path d="M2,2 L10,6 L2,10" fill="none" stroke="#37d7ef" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
+    </marker>
+    <marker id="arrowAmber" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto">
+      <path d="M2,2 L10,6 L2,10" fill="none" stroke="#ffb43d" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
+    </marker>
+    <style>
+      .bg{fill:#061529}.panel{fill:url(#panel);stroke:#2ed7ef;stroke-opacity:.45;stroke-width:2}.node{fill:#0b2848;stroke:#64ecff;stroke-width:2}.amber{stroke:#ffbd4b}.txt{font-family:ui-sans-serif,system-ui,-apple-system,Segoe UI,sans-serif;fill:#eefbff}.muted{fill:#a9c7d8}.small{font-size:22px}.label{font-size:26px;font-weight:700}.tiny{font-size:18px}.line{fill:none;stroke:#37d7ef;stroke-width:4;stroke-linecap:round;stroke-linejoin:round;marker-end:url(#arrowCyan)}.lineA{fill:none;stroke:#ffb43d;stroke-width:4;stroke-linecap:round;stroke-linejoin:round;marker-end:url(#arrowAmber)}
+    </style>
+  </defs>
+  <rect class="bg" width="1200" height="820" rx="34"/>
+  <circle cx="100" cy="78" r="6" fill="#72f3ff" opacity=".7"/><circle cx="1090" cy="82" r="5" fill="#ffbd4b" opacity=".8"/><circle cx="1028" cy="760" r="5" fill="#72f3ff" opacity=".6"/>
+
+  <rect class="panel" x="50" y="70" width="250" height="126" rx="24"/>
+  <text class="txt label" x="175" y="122" text-anchor="middle">Pi session</text>
+  <text class="muted small" x="175" y="158" text-anchor="middle">commands · tools · EventBus</text>
+
+  <rect class="panel" x="430" y="46" width="300" height="170" rx="26"/>
+  <text class="txt label" x="580" y="98" text-anchor="middle">Background registry</text>
+  <text class="muted small" x="580" y="134" text-anchor="middle">spawn · track · kill</text>
+  <text class="muted small" x="580" y="168" text-anchor="middle">closed output + durable metadata</text>
+
+  <rect class="panel" x="858" y="70" width="292" height="126" rx="24"/>
+  <text class="txt label" x="1004" y="122" text-anchor="middle">Notification</text>
+  <text class="muted small" x="1004" y="158" text-anchor="middle">footer · follow-up turn</text>
+
+  <path class="line" d="M300 132 C350 132 378 132 430 132"/>
+  <path class="line" d="M730 132 C782 132 807 132 858 132"/>
+
+  <rect class="panel" x="72" y="284" width="268" height="118" rx="24"/>
+  <text class="txt label" x="206" y="334" text-anchor="middle">Projected seed</text>
+  <text class="muted small" x="206" y="370" text-anchor="middle">visible conversation only</text>
+
+  <rect class="panel" x="462" y="274" width="278" height="138" rx="24"/>
+  <text class="txt label" x="601" y="326" text-anchor="middle">Delegate child</text>
+  <text class="muted small" x="601" y="362" text-anchor="middle">isolated · inspect-only</text>
+
+  <rect class="panel" x="870" y="284" width="250" height="118" rx="24"/>
+  <text class="txt label" x="995" y="334" text-anchor="middle">Verified result</text>
+  <text class="muted small" x="995" y="370" text-anchor="middle">hash-checked retrieval</text>
+
+  <path class="line" d="M300 196 C290 240 254 252 225 284"/>
+  <path class="line" d="M340 343 C392 343 410 343 462 343"/>
+  <path class="line" d="M740 343 C790 343 820 343 870 343"/>
+
+  <text class="txt label" x="72" y="502">Fusion workflow</text>
+  <text class="muted small" x="72" y="534">fixed purpose · clean stage policies · no silent fallback</text>
+
+  <g transform="translate(76 570)">
+    <rect class="node" x="0" y="0" width="160" height="62" rx="18"/><text class="txt small" x="80" y="39" text-anchor="middle">Candidate 1</text>
+    <rect class="node" x="0" y="78" width="160" height="62" rx="18"/><text class="txt small" x="80" y="117" text-anchor="middle">Candidate 2</text>
+    <rect class="node" x="0" y="156" width="160" height="62" rx="18"/><text class="txt small" x="80" y="195" text-anchor="middle">Candidate 3</text>
+  </g>
+  <rect class="node" x="372" y="648" width="160" height="62" rx="18"/><text class="txt small" x="452" y="687" text-anchor="middle">Blind eval</text>
+  <rect class="node amber" x="620" y="648" width="188" height="62" rx="18"/><text class="txt small" x="714" y="687" text-anchor="middle">Optional repair</text>
+  <rect class="node amber" x="896" y="648" width="154" height="62" rx="18"/><text class="txt small" x="973" y="687" text-anchor="middle">Merger</text>
+  <path class="line" d="M236 601 C292 601 310 662 372 679"/>
+  <path class="line" d="M236 679 H372"/>
+  <path class="line" d="M236 757 C292 757 310 696 372 679"/>
+  <path class="lineA" d="M532 679 H620"/>
+  <path class="lineA" d="M808 679 H896"/>
+</svg>

package/docs/assets/footer-dock.svg

@@ -0,0 +1,47 @@
+<svg xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc" viewBox="0 0 1200 560">
+  <title id="title">pi-background-tasks footer dock illustration</title>
+  <desc id="desc">A stable illustrative Pi terminal footer and focused background task dock with running, completed, and failed tasks plus controls.</desc>
+  <defs>
+    <linearGradient id="screen" x1="0" x2="1" y1="0" y2="1">
+      <stop offset="0" stop-color="#061528"/>
+      <stop offset="1" stop-color="#0b294b"/>
+    </linearGradient>
+    <linearGradient id="footer" x1="0" x2="1">
+      <stop offset="0" stop-color="#b7e7ff"/>
+      <stop offset="1" stop-color="#7df4ff"/>
+    </linearGradient>
+    <style>
+      .screen{fill:url(#screen)}.dock{fill:#071a30;stroke:#50e5ff;stroke-width:2}.row{fill:#0c2847;stroke:#1f6d89;stroke-width:1}.row2{fill:#0a223d;stroke:#1f6d89;stroke-width:1}.footer{fill:url(#footer)}.text{font-family:ui-sans-serif,system-ui,-apple-system,Segoe UI,sans-serif;fill:#effcff}.muted{fill:#a7c3d6}.navy{fill:#093456}.cyan{fill:#64edff}.amber{fill:#ffbd4b}.green{fill:#5ff2b3}.red{fill:#ff6b7a}.small{font-size:22px}.tiny{font-size:18px}.label{font-size:26px;font-weight:700}.mono{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+    </style>
+  </defs>
+  <rect class="screen" x="34" y="34" width="1132" height="492" rx="34"/>
+  <rect x="74" y="78" width="1052" height="310" rx="18" fill="#041120" stroke="#173956"/>
+  <text class="text small mono" x="104" y="126">› Working in your project while background tasks run…</text>
+  <text class="muted small mono" x="104" y="170">The main conversation stays usable.</text>
+  <text class="muted small mono" x="104" y="214">Completion arrives as a durable task notification.</text>
+
+  <rect class="footer" x="74" y="410" width="1052" height="48" rx="18"/>
+  <text class="navy label" x="104" y="442">bg 1 running · 1 done · Shift↓ · /bg-clear</text>
+  <circle cx="1074" cy="434" r="10" fill="#093456" opacity=".75"/>
+
+  <rect class="dock" x="178" y="206" width="844" height="260" rx="26"/>
+  <text class="text label" x="218" y="254">Background tasks</text>
+  <text class="muted small" x="218" y="290">focused bottom dock · stable task controls</text>
+
+  <rect class="row" x="218" y="318" width="764" height="46" rx="14"/>
+  <circle class="cyan" cx="244" cy="341" r="8"/>
+  <text class="text small" x="266" y="348">Docs preview</text>
+  <text class="muted tiny" x="520" y="347">running · ctx — · output tail available</text>
+
+  <rect class="row2" x="218" y="374" width="764" height="46" rx="14"/>
+  <path d="M237 397 l8 9 l18 -22" fill="none" stroke="#5ff2b3" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
+  <text class="text small" x="266" y="404">Config audit</text>
+  <text class="muted tiny" x="520" y="403">completed · verified result ready</text>
+
+  <rect class="row2" x="218" y="430" width="764" height="46" rx="14"/>
+  <path d="M236 442 l22 22 M258 442 l-22 22" stroke="#ff6b7a" stroke-width="5" stroke-linecap="round"/>
+  <text class="text small" x="266" y="460">Old watcher</text>
+  <text class="muted tiny" x="520" y="459">failed · open logs for details</text>
+
+  <text class="muted tiny" x="218" y="504">↑/↓ select · Enter details · k stop · R rerun · c path · Esc close</text>
+</svg>

package/docs/assets/logo.svg

@@ -0,0 +1,49 @@
+<svg xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc" viewBox="0 0 512 512">
+  <title id="title">pi-background-tasks dispatcher logo</title>
+  <desc id="desc">A friendly futuristic dispatcher coordinates three parallel task nodes that converge into a completed result, using navy, cyan, and amber.</desc>
+  <defs>
+    <radialGradient id="bg" cx="50%" cy="38%" r="70%">
+      <stop offset="0" stop-color="#12365f"/>
+      <stop offset="0.58" stop-color="#08233f"/>
+      <stop offset="1" stop-color="#041528"/>
+    </radialGradient>
+    <linearGradient id="cyan" x1="72" y1="96" x2="420" y2="410" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#7cf7ff"/>
+      <stop offset="1" stop-color="#19bfe8"/>
+    </linearGradient>
+    <linearGradient id="amber" x1="326" y1="180" x2="440" y2="316" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#ffd37a"/>
+      <stop offset="1" stop-color="#ff9f1c"/>
+    </linearGradient>
+    <filter id="softShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="14" stdDeviation="14" flood-color="#000000" flood-opacity="0.28"/>
+    </filter>
+  </defs>
+  <circle cx="256" cy="256" r="220" fill="url(#bg)"/>
+  <circle cx="256" cy="256" r="219" fill="none" stroke="#1fc7e9" stroke-opacity="0.32" stroke-width="3"/>
+  <g fill="none" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M142 168 C184 126 235 119 256 181" stroke="#59e6ff" stroke-width="15" opacity="0.9"/>
+    <path d="M142 256 C188 240 219 240 256 256" stroke="#59e6ff" stroke-width="15" opacity="0.9"/>
+    <path d="M142 344 C184 386 235 393 256 331" stroke="#59e6ff" stroke-width="15" opacity="0.9"/>
+    <path d="M274 183 C320 187 354 210 376 246" stroke="#f8b84e" stroke-width="15"/>
+    <path d="M274 329 C320 325 354 302 376 266" stroke="#f8b84e" stroke-width="15"/>
+  </g>
+  <g filter="url(#softShadow)">
+    <circle cx="142" cy="168" r="34" fill="#0d2d50" stroke="url(#cyan)" stroke-width="10"/>
+    <circle cx="142" cy="256" r="34" fill="#0d2d50" stroke="url(#cyan)" stroke-width="10"/>
+    <circle cx="142" cy="344" r="34" fill="#0d2d50" stroke="url(#cyan)" stroke-width="10"/>
+    <circle cx="256" cy="256" r="62" fill="#0b2a4b" stroke="url(#cyan)" stroke-width="12"/>
+    <path d="M224 269 q32 28 64 0" fill="none" stroke="#7cf7ff" stroke-width="10" stroke-linecap="round"/>
+    <circle cx="236" cy="244" r="7" fill="#d9fbff"/>
+    <circle cx="276" cy="244" r="7" fill="#d9fbff"/>
+    <circle cx="392" cy="256" r="52" fill="#102b45" stroke="url(#amber)" stroke-width="12"/>
+    <path d="M368 257 l15 16 l34 -38" fill="none" stroke="#fff2ca" stroke-width="14" stroke-linecap="round" stroke-linejoin="round"/>
+  </g>
+  <g opacity="0.72" fill="#83f6ff">
+    <circle cx="110" cy="103" r="5"/>
+    <circle cx="210" cy="74" r="4"/>
+    <circle cx="344" cy="88" r="5"/>
+    <circle cx="424" cy="363" r="4"/>
+    <circle cx="236" cy="438" r="5"/>
+  </g>
+</svg>

package/docs/attestations.json

@@ -0,0 +1,189 @@
+{
+  "schema_version": "pi-background-tasks.docs-attestations.v1",
+  "receipts": [
+    {
+      "authored_body_sha256": "sha256:8b8a883eb261dd221d348724fb43ae13fac19eb52a30f688d55ff80b2039be98",
+      "covers_sources": [
+        "src/core/extension-api.ts"
+      ],
+      "doc_id": "api/eventbus-v1",
+      "notes": "Reviewed EventBus channels, closed schemas, operations, request correlation and rejection, close unsubscribe behavior, terminal ordering, latched publication, retry semantics, and at-least-once deduplication guidance.",
+      "reviewer": "gpt-5.5-final-eventbus-reviewer",
+      "schema_version": "pi-background-tasks.docs-attestation.v1",
+      "source_sha256": {
+        "src/core/extension-api.ts": "sha256:f4132ea103f075d14bf8f3936f1a71e3fc46a53083cd7e8f563f9d45e4d74072"
+      },
+      "verdict": "PASS"
+    },
+    {
+      "authored_body_sha256": "sha256:36942d62aa217dad07813c7900291adbc39b1ac859b18d94f606db0ce2e13a9f",
+      "covers_sources": [
+        "src/core/context/parent-snapshot.ts",
+        "src/core/context/token-budget.ts",
+        "src/core/context/visible-conversation-v2.ts"
+      ],
+      "doc_id": "concepts/context-projection-and-budgeting",
+      "notes": "Reviewed visible conversation transform identity, active-branch snapshotting, omission receipts and hashes, text/tool/thinking/image dispositions, token estimators, calibration, reserves, warnings, and fail-loud no-truncation behavior.",
+      "reviewer": "gpt-5.5-final-context-projection-reviewer",
+      "schema_version": "pi-background-tasks.docs-attestation.v1",
+      "source_sha256": {
+        "src/core/context/parent-snapshot.ts": "sha256:94c68a3c971f97ab7f23315db07b67a98f9c3bb1d0b75c07ec9fdd7f2f00d343",
+        "src/core/context/token-budget.ts": "sha256:24ac96fe436263859222668da1537e645c649f37979942d3d856fedf6d54f008",
+        "src/core/context/visible-conversation-v2.ts": "sha256:f12cd1e59339db768c8dd5c9ff241e06ece2ce96896811d828e2700a7d6e69c0"
+      },
+      "verdict": "PASS"
+    },
+    {
+      "authored_body_sha256": "sha256:4d3d0ba1534c8ea5368e201fbf8fc7d52f2fbb353262d4af1ead263548547356",
+      "covers_sources": [
+        "src/core/attested-pi-run.ts"
+      ],
+      "doc_id": "subsystems/attested-pi-runs",
+      "notes": "Reviewed attested Pi event parsing, last-reported stopReason semantics, OAuth route observation, argv/environment safeguards, git authority, hashes, failure handling, and atomic sidecar durability.",
+      "reviewer": "gpt-5.5-final-attested-safety-reviewer",
+      "schema_version": "pi-background-tasks.docs-attestation.v1",
+      "source_sha256": {
+        "src/core/attested-pi-run.ts": "sha256:cf57b3245c506a9051a3886dc58c8e7b117e27532fb758fe85047bf7f4d82980"
+      },
+      "verdict": "PASS"
+    },
+    {
+      "authored_body_sha256": "sha256:66b00ffbb82fdbfb860a689b83d8766cb6753156d6d43817f4ccfed581de977e",
+      "covers_sources": [
+        "src/core/common.ts",
+        "src/core/registry.ts",
+        "src/core/windows-taskkill.ts"
+      ],
+      "doc_id": "subsystems/background-task-runtime",
+      "notes": "Independent GPT-5.5 panel reviewed runtime statuses, files, shell, limits, telemetry, kill and shutdown behavior; final correction review verified close-without-fsync and response-gated EventBus emission versus notification ordering.",
+      "reviewer": "gpt-5.5-final-background-runtime-review-panel",
+      "schema_version": "pi-background-tasks.docs-attestation.v1",
+      "source_sha256": {
+        "src/core/common.ts": "sha256:748d5714ba0b7a4b307d9b4f2b068aa5c11451a465bb4085266f193070d6d809",
+        "src/core/registry.ts": "sha256:b78383bad62aa1cf0fb526d917fb77a080fe6ff5ebc47f59567fffb59e18bec0",
+        "src/core/windows-taskkill.ts": "sha256:d8e21e077720f408a5b181b200924363ad75fd7b3acbafeabb6a2662a9d1fad1"
+      },
+      "verdict": "PASS"
+    },
+    {
+      "authored_body_sha256": "sha256:d5a27cd6a1f78820fe6a39996f8c64c5924efaf2dba99ea44415c1e770dc45bb",
+      "covers_sources": [
+        "src/core/durable-fs.ts",
+        "src/core/pi-launch.ts"
+      ],
+      "doc_id": "subsystems/child-launch-durability-and-safety",
+      "notes": "Reviewed durable file replacement and child launch sources, including file fsync, POSIX directory sync, Windows limitation, ordinary versus attested output wording, and loud launch/durability failures.",
+      "reviewer": "gpt-5.5-final-attested-safety-reviewer",
+      "schema_version": "pi-background-tasks.docs-attestation.v1",
+      "source_sha256": {
+        "src/core/durable-fs.ts": "sha256:be112873d9e405d38883fc8531db368675e056aacea90cf74d6283c9b0443768",
+        "src/core/pi-launch.ts": "sha256:858ed1398d3f033c3c8fd5c454ff44414e3677ee5ecfdf9f2a3cb720374fd06d"
+      },
+      "verdict": "PASS"
+    },
+    {
+      "authored_body_sha256": "sha256:a60f4f25e266ea5cf9e5c89b1b6fbf7bf7fc07d2600a6b82bc5bd9d39eb60438",
+      "covers_sources": [
+        "extensions/delegate-child.ts",
+        "src/core/delegate/artifacts.ts",
+        "src/core/delegate/budget.ts",
+        "src/core/delegate/hook-contract-evidence.json",
+        "src/core/delegate/hook-contract.ts",
+        "src/core/delegate/launch.ts",
+        "src/core/delegate/result-package.ts",
+        "src/core/delegate/runner.ts",
+        "src/core/delegate/seed.ts",
+        "src/core/delegate/types.ts",
+        "src/delegate-child-extension.ts",
+        "src/delegate-extension.ts"
+      ],
+      "doc_id": "subsystems/delegation",
+      "notes": "Independent GPT-5.5 panel reviewed all delegation behavior; final delta reviewer verified the 1200-second default, positive override handling, generated schema description, tests, and authored timeout documentation.",
+      "reviewer": "gpt-5.5-final-delegation-review-panel-plus-timeout-delta",
+      "schema_version": "pi-background-tasks.docs-attestation.v1",
+      "source_sha256": {
+        "extensions/delegate-child.ts": "sha256:b19cce44e888696c046481b133b769d9427e7ef48e9d2cccb8b5abf058f21b9f",
+        "src/core/delegate/artifacts.ts": "sha256:a1555c3e3f0d7d0ba7ffa7e4d882eb61b4350293597ed479e5c4786969f1be4d",
+        "src/core/delegate/budget.ts": "sha256:dbb4921ce41e13c44512eed5458670ab35259040c128ec5f86001c35ed9e32d0",
+        "src/core/delegate/hook-contract-evidence.json": "sha256:e662e8fff72c69fe95c5c48df2be4abab93f720e149c28420423687803b99080",
+        "src/core/delegate/hook-contract.ts": "sha256:d640d0624c69d16993a2ff9bc6b985d53b54b79a4da74d79cfee57dcf5636de1",
+        "src/core/delegate/launch.ts": "sha256:bc79dc4ee159b4364df10d4ef2211d16fee8eed2f88152ef8c5870201fc68308",
+        "src/core/delegate/result-package.ts": "sha256:690013b4db06dda53b358bc3aebb0ac76e9a0dca9f1b69639d2758c42bb07731",
+        "src/core/delegate/runner.ts": "sha256:4c6703f2c79858f9ec36e3960e8c981d2c1b35e1e156079dcdb62f9f0448da2a",
+        "src/core/delegate/seed.ts": "sha256:624d2c5193d3f4988f3f50f601702123a44956cf6d6205a04f528b4cc2f07881",
+        "src/core/delegate/types.ts": "sha256:303d5fc40a526a8fc75f9dee510599e2a3221fe7b9e798410a00cf271ed0d1c5",
+        "src/delegate-child-extension.ts": "sha256:7ada043ffcbe895a66192055ec2a7678c12e70b45bf8c654bcfe491d1f9300e8",
+        "src/delegate-extension.ts": "sha256:2a0b00e0d6631282d9f71a749a8bc9343c47f602edccd4e5f891affd01d71c2b"
+      },
+      "verdict": "PASS"
+    },
+    {
+      "authored_body_sha256": "sha256:6b1afc2083d3f21c704d5af62c6b2259217169002daedb5aa604b8631d4d2fd8",
+      "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/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/pi-child.ts",
+        "src/core/fusion/prompts.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"
+      ],
+      "doc_id": "subsystems/fusion",
+      "notes": "Fusion investigate established agent_settled as the terminal audit boundary and required strict parser behavior; final implementation uses exclusive durable journal/seal I/O, rejects extension diagnostics, and focused lifecycle/incident/compatibility tests pass.",
+      "reviewer": "fusion-investigate-agent-settled-panel-plus-regression-evidence",
+      "schema_version": "pi-background-tasks.docs-attestation.v1",
+      "source_sha256": {
+        "extensions/fusion-child.ts": "sha256:832937c8431d25f73215951d0446f5fa9e4394f0b03b8a9423fb19561eeba31a",
+        "src/core/fusion/artifacts.ts": "sha256:7f93070d3d9db18b69b87fef32a71d23f4d532aeff89bbbc61bef52f65722dc9",
+        "src/core/fusion/budget.ts": "sha256:19f8c4dba9f64d612b3dc33ae06a1c870dae918a7c783dc8f9a6ff3dbcd8e6c0",
+        "src/core/fusion/child-protocol.ts": "sha256:9f1f6defeb2045748e9e18a287bfc5e2c57cc6203abfa2697df4459e83f77d2f",
+        "src/core/fusion/clean-context.ts": "sha256:98230be181964c8309c27e58182bb172f9f30f0fdf76d70868daa5d4e9138ce2",
+        "src/core/fusion/config.ts": "sha256:6f792fb1329cca2c0b33d0bdd82eb6a77a14a8be6ed18b3e9c0573bda52b3000",
+        "src/core/fusion/context.ts": "sha256:fefec409354e14acce8e401f7bcb70265eb0c1f4562fa3321508074e7ad1d96a",
+        "src/core/fusion/evaluation.ts": "sha256:5ced311dbd03b177701c8acfb1782f48033d3c1d800d9f58fd4dbbfe7dc1fed3",
+        "src/core/fusion/orchestrator.ts": "sha256:f0d8437d2c649f70b35ff550fee3b4a18a4e4501c8ee0bd2fd3c1f6984de88c2",
+        "src/core/fusion/pi-child.ts": "sha256:bfc4981a9bedca50ff92ac7aaec7dfa93036bbdca2caf0261f4263b489868415",
+        "src/core/fusion/prompts.ts": "sha256:0462a496fcf682c6e4cef87bafb1fd6d45f23e367ef83c2c8418126d4a1ee766",
+        "src/core/fusion/source-policy.ts": "sha256:17718fe6c55bfacaaed0beebd6c8f4fbf477ec0f8210ae1ba038167231cc5f4d",
+        "src/core/fusion/types.ts": "sha256:01a57512044c034aecd9dd304cedcc40fae737d87a3a93cae1027eb8b31a875d",
+        "src/core/fusion/web-fetch.ts": "sha256:5aca8d9c8e7bb58f483cc17f60163e431e09e91dc80c299b1e0280a3b96e42aa",
+        "src/core/fusion/workflows.ts": "sha256:1960784b7f9fd8cb62bf48c0a04261359e19b59a18146d32583b619db17f7394",
+        "src/fusion-child-extension.ts": "sha256:5ce9cbe5de1a69d791dc8a8a40c05f3ac6ffca607677e150408bf9e385f9aabb",
+        "src/fusion-extension.ts": "sha256:ecaf4f6619652029333c626a73e86d25174715864ad0a79a8558700f3eb224e0",
+        "src/ui/fusion-model-selector.ts": "sha256:c6c080c7063d1fbf157c720d60dd0b634ef8e5767e004c632c011a7e543e9a34"
+      },
+      "verdict": "PASS"
+    },
+    {
+      "authored_body_sha256": "sha256:185e4ec320770ededfce51e1e8a5a166be8b4b11275b7515737f0305820555fe",
+      "covers_sources": [
+        "extensions/background-tasks.ts",
+        "src/core/update-check.ts",
+        "src/extension.ts",
+        "src/ui/background-tasks-manager.ts"
+      ],
+      "doc_id": "subsystems/host-ui-and-telemetry",
+      "notes": "Existing independent GPT-5.5 panel reviewed the host subsystem; operator delta review verified /bg-update no longer derives git tags from npm versions and SDK assertions pin main plus explicit tag verification.",
+      "reviewer": "existing-gpt-5.5-host-panel-plus-operator-update-delta",
+      "schema_version": "pi-background-tasks.docs-attestation.v1",
+      "source_sha256": {
+        "extensions/background-tasks.ts": "sha256:b221129d3a1449606de6e7c04bd8989c6b7feee3eaf5122339c2d45cffadf74f",
+        "src/core/update-check.ts": "sha256:7f754a43288c8c7dae1518f4a8c3fa7f1b5499864c5c54ae279188661aa0412d",
+        "src/extension.ts": "sha256:65b8d2a23555a244eb1ed1ef5ad5ab3aa1d70eb59e3f4f4d69efdfb553e34218",
+        "src/ui/background-tasks-manager.ts": "sha256:96c71807767499887ab3417e5eabac973a19221e4f2e985e2218d4ad672dd687"
+      },
+      "verdict": "PASS"
+    }
+  ]
+}

package/docs/choose-a-workflow.md

@@ -0,0 +1,98 @@
+---
+doc_id: choose-a-workflow
+audience: user
+mode: authored
+review_policy: contract
+stability: stable
+covers_surfaces: []
+covers_sources: []
+---
+# Choose a workflow
+
+## Quick decision tree
+
+1. **Is the work short and interactive?** Use ordinary foreground Pi work.
+2. **Is it a long shell command?** Use `/bg` if you are typing it; use `bg_run` if the agent is launching it.
+3. **Does a second agent need this conversation as context while the parent continues?** Use `bg_delegate`, then `bg_result` after completion.
+4. **Do you need local evidence from one direct Pi child run?** Use `bg_run_pi_attested`.
+5. **Do you want multiple model perspectives on one fixed-purpose prompt?** Use the matching Fusion tool.
+
+## Comparison table
+
+| Option | Sync/async | Context sent | Can read repo? | Can use network? | Can write? | Route behavior | Use when |
+|---|---|---|---:|---:|---:|---|---|
+| Foreground work | Synchronous | Current session | Depends on active tools | Depends on active tools | Depends on active tools | Current session route | You need live interaction. |
+| `/bg` | Async | None by package | Command decides | Command decides | Command decides | Not a model route unless command invokes one | You manually start a long local command. |
+| `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. |
+
+## Tradeoffs and boundaries
+
+### Foreground vs background shell
+
+Foreground commands are best when the next answer depends on immediate output. Background commands are best when the command may take long enough that Pi can do other useful work or yield until completion.
+
+`/bg` and `bg_run` are not sandboxes. They spawn local shell commands with the permissions, environment, network access, and credentials available to the Pi process. A background command can itself call paid services.
+
+### `bg_run` defaults
+
+`bg_run` requires:
+
+```json
+{"name":"Short label","command":"shell command","isAgent":false}
+```
+
+Defaults are `notifyOnCompletion:true` and `triggerOnCompletion:true`. With those defaults, Pi should not poll `bg_status` or `bg_logs` merely to wait.
+
+### Delegate boundaries
+
+`bg_delegate` supports only `capability:"inspect"`. The child is seeded with a deterministic visible-conversation projection, but omitted parent tool payloads are not available. Restate any needed facts in the delegate prompt.
+
+Use `bg_result` for retrieval. It verifies hashes before returning content and reports oversized answers as artifacts instead of silently truncating.
+
+### Fusion boundaries
+
+Fusion is a fixed workflow, not a free-form mode switch:
+
+1. Three candidate child Pi runs.
+2. One blind evaluator.
+3. One bounded conditional evaluator repair only if the evaluator JSON is invalid.
+4. One merger.
+
+`fusion_research` performs targeted retrieval of caller-supplied public URLs. It does not search the web, browse arbitrary links, fetch private URLs, or treat fetched content as instructions.
+
+## Examples
+
+### Long command
+
+```json
+{"name":"Build watch","command":"npm run build -- --watch","isAgent":false,"timeoutSeconds":7200}
+```
+
+### Delegate investigation
+
+```json
+{
+  "name": "Docs locator",
+  "prompt": "Find the docs that explain shell selection and update checks. Return exact file paths and a concise summary.",
+  "capability": "inspect"
+}
+```
+
+### Fusion validation
+
+```json
+{
+  "objective": "Review docs readiness",
+  "background": ["Only package-local Markdown and image assets changed."],
+  "changeSummary": "README became a landing page; detailed setup moved into docs.",
+  "scope": ["README.md", "docs"],
+  "acceptanceCriteria": ["Links resolve", "Examples match schemas", "Safety caveats are explicit"],
+  "verification": {"status":"not_run", "reason":"Manual review requested before checks."}
+}
+```