pi-cursor-sdk 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.5.0 - 2026-10-04
+
+### Breaking Changes
+
+- Bare `ctx.modelRegistry.complete(...)` and `ctx.modelRegistry.streamSimple(...)` calls are unsupported for Cursor models because they lack native session ownership receipts. Custom compaction and other integrations must use the owning AgentSession's stream path or an independent child AgentSession; bind/refresh/reload does not migrate bare calls. See [embedding migration guidance](README.md#embedded-sessions-report-concurrent-cursor-turns).
+
+### Changed
+
+- Refresh the SDK-derived fallback catalog to 45 models, including Claude Sonnet 5.5, GLM 5.3, and GLM 5.3 Flash. Preserve existing checkpoint-derived context windows.
+
+### Fixed
+
+- Isolate concurrent and nested in-process Cursor sessions, including direct compaction/tree/bug-report streams, bridge/replay state, pooled agents, storage, journals, and debug artifacts (#217, #234). Native request-header ownership receipts reject mismatched shared ModelRuntime calls with recovery guidance rather than choosing a sibling.
+- Keep cloud archive/delete authority, intents, and results in the command's originating session branch across auth/SDK waits and owner reload/shutdown; unstarted child reload/shutdown no longer closes a parent's live pool.
+- Restore native replay wrapper ownership after `/new`, `/resume`, reloads, and session switches without replacing third-party tools (#203).
+- Apply configured `models.json` cost rates to mapped token usage with Pi's native pricing helper; default rates and Cursor billed amounts are unchanged (#230, #231; thanks @TianZuo555).
+- Resolve the installed Cursor SDK native parser package before SDK initialization, preserving explicit `CURSOR_TREE_SITTER_VENDOR_DIR` overrides (#232).
+- Improve diagnostics with bounded, scrubbed structured errors and causes without diagnosing loader or ambiguous session-authentication failures as invalid API keys. The underlying compiled/embedded-host and idle-session failures reported in #228, #233, and #247 remain open.
+- Bound bridge tool-call IDs while preserving unique calls and matching results (#237; thanks @gwatkins-arista).
+- Keep skill activation callable with its catalog/descriptions intact and a stable system prompt (#244). Each registered session owns its skill catalog, so a sibling's same-named skill or catalog reset cannot change activation.
+- Map SDK `reasoning_effort` controls to Pi thinking without changing SDK defaults.
+- Repair context floors using the owning native projection, actual request equivalence, model compatibility, and source order after compaction/context edits—not timestamps, summary-looking text, or `tokensBefore`. Keep fresh LOCAL SDK usage authoritative and native components coherent so cumulative bills cannot trigger repeated false compaction.
+- Isolate LOCAL compaction/tree summaries in fresh text-only agents and temporary stores, without conversation tools/MCP/bridge/manifest/replay, plan mode, or resume lineage. Await cleanup before summary terminal emission; ordinary capabilities remain intact.
+- Preserve every raw turn and original reported/terminal snapshot separately from disjoint public billed data in durable origin/branch journals. Remove process-only UUID watermarks; retain delayed/revised/aggregate-only/error/abort/reopen facts without inventing branch attribution.
+
+### Added
+
+- `/cursor-usage` view, bounded public billing refresh, exclusive private JSON export, and recovery help, leaving Pi's default footer and configured-price estimates intact. Reports unavailable/pending settlement, shared or unknown history, journal gaps, other-branch facts and unclaimed records honestly. No private billing fallback or native invoice-total claim.
+- Offline working-tree qualification for exact official Pi releases without committing, including native compaction, summary cleanup and billing regressions.
+
 ## 0.4.0 - 2026-09-26
 
 ### Breaking Changes

package/README.md

@@ -51,7 +51,7 @@ If pi started without a key, run `/cursor-refresh-models` after `/login` to refr
 ## Requirements
 
 - Node.js 24+
-- pi-cursor-sdk 0.4.0 requires official Pi 0.87.1 or later. Official Pi 0.87.1/latest and current `fitchmultz/pi` main are compatibility targets; the currently validated local `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` packages are 0.87.1
+- pi-cursor-sdk 0.5.0 requires official Pi 0.87.1 or later. Official Pi 0.87.1/latest and current `fitchmultz/pi` main are compatibility targets; the exact development `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` packages are 0.99.1
 - optional Pi and TypeBox peer metadata uses `"*"` ranges per Pi package guidance
 - a Cursor SDK API key saved through `/login`, available as `CURSOR_API_KEY`, or passed with pi's `--api-key`
 
@@ -212,13 +212,14 @@ Cursor `context` becomes a pi-visible model variant because it changes pi's nati
 
 All Cursor SDK models should be treated as thinking-capable Cursor models. The `thinking` column in `pi --list-models` is narrower: it only means pi can control a Cursor SDK thinking parameter for that model.
 
-For models where Cursor exposes `reasoning`, `effort`, or boolean `thinking` parameters, pi's native thinking controls map to Cursor SDK params:
+For models where Cursor exposes `reasoning`, `effort`, `reasoning_effort`, or boolean `thinking` parameters, pi's native thinking controls map to Cursor SDK params:
 
 - `reasoning=none|low|medium|high|extra-high`
 - `effort=low|medium|high|xhigh|max`
+- `reasoning_effort=low|medium|high`
 - `thinking=false|true` for boolean thinking models
 
-Pi `xhigh` maps to Cursor `xhigh` or `extra-high`; Pi `max` maps only to a distinct Cursor `max` value.
+Pi `xhigh` maps to Cursor `xhigh` or `extra-high`; Pi `max` maps only to a distinct Cursor `max` value. Gemini 3.8 Flash exposes only `low`, `medium`, and `high` through `reasoning_effort`; its SDK default remains `high`.
 
 For Claude models with both `thinking` and `effort`, pi thinking `off` sends `thinking=false` and omits `effort`.
 
@@ -226,7 +227,7 @@ For Claude models with both `thinking` and `effort`, pi thinking `off` sends `th
 
 In `pi --list-models`, `thinking=no` means pi cannot control the model's thinking level with `--thinking`, a final `:medium` model suffix, or shift+tab. It does not mean the Cursor model cannot think.
 
-Some Cursor SDK models do not expose a `reasoning`, `effort`, or `thinking` parameter for the extension to set. Cursor thinking is still enabled/supported by the model, and Cursor may still emit thinking deltas. The extension surfaces those deltas through pi's native thinking rendering when the SDK emits them.
+Some Cursor SDK models do not expose a `reasoning`, `effort`, `reasoning_effort`, or `thinking` parameter for the extension to set. Cursor thinking is still enabled/supported by the model, and Cursor may still emit thinking deltas. The extension surfaces those deltas through pi's native thinking rendering when the SDK emits them.
 
 ## Fast mode
 
@@ -293,7 +294,7 @@ Change the session mode interactively:
 
 Maintainers can run `/cursor-tools` in a Cursor model session to print the current bridge enablement, bootstrap manifest enablement, effective `PI_CURSOR_SETTING_SOURCES`, and callable-surface snapshot (host tools summary plus current `pi__*` names). See [Cursor dogfood checklist](docs/cursor-dogfood-checklist.md).
 
-When a new local Cursor SDK agent is created, the extension seeds the mode through `Agent.create({ mode })`. The extension also sends the effective Cursor mode on every `agent.send(..., { mode })` call so `/cursor-mode` and `--cursor-mode` remain the source of truth even when a pooled SDK agent is reused.
+For conversation agents, the extension seeds the mode through `Agent.create({ mode })` and sends it on each `agent.send(..., { mode })` so `/cursor-mode` and `--cursor-mode` remain the source of truth when a pooled agent is reused. LOCAL compaction/tree summary agents always use text-only `agent` mode.
 
 Cursor SDK `plan` mode can produce plan-oriented output and Cursor todo/plan activity, but those replay cards remain display-only. They do not drive pi's plan-mode extension, pi todos, or active tool state.
 
@@ -419,7 +420,7 @@ If the agent intent cannot be persisted, pi does not send; if the returned run c
 
 `/cursor-cloud list`, `/cursor-cloud archive <bc-agentId>`, and `/cursor-cloud delete <bc-agentId> --yes` only accept exact recorded `bc-` cloud IDs.
 
-Archive/delete require resolved Cursor auth, fsync a durable intent before the SDK mutation, and fsync a durable success result afterward; an unresolved intent blocks retries and directs manual dashboard inspection instead of guessing whether an irreversible request completed.
+Archive/delete require resolved Cursor auth and unchanged originating session/branch authority before SDK work, fsync a durable intent before the mutation, and fsync its actual success result afterward. Once started, the result stays in the original journal even if that owner changes branch, reloads, or shuts down; it is not mirrored into a replacement branch. An unresolved intent blocks retries and directs manual dashboard inspection instead of guessing whether an irreversible request completed.
 
 ### Cloud boundaries
 
@@ -451,6 +452,30 @@ Only enabled local safety values are passed to `Agent.create({ local })`; false/
 Images from the latest user message are forwarded to Cursor. Historical images are kept out of the transcript and appear only as `[image omitted from transcript]` placeholders, so follow-up questions about an earlier image should reattach the image or include a textual description. The extension advertises `text` and `image` input for Cursor models because Cursor's SDK accepts image messages and Cursor models are expected to support them.
 
 
+## Context, compaction, and Cursor usage
+
+Pi's default footer and `/stats` remain native. Assistant usage components are additive and describe the current context; cumulative Cursor billing never drives Pi's overflow or compaction checks. When fresh LOCAL SDK usage is unavailable, a historical occupancy floor is used only if the owning native projection matches the actual request and the same-model measurement follows the latest native compaction or context edit. Quoted summary text and wall-clock timestamps do not establish a boundary.
+
+LOCAL compaction and tree summaries use a fresh text-only SDK agent: `tools: []`, no ambient settings or MCP, no pi bridge, no tool manifest/replay, `agent` mode even when the conversation uses `plan`, and a temporary store removed on completion, cancellation, or failure. Ordinary turns retain their configured capabilities. Cloud does not support the same tool restriction; bug-report streams have no public purpose hook and retain ordinary capabilities rather than being guessed from their text. Direct and summary cancellation depends on SDK settlement; SDK 1.0.32 provides no completion deadline, so a controller that never settles can leave cancellation waiting.
+
+Use the separate accounting view for recorded Cursor facts:
+
+```text
+/cursor-usage
+/cursor-usage refresh
+/cursor-usage export cursor-usage.json
+/cursor-usage help
+```
+
+- **View:** current-branch corrected LOCAL raw turns, original SDK telemetry, terminal status, and whole-agent public billing observations. Raw turns, wait/handle snapshots, and bills overlap; they are never added together. Cloud raw normalization remains unqualified.
+- **Refresh:** public `Agent.getUsage()` only, up to 32 recorded agents with a five-second limit each; no model sends or automatic polling. An unavailable endpoint remains unavailable—there is no private dashboard fallback.
+- **Export:** creates a new private JSON file without replacing existing files. It contains IDs, lineage, usage, configured pricing, and observation status, not prompts or tool content. Inspect local paths/identifiers before sharing.
+- **Honest limits:** observations may lag or revise; they are not final invoices. Known aggregate usage/cost stays visible even when inherited run history is incomplete; full run snapshots and aggregate-only remainders are withheld rather than invented. Unavailable refreshes retain explicitly labeled latest-known observations. LOCAL client run IDs do not join billing UUIDs. Resumed history without a known creation record is marked unknown; shared-lineage and multiple-origin observations are not billed to the current branch. Current official Pi has no public extension API for complete native invoice totals.
+
+Before a send, the extension records a unique public native branch claim and a validated, fsynced intent. Usage journals live beside the Pi session JSONL as `cursor-usage-<session-id-hash>.journal`; they retain late facts for the original owner without writing a switched session or sibling branch. Fileless sessions are explicitly ephemeral. Missing or torn inherited journals remain explicitly incomplete. Known claims outside the current branch are shown as other-branch facts; same-directory, same-ID recovery with a lost initial claim is shown as unclaimed history. Neither is newly recognized current-branch spend. If every origin reference is lost after moving directories, the extension cannot discover that history without unsafe scanning.
+
+Each origin journal has a **16 MiB ceiling**. Persistence failure before a send prevents that send. Later failure may warn once while the original owner is current; `/cursor-usage` exposes incomplete accounting without changing the response's outcome. For a torn trailing frame, view/export preserves the validated prefix and reports the incomplete journal; further appends fail closed without changing its bytes. For ceiling or torn-tail recovery, export and retain the old session/journal, then fork the conversation into a new native session or start a new session. Do not delete or truncate the journal to continue an old agent lineage. `/cursor-usage help` also documents this recovery.
+
 ## Cursor provider tool contract
 
 See [Cursor tool surfaces in pi](docs/cursor-tool-surfaces.md) for a concise guide to callable vs display-only tools, MCP catalog limits, JSONL ID patterns, and how pi toggles differ from Cursor ambient MCP.
@@ -511,11 +536,15 @@ On bootstrap sends, a compact **callable tool surfaces** block is injected into
 
 `PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1` is off by default and emits typed, allowlisted, scrubbed single-line JSONL records to `process.stderr`. These records are operational diagnostics, not anonymous telemetry: they intentionally include tool names, safe correlation IDs, bridge run state, exposed pi↔MCP name pairs, queued requests, result resolution, rejection, cancellation, and pending counts. They must not include endpoint URLs, endpoint path components, endpoint tokens, raw args/results, stdout/stderr payloads, file contents, Cursor settings output, API keys, bearer tokens, cookies, session credentials, or secrets. Do not enable or share bridge debug logs where tool names themselves are sensitive.
 
-### Maintainer platform smoke release gate
+### Maintainer cost-conscious verification
+
+Run offline/faux tests, native contracts, type checks, builds, and package checks first; preserve offline cross-platform CI. Reuse retained evidence for unchanged tested inputs. Real Cursor calls are only for the smallest meaningful changed-behavior check that needs real-service proof, on one representative environment. Docs/metadata-only changes need no paid testing. Do not replay full paid campaigns, run host matrices merely for matrix coverage, or automatically retry paid failures. Automated Cursor PR reviews continue unchanged.
+
+No paid Cursor Cloud testing for generic PRs or releases. Only a PR or issue explicitly focused on Cursor Cloud may use a necessary focused Cloud check; incidental Cloud code changes do not qualify. Cloud product capabilities, offline contracts, and explicit smoke commands remain available. Even for Cloud-focused work, the multi-lane `npm run smoke:cloud` is optional, not an unconditional gate; selected checks retain run/evidence and agent/repository cleanup requirements.
 
-For Cursor provider/runtime changes, the canonical local release and pre-commit gate is the local platform smoke gate in [Platform smoke](docs/platform-smoke.md): run `npm run smoke:platform:all`, which runs doctor before the target matrix. Cloud-runtime changes must also run `npm run smoke:cloud`. The platform gate validates macOS, Ubuntu, and Windows native through Crabbox using packed installs, a required HTTP/1.1/SSE provider-turn lane, PTY/ConPTY ANSI capture, host-rendered xterm/PNG evidence, JSONL assertions, bridge diagnostics, usage/cache checks, abort cleanup, artifact manifests, and redaction scans. After each platform run, `.artifacts/platform-smoke/latest.json` points to the latest useful evidence paths. Do not mark a release ready with optional, deferred, mostly-passing, or unobserved platform smoke checks outstanding.
+[Platform smoke](docs/platform-smoke.md) documents existing single-suite/single-target commands and the optional comprehensive `npm run smoke:platform:all` matrix. The matrix uses packed installs, PTY/ConPTY ANSI capture, host-rendered xterm/PNG evidence, JSONL assertions, bridge diagnostics, usage/cache checks, abort cleanup, artifact manifests, and redaction scans. `.artifacts/platform-smoke/latest.json` points to each platform run's evidence. Report exactly the scope observed, not unrun matrix coverage.
 
-The older live smoke helpers remain useful for inner-loop debugging and focused visual audits, not as the release gate. Use [Cursor live smoke checklist](docs/cursor-live-smoke-checklist.md), `npm run smoke:visual`, `npm run smoke:live`, or direct `pi --approve -e . --cursor-no-fast --model cursor/grok-4.6` runs when iterating on a specific TUI/card/runtime issue before the full platform gate. `npm run smoke:visual` captures an offscreen PTY rendered through browser/xterm and saved as PNG screenshots with Playwright, or with `agent_browser` from the generated HTML when available. Its default matrix is native replay only: native replay registration is forced on, Cursor setting sources are disabled, the pi bridge is off, overlapping built-in pi tools are not exposed, and inherited Cursor SDK event-debug artifact env is cleared; `--event-debug` writes to a deterministic debug directory under the visual output directory. The visible TUI/output, rendered screenshots, scrubbed diagnostics, and persisted JSONL must agree. See [Cursor testing lessons](docs/cursor-testing-lessons.md) for auth.json seeding, isolated `/tmp` harness layout, JSONL replay-error scans, and other regression traps.
+The older live smoke helpers remain useful for inner-loop debugging and focused visual audits, not as the release gate. Use [Cursor live smoke checklist](docs/cursor-live-smoke-checklist.md), `npm run smoke:visual`, `npm run smoke:live`, or direct `pi --approve -e . --cursor-no-fast --model cursor/grok-4.6` runs only when a changed TUI/card/runtime behavior needs new live evidence. Select one relevant check rather than executing every helper. `npm run smoke:visual` captures an offscreen PTY rendered through browser/xterm and saved as PNG screenshots with Playwright, or with `agent_browser` from the generated HTML when available. Its default matrix is native replay only: native replay registration is forced on, Cursor setting sources are disabled, the pi bridge is off, overlapping built-in pi tools are not exposed, and inherited Cursor SDK event-debug artifact env is cleared; `--event-debug` writes to a deterministic debug directory under the visual output directory. The visible TUI/output, rendered screenshots, scrubbed diagnostics, and persisted JSONL must agree. See [Cursor testing lessons](docs/cursor-testing-lessons.md) for auth.json seeding, isolated `/tmp` harness layout, JSONL replay-error scans, and other regression traps.
 
 ### Maintainer Cursor SDK event capture
 
@@ -544,7 +573,8 @@ Actual Cursor runs still need a key from `/login`, `CURSOR_API_KEY`, or `--api-k
 - **AGENTS.md / CLAUDE.md are not duplicated on Cursor models when Cursor loads the same rules.** Pi discovers global and project context files (`AGENTS.md`, `CLAUDE.md`, and case variants) unless you start with `-nc`. On `cursor/*` models the extension removes only `<project_instructions>` blocks that overlap Cursor `settingSources` via the `before_agent_start` hook: `user` for `~/.pi/agent/AGENTS.md`, `project` for repo/parent `AGENTS.md` and `CLAUDE.md` (verified Cursor behavior: local agents load project `AGENTS.md` and `CLAUDE.md` alongside Cursor rules). `~/.pi/agent/CLAUDE.md` is not stripped (Cursor user rules use `~/.claude/CLAUDE.md`, not pi's agent dir). With `PI_CURSOR_SETTING_SOURCES=none` or `plugins`-only, pi context is left intact. Set `PI_CURSOR_PRESERVE_PI_AGENTS_MD=1` to keep duplicate injection.
 - **Max Mode is not a manual pi variant.** Cursor's SDK may enable Max Mode automatically for models that require it. This extension only advertises exact context-window variants that the SDK catalog exposes and otherwise uses conservative SDK-derived default/non-Max context windows.
 - **Output token limits are conservative.** Cursor SDK model metadata does not currently expose output token limits directly.
-- **Local token usage uses Cursor SDK data when safely attributable.** For local turns with in-time SDK usage, pi records the latest per-turn raw `turn-ended` `inputTokens`, `outputTokens`, `cacheReadTokens`, and `cacheWriteTokens`; that raw local shape keeps full-prompt `inputTokens` with cache as a partition (published SDK `toTokenUsage` totals differ), so pi maps disjoint components (`input = inputTokens - cacheRead - cacheWrite`, plus cache fields) and sets `totalTokens = inputTokens + outputTokens` for occupancy/compaction. If the local SDK reports no usage in time, the extension falls back to local `input/output` activity estimates while setting `totalTokens` to the current replayable context estimate so the footer/compaction percentage does not collapse after split tool turns. Later usage for that live run is ignored rather than risk applying stale usage to the wrong pi turn. Raw cloud usage remains display-only until its field semantics are independently captured. Cursor SDK cost is not exposed, so pi cost remains zero/absent.
+- **Local token usage uses Cursor SDK data when safely attributable.** In-time LOCAL raw `turn-ended` usage keeps full-prompt input with cache as a partition: pi maps `input = inputTokens - cacheRead - cacheWrite`, retains the cache fields, and sets `totalTokens = inputTokens + outputTokens`. Fallback components and total describe the same estimated current context. Late SDK usage is not retroactively applied to an emitted pi message, but every raw turn remains separately recorded by the [Cursor usage ledger](#context-compaction-and-cursor-usage). Raw Cloud telemetry is retained without assuming LOCAL normalization.
+- **Configured cost is separate from Cursor billing.** Discovered models register zero rates. `models.json` per-million `cost` overrides, including tiers, use pi's native pricing helper on each emitted message's coherent context components. Fallback has no inferred cache split; split-message estimates can differ from actual internal request pricing. Public `getUsage()` billed input/cache/output categories are already disjoint—cache is not subtracted again—and optional `cost.rawCostCents` / `cost.chargedCents` are retained separately in floating-point cents. Neither these revisable observations nor native configured estimates promise invoice reconciliation.
 
 ## Troubleshooting
 
@@ -552,7 +582,7 @@ Actual Cursor runs still need a key from `/login`, `CURSOR_API_KEY`, or `--api-k
 
 You may be seeing fallback startup models or a missing/invalid Cursor SDK API key. Cursor Agent CLI/Desktop login is not reused by this extension. In interactive pi, run `/login`, choose `Use an API key`, choose `Cursor`, paste the key, then run `/cursor-refresh-models`.
 
-When a Cursor run fails after auth is configured, pi now surfaces scrubbed provider detail instead of only `Cursor SDK run failed`. Generic SDK failures include safe run metadata such as model id, a short run id prefix, and duration when available, and are phrased as pi retryable provider errors so automatic retry/backoff can recover transient SDK failures.
+When a Cursor run fails after auth is configured, pi surfaces scrubbed provider detail instead of only `Cursor SDK run failed`. Structured errors retain bounded name, code, message, and up to two nested causes; headers and other object fields are not displayed. Generic completed-run failures include safe run metadata such as model id, a short run id prefix, and duration when available, and are phrased as pi retryable provider errors so automatic retry/backoff can recover transient SDK failures. Unknown startup failures, module-loading errors, and ambiguous session authentication errors are not diagnosed as invalid API keys. Explicit missing, invalid, or revoked API-key errors still show key setup guidance.
 
 Aborted runs now include a likely cause when determinable, for example `Cancelled: prompt interrupted.` for user cancel or `Cancelled: Cursor SDK run was cancelled.` for SDK-side cancellation.
 
@@ -571,6 +601,20 @@ Or run a one-shot command:
 pi --api-key "your-key" --model cursor/grok-4.6 -p "Say ok only"
 ```
 
+### Embedded sessions report concurrent Cursor turns
+
+In-process sessions using independent `ModelRuntime` instances (the SDK default on supported Pi hosts) support concurrent turns, children launched inside parent tools, and direct compaction/tree/bug-report summaries. Each provider registration captures its own session, bridge, storage, and debug scope. Fork-inherited tool-result IDs cannot drain a parent's live run; replay wrappers reject foreign-owner or wrong-tool results without consuming the original card or executing work. Native request-header receipts verify the calling session before SDK/storage work, including auxiliary streams. Explicitly sharing a `ModelRuntime` overwrites its Cursor registration: requests from another session fail closed rather than entering the sibling's scope. Use independent runtimes, or run `/cursor-refresh-models`/reload to restore the intended registration. A not-yet-bound or shut-down provider closure cannot send. **Migration from 0.4.0:** bare `ctx.modelRegistry.complete(...)` and `ctx.modelRegistry.streamSimple(...)` calls lack the native receipt and are unsupported for Cursor, including custom compaction integrations; bind/refresh/reload does not fix that path. Use the owning AgentSession's stream path or an independent child AgentSession. CLI flags and their one-shot local-force consumption remain owned by each embedded session runtime across reload. Cursor SDK HTTP/1.1 transport configuration and environment/user defaults remain process-global; branch preferences are session-scoped, not independent SDK transport configurations. See [multi-session embedding semantics](docs/cursor-model-ux-spec.md#multi-session-embedding).
+
+### Native shell parsing or module loading fails
+
+Before loading the SDK, the extension resolves the installed `@cursor/sdk-<platform>-<arch>` package relative to `@cursor/sdk` and supplies its `vendor` directory through the SDK's `CURSOR_TREE_SITTER_VENDOR_DIR`. This lets native Bash parsing work when Pi's launcher and extension live in separate installation trees. The platform package must be installed; the extension does not download or bundle replacement native binaries.
+
+An explicitly set `CURSOR_TREE_SITTER_VENDOR_DIR` is left untouched. Use an absolute path to a vendor directory containing both `tree-sitter` and `tree-sitter-bash`, or unset it to use package-relative discovery. Empty and relative overrides are also preserved; the SDK decides whether to use them or its own fallback lookup.
+
+The automatically selected path is process-wide and inherited by bash commands and child Pi processes. A child running another extension install or worktree treats that inherited value as an explicit override, even if the parent's install has moved or been deleted. To rediscover the child's own parser package, launch it with `env -u CURSOR_TREE_SITTER_VENDOR_DIR pi -e .` (or remove the variable from the child environment on Windows). Alternatively, set an absolute vendor path for the child's install. Inherited overrides are not validated or replaced automatically.
+
+A `ResolveMessage`, missing module, or missing `protoBase64` export is a loader problem, not evidence of a bad API key. Reports involving compiled Bun Pi and embedded hosts remain open; this native-path repair does not change their dependency loading graph. An npm-installed Node Pi is the known working control. Likewise, preserving the reported idle-session `Authentication error` does not establish why an hour-idle session fails or promise automatic recovery.
+
 ### `pi --list-models cursor` shows no Cursor models
 
 Confirm the package is installed:
@@ -681,13 +725,21 @@ Cursor native replay is a display enhancement for TUI sessions and structured JS
 
 ## Development
 
-The source qualification baseline is official Pi **0.87.1**, with official Pi latest and current `fitchmultz/pi` main as compatibility targets, optional wildcard Pi/TypeBox host peers, and exact Cursor SDK **1.0.32**. The currently validated local Pi packages are `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` 0.87.1. Run `npm ci --ignore-scripts` then `npm run check:compat` in an empty HOME/agent profile for credential-free qualification. This builds the manifest entry, runs existing type/unit/package checks, and tests the compiled provider's registration plus production prompt shaping against native Pi transcript/tool transitions. Replay arguments must match their JSON stream deltas. Tests use no live Cursor service.
+The source qualification baseline is official Pi **0.99.1**, with official Pi latest and current `fitchmultz/pi` main as compatibility targets, optional wildcard Pi/TypeBox host peers, and exact Cursor SDK **1.0.32**. The exact development Pi cohort is 0.99.1, with host TypeBox 1.3.27. Run `npm ci --ignore-scripts` then `npm run check:compat` in an empty HOME/agent profile for credential-free qualification. This builds the manifest entry, runs existing type/unit/package checks, and tests the compiled provider's registration plus production prompt shaping against native Pi transcript/tool transitions. Replay arguments must match their JSON stream deltas. A second native contract runs the registered Cursor provider with only its external SDK transport/storage substituted: real loopback bridge execution, display-only replay, persisted usage, incremental sends, tree navigation, compaction, request-boundary steering, abort and reload/disposal. Tests use no live Cursor service.
 
 TypeScript 7 builds and checks package types. `@typescript/typescript6` is dev-only and used solely by the AST architecture test because TypeScript 7 does not expose a stable compiler API. Vitest 5 runs with `clearMocks: true` by default.
 
 Pull-request CI runs that suite once, then checks the installed package offline with the oldest supported official Pi release, the current official release, and a source-built revision of the Pi fork. It checks both npm and Git installations without starting a Cursor model turn. The selected official version and fork commit are printed in the check log. Separate macOS and Windows jobs install with lifecycle scripts, load `node-pty`, and run the platform-build test, typecheck, and pack checks on Node 24.
 
-This is not Cursor authentication, desktop/cloud execution, visual, or all-platform release proof. The existing `smoke:platform:all` and applicable `smoke:cloud` gates remain required; a passing compatibility check does not make a runtime change release-ready. Older advertised Pi/Node floors require their own matrix evidence.
+For authorized uncommitted repairs, qualify an isolated immutable working-tree snapshot without committing:
+
+```bash
+node scripts/ci-compatibility.mjs --working-tree --official-only --versions 0.87.1,0.99.1,1.0.2
+```
+
+This builds and packs the snapshot, checks package loading, and exercises actual official native provider/session flows. The default invocation still requires a clean checkout and includes the maintained fork. `--help` documents selection and exit codes.
+
+This is offline compatibility proof, not Cursor authentication, desktop/cloud execution, visual, or all-platform live proof. Add only necessary changed-behavior live evidence under the [cost-conscious verification policy](#maintainer-cost-conscious-verification); the comprehensive paid matrix is optional, and paid Cloud testing is restricted to explicitly Cursor Cloud-focused PRs/issues. Older advertised Pi/Node floors require their own offline compatibility evidence.
 
 Run checks:
 

package/dist/context-window-cache.js

@@ -4,7 +4,6 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { BUNDLED_CONTEXT_WINDOWS } from "./bundled-context-windows.js";
 import { asRecord } from "./cursor-record-utils.js";
 const CONTEXT_WINDOW_CACHE_FILE = "cursor-sdk-context-windows.json";
-let userContextWindowOverrideLoadCount = 0;
 function getCachePath() {
     return join(getAgentDir(), CONTEXT_WINDOW_CACHE_FILE);
 }
@@ -26,7 +25,6 @@ function parseContextWindowCacheFile(value) {
     };
 }
 function loadUserContextWindowOverrides() {
-    userContextWindowOverrideLoadCount += 1;
     const path = getCachePath();
     const overrides = new Map();
     if (!existsSync(path))
@@ -85,8 +83,4 @@ export function saveCachedContextWindow(modelId, contextWindow) {
 }
 export const __testUtils = {
     getCachePath,
-    getUserContextWindowOverrideLoadCount: () => userContextWindowOverrideLoadCount,
-    resetUserContextWindowOverrideLoadCount: () => {
-        userContextWindowOverrideLoadCount = 0;
-    },
 };

package/dist/context.js

@@ -324,6 +324,14 @@ export function buildCursorIncrementalPrompt(context, options = {}) {
     const parts = applyPromptBudget(sectionsBeforeMessages, latestUserMessageSections, [getCursorToolTailGuardText(options)], latestUserMessageIndex, budgetOptions);
     return { text: parts.join(SECTION_SEPARATOR), images };
 }
+/** Native compaction/tree instructions are already a complete summarization request. */
+export function buildCursorSummaryPrompt(context) {
+    const { systemPrompt } = resolveCursorPiContext(context);
+    const sections = normalizePiContextMessages(context.messages).map(formatMessage).filter((text) => text !== undefined);
+    if (systemPrompt)
+        sections.unshift(`System instructions from pi:\n${systemPrompt}`);
+    return { text: sections.join(SECTION_SEPARATOR), images: [] };
+}
 export function buildCursorPrompt(context, options = {}) {
     const sectionsBeforeMessages = [getCursorToolBoundaryText({
             agentMode: options.agentMode,