pi-background-tasks 1.0.3 → 1.0.4

package/README.md

@@ -26,7 +26,7 @@
 | Fact | Value |
 | --- | --- |
 | Package | `pi-background-tasks` |
-| Version | `1.0.3` |
+| Version | `1.0.4` |
 | Node engine | `>=22.19.0` |
 | Pi entrypoint | `./extensions/background-tasks.ts` |
 | Package image | [logo.png](https://raw.githubusercontent.com/ismailsaleekh/pi-background-tasks/main/logo.png) |

package/TESTING.md

@@ -87,7 +87,7 @@ Current smoke is `tsx scripts/smoke.ts`. It creates a temporary Pi agent/session
 
 - the pre-fix full-transcript canonical input and the fact that it is rejected against the panel's smallest route;
 - the post-fix projected canonical input with full omission accounting and a byte-identical rebuild check;
-- the measured candidate, evaluator, evaluation-repair, and merger prompt sizes against the allowed input budget, using the largest real candidate answer (45,434 B) and evaluator output (54,829 B) observed in `.pi/fusion`.
+- the measured candidate, evaluator, evaluation-repair, and merger prompt sizes against the allowed input budget, using the enforced contract maxima: 48 KiB (49,152 B) for each candidate output and 64 KiB (65,536 B) for evaluator output.
 
 It performs no inference and spawns no child, so it is safe to run offline and costs nothing. It exits non-zero if any stage would exceed the budget.
 
@@ -186,7 +186,7 @@ npm run test:rpc
 npm run test:agent-loop
 ```
 
-The Fusion SDK/RPC/scripted-provider tests install a deterministic fake child `pi` in a temp `PATH` from `tests/helpers/fusion-fake-pi.ts`. Parent Pi remains the real SDK/RPC runtime; only direct child `pi --mode text` calls with the package-owned private compact metadata extension are intercepted. `PI_CODING_AGENT_DIR` is pointed at the temp agent directory so `fusion-models.json` is never read from the user's real global Pi directory. Fusion v1 public-surface coverage asserts exactly four tools (`fusion_reason`, `fusion_investigate`, `fusion_research`, `fusion_validate`), no public capability argument, retired-tool active-tool removal, `/fusion` mapping to reason/no-tool candidates, closed schemas with Google-compatible enum status, targeted URL fetch not search, URL exfiltration warnings, strict validation verification rules, historical v4 rendering without old-tool activation, and actionable migration errors for `fusion_validate({prompt})`. Fusion context coverage covers both reason conversation projection and clean-task non-interference invariants, including parent-sentinel absence from every clean downstream prompt/artifact and byte-identical clean inputs across unrelated parent sessions. `tests/unit/fusion-context-prompts.test.ts` verifies that a synthetic session carrying more than 1 MB of tool arguments/results still yields a small canonical input, that user and assistant text survive verbatim, that thinking and tool payloads never appear (including no head/tail/preview sentinel), that omission counts, byte totals, and hashes are exact and stable, that repeated construction is byte-identical, that the active Fusion tool leaf and sibling calls stay scope-excluded, that images remain marker-only or ledger-only with no raw base64 in child prompts, and that every retained source block receives exactly one disposition. `tests/unit/fusion-high-cardinality.test.ts` covers the receipt-cardinality regression: a session of many short interleaved tool events (rather than a few enormous results) pins per-receipt cost, proves the compact `omitted_activity` fields are the only model-facing ones, reconciles every receipt against the ledger through `projection_map`, and proves the whole workflow fits a real route budget. `tests/unit/fusion-budget.test.ts` covers stage budgets: the limiting model is the smallest configured route (including when it is the evaluator rather than a candidate), unknown or too-small capacities fail before spawn, boundary prompts pass at exactly the limit and fail one byte past it, the child system prompt counts as input, dense multi-byte UTF-8 cannot bypass byte accounting, and candidate, evaluator, evaluation-repair, and merger expansions are each rejected before their child is spawned with zero partial launches. `tests/package/typebox-compat.test.ts` pins the TypeBox posture and compiles nullable-array schemas. The release-only `npm run test:compat` packs the package, installs exact supported Pi versions, runs `/jobs`, runs `/fusion` through the installed package entrypoint with the fake child Pi, verifies five child invocations, verifies `/fusion-models` rejects non-TUI mode, asserts the resolved `typebox` is Pi's bundled peer rather than a private or nested copy, and scans the installed package bytes for TypeBox APIs removed in the 1.3.x line. It then drives the current host Pi through a real RPC `fusion_reason` parent-agent loop, checks the persisted tool result carries the complete Pi `Usage.cost` object, invokes `get_session_stats` (the same aggregation boundary used by the TUI footer), reopens the durable session, and verifies identical token/cost totals. All parent and child inference remains deterministic and local.
+The Fusion SDK/RPC/scripted-provider tests install a deterministic fake child `pi` in a temp `PATH` from `tests/helpers/fusion-fake-pi.ts`. Parent Pi remains the real SDK/RPC runtime; only direct child `pi --mode text` calls with the package-owned private compact metadata extension are intercepted. `PI_CODING_AGENT_DIR` is pointed at the temp agent directory so `fusion-models.json` is never read from the user's real global Pi directory. Fusion v1 public-surface coverage asserts exactly four tools (`fusion_reason`, `fusion_investigate`, `fusion_research`, `fusion_validate`), no public capability argument, retired-tool active-tool removal, `/fusion` mapping to reason/no-tool candidates, closed schemas with Google-compatible enum status, targeted URL fetch not search, URL exfiltration warnings, strict validation verification rules, historical v4 rendering without old-tool activation, and actionable migration errors for `fusion_validate({prompt})`. Fusion context coverage covers both reason conversation projection and clean-task non-interference invariants, including parent-sentinel absence from every clean downstream prompt/artifact and byte-identical clean inputs across unrelated parent sessions. `tests/unit/fusion-context-prompts.test.ts` verifies that a synthetic session carrying more than 1 MB of tool arguments/results still yields a small canonical input, that user and assistant text survive verbatim, that thinking and tool payloads never appear (including no head/tail/preview sentinel), that omission counts, byte totals, and hashes are exact and stable, that repeated construction is byte-identical, that the active Fusion tool leaf and sibling calls stay scope-excluded, that images remain marker-only or ledger-only with no raw base64 in child prompts, and that every retained source block receives exactly one disposition. `tests/unit/fusion-high-cardinality.test.ts` covers the receipt-cardinality regression: a session of many short interleaved tool events (rather than a few enormous results) pins per-receipt cost, proves the compact `omitted_activity` fields are the only model-facing ones, reconciles every receipt against the ledger through `projection_map`, and proves the whole workflow fits a real route budget. `tests/unit/fusion-budget.test.ts` covers stage budgets: the limiting model is the smallest configured route (including when it is the evaluator rather than a candidate), unknown or too-small capacities fail before spawn, boundary prompts pass at exactly the limit and fail one byte past it, the child system prompt counts as input, dense multi-byte UTF-8 cannot bypass byte accounting, and candidate, evaluator, evaluation-repair, and merger expansions are each rejected before their child is spawned with zero partial launches. `tests/package/typebox-compat.test.ts` pins the TypeBox posture and compiles nullable-array schemas. The release-only `npm run test:compat` packs the package, installs exact supported Pi versions, runs `/jobs`, runs `/fusion` through the installed package entrypoint with the fake child Pi, verifies five child invocations, verifies `/fusion-models` rejects non-TUI mode, requires each supported Pi line to declare terminal `agent_settled`, asserts the resolved `typebox` is Pi's bundled peer rather than a private or nested copy, and scans the installed package bytes for TypeBox APIs removed in the 1.3.x line. Pi 0.75.5 is intentionally unsupported because it lacks the terminal event required to seal a Fusion audit after retries and compaction. It then drives the current host Pi through a real RPC `fusion_reason` parent-agent loop, checks the persisted tool result carries the complete Pi `Usage.cost` object, invokes `get_session_stats` (the same aggregation boundary used by the TUI footer), reopens the durable session, and verifies identical token/cost totals. All parent and child inference remains deterministic and local.
 
 ## Coverage summary
 

package/TEST_PLAN.md

@@ -40,7 +40,7 @@ The table below remains the exhaustive acceptance source. Do not replace it with
 | Smoke | `npm run smoke` | no | implemented; isolated load-only |
 | Large-context smoke | `npm run smoke:large-context` | release gate | implemented; rebuilds the production failure byte composition, proves the pre-fix input is rejected and the post-fix projection fits all four stages against the smallest configured route, with no inference and no child spawn |
 | Live subscription evidence | `npx tsx scripts/delegate-live-run.ts` | release gate | implemented; one real subscription-OAuth child on the parent's current route, large seeded session, hash-verified answer, and explicit leak checks. Caught two defects no offline gate did (undelivered prompt, seed-not-prompt budgeting), both now pinned by unit and mutation tests |
-| Compatibility | `npm run test:compat` | release gate | implemented; exact Pi `0.75.5`, `0.81.1`, `0.82.1`, `0.83.0` pack/install plus `/jobs`, `/fusion`, and `/fusion-models` surfaces, per-version bundled-TypeBox peer verification, removed-TypeBox-API scan of installed package bytes, followed by a current-host real `fusion_reason` session-stat and replay witness |
+| Compatibility | `npm run test:compat` | release gate | implemented; exact Pi `0.81.1`, `0.82.1`, `0.83.0` pack/install plus `/jobs`, `/fusion`, and `/fusion-models` surfaces, per-version `agent_settled` event declaration and bundled-TypeBox peer verification, removed-TypeBox-API scan of installed package bytes, followed by a current-host real `fusion_reason` session-stat and replay witness |
 | Docs verification | `npm run docs:verify` | prepack/release gate | implemented; offline docs freshness, generated region/index/manifest/link/reachability/coverage/attestation checks |
 | Docs tests | `npm run test:docs` | targeted docs gate | implemented; docs-gate unit/package tests |
 | Payload policy | `npm run payload:check` | prepack/release gate | implemented; package payload/docs/assets exclusions and inclusions |
@@ -84,7 +84,7 @@ SDK/RPC/scripted-provider/package/compatibility coverage asserts exactly four to
 | Fusion research web fetch | `fusion_web_fetch({ url, extract? })`, `candidate-<slot>.attempt-<n>.tool-calls.jsonl` | yes |  |  |  |  | yes | live child | Unit covers the closed schema surface through the child extension, registration only when research mode is enabled, unsupported schemes and URL credentials failing before network access, blocked DNS classes, a mixed public-plus-blocked DNS answer failing loudly, a redirect to a blocked address failing loudly, redirect-loop limit failure, Content-Length and streamed-body response caps, unsupported content types, Markdown extraction preserving links/headings/tables/code blocks, script/style stripping, text/plain passthrough with hash and byte count, UTF-8-safe output truncation, and typed timeout. Unit also proves the resolver is consulted once and the connection is pinned to that vetted address, undeclared research URLs are rejected before fetch with only the attempted URL hash audited, and that audit metadata records `url`, `final_url`, `http_status`, `response_bytes`, and `content_sha256` without raw page content. Package guards require `fusion_web_fetch` registration behind the research env flag. Live verification fetched `https://example.com/`, reported the page H1, read a repository constant, and refused instruction-like text from both a repo file and the fetched page. |
 | Fusion multi-message transcript validation | `*.events.jsonl`, stop reasons `toolUse`/`stop` | yes |  |  |  |  |  |  | Unit accepts a multi-message tool loop, reconstructs stdout from the final assistant message only, and sums usage across all compact metadata records. Non-final records must be `toolUse`, the final record must be `stop`, and `length`, `error`, `aborted`, and `pending` fail loudly instead of being skipped. |
 | Fusion stale-action watchdog | `FUSION_CHILD_IDLE_TIMEOUT_MS`, child process lifecycle | yes |  |  |  |  |  |  | Unit proves a child with no stdout or stderr activity fails as `child_timeout` with the stalled-child message and is terminated; stderr activity resets the watchdog and allows success; the 30-minute absolute timeout path remains distinct and is not reported as a stalled child. |
-| Fusion candidate tool-call audit log | `candidate-<slot>.attempt-<n>.tool-calls.jsonl`, `*.seal.json`, `pi-background-tasks.fusion-tool-call.v1` | yes |  |  |  |  |  |  | Unit proves completed tool calls are logged with tool name, byte counts, and hashes while raw arguments/results containing a secret never appear; `agent_end` seals exact count, aggregate result bytes, status, and log hash; the parent rejects a missing/failed/mismatched seal and independently rejects aggregate result bytes above 8 MiB. A complete 3-call log summarizes count and result bytes; a trailing partial line, ordinal gap, duplicate ordinal, wrong schema version, and inspect-child partial log all fail loudly. Artifact coverage verifies successful attempts persist the JSONL and manifest summary, while no-log attempts do not invent one. |
+| Fusion candidate tool-call audit log | `candidate-<slot>.attempt-<n>.tool-calls.jsonl`, `*.seal.json`, `pi-background-tasks.fusion-tool-call.v1` | yes |  |  |  |  |  |  | Unit proves completed tool calls are logged with tool name, byte counts, and hashes while raw arguments/results containing a secret never appear. Repeated low-level `agent_end` boundaries publish no seal; terminal `agent_settled` exclusively seals the complete log after all retry/compaction/follow-up work. The 46-call incident regression proves a 22-call prefix is never sealed and duplicate settlement fails without replacement. Shutdown before settlement writes failed evidence and latches process failure. The parent rejects extension diagnostics and missing/failed/mismatched seals and independently rejects aggregate result bytes above 8 MiB. A trailing partial line, ordinal gap, duplicate ordinal, wrong schema version, and inspect-child partial log all fail loudly. |
 | Pi/TypeBox compatibility | `peerDependencies`, packed bytes | yes |  |  |  |  | yes |  | Unit pins typebox as a `"*"` peer that is neither a runtime nor bundled dependency, requires the resolved TypeBox to be Pi 0.83's 1.3.x line, requires all four supported Pi/TUI lines in the peer range, scans all package TypeScript for the seven removed TypeBox APIs, and compiles the shipped tool schema plus nullable-array/nullable-string and optional-field shapes under TypeBox 1.3. The release compat gate repeats the removed-API scan against installed package bytes per Pi version. |
 | Pi hook contract | `npm run test:hook-contract`, `tests/scripted-provider/pi-hook-contract-evidence.json`, `src/core/delegate/hook-contract-evidence.json` |  |  |  |  |  | evidence parity | yes | Executes a real Pi agent loop and records, rather than assumes: `context` fires once before every model call in load order; returned messages reach the provider; **throwing** in `context` does NOT block dispatch (Pi catches and continues); `ctx.abort()` does not skip the call site but delivers an already-aborted signal and terminates the run; `tool_result` fires before the transcript entry, chains in load order, replacement reaches the provider while the original does not, and toolCallId/role/`isError` survive. Handler ordering across two separate probe extensions is pinned. The evidence file is compared, never silently regenerated, and a package test asserts the shipped copy is byte-identical. |
 | Delegate context seeding | `bg_delegate` seed `pi-background-tasks.delegate-seed.v1`, `seed.json`, `context-omission-ledger.json` | yes | yes |  |  |  | mutation guard | yes | Unit covers verbatim visible user/assistant text, complete exclusion of thinking/tool-call arguments/tool-result payloads, marker-only images with no raw bytes anywhere in the seed, exclusion of the in-flight `bg_delegate` call **and every sibling call in the same assistant message** (two delegates launched together get byte-identical projected history), the prompt preserved exactly and marked `explicit_text` authority, zero payload-preview bytes, byte-identical construction across repeated builds and across separate processes via a fixed-leaf fixture, and refusal of a blank prompt. Receive-side verification rejects a single mutated byte, a foreign task identity, a structurally malformed seed whose hash matches, a directive whose hash disagrees with its text, and an unsupported capability. SDK proves the projected parent text actually reaches the child. |

package/docs/attestations.json

@@ -118,7 +118,7 @@
       "verdict": "PASS"
     },
     {
-      "authored_body_sha256": "sha256:0bcc2c31c037782d1585b2d6ca317924cd4d20bacd217145cb15d9b8a3ac54b7",
+      "authored_body_sha256": "sha256:6b1afc2083d3f21c704d5af62c6b2259217169002daedb5aa604b8631d4d2fd8",
       "covers_sources": [
         "extensions/fusion-child.ts",
         "src/core/fusion/artifacts.ts",
@@ -140,8 +140,8 @@
         "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",
+      "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",
@@ -153,13 +153,13 @@
         "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/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:ba69cb6853ab51d21908f43bdbfd99345d929bfd14371f3efcbe2ef5a474f7a0",
+        "src/fusion-child-extension.ts": "sha256:5ce9cbe5de1a69d791dc8a8a40c05f3ac6ffca607677e150408bf9e385f9aabb",
         "src/fusion-extension.ts": "sha256:ecaf4f6619652029333c626a73e86d25174715864ad0a79a8558700f3eb224e0",
         "src/ui/fusion-model-selector.ts": "sha256:c6c080c7063d1fbf157c720d60dd0b634ef8e5767e004c632c011a7e543e9a34"
       },

package/docs/manifest.json

@@ -89,7 +89,7 @@
       "state": "pass"
     },
     {
-      "authored_body_sha256": "sha256:0bcc2c31c037782d1585b2d6ca317924cd4d20bacd217145cb15d9b8a3ac54b7",
+      "authored_body_sha256": "sha256:6b1afc2083d3f21c704d5af62c6b2259217169002daedb5aa604b8631d4d2fd8",
       "covers_sources": [
         "extensions/fusion-child.ts",
         "src/core/fusion/artifacts.ts",
@@ -111,10 +111,10 @@
         "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.",
+      "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.",
       "rel": "docs/subsystems/fusion.md",
       "required": true,
-      "reviewer": "gpt-5.5-final-fusion-review-panel-plus-timeout-delta",
+      "reviewer": "fusion-investigate-agent-settled-panel-plus-regression-evidence",
       "state": "pass"
     },
     {
@@ -787,7 +787,7 @@
     "image": "https://raw.githubusercontent.com/ismailsaleekh/pi-background-tasks/main/logo.png",
     "name": "pi-background-tasks",
     "type": "module",
-    "version": "1.0.3"
+    "version": "1.0.4"
   },
   "public_surface_ids": [
     "command:bg",

package/docs/reference/runtime-contracts.md

@@ -16,27 +16,27 @@ This generated registry lists production environment-variable references, runtim
 
 | Name | Access | Provenance |
 | --- | --- | --- |
-| `ANTHROPIC_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:69` |
-| `ANTHROPIC_AUTH_TOKEN` | remove | `src/core/fusion/pi-child.ts:69` |
-| `ANTHROPIC_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:69` |
-| `AZURE_OPENAI_AD_TOKEN` | remove | `src/core/fusion/pi-child.ts:69` |
-| `AZURE_OPENAI_API_KEY` | remove | `src/core/fusion/pi-child.ts:69` |
-| `AZURE_OPENAI_API_VERSION` | remove | `src/core/fusion/pi-child.ts:69` |
-| `AZURE_OPENAI_BASE_URL` | remove | `src/core/fusion/pi-child.ts:69` |
-| `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` | remove | `src/core/fusion/pi-child.ts:69` |
-| `AZURE_OPENAI_ENDPOINT` | remove | `src/core/fusion/pi-child.ts:69` |
-| `AZURE_OPENAI_RESOURCE_NAME` | remove | `src/core/fusion/pi-child.ts:69` |
+| `ANTHROPIC_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `ANTHROPIC_AUTH_TOKEN` | remove | `src/core/fusion/pi-child.ts:70` |
+| `ANTHROPIC_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_AD_TOKEN` | remove | `src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_API_KEY` | remove | `src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_API_VERSION` | remove | `src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_BASE_URL` | remove | `src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` | remove | `src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_ENDPOINT` | remove | `src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_RESOURCE_NAME` | remove | `src/core/fusion/pi-child.ts:70` |
 | `ComSpec` | read | `src/core/common.ts:683`<br>`src/core/common.ts:692` |
-| `OPENAI_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:69` |
-| `OPENAI_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:69` |
-| `OPENROUTER_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:69` |
-| `OPENROUTER_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:69` |
+| `OPENAI_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `OPENAI_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `OPENROUTER_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `OPENROUTER_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
 | `path` | read | `src/core/common.ts:638` |
 | `Path` | read | `src/core/common.ts:638` |
 | `PATH` | read | `src/core/common.ts:638` |
-| `PI_API_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:69` |
-| `PI_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:69` |
-| `PI_AUTH_FILE` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:69` |
+| `PI_API_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_AUTH_FILE` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
 | `PI_BG_DELEGATE_ARTIFACT_DIR` | read, write | `src/core/delegate/launch.ts:324`<br>`src/delegate-child-extension.ts:277` |
 | `PI_BG_DELEGATE_LAUNCH_NONCE` | read, write | `src/core/delegate/launch.ts:328`<br>`src/delegate-child-extension.ts:281` |
 | `PI_BG_DELEGATE_SEED_PATH` | read, write | `src/core/delegate/launch.ts:325`<br>`src/delegate-child-extension.ts:278` |
@@ -48,17 +48,17 @@ This generated registry lists production environment-variable references, runtim
 | `PI_BG_REGISTRY_URL` | read | `src/extension.ts:453` |
 | `PI_BG_SHELL` | read | `src/core/common.ts:679` |
 | `PI_BG_SHELL_PATH` | read | `src/core/common.ts:680` |
-| `PI_FUSION_RESEARCH_ENABLED` | read, remove, write | `src/core/fusion/pi-child.ts:1256`<br>`src/core/fusion/pi-child.ts:69`<br>`src/fusion-child-extension.ts:277` |
-| `PI_FUSION_SOURCE_POLICY_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1257`<br>`src/core/fusion/pi-child.ts:69`<br>`src/fusion-child-extension.ts:237` |
-| `PI_FUSION_SOURCE_POLICY_SHA256` | read, remove, write | `src/core/fusion/pi-child.ts:1258`<br>`src/core/fusion/pi-child.ts:69`<br>`src/fusion-child-extension.ts:238` |
-| `PI_FUSION_TOOL_CALL_LOG_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1251`<br>`src/core/fusion/pi-child.ts:69`<br>`src/fusion-child-extension.ts:276` |
-| `PI_MODEL` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:69` |
+| `PI_FUSION_RESEARCH_ENABLED` | read, remove, write | `src/core/fusion/pi-child.ts:1291`<br>`src/core/fusion/pi-child.ts:70`<br>`src/fusion-child-extension.ts:393` |
+| `PI_FUSION_SOURCE_POLICY_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1292`<br>`src/core/fusion/pi-child.ts:70`<br>`src/fusion-child-extension.ts:349` |
+| `PI_FUSION_SOURCE_POLICY_SHA256` | read, remove, write | `src/core/fusion/pi-child.ts:1293`<br>`src/core/fusion/pi-child.ts:70`<br>`src/fusion-child-extension.ts:350` |
+| `PI_FUSION_TOOL_CALL_LOG_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1280`<br>`src/core/fusion/pi-child.ts:70`<br>`src/fusion-child-extension.ts:392` |
+| `PI_MODEL` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:70` |
 | `PI_OFFLINE` | read | `src/extension.ts:445` |
-| `PI_PROVIDER` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:69` |
-| `PI_REASONING_LEVEL` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:69` |
-| `PI_SESSION_FILE` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:69` |
-| `PI_SESSION_ID` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:69` |
-| `PI_SKIP_VERSION_CHECK` | write | `src/core/delegate/launch.ts:323`<br>`src/core/fusion/pi-child.ts:233` |
+| `PI_PROVIDER` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_REASONING_LEVEL` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_SESSION_FILE` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_SESSION_ID` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_SKIP_VERSION_CHECK` | write | `src/core/delegate/launch.ts:323`<br>`src/core/fusion/pi-child.ts:234` |
 | `SHELL` | read | `src/core/common.ts:675` |
 | `SystemRoot` | read | `src/core/windows-taskkill.ts:96` |
 | `WINDIR` | read | `src/core/windows-taskkill.ts:101` |

package/docs/subsystems/docs-freshness-gate.md

@@ -9,10 +9,10 @@ covers_sources: []
 ---
 # Docs freshness gate
 
-This authored section defines the boundary: documentation facts are extracted from package metadata and TypeScript ASTs, then generated into docs and the manifest. Unsupported syntax fails the gate rather than falling back to regex or stale hand-maintained inventories.
+This authored section defines the boundary: documentation facts are extracted from package metadata and TypeScript ASTs, then generated into docs and the manifest. Unsupported syntax fails the gate rather than falling back to regex or stale hand-maintained inventories. Public registrations must remain unconditional top-level direct calls or use the one validated local tool-wrapper shape; host/method aliases, computed access, nested or conditional registration, wrapper chaining/passing, constructor helpers, ambiguous public metadata, destructured Pi parameters, and repeated imported registrars are rejected.
 
 <!-- pi-docs:begin name="docs-freshness-gate" generator="scripts/docs/generate.mjs" -->
-- Canonical package version: `1.0.3`
+- Canonical package version: `1.0.4`
 - Governed markdown docs: 40
 - Public surfaces extracted: 30
 - Governed production sources: 44

package/docs/subsystems/fusion.md

@@ -105,6 +105,8 @@ Run artifacts are private local evidence under `.pi/fusion/<session-id>-<pid>/<r
 
 Artifact writes use durable private temp-file/fsync/rename. Manifests enforce legal state transitions and record config, resolved models, fixed capabilities, context policy, tool policy, anonymous map, attempts, artifact refs, cumulative usage, and errors. Successful, failed, and cancelled observed attempts preserve complete Pi usage/cost components; public tool results clone the same `Usage` shape.
 
+For tool-enabled children, the private audit journal remains open across every low-level `agent_end`, because Pi may still retry, compact and retry, or process a queued continuation. Only terminal `agent_settled` can exclusively publish the complete hash/count/byte seal. Tool activity after finalization, duplicate settlement, pre-settlement shutdown, extension diagnostics, and missing/failed/stale seals are fatal. This lifecycle requires Pi 0.81.1 or newer; older Pi lines do not expose the required terminal event and are not claimed as compatible.
+
 Cancellation and shutdown are loud and durable when a run store exists. The extension tracks active runs, links external abort signals, aborts on session shutdown/reload, and waits for settlement. Child processes have a 30 minute wall timeout, 20 minute idle watchdog, SIGTERM grace, SIGKILL wait, process-group kill on POSIX, bounded stdout/stderr, and cleanup-error propagation.
 
 ## Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-background-tasks",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Pi extension for durable background shell tasks, read-only delegated agents, local attested Pi runs, and fixed-purpose Fusion workflows through child Pi processes.",
   "type": "module",
   "license": "ISC",
@@ -82,8 +82,8 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.75.5 || ^0.81.1 || ^0.82.1 || ^0.83.0",
-    "@earendil-works/pi-tui": "^0.75.5 || ^0.81.1 || ^0.82.1 || ^0.83.0",
+    "@earendil-works/pi-coding-agent": "^0.81.1 || ^0.82.1 || ^0.83.0",
+    "@earendil-works/pi-tui": "^0.81.1 || ^0.82.1 || ^0.83.0",
     "typebox": "*"
   },
   "devDependencies": {

package/src/core/fusion/pi-child.ts

@@ -64,7 +64,8 @@ export const FUSION_CHILD_TIMEOUT_MS = 30 * 60 * 1000;
 export const FUSION_CHILD_IDLE_TIMEOUT_MS = 20 * 60 * 1000;
 export const FUSION_CHILD_KILL_GRACE_MS = 3000;
 export const FUSION_CHILD_SIGKILL_WAIT_MS = 5000;
-const FUSION_PI_CHILD_O_NOFOLLOW = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+const FUSION_PI_CHILD_O_NOFOLLOW =
+  typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
 
 export const FUSION_CHILD_REMOVED_ENV_KEYS = [
   'PI_SESSION_ID',
@@ -452,6 +453,7 @@ export function buildFusionPiChildArgv(
 
 const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
 const FUSION_CHILD_RESULT_PREFIX_BYTES = Buffer.from(FUSION_CHILD_RESULT_PREFIX, 'utf8');
+const PI_EXTENSION_ERROR_PREFIX_BYTES = Buffer.from('Extension error (', 'utf8');
 
 interface ParsedFusionChildStderr {
   records: FusionChildResultMetadata[];
@@ -728,36 +730,53 @@ export function parseFusionToolCallLog(bytes: Buffer): FusionToolCallTrace {
   };
 }
 
-
 async function assertCompletedToolPolicy(
   trace: FusionToolCallTrace,
   capability: FusionCapability,
   sourcePolicy: { path: string; sha256: string } | undefined,
 ): Promise<void> {
-  const allowed = capability === 'inspect' ? FUSION_INSPECT_TOOLS : capability === 'research' ? FUSION_RESEARCH_TOOLS : [];
+  const allowed =
+    capability === 'inspect'
+      ? FUSION_INSPECT_TOOLS
+      : capability === 'research'
+        ? FUSION_RESEARCH_TOOLS
+        : [];
   const allowedSet = new Set<string>(allowed);
   const declared =
     capability === 'research' && sourcePolicy !== undefined
-      ? new Set((await readFusionSourcePolicyFile(sourcePolicy.path, sourcePolicy.sha256)).sources.map((source) => source.canonical_url))
+      ? new Set(
+          (await readFusionSourcePolicyFile(sourcePolicy.path, sourcePolicy.sha256)).sources.map(
+            (source) => source.canonical_url,
+          ),
+        )
       : undefined;
   for (const record of trace.records) {
     if (!allowedSet.has(record.tool_name)) {
       throw new Error(`fusion child used non-allowlisted tool ${record.tool_name}`);
     }
     if (capability === 'research' && record.tool_name === FUSION_WEB_FETCH_TOOL_NAME) {
-      if (sourcePolicy === undefined || declared === undefined) throw new Error('fusion research source policy missing during audit');
+      if (sourcePolicy === undefined || declared === undefined)
+        throw new Error('fusion research source policy missing during audit');
       if (record.status === 'ok') {
         if (record.url === undefined) throw new Error('fusion research fetch audit is missing url');
         const canonicalUrl = canonicalizeFusionPublicUrl(record.url);
-        if (record.url !== canonicalUrl) throw new Error('fusion research fetch audit URL was not canonical');
-        if (!declared.has(canonicalUrl)) throw new Error('fusion research fetch audit URL was not declared');
+        if (record.url !== canonicalUrl)
+          throw new Error('fusion research fetch audit URL was not canonical');
+        if (!declared.has(canonicalUrl))
+          throw new Error('fusion research fetch audit URL was not declared');
         if (record.rejected_url_sha256 !== undefined) {
-          throw new Error('fusion research successful fetch audit must not include rejected_url_sha256');
+          throw new Error(
+            'fusion research successful fetch audit must not include rejected_url_sha256',
+          );
         }
-        if (record.final_url === undefined) throw new Error('fusion research fetch audit is missing final_url');
-        if (record.http_status === undefined) throw new Error('fusion research fetch audit is missing http_status');
-        if (record.response_bytes === undefined) throw new Error('fusion research fetch audit is missing response_bytes');
-        if (record.content_sha256 === undefined) throw new Error('fusion research fetch audit is missing content_sha256');
+        if (record.final_url === undefined)
+          throw new Error('fusion research fetch audit is missing final_url');
+        if (record.http_status === undefined)
+          throw new Error('fusion research fetch audit is missing http_status');
+        if (record.response_bytes === undefined)
+          throw new Error('fusion research fetch audit is missing response_bytes');
+        if (record.content_sha256 === undefined)
+          throw new Error('fusion research fetch audit is missing content_sha256');
       } else {
         if (record.url !== undefined || record.final_url !== undefined) {
           throw new Error('fusion research rejected fetch audit must not persist raw URL');
@@ -828,7 +847,8 @@ async function assertFusionToolCallLogSeal(
   }
   try {
     const stats = await handle.stat();
-    if (!stats.isFile()) throw new Error('fusion tool-call audit completion seal is not a regular file');
+    if (!stats.isFile())
+      throw new Error('fusion tool-call audit completion seal is not a regular file');
     if (stats.size > 4096) throw new Error('fusion tool-call audit completion seal is oversized');
     const bytes = await handle.readFile();
     if (bytes.at(-1) !== 10) throw new Error('fusion tool-call audit completion seal is partial');
@@ -841,7 +861,13 @@ async function assertFusionToolCallLogSeal(
       throw new Error('fusion tool-call audit completion seal must be an object');
     }
     const keys = Object.keys(parsed).sort();
-    const expected = ['log_sha256', 'record_count', 'schema_version', 'status', 'total_result_bytes'];
+    const expected = [
+      'log_sha256',
+      'record_count',
+      'schema_version',
+      'status',
+      'total_result_bytes',
+    ];
     if (keys.join('\0') !== expected.join('\0')) {
       throw new Error('fusion tool-call audit completion seal keys mismatch');
     }
@@ -939,6 +965,9 @@ export class FusionPiCompactResultParser {
     diagnostics: Buffer;
   } {
     const parsed = parseFusionChildStderr(stderr);
+    if (parsed.diagnostics.includes(PI_EXTENSION_ERROR_PREFIX_BYTES)) {
+      throw new Error('Pi child reported an extension error diagnostic');
+    }
     const final = parsed.records.at(-1);
     if (final === undefined) throw new Error('Pi child emitted no compact result metadata');
     for (const record of parsed.records) this.assertModel(record);
@@ -1251,7 +1280,13 @@ export async function runPiChild(options: RunPiChildOptions): Promise<FusionChil
     env[FUSION_TOOL_CALL_LOG_PATH_ENV] = options.toolCallLogPath;
     if (capability === 'research') {
       if (options.sourcePolicy === undefined) {
-        throw childError('fusion research child requires a source-policy path and hash', 'orchestration_failed', options, false, false);
+        throw childError(
+          'fusion research child requires a source-policy path and hash',
+          'orchestration_failed',
+          options,
+          false,
+          false,
+        );
       }
       env[FUSION_RESEARCH_ENABLED_ENV] = '1';
       env[FUSION_SOURCE_POLICY_PATH_ENV] = options.sourcePolicy.path;
@@ -1335,7 +1370,15 @@ export async function runPiChild(options: RunPiChildOptions): Promise<FusionChil
             options,
           );
         }
-        terminateChild(child, state, platform, killProcess, killGraceMs, sigkillWaitMs, settleClose);
+        terminateChild(
+          child,
+          state,
+          platform,
+          killProcess,
+          killGraceMs,
+          sigkillWaitMs,
+          settleClose,
+        );
       }, idleTimeoutMs),
     );
   };

package/src/fusion-child-extension.ts

@@ -1,5 +1,14 @@
 import { createHash } from 'node:crypto';
-import { closeSync, constants, fstatSync, fsyncSync, openSync, readFileSync, writeSync } from 'node:fs';
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  fsyncSync,
+  openSync,
+  readFileSync,
+  writeSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Type, type Static } from 'typebox';
 import {
@@ -100,24 +109,115 @@ function utf8JsonBytes(value: unknown, label: string): Buffer {
   return Buffer.from(text, 'utf8');
 }
 
-function appendToolCallLogLine(path: string, record: FusionToolCallLogRecord): void {
-  // The log is an audit trail, not a payload copy: raw tool arguments/results may
-  // contain secrets, so only byte counts and SHA-256 digests are persisted.
-  const line = `${JSON.stringify(record)}\n`;
-  const expectedBytes = Buffer.byteLength(line, 'utf8');
+function throwableError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value));
+}
+
+function writeAllSync(fd: number, bytes: Buffer, label: string): void {
+  let offset = 0;
+  while (offset < bytes.length) {
+    const written = writeSync(fd, bytes, offset, bytes.length - offset, null);
+    if (written <= 0) {
+      throw new Error(`${label} made no write progress at byte ${String(offset)}`);
+    }
+    offset += written;
+  }
+}
+
+function withRegularFileDescriptorSync(
+  path: string,
+  flags: number,
+  mode: number | undefined,
+  label: string,
+  operation: (fd: number) => void,
+): void {
   let fd: number | undefined;
+  let primaryFailure: unknown;
+  let closeFailure: unknown;
   try {
-    fd = openSync(path, 'a', 0o600);
-    const written = writeSync(fd, line, undefined, 'utf8');
-    if (written !== expectedBytes) {
-      throw new Error(
-        `short write: wrote ${String(written)} of ${String(expectedBytes)} bytes`,
-      );
+    fd = mode === undefined ? openSync(path, flags) : openSync(path, flags, mode);
+    const stats = fstatSync(fd);
+    if (!stats.isFile()) throw new Error(`${label} at ${path} is not a regular file`);
+    operation(fd);
+  } catch (error) {
+    primaryFailure = error;
+  }
+  if (fd !== undefined) {
+    try {
+      closeSync(fd);
+    } catch (error) {
+      closeFailure = error;
     }
+  }
+  if (primaryFailure !== undefined && closeFailure !== undefined) {
+    throw new AggregateError(
+      [primaryFailure, closeFailure],
+      `${label} operation and descriptor close both failed`,
+    );
+  }
+  if (primaryFailure !== undefined) throw throwableError(primaryFailure);
+  if (closeFailure !== undefined) throw throwableError(closeFailure);
+}
+
+function fsyncParentDirectorySync(path: string): void {
+  if (process.platform === 'win32') return;
+  const parent = dirname(path);
+  let fd: number | undefined;
+  let primaryFailure: unknown;
+  let closeFailure: unknown;
+  try {
+    fd = openSync(parent, constants.O_RDONLY | FUSION_CHILD_O_NOFOLLOW);
+    const stats = fstatSync(fd);
+    if (!stats.isDirectory())
+      throw new Error(`fusion audit parent at ${parent} is not a directory`);
     fsyncSync(fd);
-  } finally {
-    if (fd !== undefined) closeSync(fd);
+  } catch (error) {
+    primaryFailure = error;
+  }
+  if (fd !== undefined) {
+    try {
+      closeSync(fd);
+    } catch (error) {
+      closeFailure = error;
+    }
   }
+  if (primaryFailure !== undefined && closeFailure !== undefined) {
+    throw new AggregateError(
+      [primaryFailure, closeFailure],
+      'fusion audit directory sync and descriptor close both failed',
+    );
+  }
+  if (primaryFailure !== undefined) throw throwableError(primaryFailure);
+  if (closeFailure !== undefined) throw throwableError(closeFailure);
+}
+
+function createToolCallLog(path: string): void {
+  withRegularFileDescriptorSync(
+    path,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | FUSION_CHILD_O_NOFOLLOW,
+    0o600,
+    'fusion tool-call log',
+    (fd) => {
+      fsyncSync(fd);
+    },
+  );
+  fsyncParentDirectorySync(path);
+}
+
+function appendToolCallLogLine(path: string, record: FusionToolCallLogRecord): void {
+  // The log is an audit trail, not a payload copy: raw tool arguments/results may
+  // contain secrets, so only byte counts and SHA-256 digests are persisted.
+  const bytes = Buffer.from(`${JSON.stringify(record)}\n`, 'utf8');
+  withRegularFileDescriptorSync(
+    path,
+    constants.O_WRONLY | constants.O_APPEND | FUSION_CHILD_O_NOFOLLOW,
+    undefined,
+    'fusion tool-call log',
+    (fd) => {
+      writeAllSync(fd, bytes, 'fusion tool-call log append');
+      fsyncSync(fd);
+    },
+  );
 }
 
 function writeToolCallLogSeal(
@@ -126,7 +226,7 @@ function writeToolCallLogSeal(
   totalResultBytes: number,
   complete: boolean,
 ): void {
-  const logBytes = readFileSync(path);
+  const logBytes = readRegularFileNoSymlinkSync(path, 'fusion tool-call log');
   const seal = {
     schema_version: FUSION_TOOL_CALL_SEAL_SCHEMA_VERSION,
     status: complete ? 'complete' : 'failed',
@@ -135,17 +235,22 @@ function writeToolCallLogSeal(
     log_sha256: sha256(logBytes),
   } as const;
   const bytes = Buffer.from(`${JSON.stringify(seal)}\n`, 'utf8');
-  let fd: number | undefined;
-  try {
-    fd = openSync(`${path}${FUSION_TOOL_CALL_SEAL_SUFFIX}`, 'wx', 0o600);
-    const written = writeSync(fd, bytes);
-    if (written !== bytes.length) {
-      throw new Error(`fusion tool-call seal short write: ${String(written)} of ${String(bytes.length)} bytes`);
-    }
-    fsyncSync(fd);
-  } finally {
-    if (fd !== undefined) closeSync(fd);
-  }
+  const sealPath = `${path}${FUSION_TOOL_CALL_SEAL_SUFFIX}`;
+  withRegularFileDescriptorSync(
+    sealPath,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | FUSION_CHILD_O_NOFOLLOW,
+    0o600,
+    'fusion tool-call audit completion seal',
+    (fd) => {
+      writeAllSync(fd, bytes, 'fusion tool-call audit completion seal');
+      fsyncSync(fd);
+    },
+  );
+  fsyncParentDirectorySync(sealPath);
+}
+
+function latchAuditProcessFailure(): void {
+  if (process.exitCode === undefined || process.exitCode === 0) process.exitCode = 1;
 }
 
 async function writeMetadata(record: FusionChildResultMetadata): Promise<void> {
@@ -165,7 +270,9 @@ function strictFusionWebFetchArgs(args: unknown): FusionWebFetchParamsValue {
   const keys = Object.keys(args);
   const unknownKeys = keys.filter((key) => key !== 'url' && key !== 'extract');
   if (unknownKeys.length > 0 || !keys.includes('url')) {
-    throw new Error(`${FUSION_WEB_FETCH_TOOL_NAME} arguments must contain url and optional extract only`);
+    throw new Error(
+      `${FUSION_WEB_FETCH_TOOL_NAME} arguments must contain url and optional extract only`,
+    );
   }
   const url = Reflect.get(args, 'url');
   if (typeof url !== 'string' || url.trim().length === 0) {
@@ -189,7 +296,10 @@ function stringField(value: object, key: string): string | undefined {
   return typeof field === 'string' && field.length > 0 ? field : undefined;
 }
 
-function fetchAuditMetadataFromObject(value: object, fallbackUrl: string): FusionWebFetchAuditMetadata {
+function fetchAuditMetadataFromObject(
+  value: object,
+  fallbackUrl: string,
+): FusionWebFetchAuditMetadata {
   const metadata: FusionWebFetchAuditMetadata = {
     url: stringField(value, 'url') ?? canonicalizeFusionPublicUrl(fallbackUrl),
   };
@@ -204,7 +314,10 @@ function fetchAuditMetadataFromObject(value: object, fallbackUrl: string): Fusio
   return metadata;
 }
 
-function fetchAuditMetadataFromError(error: unknown, attemptedUrl: string): FusionWebFetchAuditMetadata {
+function fetchAuditMetadataFromError(
+  error: unknown,
+  attemptedUrl: string,
+): FusionWebFetchAuditMetadata {
   const metadata: FusionWebFetchAuditMetadata = { rejected_url_sha256: sha256(attemptedUrl) };
   if (error instanceof FusionWebFetchError && typeof error === 'object' && error !== null) {
     const status = numberField(error, 'status');
@@ -213,7 +326,6 @@ function fetchAuditMetadataFromError(error: unknown, attemptedUrl: string): Fusi
   return metadata;
 }
 
-
 function readRegularFileNoSymlinkSync(path: string, label: string): Buffer {
   let fd: number | undefined;
   try {
@@ -237,13 +349,17 @@ function loadDeclaredResearchUrls(): ReadonlySet<string> {
   const policyPath = process.env[FUSION_SOURCE_POLICY_PATH_ENV];
   const expectedHash = process.env[FUSION_SOURCE_POLICY_SHA256_ENV];
   if (policyPath === undefined || expectedHash === undefined) {
-    throw new Error(`${FUSION_WEB_FETCH_TOOL_NAME} research mode requires source policy path and sha256`);
+    throw new Error(
+      `${FUSION_WEB_FETCH_TOOL_NAME} research mode requires source policy path and sha256`,
+    );
   }
-  if (!/^[0-9a-f]{64}$/.test(expectedHash)) throw new Error('fusion source policy hash is malformed');
+  if (!/^[0-9a-f]{64}$/.test(expectedHash))
+    throw new Error('fusion source policy hash is malformed');
   const bytes = readRegularFileNoSymlinkSync(policyPath, 'fusion source policy');
   if (sha256(bytes) !== expectedHash) throw new Error('fusion source policy hash mismatch');
   const text = bytes.toString('utf8');
-  if (!Buffer.from(text, 'utf8').equals(bytes)) throw new Error('fusion source policy is not UTF-8');
+  if (!Buffer.from(text, 'utf8').equals(bytes))
+    throw new Error('fusion source policy is not UTF-8');
   const parsed = parseFusionSourcePolicy(JSON.parse(text));
   return new Set(parsed.sources.map((source) => source.canonical_url));
 }
@@ -279,30 +395,97 @@ export default function fusionChildExtension(pi: ExtensionAPI): void {
     throw new Error(`${FUSION_RESEARCH_ENABLED_ENV} must be unset or exactly 1`);
   }
   if (researchEnabled === '1' && toolCallLogPath === undefined) {
-    throw new Error(`${FUSION_WEB_FETCH_TOOL_NAME} research mode requires ${FUSION_TOOL_CALL_LOG_PATH_ENV}`);
+    throw new Error(
+      `${FUSION_WEB_FETCH_TOOL_NAME} research mode requires ${FUSION_TOOL_CALL_LOG_PATH_ENV}`,
+    );
   }
   const declaredResearchUrls = researchEnabled === '1' ? loadDeclaredResearchUrls() : undefined;
   const fetchAuditMetadata = new Map<string, FusionWebFetchAuditMetadata>();
   if (toolCallLogPath !== undefined) {
-    // Create the log immediately, before tools can run. Without this, an absent file
-    // is ambiguous: it could mean "this child made zero tool calls" or "the audit trail
-    // was never written". The parent must be able to tell those apart, so existence is
-    // established up front and a missing file is a hard failure rather than an empty trace.
-    closeSync(openSync(toolCallLogPath, 'a', 0o600));
+    // Establish the audit file before tools can run. Exclusive creation makes a reused
+    // attempt path or redirected file loud instead of appending to untrusted history.
+    try {
+      createToolCallLog(toolCallLogPath);
+    } catch (error) {
+      latchAuditProcessFailure();
+      throw error;
+    }
+
+    type AuditPhase = 'open' | 'finalizing' | 'sealed-complete' | 'sealed-failed';
+    interface ToolStart {
+      startedAt: number;
+      toolName: string;
+    }
+
+    let phase: AuditPhase = 'open';
     let ordinal = 0;
     let totalToolResultBytes = 0;
     let auditFailed = false;
-    const starts = new Map<string, number>();
+    const starts = new Map<string, ToolStart>();
+
+    const failAudit = (error: unknown): never => {
+      auditFailed = true;
+      latchAuditProcessFailure();
+      throw error instanceof Error ? error : new Error(String(error));
+    };
+    const requireOpen = (eventName: string): void => {
+      if (phase !== 'open') {
+        failAudit(`fusion tool-call audit received ${eventName} while ${phase}`);
+      }
+    };
+    const finalizeAudit = (normalSettlement: boolean, trigger: string): void => {
+      if (phase !== 'open') {
+        failAudit(
+          `fusion tool-call audit received duplicate finalization from ${trigger} while ${phase}`,
+        );
+      }
+      phase = 'finalizing';
+      const unmatchedStarts = starts.size;
+      const complete = normalSettlement && !auditFailed && unmatchedStarts === 0;
+      if (!complete) {
+        auditFailed = true;
+        latchAuditProcessFailure();
+      }
+      try {
+        writeToolCallLogSeal(toolCallLogPath, ordinal, totalToolResultBytes, complete);
+      } catch (error) {
+        phase = 'sealed-failed';
+        failAudit(error);
+      }
+      phase = complete ? 'sealed-complete' : 'sealed-failed';
+      if (!complete) {
+        failAudit(
+          `fusion tool-call audit finalized as failed from ${trigger}: ${String(unmatchedStarts)} unmatched tool start(s)`,
+        );
+      }
+    };
+
     pi.on('tool_call', (event) => {
-      starts.set(event.toolCallId, Date.now());
+      try {
+        requireOpen('tool_call');
+        if (starts.has(event.toolCallId)) {
+          throw new Error(`fusion tool-call log duplicate start for ${event.toolCallId}`);
+        }
+        starts.set(event.toolCallId, {
+          startedAt: Date.now(),
+          toolName: event.toolName,
+        });
+      } catch (error) {
+        failAudit(error);
+      }
     });
     pi.on('tool_result', (event) => {
       try {
+        requireOpen('tool_result');
         const start = starts.get(event.toolCallId);
         if (start === undefined) {
           throw new Error(`fusion tool-call log missing start for ${event.toolCallId}`);
         }
-        starts.delete(event.toolCallId);
+        if (start.toolName !== event.toolName) {
+          throw new Error(
+            `fusion tool-call log tool mismatch for ${event.toolCallId}: started ${start.toolName}, completed ${event.toolName}`,
+          );
+        }
         const argumentsBytes = utf8JsonBytes(event.input, 'arguments');
         const resultBytes = utf8JsonBytes(
           {
@@ -314,7 +497,7 @@ export default function fusionChildExtension(pi: ExtensionAPI): void {
           'result',
         );
         const fetchMetadata = fetchAuditMetadata.get(event.toolCallId);
-        fetchAuditMetadata.delete(event.toolCallId);
+        const nextTotalToolResultBytes = totalToolResultBytes + resultBytes.length;
         const record: FusionToolCallLogRecord = {
           schema_version: FUSION_TOOL_CALL_LOG_SCHEMA_VERSION,
           ordinal,
@@ -324,25 +507,33 @@ export default function fusionChildExtension(pi: ExtensionAPI): void {
           result_bytes: resultBytes.length,
           result_sha256: sha256(resultBytes),
           status: event.isError === true ? 'error' : 'ok',
-          duration_ms: Math.max(0, Date.now() - start),
+          duration_ms: Math.max(0, Date.now() - start.startedAt),
           ...(fetchMetadata === undefined ? {} : fetchMetadata),
         };
-        ordinal += 1;
         appendToolCallLogLine(toolCallLogPath, record);
-        totalToolResultBytes += resultBytes.length;
+        starts.delete(event.toolCallId);
+        fetchAuditMetadata.delete(event.toolCallId);
+        ordinal += 1;
+        totalToolResultBytes = nextTotalToolResultBytes;
         if (totalToolResultBytes > FUSION_CHILD_MAX_TOTAL_TOOL_RESULT_BYTES) {
           throw new Error(
             `fusion candidate exceeded the aggregate tool-output budget: ${String(totalToolResultBytes)} bytes across ${String(ordinal)} calls exceeds ${String(FUSION_CHILD_MAX_TOTAL_TOOL_RESULT_BYTES)}`,
           );
         }
       } catch (error) {
-        auditFailed = true;
-        throw error;
+        failAudit(error);
+      }
+    });
+    // agent_end is only the end of one low-level run. Pi may still retry, compact and
+    // retry, or consume queued continuations. Sealing there created stale prefix seals.
+    pi.on('agent_settled', (_event, ctx) => {
+      if (!ctx.isIdle()) {
+        failAudit('fusion child emitted agent_settled while the agent was not idle');
       }
+      finalizeAudit(true, 'agent_settled');
     });
-    pi.on('agent_end', () => {
-      const complete = !auditFailed && starts.size === 0;
-      writeToolCallLogSeal(toolCallLogPath, ordinal, totalToolResultBytes, complete);
+    pi.on('session_shutdown', () => {
+      if (phase === 'open') finalizeAudit(false, 'session_shutdown before agent_settled');
     });
   }
 
@@ -366,10 +557,14 @@ export default function fusionChildExtension(pi: ExtensionAPI): void {
         try {
           const canonicalUrl = canonicalizeFusionPublicUrl(params.url);
           if (params.url !== canonicalUrl) {
-            throw new Error(`${FUSION_WEB_FETCH_TOOL_NAME} URL must exactly match its declared canonical URL`);
+            throw new Error(
+              `${FUSION_WEB_FETCH_TOOL_NAME} URL must exactly match its declared canonical URL`,
+            );
           }
           if (declaredResearchUrls === undefined || !declaredResearchUrls.has(canonicalUrl)) {
-            throw new Error(`${FUSION_WEB_FETCH_TOOL_NAME} URL was not declared in the research source policy`);
+            throw new Error(
+              `${FUSION_WEB_FETCH_TOOL_NAME} URL was not declared in the research source policy`,
+            );
           }
           const result = await fusionWebFetch(
             params.extract === undefined