@herbertgao/pi-extensions 2026.9.19 → 2026.10.0

package/node_modules/@herbertgao/sol-pi/README.md

@@ -1,10 +1,11 @@
 <p align="center">
-  <img src="assets/sol-pi-hero.png" width="100%" alt="SoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses" />
+  <img src="https://raw.githubusercontent.com/HerbertGao/pi-extensions/refs/heads/master/packages/sol-pi/assets/sol-pi-hero.png" width="100%" alt="SoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses" />
 </p>
 
 # ⚡ SoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses
 
 <p align="center">
+  <a href="https://arxiv.org/abs/2609.20519"><img src="https://img.shields.io/badge/arXiv-2609.20519-B31B1B?logo=arxiv&amp;logoColor=white" alt="arXiv: 2609.20519" /></a>
   <a href="#getting-started"><img src="https://img.shields.io/badge/Getting%20Started-Install-76B900" alt="Getting Started" /></a>
   <a href="docs/configuration.md"><img src="https://img.shields.io/badge/Docs-Configuration-555555" alt="Configuration" /></a>
   <a href="https://nvlabs.github.io/SoL-Pi/"><img src="https://img.shields.io/badge/Blog-SoL--Pi-76B900" alt="SoL-Pi Blog" /></a>
@@ -52,32 +53,36 @@ The mechanisms share four rules:
 
 Read the [SoL-Pi blog](https://nvlabs.github.io/SoL-Pi/) for a deeper look at the technical details, design rationale, and core insights behind SoL-Pi, including how auto-research led to the four efficiency mechanisms and how they work.
 
+## Paper
+
+Read our paper: [SoL-Pi: Recursively Scaling Auto-Research Loops for Efficient Agent Harness](https://arxiv.org/abs/2609.20519).
+
 ## Getting Started
 
 ### Requirements
 
 - Node.js 24 or newer
 - npm
-- `@earendil-works/pi-coding-agent` 0.85.1
+- `@earendil-works/pi-coding-agent` 1.0.4 (the monorepo's tested host; runtime peers remain `*`)
 
 ### Install
 
 Install the tested Pi release:
 
 ```bash
-npm install --global @earendil-works/pi-coding-agent@0.85.1
+npm install --global @earendil-works/pi-coding-agent@1.0.4
 ```
 
-Then install SoL-Pi directly from [NVlabs/SoL-Pi](https://github.com/NVlabs/SoL-Pi):
+Install this independently maintained package, or use `@herbertgao/pi-extensions` for the collection:
 
 ```bash
-pi install git:github.com/NVlabs/SoL-Pi
+pi install npm:@herbertgao/sol-pi
 ```
 
 To install it only for the current project, use the project-local scope:
 
 ```bash
-pi install git:github.com/NVlabs/SoL-Pi --local --approve
+pi install npm:@herbertgao/sol-pi --local --approve
 ```
 
 ### Configure
@@ -102,9 +107,9 @@ The following conservative configuration enables only the two local mechanisms t
 }
 ```
 
-Enable additional mechanisms only after reviewing their configuration and security implications. SoL-Pi uses no dedicated environment variables; feature flags, the reducer provider/model route, and the compaction ratio are configured in `sol-pi.json`.
+Enable additional mechanisms only after reviewing their configuration and security implications. SoL-Pi uses no dedicated environment variables; feature flags, the reducer provider/model route, and the compaction ratio are configured in `sol-pi.json`. See [sol-pi.example.json](sol-pi.example.json) for a template listing every key.
 
-For the complete schema, see [Configuration](docs/configuration.md). Coding agents and automated environments should follow the canonical [agent installation and configuration protocol](agents-install.md). Its all-enabled profile is checked with `scripts/check-sol-pi-config.mjs --require-all-enabled`.
+For the complete schema, see [Configuration](docs/configuration.md). Coding agents and automated environments should follow the canonical [agent installation and configuration protocol](agents-install.md), which describes an all-enabled configuration checked with `scripts/check-sol-pi-config.mjs --require-all-enabled`.
 
 ## Storage and Security
 
@@ -118,7 +123,9 @@ ObservationPack and Evidence-Preserving Reducer store session-specific archives
 
 They archive eligible source material in this directory. The archived copies remain local and are not automatically deleted when the Pi session ends.
 
-Online Context Compact stores its state in Pi's session log. After a successful compaction, it starts a new turn and automatically continues the active task. Cancelling the run or exiting Pi does not trigger automatic continuation.
+With `pi --no-session` or `SessionManager.inMemory()`, Pi provides no session directory. SoL-Pi instead creates a private directory named `sol-pi-<session-id>-<random>/` under the operating system's temporary directory. ObservationPack and Evidence-Preserving Reducer share this directory for the lifetime of the loaded extension. These modes disable Pi's session-log persistence; SoL-Pi still writes archive files for exact recall. Temporary archives are also retained after the session or worker exits so callers can read referenced evidence. Their eventual cleanup follows the host's temporary-file policy or the caller's cleanup, and they are not guaranteed to survive system cleanup or support session recovery.
+
+Online Context Compact stores its state in Pi's session log. After a successful compaction, or a recoverable native refusal (session too small, already compacted, or an incomplete summary at the token cap), it automatically continues the active task. A refused attempt retains the existing context and adds no cache debt; plan-only turns cannot repeatedly retry it. Cancelling the run or exiting Pi does not trigger automatic continuation.
 
 Evidence-Preserving Reducer may send eligible diagnostic-log content to its configured reducer model using Pi-managed authentication. Review [SECURITY.md](SECURITY.md) before enabling it. Do not enable remote reduction for logs that must remain local.
 
@@ -133,22 +140,22 @@ Evidence-Preserving Reducer may send eligible diagnostic-log content to its conf
 
 ## Development
 
-Install from the lockfile and run the complete source checks:
+From the monorepo root, install from its Bun lockfile and run the complete source checks:
 
 ```bash
-npm ci --ignore-scripts
-npm run check
-npm audit --audit-level=high
-node scripts/check-pi-compat.mjs
+bun install --frozen-lockfile
+bun run check
+bun audit
+node packages/sol-pi/scripts/check-pi-compat.mjs
 ```
 
-`npm run check` covers TypeScript, the complete test suite, and package inspection. The development dependency set is pinned to Pi 0.84.2; runtime Pi packages remain peer dependencies so Pi owns their installation and upgrades.
+For package-only checks, run `bun run --cwd packages/sol-pi typecheck` and `bun run --cwd packages/sol-pi test`, then inspect the package with `npm pack --dry-run` from `packages/sol-pi`. Root development dependencies provide Pi 1.0.4; runtime Pi packages remain peer dependencies so Pi owns their installation and upgrades.
 
 ## Project Status
 
-SoL-Pi is developed and maintained by NVIDIA as a standalone extension for Pi.
+The original SoL-Pi project is developed by NVIDIA as a standalone extension for Pi. This package is independently maintained in HerbertGao/pi-extensions.
 
-External code contributions are not accepted at this time. Bug reports and private security reports remain welcome through the channels described in [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+For upstream contributions, see [CONTRIBUTING.md](CONTRIBUTING.md). Report collection-specific issues to [HerbertGao/pi-extensions](https://github.com/HerbertGao/pi-extensions/issues); upstream private security channels remain described in [SECURITY.md](SECURITY.md).
 
 ## Acknowledgements
 
@@ -157,3 +164,15 @@ SoL-Pi builds on the public extension interfaces provided by [Pi](https://github
 ## License
 
 SoL-Pi is released under the [MIT License](LICENSE).
+
+## Star History
+
+This chart tracks the original NVIDIA project. Its generator and tests are retained as development-only references; publication stays in the [upstream workflow](docs/star-history.md), not this monorepo.
+
+<a href="https://www.star-history.com/?repos=NVlabs%2FSoL-Pi&amp;type=date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/NVlabs/SoL-Pi/star-history/star-history-dark.svg" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/NVlabs/SoL-Pi/star-history/star-history-light.svg" />
+    <img alt="SoL-Pi star history chart" src="https://raw.githubusercontent.com/NVlabs/SoL-Pi/star-history/star-history-light.svg" width="100%" />
+  </picture>
+</a>

package/node_modules/@herbertgao/sol-pi/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-Party Notices
 
-SoL-Pi does not vendor third-party source code. Its npm tarball contains only SoL-Pi source, documentation, tests-excluded assets, and project metadata.
+This independently maintained package imports the MIT-licensed SoL-Pi source from [NVlabs/SoL-Pi](https://github.com/NVlabs/SoL-Pi). Original NVIDIA copyright and MIT notices are preserved; `package.json` records the imported baseline in `x-upstream`. Its npm tarball contains only SoL-Pi source, documentation, assets, and project metadata, without vendored Pi or Star History source.
 
 ## Runtime peer dependencies
 
@@ -8,12 +8,16 @@ The following packages are supplied by the user's Pi installation and retain the
 
 | Package | Development-tested version | License | Source |
 | --- | ---: | --- | --- |
-| `@earendil-works/pi-agent-core` | 0.85.1 | MIT | <https://github.com/earendil-works/pi> |
-| `@earendil-works/pi-ai` | 0.85.1 | MIT | <https://github.com/earendil-works/pi> |
-| `@earendil-works/pi-coding-agent` | 0.85.1 | MIT | <https://github.com/earendil-works/pi> |
-| `@earendil-works/pi-tui` | 0.85.1 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-agent-core` | 1.0.4 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-ai` | 1.0.4 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-coding-agent` | 1.0.4 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-tui` | 1.0.4 | MIT | <https://github.com/earendil-works/pi> |
 | `typebox` | 1.3.7 | MIT | <https://github.com/sinclairzx81/typebox> |
 
 ## Development-only dependencies
 
-`@types/node` (MIT), TypeScript (Apache-2.0), and Vitest (MIT) are used to type-check and test the repository. They are not included in the SoL-Pi npm tarball. Exact versions and transitive dependency metadata are recorded in `package-lock.json`.
+`@types/node` (MIT), TypeScript (Apache-2.0), and Vitest (MIT) are used to type-check and test the repository. They are not included in the SoL-Pi npm tarball. Exact versions and transitive dependency metadata are recorded in the monorepo root's `bun.lock`.
+
+## Star history chart generation
+
+The upstream documentation workflow (not enabled in this monorepo) checks out the MIT-licensed [Star History renderer](https://github.com/star-history/star-history/tree/c326eac651bc5afb4cd40d354223dd419e1e2ae6) to preserve its chart design. Its source and dependencies are installed only for chart generation and are not included in the SoL-Pi npm tarball. The generated chart branch includes the upstream MIT license as `LICENSE-star-history.txt`.

package/node_modules/@herbertgao/sol-pi/agents-install.md

@@ -7,11 +7,11 @@ Installation and configuration are complete only when Pi remains unmodified, the
 ## Rules
 
 - Do not modify, patch, fork, or vendor upstream Pi. SoL-Pi must load as a standalone extension through Pi's public package interface.
-- Use Node.js 24 or newer and the tested Pi release `@earendil-works/pi-coding-agent@0.85.1`. Treat a different Pi version as a compatibility change and rerun the full suite before using it.
+- Use Node.js 24 or newer and the tested Pi release `@earendil-works/pi-coding-agent@1.0.4`. Treat a different Pi version as a compatibility change and rerun the full suite before using it.
 - Do not clean, reset, switch, or overwrite unrelated repository changes.
 - Do not print, log, commit, upload, or include any secret in a command line. Check only whether a credential is present.
 - Keep SoL-Pi settings in `sol-pi.json`. The Evidence-Preserving Reducer provider/model route is a SoL-Pi setting; provider URLs, credentials, the main agent model, and shell behavior remain Pi settings.
-- Keep persistent artifacts under Pi's session-derived `sol-pi/<session-id>/` root; do not configure a separate storage path.
+- Keep persistent artifacts under Pi's session-derived `sol-pi/<session-id>/` root. For `--no-session` and in-memory sessions, use the automatic private directory under the system temporary directory; do not configure a separate storage path. Temporary archives remain after worker exit for callers to read, with cleanup managed by the host or caller.
 
 ## Inputs
 
@@ -35,30 +35,33 @@ node --version
 npm --version
 ```
 
-Require Node.js 24 or newer. Install from the lockfile and run the source checks:
+Require Node.js 24 or newer. In this monorepo, run the dependency and full checks from the repository root, then return to `packages/sol-pi` for package validation:
 
 ```bash
-npm ci --ignore-scripts
-npm run check
-npm audit --audit-level=high
+# Repository root
+bun install --frozen-lockfile
+bun run check
+bun audit
+# packages/sol-pi
 node scripts/check-pi-compat.mjs
-npx vitest run tests/all-mechanisms.test.ts
+bun run test -- tests/all-mechanisms.test.ts
+npm pack --dry-run
 ```
 
-`npm run check` covers type checking, the complete test suite, and package inspection. `tests/all-mechanisms.test.ts` confirms that one all-enabled configuration registers all four mechanisms against Pi's public extension API. The tests run without a model provider.
+`bun run check` covers root formatting, linting, type checking, and the complete test suites; `npm pack --dry-run` inspects this package. `tests/all-mechanisms.test.ts` confirms that one all-enabled configuration registers all four mechanisms against Pi's public extension API. The tests run without a model provider.
 
-Stop if any command fails. Do not hide a failure with `|| true` or replace `npm ci` with an unlocked install.
+Stop if any command fails. Do not hide a failure with `|| true` or replace the frozen-lockfile install with an unlocked install.
 
 ## Phase 2: install Pi and SoL-Pi
 
 Install the tested Pi release without changing its source:
 
 ```bash
-npm install --global --ignore-scripts @earendil-works/pi-coding-agent@0.85.1
+npm install --global --ignore-scripts @earendil-works/pi-coding-agent@1.0.4
 pi --version
 ```
 
-Require `pi --version` to report `0.85.1`.
+Require `pi --version` to report `1.0.4`. Runtime peer ranges remain `*`; other hosts need their own validation.
 
 For a project-local registration, run this from `target_project` and substitute the resolved absolute `sol_pi_root`:
 
@@ -124,7 +127,7 @@ Require exit status 0 and retain its JSON output. The check applies SoL-Pi's def
 
 1. Run `pi list --approve` from `target_project` and confirm the expected SoL-Pi source and scope.
 2. Run `check-sol-pi-config.mjs --require-all-enabled` against the effective `sol-pi.json`.
-3. Re-run `npx vitest run tests/all-mechanisms.test.ts` from `sol_pi_root`.
+3. Re-run `bun run test -- tests/all-mechanisms.test.ts` from `sol_pi_root`.
 4. Start Pi with `--offline --approve`, send no prompt, confirm there is no extension load error, and exit.
 5. Confirm that upstream Pi was not patched and that the SoL-Pi checkout contains no vendored Pi monorepo source.
 

package/node_modules/@herbertgao/sol-pi/docs/compatibility.md

@@ -1,6 +1,6 @@
 # Pi Compatibility
 
-SoL-Pi is developed and tested against `@earendil-works/pi-coding-agent` 0.85.1. Its public API surface is also type-checked and exercised against Pi 0.81.1, the base used by the original Pi fork. The runtime range is deliberately expressed as a peer dependency because Pi owns installation and upgrade of its packages.
+This monorepo tests `@herbertgao/sol-pi` against the root development host Pi 1.0.4. Pi runtime peers remain `*`, so Pi owns installation and upgrades; that range is not a guarantee for every host. Upstream reports a 19-file/140-test suite and offline startup passing on 0.85.1 and 0.84.2, with earlier public-API checks on the 0.81.1 fork. Those are historical upstream results, not results for the locally adapted package. Its tests use Pi 1.x `ExtensionToolContext` for tool execution.
 
 SoL-Pi imports only public package exports:
 
@@ -19,10 +19,16 @@ The built-in edit/write definitions capture their working directory, so SoL-Pi c
 
 Action Fusion decodes `file://` targets with Node's `fileURLToPath()` before resolving the queue and hash-check path. This keeps file URLs, including percent-encoded filenames and Pi's optional `@` prefix, aligned with the file handled by the built-in mutation tool.
 
+On Windows it applies the same drive-path conversion Pi's own resolver applies, so Git Bash, MSYS, Cygwin, and WSL targets such as `/c/src/app.ts` and home-relative `~\` paths resolve to the file the built-in mutation tool wrote. On other platforms those inputs keep their POSIX meaning.
+
 The queue covers only fused operations registered by this SoL-Pi instance. External processes, direct built-in-tool calls outside the replacement, and unrelated extensions are not globally locked. SoL-Pi hashes the target immediately before launching `then_run` and skips the command if it observes an intervening content change.
 
 When another extension already owns `write`, Action Fusion leaves that tool in place and only registers its `edit` replacement.
 
+A native local `write` exposes the runtime-only `Symbol.for("herbertgao.pi.writeMetadataObserver")` annotation. CC-style rendering can register bounded previous-file capture inside Pi's native `WriteOperations.writeFile` mutation queue, rather than racing a `tool_call` hook. Custom write operations reject registration because they may not target the local filesystem. Cancellation during capture prevents the actual write. This annotation adds no runtime dependency or global observer state.
+
+Pi 1.x may return `Bash.isError` instead of throwing on a failed follow-up. Action Fusion reports that failure while retaining the successful mutation.
+
 ## ObservationPack
 
 ObservationPack changes only the messages projected through the public `context` event. Stored session history remains intact. Original bytes and the JSONL ledger live under the session-derived SoL-Pi directory.
@@ -31,9 +37,9 @@ ObservationPack changes only the messages projected through the public `context`
 
 The reducer handles public `tool_result` events and resolves the configured reducer provider/model through Pi's model registry before calling `ExtensionContext.modelRegistry.complete()` when available. For the Pi 0.81.1 fork, which exposes no registry `complete()` method, it resolves authentication for that reducer model through `getApiKeyAndHeaders()` and calls the shared `@earendil-works/pi-ai/compat` completion API. The reducer preserves the original result whenever the configured reducer model is unavailable or eligibility, model-call, schema, source-hash, exact-quote, size, or likely-secret checks fail.
 
-All persistent paths use `SessionManager.getSessionDir()` and `getSessionId()`, which are present in both the fork and Pi 0.85.1. SoL-Pi creates no configurable storage-path surface.
+All persistent paths use `SessionManager.getSessionDir()` and `getSessionId()`, which are present in both the fork and Pi 0.85.1. If the session directory is empty (`--no-session` or `SessionManager.inMemory()`), SoL-Pi lazily creates a private `sol-pi-<session-id>-<random>/` directory under `os.tmpdir()`. Its path is reused by session ID across contexts and both archiving mechanisms while the extension is loaded. These files remain available after worker shutdown for callers that need to read evidence; cleanup is left to the host or caller. SoL-Pi creates no configurable storage-path surface.
 
-The unpublished shared artifact layout is not read or migrated. Each session starts from its own `<sessionDir>/sol-pi/<sessionId>/` directory.
+The unpublished shared artifact layout is not read or migrated. Each persistent session starts from its own `<sessionDir>/sol-pi/<sessionId>/` directory; ephemeral sessions use the temporary fallback above.
 
 ## Online Context Compact
 
@@ -41,13 +47,19 @@ Online Context Compact uses ordinary public `context` and `before_provider_reque
 
 Before selecting or executing a boundary compaction, it also checks the optional `Symbol.for("pi-subagents:manager")` registry exposed by `pi-subagents`. A running top-level subagent, or an unreadable registry, suppresses that compaction rather than risking a context rewrite during delegated work. When the registry is absent, the check is a no-op.
 
-Pi does not expose its active retained-tail compaction setting through the public extension context. The standalone extension therefore uses the documented Pi 0.85.1 default of 20,000 tokens for its economic estimate. Its programmatic factory accepts an explicit matching value for a non-default Pi setting.
+The native cut is selected from session entries, while removable-token savings are measured from the corresponding messages in the latest observed projection. ObservationPack placeholders are therefore priced at their projected size. Dropped messages, unseen additions, and ambiguous matches contribute no proven savings; the estimator never substitutes their raw byte counts or reruns context hooks to estimate them.
+
+Compaction preserves the current plan, request-horizon samples, and context-growth history. Every plan update uses the same step-ID/status comparison, including the first update after compaction. A boundary requires a previously registered unfinished step to become completed. Newly introduced completed IDs establish history without creating a boundary, so re-keyed completed snapshots do not retrigger compaction. An assistant must register a step before completing it to make that completion eligible for OCC. Economic compaction has a two-provider-request cooldown; context-window protection can override it. A new user task following a fully completed plan resets the request-horizon samples while preserving unpaid cache debt.
 
-Pi 0.85.1's `ExtensionContext.compact()` aborts the active agent before it summarizes, and `agent_settled` fires only once a whole run has drained every turn, retry, auto-compaction, and queued continuation. A plan boundary that selects compaction therefore saves its plan and progress state, calls `ExtensionContext.abort()` to stop the run, and runs compaction from the `agent_settled` that stop produces. The handler awaits the compaction's own `onComplete`/`onError` callbacks. On success, the extension sends a hidden reminder through public `ExtensionAPI.sendMessage()` with `triggerTurn: true`, so Pi starts a new turn against the compacted context and rebuilds the plan even when the native summary omits that instruction.
+Pi does not expose its active retained-tail compaction setting through the public extension context. The standalone extension therefore uses the Pi 0.85.1 default of 20,000 tokens for its economic estimate. Its programmatic factory accepts an explicit matching value for a non-default Pi setting.
 
-A settlement barrier keeps the original `agent_settled` dispatch open until the triggered continuation settles. Print- and JSON-mode processes therefore complete the compact-and-continue sequence within the same Pi invocation; an outer driver does not need to resume the session or send `Continue working`. This continuation is armed only by a successful boundary compaction. Cancelling or exiting does not schedule one. A Pi build that never emits `agent_settled` starts no boundary compaction.
+Pi 0.85.1's `ExtensionContext.compact()` aborts the active agent before it summarizes, and `agent_settled` fires only once a whole run has drained every turn, retry, auto-compaction, and queued continuation. A plan boundary that selects compaction therefore saves its plan and progress state, calls `ExtensionContext.abort()` to stop the run, and runs compaction from the `agent_settled` that stop produces. The handler awaits the compaction's own `onComplete`/`onError` callbacks. On success, the extension sends a hidden reminder through public `ExtensionAPI.sendMessage()` with `triggerTurn: true`, so Pi starts a new turn against the compacted context and continues the current plan. The reminder asks it to preserve existing step IDs when updating progress; an immediate plan update is not required.
 
-Pi 0.85.1 does not return a promise from `ExtensionAPI.sendMessage()`. The barrier is therefore verified for standalone SoL-Pi and depends on Pi starting the requested turn synchronously. A later-loaded third-party extension that performs long asynchronous work in its own `agent_settled` handler is outside this guarantee and needs an integration test with that extension set.
+A settlement barrier keeps the original `agent_settled` dispatch open until a synchronously triggered continuation settles. Print- and JSON-mode processes therefore complete the compact-and-continue sequence within the same Pi invocation; an outer driver does not need to resume the session or send `Continue working`. Successful compaction schedules a continuation. The exact native refusals `Nothing to compact (session too small)` and `Already compacted`, and Pi's explicit incomplete-summary token-cap error, also resume the interrupted task with the existing context. These skips are recorded as `sol-pi-online-context-compact-skipped` entries and shown as TUI warnings; they do not record a compaction or charge new cache debt. Plan-only turns cannot retry compaction until successful non-plan tool work or new user input occurs. Cancelling or exiting does not schedule a continuation. Other compaction errors still propagate.
+
+Pi 0.85.1 does not return a promise from `ExtensionAPI.sendMessage()` and starts the requested turn synchronously, so it uses the extension's settlement barrier. Newer hosts can keep the context idle and defer the turn until settled handlers return; OCC returns control to such a host instead of waiting on the deferred turn or reporting a false start failure. A later-loaded third-party extension that performs long asynchronous work in its own `agent_settled` handler needs an integration test with that extension set.
+
+For reasoning models, native compaction temporarily lowers high/xhigh/max thinking to medium to leave output budget for summary text, then restores it if no one else changed it.
 
 Pi reports the session as idle while an extension-requested manual compaction is running. SoL-Pi cancels `session_before_tree` during that interval to prevent tree navigation from moving the active leaf underneath the compaction. Navigation works normally after the compaction callback settles.
 
@@ -66,4 +78,8 @@ events, print output, or RPC UI requests.
 
 ## Test doubles
 
-The test suite drives every extension through the same public `ExtensionAPI` and `ExtensionContext` surface Pi provides, over a real public `SessionManager`, with no provider registered. That keeps the suite zero-spend and independent of the deleted Pi monorepo test harness. Suites that need a genuine session tree — branch order, compaction entries, custom entries, resume — use `SessionManager.inMemory()` or `SessionManager.create()` rather than reimplementing them.
+The test suite drives every extension through the same public `ExtensionAPI` and `ExtensionContext` surface Pi provides, over a real public `SessionManager`, without calling a remote model provider. That keeps the suite zero-spend and independent of the deleted Pi monorepo test harness. Suites that need a genuine session tree — branch order, compaction entries, custom entries, resume — use `SessionManager.inMemory()` or `SessionManager.create()` rather than reimplementing them.
+
+`tests/pi-package-integration.test.ts` loads the actual TypeScript entrypoint through Pi's `DefaultResourceLoader`, reads a trusted all-enabled project configuration, and executes a fused write/command and a plan update in a real `AgentSession`. `tests/online-context-compact-agent-session.test.ts` verifies one and two consecutive native compactions and waits for automatic continuation before the original prompt returns. These integration tests use Pi's deterministic faux provider; they verify runtime compatibility, not live provider authentication or token savings.
+
+Upstream's historical 0.84.2 backward-compatibility run used an isolated copy of its source and tests, separate dependencies, and an empty Pi agent directory. Only the copy's four Pi development dependency versions, lockfile, and installation-guide version mentions changed. No source or test changes were needed. The run included all four mechanisms and the native compaction/continuation integration tests; it did not repeat live-provider benchmarks on 0.84.2.

package/node_modules/@herbertgao/sol-pi/docs/configuration.md

@@ -41,7 +41,7 @@ This preflight does not make every valid SoL-Pi configuration all-enabled. Witho
 
 ## Feature behavior
 
-- `actionFusion`: registers SoL-Pi replacements for Pi's `edit` and `write` tools.
+- `actionFusion`: registers SoL-Pi replacements for Pi's `edit` and `write` tools. With `@herbertgao/pi-cc-extensions` installed, local writes also provide the execution metadata needed for ccstyle's rich diff without replacing the fused tool. Custom write operations still defer to their owner because a local file snapshot may not describe a remote write.
 - `observationPack`: registers `obs_recall` and a provider-context projection handler.
 - `evidencePreservingReducer`: registers a `tool_result` handler and delegates long diagnostic-log reduction to the configured reducer provider/model.
 - `evidencePreservingReducerProvider`: provider namespace used to resolve the reducer model through Pi's model registry.
@@ -62,7 +62,7 @@ The release entry uses two runtime inputs:
 - **Context window** — from `ExtensionContext.getContextUsage()`, used for window-pressure protection.
 - **Cache write/read ratio** — from `cacheWriteReadRatio` in the effective `sol-pi.json`. The value remains fixed for the session and is not recomputed when the model changes. It drives one runtime decision and is not a cost report.
 
-The configured ratio stays fixed for the loaded extension. The mechanism stores its current plan, progress summaries, request horizon, context growth, and compaction debt as versioned custom entries in Pi's session log. After a successful compaction it sends one hidden, generic message with `triggerTurn: true`, which starts a new turn and instructs the assistant to rebuild its plan. A settlement barrier keeps print and JSON modes in the same Pi invocation until that continuation settles, so callers do not need to resume the session or inject `Continue working`. Cancelling or exiting does not schedule an automatic continuation. The mechanism creates no separate Online Context Compact files. The programmatic factory exposes only a matching retained-tail value for installations whose Pi compaction setting differs from the default.
+The configured ratio stays fixed for the loaded extension. The mechanism stores its current plan, progress summaries, request horizon, context growth, and compaction debt as versioned custom entries in Pi's session log. After a successful compaction it sends one hidden, generic message with `triggerTurn: true`, which starts a new turn and asks the assistant to continue the current plan, preserving existing step IDs when updating progress. A settlement barrier keeps print and JSON modes in the same Pi invocation until that continuation settles, so callers do not need to resume the session or inject `Continue working`. On Pi 1.x, OCC returns to the host to let its deferred continuation run after settled handlers finish. Recoverable native refusals (session too small, already compacted, or an incomplete summary at the token cap) resume with the unchanged context and no new cache debt; successful non-plan tool work or new user input is required before another plan-only attempt. Economic compaction has a two-provider-request cooldown, but window protection overrides it. Cancelling or exiting does not schedule an automatic continuation. The mechanism creates no separate Online Context Compact files. The programmatic factory exposes only a matching retained-tail value for installations whose Pi compaction setting differs from the default.
 
 ## Pi integration
 

package/node_modules/@herbertgao/sol-pi/docs/star-history.md

@@ -0,0 +1,18 @@
+# Star history chart
+
+The README chart is generated by [Update star history](https://github.com/NVlabs/SoL-Pi/actions/workflows/star-history.yml). It runs hourly at minute 17, when the generator or workflow changes on `main`, and on manual dispatch. GitHub may delay scheduled runs; the image shows the actual successful fetch time in UTC.
+
+The workflow uses its built-in `GITHUB_TOKEN`, Node.js, and the [GitHub aggregate star history and count endpoints](https://docs.github.com/en/rest/activity/starring). It fetches every history page and renders locally with the original [Star History renderer](https://github.com/star-history/star-history/tree/c326eac651bc5afb4cd40d354223dd419e1e2ae6), pinned to a specific commit and installed from its lockfiles. No additional secrets or cached third-party chart API are used.
+
+The chart retains Star History's original layout, typography, legend, and axes, with only an updated timestamp added below it. The line sums GitHub's daily star additions. The current total is retained in the source JSON and can differ from that sum because it excludes removed stars. Daily boundaries follow GitHub's reported week timestamps and are not guaranteed to align with UTC. No stargazer identities are collected.
+
+The light SVG, dark SVG, source JSON, and renderer's MIT license are committed to the dedicated `star-history` branch. The README loads the SVGs from `raw.githubusercontent.com`; GitHub's image cache may add a short delay. The workflow does not change `main` or the website's `gh-pages` branch. Fetching, validation, and rendering finish before publication, so a failed run leaves the previous published chart available.
+
+To refresh manually, open the workflow, select **Run workflow**, and run it on `main`. For a local preview, check out the pinned Star History revision separately, install its root and backend dependencies using pnpm 9.15.9 with `--frozen-lockfile --ignore-scripts`, then run:
+
+```bash
+export STAR_HISTORY_RENDERER=/absolute/path/to/star-history-checkout
+"$STAR_HISTORY_RENDERER/backend/node_modules/.bin/tsx" scripts/update-star-history.mjs NVlabs/SoL-Pi /absolute/path/to/star-history-preview
+```
+
+For a higher API rate limit, supply `GITHUB_TOKEN` through the environment. Never put the token in a URL or command argument. Run generator tests with `npx vitest run tests/star-history.test.js`.

package/node_modules/@herbertgao/sol-pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbertgao/sol-pi",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Token-efficient context and tool extensions for Pi, maintained from NVlabs/SoL-Pi.",
   "keywords": [
     "pi-package",
@@ -27,11 +27,13 @@
     "assets",
     "docs/compatibility.md",
     "docs/configuration.md",
+    "docs/star-history.md",
     "scripts/check-pi-compat.mjs",
     "scripts/check-sol-pi-config.mjs",
     "agents-install.md",
     "README.md",
     "LICENSE",
+    "CONTRIBUTING.md",
     "SECURITY.md",
     "THIRD_PARTY_NOTICES.md",
     "sol-pi.example.json"
@@ -71,6 +73,6 @@
     "version": "0.1.0",
     "reviewedVersion": "0.1.0",
     "repository": "https://github.com/NVlabs/SoL-Pi",
-    "commit": "22277b7e0c3c46ba1259a6687f31fe39ade421a5"
+    "commit": "e1a586af0ad8956f42ae5b26bba20e48fbf30e00"
   }
 }

package/node_modules/@herbertgao/sol-pi/scripts/check-sol-pi-config.mjs

@@ -106,7 +106,7 @@ function validateConfig(value, requireAllEnabled) {
 function stringConfigValue(value, key, defaultValue) {
 	const configured = Object.hasOwn(value, key) ? value[key] : defaultValue;
 	if (typeof configured !== "string" || configured.trim().length === 0) fail(`${key} must be a non-empty string`);
-	return configured;
+	return configured.trim();
 }
 
 try {

package/node_modules/@herbertgao/sol-pi/src/sol-pi/config.ts

@@ -131,5 +131,5 @@ function stringConfigValue(
 	if (typeof value !== "string" || value.trim().length === 0) {
 		throw new Error(`SoL-Pi config ${key} must be a non-empty string: ${path}`);
 	}
-	return value;
+	return value.trim();
 }

package/node_modules/@herbertgao/sol-pi/src/sol-pi/extensions/action-fusion/file-queue.ts

@@ -9,17 +9,36 @@ import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const queueTails = new Map<string, Promise<void>>();
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/gu;
+const WINDOWS_SHELL_DRIVE = /^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i;
 
-function stripToolPathPrefix(filePath: string): string {
-	return filePath.startsWith("@") ? filePath.slice(1) : filePath;
+function normalizeToolPath(filePath: string): string {
+	const normalized = filePath.replace(UNICODE_SPACES, " ");
+	return normalized.startsWith("@") ? normalized.slice(1) : normalized;
+}
+
+/**
+ * Git Bash, MSYS, Cygwin, and WSL hand Pi paths like `/c/src/app.ts`. On
+ * Windows, Pi's built-in mutation tools convert those to a native drive path
+ * before touching the filesystem, so the queue and hash guard must convert them
+ * the same way or they address a file the mutation never wrote.
+ */
+export function normalizeWindowsShellPath(filePath: string): string {
+	if (process.platform !== "win32") return filePath;
+	if (!filePath.startsWith("/") || filePath.startsWith("//") || filePath.includes("\\")) return filePath;
+	const match = WINDOWS_SHELL_DRIVE.exec(filePath);
+	if (!match?.[1]) return filePath;
+	return `${match[1].toUpperCase()}:\\${match[2]?.replaceAll("/", "\\") ?? ""}`;
 }
 
 export function resolveToolPath(cwd: string, filePath: string): string {
-	const stripped = stripToolPathPrefix(filePath);
+	const stripped = normalizeWindowsShellPath(normalizeToolPath(filePath));
 	// Pi accepts file URLs; the queue and hash guard must use the same target.
 	const expanded = stripped.startsWith("file://") ? fileURLToPath(stripped) : stripped;
 	if (expanded === "~") return homedir();
-	if (expanded.startsWith("~/")) return resolve(homedir(), expanded.slice(2));
+	if (expanded.startsWith("~/") || (process.platform === "win32" && expanded.startsWith("~\\"))) {
+		return resolve(homedir(), expanded.slice(2));
+	}
 	return resolve(cwd, expanded);
 }
 

package/node_modules/@herbertgao/sol-pi/src/sol-pi/extensions/action-fusion/index.ts

@@ -17,6 +17,7 @@
  * This standalone version composes only Pi's public tool definitions.
  */
 
+import { mkdir, writeFile } from "node:fs/promises";
 import {
 	type BashToolOptions,
 	createEditToolDefinition,
@@ -42,6 +43,10 @@ const EDIT_THEN_RUN_DESCRIPTION =
 const WRITE_THEN_RUN_DESCRIPTION =
 	"Command to run next on this file after the write succeeds — e.g. run, build, start/restart, install, or check it; optional timeout in seconds. Skipped if the write fails; a non-zero exit is reported but keeps the write.";
 
+// Runtime-only annotation: Pi preserves symbol keys in getAllTools(), but JSON omits them.
+const WRITE_METADATA_OBSERVER = Symbol.for("herbertgao.pi.writeMetadataObserver");
+type WriteMetadataObserver = (toolCallId: string, path: string, write: () => Promise<void>) => Promise<void>;
+
 export interface ActionFusionOptions {
 	/** Optional programmatic bash overrides, primarily for tests and embedded runtimes. */
 	readonly bashOptions?: BashToolOptions;
@@ -82,6 +87,7 @@ export function createActionFusionExtension(options: ActionFusionOptions = {}):
 	return (pi: ExtensionAPI) => {
 		const editTemplate = baseEdit(process.cwd());
 		const writeTemplate = baseWrite(process.cwd());
+		let observeWrite: WriteMetadataObserver | undefined;
 
 		const editParameters = Type.Object({
 			...editTemplate.parameters.properties,
@@ -131,6 +137,14 @@ export function createActionFusionExtension(options: ActionFusionOptions = {}):
 		pi.registerTool<typeof writeParameters, undefined>({
 			...writeTemplate,
 			parameters: writeParameters,
+			annotations: Object.assign({}, writeTemplate.annotations, {
+				[WRITE_METADATA_OBSERVER]: (observer: WriteMetadataObserver) => {
+					// Custom operations may write remotely; local snapshots would be misleading.
+					if (options.writeOptions?.operations) return false;
+					observeWrite = observer;
+					return true;
+				},
+			}),
 			async execute(toolCallId, input, signal, onUpdate, ctx) {
 				const { then_run, ...writeInput } = input as typeof input & { then_run?: ThenRunInput };
 				const result = await executeMutationThenRun({
@@ -140,7 +154,24 @@ export function createActionFusionExtension(options: ActionFusionOptions = {}):
 					bashOptions: options.bashOptions,
 					signal,
 					ctx,
-					mutate: () => baseWrite(ctx.cwd).execute(toolCallId, writeInput, signal, onUpdate, ctx),
+					mutate: () => {
+						const observer = observeWrite;
+						const write = observer
+							? createWriteToolDefinition(ctx.cwd, {
+								operations: {
+									mkdir: async (dir) => {
+										await mkdir(dir, { recursive: true });
+									},
+									// Pi invokes this inside its mutation queue, so the snapshot is atomic with the write.
+									writeFile: (path, content) => observer(toolCallId, path, () => {
+										if (signal?.aborted) throw new Error("Operation aborted");
+										return writeFile(path, content, "utf8");
+									}),
+								},
+							})
+							: baseWrite(ctx.cwd);
+						return write.execute(toolCallId, writeInput, signal, onUpdate, ctx);
+					},
 				});
 				if (
 					then_run &&

package/node_modules/@herbertgao/sol-pi/src/sol-pi/extensions/action-fusion/then-run.ts

@@ -5,7 +5,7 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import { type BashToolOptions, createBashToolDefinition, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type BashToolOptions, createBashToolDefinition, type ExtensionToolContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { withFusedFileQueue } from "./file-queue.ts";
 
@@ -90,7 +90,7 @@ export async function executeMutationThenRun<TDetails>({
 	mutate: () => Promise<AgentToolResult<TDetails>>;
 	bashOptions: BashToolOptions | undefined;
 	signal: AbortSignal | undefined;
-	ctx: ExtensionContext;
+	ctx: ExtensionToolContext;
 }): Promise<AgentToolResult<TDetails>> {
 	return withFusedFileQueue(absolutePath, async () => {
 		let mutationResult: AgentToolResult<TDetails>;
@@ -113,6 +113,7 @@ export async function executeMutationThenRun<TDetails>({
 			// pi-lens-ignore: sql-injection
 			const bashResult = await bash.execute(`${toolCallId}:then_run`, thenRun, signal, undefined, ctx);
 			const output = resultText(bashResult);
+			if (bashResult.isError) throw new Error(output);
 			return {
 				...mutationResult,
 				content: [

package/node_modules/@herbertgao/sol-pi/src/sol-pi/extensions/observation-pack/observation.ts

@@ -100,7 +100,7 @@ export function createObservation(message: ToolResultMessage, runtimeRoot: strin
 	if (containsReducerReceipt(text)) return undefined;
 	const bytes = Buffer.byteLength(text, "utf8");
 	if (bytes <= THRESHOLD_BYTES) return undefined;
-	if (!runtimeRoot) throw new Error("Persistent SoL-Pi runtime directory is unavailable");
+	if (!runtimeRoot) throw new Error("SoL-Pi runtime directory is unavailable");
 
 	const contentHash = hash(text);
 	const id = `obs_${hash(`${message.toolName}\0${message.toolCallId}\0${contentHash}`).slice(0, 24)}`;