pi-background-tasks 0.7.7 → 1.0.3

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:0bcc2c31c037782d1585b2d6ca317924cd4d20bacd217145cb15d9b8a3ac54b7",
+      "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": "Independent GPT-5.5 panel reviewed all Fusion behavior; final delta reviewer verified the 20-minute idle watchdog, unchanged 30-minute absolute timeout, activity reset, child_timeout termination, tests, and source-constant documentation.",
+      "reviewer": "gpt-5.5-final-fusion-review-panel-plus-timeout-delta",
+      "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:52dffbb8b047843e382bd2e534bbdb685b49c3c0607d118b693047b0cd22fec2",
+        "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:ba69cb6853ab51d21908f43bdbfd99345d929bfd14371f3efcbe2ef5a474f7a0",
+        "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."}
+}
+```

package/docs/commands/bg-clear.md

@@ -0,0 +1,70 @@
+---
+doc_id: commands/bg-clear
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:bg-clear]
+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:548` |
+<!-- pi-docs:end name="command-contract-bg-clear" -->
+
+Clear finished background task footer notices.
+
+## Synopsis
+
+
+`/bg-clear`
+
+## When to use
+
+Use this after you have seen completed, failed, or killed task badges in the footer and want to remove those finished counts from the dock status.
+
+## Defaults
+
+No arguments. It only marks currently unseen finished tasks as seen.
+
+## Lifecycle
+
+A finished task's footer badge is marked seen when its detail view opens. `/bg-clear` or the equivalent shortcut marks every currently unseen finished task seen at once. Merely opening the list view or closing the task manager does not clear badges. Running task counts remain visible after clearing finished notices.
+
+## Examples
+
+```text
+/bg-clear
+```
+
+## Output/result
+
+Interactive notification:
+
+- `Cleared N finished background task notice(s).` when at least one unseen finished task was marked seen.
+- `No finished background task notices to clear.` when none were pending.
+
+## Errors
+
+No task-resolution errors; the command operates on the in-memory task registry.
+
+## Runtime artifacts
+
+No task files are deleted. Output and metadata under `.pi/tasks/...` remain intact.
+
+## Safety boundaries
+
+`/bg-clear` does not kill, prune, or modify tasks. It only updates the host UI's seen set for this extension runtime.
+
+## Related docs
+
+- [Shortcuts and dock](../reference/shortcuts-and-dock.md)
+- [`/tasks` and `/bg-tasks`](task-manager.md)
+- [Host UI and telemetry](../subsystems/host-ui-and-telemetry.md)
+
+## Source ownership/reference
+
+Surface registration lives in `src/extension.ts`; footer behavior is owned by [host-ui-and-telemetry](../subsystems/host-ui-and-telemetry.md).

package/docs/commands/bg-update.md

@@ -0,0 +1,82 @@
+---
+doc_id: commands/bg-update
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:bg-update]
+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:556` |
+<!-- pi-docs:end name="command-contract-bg-update" -->
+
+Show update instructions for `pi-background-tasks`.
+
+## Synopsis
+
+
+`/bg-update`
+
+## When to use
+
+Use this when the footer shows an update segment such as `⬆ v999.0.0 /bg-update`, or whenever you want the package's install/update commands printed without performing an install.
+
+## Defaults
+
+No arguments. The command reads the installed package name/version and any latest version found by the session update check.
+
+## Lifecycle
+
+The update check is one-shot per extension runtime, started after `session_start`, and is not awaited on the session-start path. It is skipped when:
+
+- `PI_BG_DISABLE_UPDATE_CHECK=1`,
+- `PI_OFFLINE=1`, or
+- the installed package version is unavailable.
+
+The registry request is time-boxed by `fetchLatestVersion` and failures resolve to no update segment. `/bg-update` itself only prints instructions; it never installs, self-updates, or mutates package files.
+
+## Examples
+
+```text
+/bg-update
+```
+
+## Output/result
+
+The notification includes current installed version and, when known, latest published version, then prints:
+
+```text
+pi install npm:pi-background-tasks@latest
+pi install npm:pi-background-tasks@<version>
+pi install git:github.com/ismailsaleekh/pi-background-tasks@main
+For a pinned git release, first verify the tag exists, then use git:github.com/ismailsaleekh/pi-background-tasks@<existing-tag>.
+This command only prints update instructions; it does not install or self-update.
+```
+
+If no latest npm version is known, `<version>` is printed for the pinned npm command. The command never derives a git tag from the npm version: npm releases and repository tags are independent, and a pinned git tag must be verified separately.
+
+## Errors
+
+The command has no task-resolution errors. Update-check network, timeout, bad status, and malformed payload failures are offline-safe and do not throw into the UI.
+
+## Runtime artifacts
+
+No task artifacts. The footer segment is UI state only.
+
+## Safety boundaries
+
+Instruction-only. It does not run `pi install`, `npm`, `git`, or any package manager.
+
+## Related docs
+
+- [Shortcuts and dock](../reference/shortcuts-and-dock.md)
+- [Host UI and telemetry](../subsystems/host-ui-and-telemetry.md)
+
+## Source ownership/reference
+
+Surface registration lives in `src/extension.ts`; update lookup is implemented in `src/core/update-check.ts` and owned by [host-ui-and-telemetry](../subsystems/host-ui-and-telemetry.md).