pi-cursor-sdk 0.5.0 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## 0.5.3 - 2026-10-07
+
+### Changed
+
+- Upgrade the exact unbundled Cursor SDK and five optional platform pins to 1.0.37. Keep the SDK 1.0.36 catalog capture from 2026-10-06 and private hook canary attributed to their historical version.
+- Refresh the fallback catalog from the authenticated SDK 1.0.37 catalog-only observation on 2026-10-07: 46 models, adding Claude Haiku 5.5 (`claude-haiku-5-5`) with 20 thinking/context/effort variants while preserving all 45 prior model records. The 33 bundled checkpoint-derived entries remain unchanged; no Agent/model turn or Cloud run was performed.
+
+### Fixed
+
+- Map boolean `thinking` combined with either `effort` or `reasoning_effort` through native thinking controls. Haiku 5.5 now exposes all five catalog-supported enabled effort levels at both `@300k` and `@1m`; `off` sends `thinking=false` without the effort parameter. Verified offline against the captured SDK 1.0.37 catalog; no Agent/model turn or Cloud run was performed.
+- Select the declared TypeScript 7 entrypoint explicitly for all typechecks, matching the build and avoiding npm `tsc` shim collisions.
+- Separate SessionManager-owned runtime scopes from unchanged durable identities. A same-file sibling's reload/tree/shutdown no longer closes another manager's pool or pending bridge run; process-local claims exclude live handles from resume and cleanup (#282 reproduced trigger, not the original reporter's full qualification).
+- Label structured tool history as historical request/result/error without declaring unmatched requests completed. Preserve prose, IDs, arguments, errors and raw history; do not synthesize tool calls, strip narration or automatically resend effects (#257 mitigation).
+- Make `/cursor-tools` report current-registry exposure eligibility, not live-run connectivity. Add opt-in validated initialization and catalog-handler output receipts with explicit client/model/health ceilings (#206 diagnostics, not Windows reporter qualification).
+
+### Security
+
+- Update development-only transitive `source-map-js` to 1.2.2 for its event-loop denial-of-service fix.
+
+### Verification and limits
+
+- Document SDK 1.0.37's new public `computerUse` output through the existing bounded generic Cursor activity/summary fallback, without dedicated action/screenshot presentation or a new public local execution option.
+- Record SDK 1.0.37's vendored HTTP/2 ping/response-iteration and local retry-classification source changes. Public controls, bearer/lease/reload mechanisms, LOCAL ID/inherit-only custom agents and inspected storage layouts remain unchanged; internal definition-only MCP setters are not supported options. These source comparisons do not resolve the original #247 authentication cause, #339 signal sender, #173 rtk behavior, #233 Windows loader or #206 readiness reports.
+- Exercise real public installed-SDK first-send linking through a blocked key-exchange boundary, with a request-time missing-module negative control. Native SDK-substituted session tests remain separate; neither proves authenticated inference or every embedded loader.
+- Clarify inspected SDK hook/parser/authentication mechanisms and remaining reporter-only unknowns (#173, #339, #247, #233). Public commit/PR attribution controls remain absent (#302); no SDK-internal patch or paid test campaign is added.
+
+## 0.5.2
+
+### Fixed
+
+- Pair all shared CI/release workflow invocations, automation inputs, and checkouts at one reviewed revision. The shared fork producer now uses the fork's canonical artifact-set API; the existing host consumer reads the receipt's relative tarball paths and verifies their hashes. Preserve once-resolved latest official/fork targets, offline platform jobs, and manual npm approval.
+- Carry forward the Grok 4.7 selection fix from #344 (mirroring #343 by @LucasAIBuilder): omit only an outgoing `context` equal to the base catalog's default-variant context, including unambiguous aliases and fast/slow variants. Keep model metadata, non-default contexts, effort, and speed explicit; omit nothing when no catalog default context exists. The reporter describes an SDK 1.0.36 LOCAL reject/pass pair; that report is not qualification of this release candidate or Cloud behavior.
+
+### Changed
+
+- Align locked development Pi snapshots and their resolved transitives to 1.0.4. These reproducible build inputs are not qualification targets; Node 24+, official Pi 0.87.1+, and optional wildcard Pi/TypeBox peers remain unchanged.
+- Include the unpublished 0.5.1 backlog changes below: exact unbundled SDK/platform 1.0.36, static source/compiled-loader graph, native prompt/image and usage ownership, pending bridge-call protection, shell correlation, bounded diagnostics, trusted SDK-native subagents, and persistent LOCAL store roots with migration/cleanup guards. Preserve Pi's native footer, full question UI opt-in (`PI_CURSOR_ASK_QUESTION=1`, off by default), ordinary explicit Cloud capability, and the documented limits. This is not another SDK upgrade or evidence that all open reporter/service issues are fixed.
+
+## 0.5.1 (unpublished source history)
+
+These changes are carried into 0.5.2; this section does not record a successful npm publication. Historical candidate evidence remains bound to its original source, version, and run.
+
+### Added
+
+- Support trusted config-defined SDK-native subagents with independent catalog selections and content-digest session invalidation (adapted from #208 by Sam Armstrong). SDK 1.0.36 LOCAL conversion retains only model ID/inherit, not thinking/fast/context parameters; Cloud retains selections without delegated service-honoring proof. LOCAL compaction/tree summaries remain definition-free.
+- Add persistent LOCAL SQLite roots through `PI_CURSOR_SDK_STATE_ROOT` or user `local.storeRoot`, with environment precedence and captured private absolute-path selection (adapted from #236 by @gwatkins-arista). Project/session/CLI roots are excluded; fileless and LOCAL summary stores remain temporary. Root changes retain old history, without automatic copy, merge or deletion.
+
+### Fixed
+
+- Preserve genuine persisted native user input, following notices as background context, and current images across incremental, budgeted bootstrap and offline Cloud fresh prompts (#229). Custom-only continuation does not resend old requests/images; payload/order-changing transforms remain conservative.
+- Protect each live run's pending pi bridge calls, including human questions, from idle disposal. After the last owned call settles and the drain lease ends, restart the full configured window, including previously armed cleanup. Explicit cancellation, compaction, shutdown and bridge/MCP deadlines remain independent (#281).
+- Filter verified bounded SDK bootstrap frames through one byte-preserving process sink retained through deferred SDK completion and bridge/replay turns. Known plugin-confinement/parser warnings escape the creation-only mute as bounded owner-scoped recovery notices and non-model session entries, without raw paths (#284/#232). Plugin confinement remains enforced; unknown warnings are not universally filtered.
+- Keep Cursor SDK and bridge imports in Pi's static extension graph and initialize the native parser vendor path before SDK evaluation (#228). Retained credential-free packed compiled-Bun proof reached the authentication boundary on official Pi 1.0.3/macOS arm64; Windows embedded-loader behavior remains unqualified.
+- Preserve scrubbed network classification through real SDK UNAVAILABLE wrappers and bounded cause provenance (#265). Keep SDK-vendored/backend process-error guards scoped; unrelated connect-node-only errors remain fatal. Retry eligibility is not backend recovery proof.
+- Match shell completions by exact ID or unique identical arguments, accepting legacy aliases without hiding unmatched/error activity (adapted from #258 by @yansigit). Installed SDK 1.0.36 contracts cover its typed shell payload and ID-less step-before-completed-delta producer, not an observed alias-changing service pair or universal stale-shell recovery.
+- Preserve default-store resume/cleanup ownership across the SDK's MD5-to-SHA256 workspace migration, without merging stores. Validate exact recorded identities before bounded path walks and retain same-cwd ownership through admission/open/disposal. Reject unsafe owned layouts before migration; higher user-managed links remain supported only for default storage. This is not a cross-process migration lock.
+- Keep custom-root admission exact to the current session. Wrong-domain, identity-less or malformed cleanup candidates become durably non-retryable; temporary damage at admitted paths remains retryable. Retain default cleanup candidates across root changes. Clean up before relocation if desired: restoring a root does not revive excluded candidates. Windows ACL/all-reparse and hostile same-user pathname confinement are not guaranteed.
+- Bound artifact gzip output at the existing public size cap. Separate compatibility build, verification and native contracts into bounded phases, stopping timed-out POSIX command descendants before workspace removal without increasing individual test deadlines.
+
+### Changed
+
+- Upgrade the exact unbundled Cursor SDK and all five optional platform pins to 1.0.36; requalify installed stall/error construction, MCP, transport, bootstrap, custom-agent, SQLite and public usage contracts offline. Refresh fallback-catalog provenance from the authenticated SDK 1.0.36 observation on 2026-10-06; all 45 model records match the reviewed metadata and checkpoint limits remain unchanged. The SDK upgrade alone establishes no open service/reporter fix.
+- Replace serialized catalog resync with public native API-key auth and accepted-generation publication (adapted from #300/#301 by @yansigit). Startup and login/logout/key/runtime mutations resync matching cache/fallback without catalog requests. Opt-in `PI_CURSOR_HIDE_MODELS_WHEN_LOGGED_OUT` hides AVAILABLE picker/list results, preserving KNOWN CLI identities and login. Cancellation/supersession reject late publication, not underlying SDK transport work.
+- Add default-visible `PI_CURSOR_FOOTER`; `0` hides only Cursor extension status, not Pi's native model/usage footer or provider behavior (#213).
+- Make `cursor_ask_question` OFF by default; `PI_CURSOR_ASK_QUESTION=1` retains the full bridged UI capability without disabling other pi tools (#238).
+- Apply the GitHub issue/PR comment rule to bootstrap and incremental prompt tails: comment only when the user asks (#239). Reads and requested writes remain supported; prompt guidance is not a hard execution-permission boundary.
+- Add private strict decimal `PI_CURSOR_LIVE_RUN_IDLE_DISPOSE_MS`, accepting `1`–`2147483647` milliseconds with a five-minute default (adapted from #283 by @aaalexliu). This tunes eligible abandonment cleanup, not authentication/transport recovery.
+- Upgrade the bundled MCP bridge to adapter 2.0.2/server 2.3.1/Hono 4.13.13, retaining node-server 2.1.3, bounded JSON parsing and Host/Origin rejection. Upgrade development-only ConnectRPC to 2.2.0 and MCP client to 2.3.1 without replacing the SDK's nested Connect 1.7.0/Protobuf 1.10.0 transport graph.
+- Align direct development Pi snapshots/transitives to 1.0.3, root TypeBox to 1.3.36 and Vitest to 5.0.3. Node 24+, official Pi 0.87.1+ and optional wildcard Pi/TypeBox host peers remain unchanged; qualification targets latest stable official Pi and current maintained fork main.
+- Extend native context-edit/filtering contracts to preserve raw history, current system instructions/tools and explicit tool removal (#271 native slice only). Strengthen public aggregate-only usage and original-origin terminal/late telemetry contracts without placing cumulative billing in native occupancy or claiming invoice/branch attribution.
+
+### Known limits
+
+- Official Pi 1.0.4 has a demonstrated startup refresh-admission race that can temporarily retain fallback models and an incorrect missing-key warning despite a matching authenticated cache (#337). The shared-owner repair is merged in `fitchmultz/pi` via #190; this release does not claim the official host is fixed.
+- Attribution controls remain upstream-blocked in canonical #302 for BOTH commit and PR attribution; #143 is a duplicate, not a fix. LOCAL summary-state isolation is distinct from summary-content quality (#223). The new non-Cursor/opencode parser-warning/SIGTERM report (#339) has no established causal owner. Other open reporter/service cases are not closed by the SDK version or offline contracts.
+
 ## 0.5.0 - 2026-10-04
 
 ### Breaking Changes

package/README.md

@@ -51,11 +51,11 @@ If pi started without a key, run `/cursor-refresh-models` after `/login` to refr
 ## Requirements
 
 - Node.js 24+
-- 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
+- pi-cursor-sdk 0.5.3 requires official Pi 0.87.1 or later. The latest stable official Pi and current `fitchmultz/pi` main are required compatibility targets, resolved once per workflow run; locked development Pi packages are reproducible snapshots, not validation targets
 - 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`
 
-No global `@cursor/sdk` install is required. This package depends on exact `@cursor/sdk@1.0.32`, so normal package installation brings in the tested SDK. The extension intentionally does not bundle `@cursor/sdk` or its platform packages, because packing from one maintainer OS can ship the wrong optional SDK binary for another OS. The SDK has used its current single-file/new-chunk package layout since 1.0.28. Pi hosts that pass transcript-only provider contexts are supported through Pi 0.87.1's required public replay helpers.
+No global `@cursor/sdk` install is required. This package depends on exact `@cursor/sdk@1.0.37`, so normal package installation brings in that SDK. The extension intentionally does not bundle `@cursor/sdk` or its platform packages, because packing from one maintainer OS can ship the wrong optional SDK binary for another OS. The SDK has used its current single-file/new-chunk package layout since 1.0.28. Pi hosts that pass transcript-only provider contexts are supported through Pi 0.87.1's required public replay helpers.
 
 ## Install
 
@@ -124,9 +124,11 @@ Then, inside pi:
 4. Paste your Cursor SDK API key.
 5. The key is saved in pi's native `~/.pi/agent/auth.json`.
 
-If pi started without a key, fallback Cursor models still register so `/login` is reachable. After `/login`, fallback model runs can use the stored key, and `/cursor-refresh-models` refreshes the full live Cursor model catalog discovered from the Cursor SDK without restarting pi.
+If pi started without a key, known fallback Cursor models still register so `/login` and CLI model selection remain reachable. Native login, logout, key rotation, and runtime-key changes immediately resync the matching cached catalog or fallback in the same session, without making a catalog request. Run `/cursor-refresh-models` for the full live catalog without restarting pi.
 
-Note: if `/login` shows `Cursor ✓ key in models.json` but you have not saved a Cursor key and `CURSOR_API_KEY` is unset, that status is a pi auth-status limitation. A real Cursor SDK API key is still required for Cursor runs.
+Set `PI_CURSOR_HIDE_MODELS_WHEN_LOGGED_OUT=1` to hide unauthenticated Cursor models from the picker and `--list-models`. This is off by default. Known model identities remain CLI-selectable, including `pi --model cursor/grok-4.6 --api-key "your-key"`; `/login` stays reachable. Stored logout does not hide models or delete the matching cache when environment or `models.json` auth remains. Pi's native logout also removes its runtime key override.
+
+The default fallback availability policy is not proof of a usable key. A real Cursor SDK API key is still required for Cursor runs.
 
 Environment setup:
 
@@ -141,17 +143,21 @@ One-shot setup:
 pi --api-key "your-key" --model cursor/grok-4.6 --cursor-no-fast -p "Say ok only."
 ```
 
-Startup discovery intentionally does not parse Pi CLI arguments. It uses the stored `cursor` key in `~/.pi/agent/auth.json`, then `CURSOR_API_KEY`; without either, the bundled fallback catalog registers. Provider turns still receive Pi's resolved `--api-key`. `/cursor-refresh-models` and `/cursor-cloud` mutations ask Pi's ModelRegistry for provider `cursor`, so command-time auth follows Pi's provider-scoped resolution and is normalized through `CURSOR_API_KEY` placeholders before reaching the Cursor SDK.
+Pi owns CLI parsing and credential storage. Cursor's public native API-key auth honors runtime keys, stored keys or provider-scoped `env.CURSOR_API_KEY`, composed `models.json` keys, then ambient `CURSOR_API_KEY`. Unresolved placeholder values are not real keys, and unsupported stored credential types do not fall through to ambient auth. Discovery receives the effective native key explicitly; it never reads an unrelated default auth file. Provider turns keep Pi's resolved request key. Environment or `models.json` changes take effect on the next native registry refresh (for example opening `/model`); there is no auth-file watcher.
 
 ### Model catalog cache
 
-To avoid a live `Cursor.models.list` network round-trip on every pi startup, the discovered catalog is cached on disk at `~/.pi/agent/cursor-sdk-model-list.json` (written `0600`, keyed by an API-key fingerprint — the key itself is never stored). Warm startups within the cache TTL skip the network call and avoid loading `@cursor/sdk` until a Cursor turn needs it; `/cursor-refresh-models` always bypasses the cache and refreshes the live catalog. If a refresh fails, a previously cached catalog is preferred over the generic bundled fallback.
+The discovered catalog is cached at `~/.pi/agent/cursor-sdk-model-list.json` (written `0600`, keyed by an API-key fingerprint — the key itself is never stored). Startup and native auth mutations are always cache-only: a matching cache, even if expired, or the bundled fallback supplies known models with zero catalog/network calls. The SDK remains in the static extension graph for compiled-Bun loading; cache-only does not mean zero SDK module evaluation. Pi may separately request a network-allowed refresh; fresh matching caches then skip the request. `/cursor-refresh-models` requests a forced native live refresh and reports cancellation or failure truthfully. Authenticated errors prefer the matching cached catalog over the generic fallback.
+
+Only an accepted native generation can update the catalog, selection metadata, cache, and fallback warning. An effective no-auth refresh removes only the extension's valid regular-file orphaned catalog. Cancelled, superseded, or shut-down refreshes cannot install late results. SDK 1.0.37 catalog requests have no public caller-abort option, so cancellation rejects their late publication rather than promising to stop the underlying request.
+
+Known host limitation: official Pi 1.0.4 has a demonstrated startup refresh-admission race that can temporarily leave fallback models and an incorrect missing-key warning despite a matching authenticated cache. The shared-owner repair is merged in `fitchmultz/pi` via [#190](https://github.com/fitchmultz/pi/pull/190); this is not an official-host fix. See [#337](https://github.com/fitchmultz/pi-cursor-sdk/pull/337). It is separate from Cursor service authentication failures and the compiled-loader repair.
 
 ```bash
 # Cache lifetime in milliseconds (default 86400000 = 24h).
 PI_CURSOR_SDK_MODEL_CACHE_TTL_MS=3600000 pi --model cursor/grok-4.6
 
-# Disable the cache and always discover live.
+# Disable cache reads/writes; cache-only phases still use the fallback.
 PI_CURSOR_SDK_DISABLE_MODEL_CACHE=1 pi --model cursor/grok-4.6
 ```
 
@@ -216,12 +222,12 @@ For models where Cursor exposes `reasoning`, `effort`, `reasoning_effort`, or bo
 
 - `reasoning=none|low|medium|high|extra-high`
 - `effort=low|medium|high|xhigh|max`
-- `reasoning_effort=low|medium|high`
+- `reasoning_effort=low|medium|high|xhigh|max` where exposed by the catalog
 - `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. 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`.
+For Claude models with boolean `thinking` and either `effort` or `reasoning_effort`, enabled pi levels send `thinking=true` and the mapped effort value; `off` sends `thinking=false` and omits the effort parameter. Haiku 5.5 exposes all five enabled effort levels (`low`, `medium`, `high`, `xhigh`, `max`) at both `@300k` and `@1m`.
 
 ### Why some Cursor models show `thinking=no`
 
@@ -256,7 +262,7 @@ The `:fast` and `:slow` aliases are available only for Cursor models whose catal
 
 Composer 2 and Composer 2.5 can default to fast. Use `--cursor-no-fast` or a `:slow` virtual alias for a one-shot no-fast Composer run. In print mode (`-p`), `--cursor-no-fast` is silent and does not write `~/.pi/agent/cursor-sdk.json`.
 
-In interactive mode, the footer shows Cursor status only while a Cursor model is active. Fast-capable models show fast state explicitly, and fast and plan mode share one Cursor status value so they do not overwrite each other:
+In interactive mode, the footer shows Cursor status only while a Cursor model is active. Set `PI_CURSOR_FOOTER=0` to hide this status; it is visible by default. This controls display only: runtime, mode, and transport selection and validation are unchanged. Fast-capable models show fast state explicitly, and fast and plan mode share one Cursor status value so they do not overwrite each other:
 
 ```text
 cursor:local · fast:n/a
@@ -292,7 +298,7 @@ Change the session mode interactively:
 
 `/cursor-mode` with no argument reports the current mode and usage. The CLI flag does not persist to the session; slash-command changes are persisted with `pi.appendEntry()`.
 
-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).
+Maintainers can run `/cursor-tools` in a Cursor model session to print bridge/manifest enablement, effective `PI_CURSOR_SETTING_SOURCES`, and the current registry's bridge exposure eligibility. This is not a live-run connection or invocation check; use the [bridge diagnostics](#cursor-provider-tool-contract) below for per-run observations. See [Cursor dogfood checklist](docs/cursor-dogfood-checklist.md).
 
 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.
 
@@ -300,7 +306,9 @@ Cursor SDK `plan` mode can produce plan-oriented output and Cursor todo/plan act
 
 ## Cursor local agent config and safety controls
 
-`/cursor-refresh-config` calls the current pooled SDK agent's `agent.reload()` so Cursor reloads filesystem config such as local hooks, project MCP, and subagents without restarting pi. If no Cursor agent exists yet, the next Cursor run loads config normally.
+`/cursor-refresh-config` calls the current pooled SDK agent's `agent.reload()` so Cursor reloads its filesystem config such as local hooks, project MCP, and Cursor-managed subagents without restarting pi. Extension `cursor-sdk.json` definitions below are captured on the next ordinary turn; changed definitions recreate the pooled agent instead of relying on SDK reload.
+
+**Hook enforcement is not qualified by settings loading or replay cards.** SDK 1.0.37 source retains Shell `preToolUse` command-rewrite plumbing. The retained SDK 1.0.36 offline probe executed a rewritten command using private lexical bindings and permissive approval; it is not an executed SDK 1.0.37 canary. That is not an end-to-end Pi/rtk or security-policy guarantee. Replay may show the original model arguments before the SDK applies a rewrite. Verify the hook decision and actual executed command together when relying on hooks; the reported native-Agent/Pi discrepancy remains open in [#173](https://github.com/fitchmultz/pi-cursor-sdk/issues/173).
 
 Cursor SDK local safety controls stay off by default. Enable them explicitly for one run:
 
@@ -325,7 +333,27 @@ pi --model cursor/grok-4.6 --cursor-no-local-resume
 PI_CURSOR_LOCAL_RESUME=0 pi --model cursor/grok-4.6
 ```
 
-Resume is strict: the current pi session file/id, branch path prefix, cwd/repo root, model/API/tool-surface pool key, SDK store identity, and compaction generation must match. Each persisted pi session gets a SQLite store under `<getDefaultSdkStateRoot(cwd)>/pi-sessions/<session-hash>/`, and that same store is used for create/resume, transcript reads, checkpoint lookup, and exact-ID cleanup so parallel pi sessions do not contend on one workspace `index.db`. Fileless sessions use a unique OS-temporary store per acquisition, remove it on graceful disposal, and start a fresh agent after invalidation instead of reopening a disposed temporary store. Legacy resume entries still try the SDK's default workspace store; if that resume fails or the agent is later replaced, the new agent moves to the per-session store. A trailing user message already present at process startup is crash-ambiguous and invalidates the old handle; only a user message appended in the current process may span a recorded handle, preventing restart from resending an already-submitted prompt. A successful process reattachment bootstraps the current pi transcript once while retaining the resumed Cursor agent's native state; later in-process turns remain incremental. If `Agent.resume()` fails, pi bootstraps a new local Cursor agent from the current transcript and streams one display-only continuity note. Superseded local agents can be cleaned up explicitly with `/cursor-local-resume-cleanup --dry-run` and `/cursor-local-resume-cleanup --yes`; cleanup only deletes exact recorded `agent-*` IDs from their recorded store. Cloud resume remains disabled; `/cursor-cloud list|archive|delete` only manages recorded cloud agents.
+Resume is strict: the current pi session file/id, branch path prefix, cwd/repo root, model/API/tool-surface pool key, SDK store identity, and compaction generation must match. By default, each persisted pi session gets a SQLite store under `<getDefaultSdkStateRoot(cwd)>/pi-sessions/<session-hash>/`, and that same store is used for create/resume, transcript reads, checkpoint lookup, and exact-ID cleanup so parallel pi sessions do not contend on one workspace `index.db`. Fileless sessions use a unique OS-temporary store per acquisition, remove it on graceful disposal, and start a fresh agent after invalidation instead of reopening a disposed temporary store. With default storage selected, legacy resume entries still try the SDK's default workspace store; if that resume fails or the agent is later replaced, the new agent moves to the per-session store. A trailing user message already present at process startup is crash-ambiguous and invalidates the old handle; only a user message appended in the current process may span a recorded handle, preventing restart from resending an already-submitted prompt. A successful process reattachment bootstraps the current pi transcript once while retaining the resumed Cursor agent's native state; later in-process turns remain incremental. If `Agent.resume()` fails, pi bootstraps a new local Cursor agent from the current transcript and streams one display-only continuity note. Superseded local agents can be cleaned up explicitly with `/cursor-local-resume-cleanup --dry-run` and `/cursor-local-resume-cleanup --yes`; cleanup only deletes exact recorded `agent-*` IDs from their recorded store. Cloud resume remains disabled; `/cursor-cloud list|archive|delete` only manages recorded cloud agents.
+
+If a default local-store error names a rejected link or non-directory, make that SDK-owned prefix/component a real directory without discarding its data, or relocate via a link at a higher ancestor such as `~/.cursor/projects` instead. Custom roots reject user-controlled ancestor links too.
+
+### Custom local SQLite root
+
+For persistent LOCAL conversations, set `PI_CURSOR_SDK_STATE_ROOT` or user `~/.pi/agent/cursor-sdk.json`:
+
+```json
+{ "local": { "storeRoot": "/absolute/private/cursor-state" } }
+```
+
+Environment wins over user; blank values are absent. Project, session, CLI and built-in settings cannot select a root. With neither set, SDK-default storage/migration is unchanged. Selection is captured once per turn and at explicit cleanup entry, not reread after asynchronous work.
+
+Custom layout: `<canonical-root>/<sha256(resolve(cwd))[0:32]>/pi-sessions/<session-hash>/`. Only extension SQLite/checkpoints move—not auth, settings/rules, model caches or IDE data. Fileless and LOCAL compaction/tree stores ignore persistent selection entirely, even when its path is unusable.
+
+Use a fully qualified native absolute path, not a filesystem/share root, relative/device path, or a path with explicit `.`/`..` components. No tilde/environment expansion occurs. Invalid winning paths fail closed, never falling back to default. POSIX ancestors must be root/current-user owned and not group/other writable, except trusted sticky system temporary directories; after shared directories, components must belong to the current user. Owned destinations are private (0700). User-controlled links/junctions and linked/nonregular fixed SQLite files are rejected; verified root-owned system aliases such as macOS `/var` are supported.
+
+On Windows, choose a user-controlled, ACL-protected location. Node-visible links/junctions, type, identity and writability are checked, but ACLs are not hardened and not every reparse-point type is guaranteed to be rejected. The SDK opens by pathname, including lazy checkpoints; these checks are not a sandbox against malicious same-user processes or administrators.
+
+Changing root replaces a live pooled agent on the next turn and bootstraps from the Pi transcript. Custom resume/cleanup admits only the exact current custom **session** identity; identity-less legacy, SDK-default, other-root and other-session addresses are never reinterpreted. Old data is retained: no copy, migration, merge or automatic deletion. Run explicit cleanup **before** relocating if desired: cleanup at B can durably mark A's candidates non-retryable, and returning to A does not revive them. Manually retained state remains your responsibility after retiring its sessions and stopping their processes.
 
 Config can also set non-secret defaults in `~/.pi/agent/cursor-sdk.json` or trusted `.pi/cursor-sdk.json`. Project config activates only when Pi's project-trust flow reached this extension and approved the project, or the run started with explicit `--approve`; Pi's implicit trust for a project with no recognized resources is not enough. Because project-local package extensions load after the trust event, `pi install -l` users must pass `--approve` on every run that reads or writes `.pi/cursor-sdk.json`. A trust resource added after trust resolution requires restarting pi. `/cursor-runtime ... --save-project` requires the same trust provenance and does not create Pi trust resources automatically. Explicit runtime, fast-default, and HTTP transport saves preserve unrecognized fields, reject malformed or non-object JSON without rewriting it, and serialize concurrent writers. A completed global preference write is retained if Pi's subsequent session-journal append fails, because Pi may already have mutated the in-memory branch; the command reports that partial journal failure and ignores the uncertain session entry until a later successful save or session restart. If a process is force-killed during the tiny update window, the next save reports the `.lock` path; remove it only after confirming no pi process is writing that config.
 
@@ -340,6 +368,38 @@ Config can also set non-secret defaults in `~/.pi/agent/cursor-sdk.json` or trus
 }
 ```
 
+### SDK-native custom agents
+
+Define named Cursor delegates in user `~/.pi/agent/cursor-sdk.json` or trusted project `.pi/cursor-sdk.json`:
+
+```json
+{
+  "subagents": {
+    "reviewer": {
+      "description": "Review code changes for correctness and maintainability.",
+      "prompt": "Inspect the changes and report concrete findings without editing.",
+      "model": "grok-4.6:slow",
+      "thinking": "high",
+      "fast": false
+    },
+    "helper": {
+      "description": "Investigate a focused question.",
+      "prompt": "Research the question and return concise evidence.",
+      "model": "inherit"
+    }
+  }
+}
+```
+
+- Names follow this extension's policy: 1–64 characters, starting with an ASCII letter, then letters, digits, `.`, `_`, or `-`. Required `description` and `prompt` must be nonblank strings; text is trimmed. Invalid entries are skipped individually. Invalid optional `model`, `thinking`, or `fast` values are omitted; unsupported fields, including per-entry MCP, are not forwarded.
+- A trusted project with any valid definitions replaces the **whole** user set, not individual names. Empty/all-invalid project sets fall back to user definitions. No CLI, environment, or session override exists. Keep definitions non-secret.
+- `model` uses a registered Cursor model ID **without** the `cursor/` provider prefix; set thinking separately to `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Omitted model and explicit `inherit` both inherit the parent model in SDK 1.0.37; `thinking`/`fast` do not override inherited models.
+- Explicit models use catalog metadata for aliases, context and thinking. `:fast`/`:slow` wins over the entry's `fast`; unsuffixed models use entry `fast`, otherwise the catalog default. Parent thinking, `/cursor-fast`, saved fast defaults and process fast flags do not affect the definition. Unknown IDs pass through unchanged without invented parameters or a catalog request.
+- **SDK 1.0.37 LOCAL ceiling:** its converter sends only the selected model ID or `inherit`, dropping all thinking/fast/context parameters. Thus `grok-4.6:slow` resolves to `grok-4.6`, but does not enforce child slow mode locally. Cloud conversion preserves the full selection; service acceptance/honoring of those parameters is not qualified here. Resource inheritance (`local.subagentInherit`) is not a model-parameter workaround.
+- Definitions are passed through public SDK `agents` on ordinary create/resume and cloud creation. Changed resolved content replaces the local pooled agent on the next turn and rejects stale resume handles, bootstrapping from the Pi transcript; equivalent reordered content reuses it. Resume keys contain only a digest, not definition text. Removing all definitions restores the original no-feature key.
+
+This is Cursor SDK-native delegation by configured name, not a second Pi subagent implementation. When exposed, `pi__subagent` remains preferred. LOCAL compaction/tree summary agents receive no definitions, tools, settings or MCP; bug-report streams retain ordinary capabilities.
+
 ### Cloud runtime and acknowledgement
 
 Cloud/runtime keys are minimal and explicit. Defaults stay local runtime with the loopback MCP bridge as the sole Pi-tool transport, no inline cloud MCP, and no local-state/env-file forwarding. SDK `customTools` remains deferred pending SDK cancellation/deadline support. Invalid non-empty `--cursor-runtime`, `--cursor-cloud-context`, `PI_CURSOR_RUNTIME`, or `PI_CURSOR_CLOUD_CONTEXT` values fail closed instead of falling through to lower-precedence config.
@@ -443,20 +503,22 @@ Local resume cleanup is explicit and session-ledger scoped:
 /cursor-local-resume-cleanup --yes
 ```
 
-It only deletes superseded local `agent-*` IDs that this extension recorded as cleanup candidates, one exact ID at a time through the Cursor SDK using the candidate's recorded store identity (or the SDK default workspace store for legacy candidates without one), and protects agents still resumable from any session-tree branch. Before SDK deletion it verifies and fsyncs an exact intent in the Pi session JSONL, then verifies and fsyncs the result; a missing or non-durable intent prevents deletion, while a missing or non-durable result leaves the durable intent—and a conservative current-process marker—blocking automatic retry. A candidate with a recorded store identity that is invalid for the current session is durably marked non-retryable and excluded from later cleanup attempts. It does not sweep any SDK store or call lower-level empty delete filters. Removing a pi session file does not automatically remove its persisted store directory. After permanently retiring that session and confirming no pi process is using it, a recorded root may be removed manually only when it is the session-derived `<getDefaultSdkStateRoot(cwd)>/pi-sessions/<session-hash>/` path. Never manually remove the SDK default workspace root, which legacy entries may record and other sessions may share.
+With SDK-default storage selected, SDK 1.0.37 retains SDK 1.0.36's workspace-root derivation with SHA256 instead of MD5 and may rename the entire old workspace root on first use. Pi admits only exact cwd/session-derived old or current identities. After a rename, it verifies the recorded agent and cwd in the derived destination before resuming or cleaning up. If both roots exist, recorded legacy identities stay with the legacy store; nothing is merged. Failed renames retain the old store. Same-cwd acquisitions share atomic in-flight root derivation and retain ownership through resume/cleanup admission and open-store disposal; only then may the SDK retry. User-managed links/junctions above the SDK-owned `sdk-agent-store` prefix (such as `~/.cursor` or `~/.cursor/projects`) remain supported. Owned prefix and old/current workspace components are checked before the SDK getter can migrate history; links/non-directories within the owned layout fail closed. Recorded identities must match exact derived roots before any path walk; malformed paths fall back on resume or are durably non-retryable for cleanup. Stop other processes using old SDK state before upgrading; this in-process ownership guard is not a cross-process migration lock.
+
+It only deletes superseded local `agent-*` IDs that this extension recorded as cleanup candidates, one exact ID at a time through the Cursor SDK using the candidate's recorded store identity (or, only with default storage selected, the SDK default workspace store for legacy candidates without one), and protects agents still resumable from any session-tree branch. Before SDK deletion it verifies and fsyncs an exact intent in the Pi session JSONL, then verifies and fsyncs the result; a missing or non-durable intent prevents deletion, while a missing or non-durable result leaves the durable intent—and a conservative current-process marker—blocking automatic retry. A candidate with a recorded store identity that is invalid for the current session is durably marked non-retryable and excluded from later cleanup attempts. It does not sweep any SDK store or call lower-level empty delete filters. Removing a pi session file does not automatically remove its persisted store directory. After permanently retiring that session and confirming no pi process is using it, a recorded root may be removed manually only when it is the exact cwd/session-derived current or surviving legacy `pi-sessions/<session-hash>/` directory. Do not remove a stale recorded MD5 path after migration: resolve and verify the actual owning directory first. Never manually remove the SDK default workspace root, which legacy entries may record and other sessions may share.
 
 Only enabled local safety values are passed to `Agent.create({ local })`; false/default values are omitted to preserve the current local-agent behavior. Local force is one-shot/manual-only through CLI/env and is passed only to the next `Agent.send({ local: { force: true } })`. Local resume is enabled by default for local runtime; opt out with `local.resume: false`, `--cursor-no-local-resume`, or `PI_CURSOR_LOCAL_RESUME=0`. Changes take effect on the next turn without recreating a healthy pooled agent.
 
 ## Images
 
-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.
+For request-equivalent native session inputs, images from the latest pending native user message are forwarded to Cursor, even when hidden model-visible notices follow it. Those notices travel as background context alongside the request, and the pending input group remains required under transcript budgeting. A custom-only continuation does not resubmit an old request or attachment. Request-local transforms that change payload/order lack canonical origin and retain conservative last-converted-user selection. 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.
+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.37 provides no public completion deadline, so a controller that never settles can leave cancellation waiting.
 
 Use the separate accounting view for recorded Cursor facts:
 
@@ -485,19 +547,21 @@ Local Cursor runs use two separate tool surfaces:
 - **Cursor-native surface:** Cursor local-agent tools, Cursor settings, plugins, and configured Cursor MCP servers. These remain owned by the Cursor SDK local agent path. Pi CLI tool toggles such as `--no-tools`, `--tools`, and `--exclude-tools` do not disable this Cursor-native surface.
 - **pi bridge surface:** pi-cursor-sdk exposes bridgeable active pi tools through a per-run local loopback MCP bridge when the bridge is enabled and the current pi tool registry has exposed tools. Pi CLI tool toggles affect this bridge surface because they change pi's active tool registry.
 
-The bridge uses stable MCP v2 with `@modelcontextprotocol/server@2.1.0`, `@modelcontextprotocol/hono@2.0.1`, `hono@4.13.9`, and `@hono/node-server@2.1.1`, bundled as its runtime closure. It binds only to loopback and validates Hono `Host` and `Origin` headers.
+The bridge uses stable MCP v2 with `@modelcontextprotocol/server@2.3.1`, `@modelcontextprotocol/hono@2.0.2`, `hono@4.13.13`, and `@hono/node-server@2.1.3`, bundled as its runtime closure. It binds only to loopback and validates Hono `Host` and `Origin` headers.
 
 Bridge capabilities are snapshotted from `pi.getActiveTools()` and `pi.getAllTools()` for each Cursor run, including per-tool prompt guidelines when pi exposes them. Cursor sees active bridgeable pi tools as collision-safe MCP names such as `pi__sem_reindex` only when they are exposed in that current run. When exposed, Cursor is instructed to prefer `pi__mcp` for MCP work and `pi__subagent` for delegation; Cursor-configured MCP and Cursor-native subagents are fallbacks when the matching pi tool is not exposed or is unavailable. Pi session output, tool cards, confirmations, hooks, renderers, history, and abort behavior use the real pi tool name, such as `sem_reindex`. The bridge queues Cursor's MCP call, emits a normal pi `toolCall`, waits for the matching pi `toolResult`, and resolves that result back into the same live Cursor SDK run without creating a new `Agent`, unless the run was disposed, aborted, or cancelled. The bridge does not call pi tool `execute()` handlers directly.
 
-Overlapping built-in pi tools (`read`, `bash`, `write`, `edit`, `grep`, `find`, `ls`) are hidden by default because Cursor local agents already have native equivalents. Extension/custom tools and non-overlapping active tools present in pi's active tool registry normally remain exposed. The bridge also exposes `cursor_ask_question` as `pi__cursor_ask_question` when enabled, allowing Cursor to ask the user through pi UI instead of silently choosing a default. For local runtime, when pi has visible Agent Skills loaded, the extension rewrites pi's skill catalog for Cursor and exposes `cursor_activate_skill` as `pi__cursor_activate_skill`; Cursor should call that bridge tool with a listed skill name to load the full `SKILL.md` and bundled resource list before applying the skill. If the local bridge is disabled, the catalog remains available and instructs Cursor to fall back to reading the listed `SKILL.md` path directly. Cloud runtime preserves Pi project instructions but omits Pi's local skill catalog and keeps `cursor_activate_skill` inactive because the bridge and local absolute skill paths are unavailable there.
+Overlapping built-in pi tools (`read`, `bash`, `write`, `edit`, `grep`, `find`, `ls`) are hidden by default because Cursor local agents already have native equivalents. Extension/custom tools and non-overlapping active tools present in pi's active tool registry normally remain exposed. The bridge also exposes `cursor_ask_question` as `pi__cursor_ask_question` when `PI_CURSOR_ASK_QUESTION=1`. It is off by default so Cursor does not block on questionnaires. For local runtime, when pi has visible Agent Skills loaded, the extension rewrites pi's skill catalog for Cursor and exposes `cursor_activate_skill` as `pi__cursor_activate_skill`; Cursor should call that bridge tool with a listed skill name to load the full `SKILL.md` and bundled resource list before applying the skill. If the local bridge is disabled, the catalog remains available and instructs Cursor to fall back to reading the listed `SKILL.md` path directly. Cloud runtime preserves Pi project instructions but omits Pi's local skill catalog and keeps `cursor_activate_skill` inactive because the bridge and local absolute skill paths are unavailable there.
 
 Cursor-native tool replay is separate from the bridge. Replay cards are display-only recorded Cursor SDK activity. They never re-run Cursor-side commands, reapply Cursor edits, call MCP servers, or mutate pi state. See [Cursor native tool replay](docs/cursor-native-tool-replay.md).
 
+Footer display control: `PI_CURSOR_FOOTER=0` hides the Cursor status without hiding Pi's model or usage footer. Like other boolean controls, it accepts `0`, `false`, `off`, `none`, `no`, and `disabled` to hide; `1`, `true`, `on`, `yes`, and `enabled` to show (case-insensitive). Unset, blank, or unrecognized values keep the default visible status.
+
 Bridge controls:
 
 ```bash
-# Keep the pi bridge but disable Cursor's interactive question tool.
-PI_CURSOR_ASK_QUESTION=0 pi --model cursor/grok-4.6
+# Opt in to Cursor's interactive question tool through pi UI.
+PI_CURSOR_ASK_QUESTION=1 pi --model cursor/grok-4.6
 
 # Roll back to Cursor SDK tools/settings/MCP only; do not expose active pi tools through the bridge.
 PI_CURSOR_PI_TOOL_BRIDGE=0 pi --model cursor/grok-4.6
@@ -530,12 +594,25 @@ PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1 pi --model cursor/grok-4.6
 
 On bootstrap sends, a compact **callable tool surfaces** block is injected into the Cursor prompt by default. It reminds the model that Cursor host/configured MCP tools are controlled by Cursor, while pi tool toggles only affect pi tools/bridge exposure; when bridge tools are exposed, it lists the current `pi__*` names. Disable with `PI_CURSOR_TOOL_MANIFEST=0`.
 
-`PI_CURSOR_ASK_QUESTION=0` disables only `cursor_ask_question`, leaving the rest of the pi bridge available; it is enabled by default. `PI_CURSOR_PI_TOOL_BRIDGE=0` is the supported rollback flag and disables the bridge entirely. Both flags treat `false`, `off`, `none`, `no`, and `disabled` as off; `1`, `true`, `on`, `yes`, and `enabled` as on. `PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1` opts in to exposing overlapping pi tool names that Cursor already has native equivalents for. The installed Cursor SDK uses a 60-second MCP protocol default with no public per-server timeout option. pi-cursor-sdk overrides that seam in two directions by default: MCP `callTool` requests are extended to 3600 seconds for long-running local MCP tools (including the pi bridge and configured Cursor MCP servers), and known MCP initialize/listTools requests on first send are shortened to 10 seconds so unavailable configured MCP servers fail fast instead of blocking for a full minute. Unknown Cursor SDK MCP protocol timeout stacks keep the SDK default instead of being shortened. Override tool-call timeouts with `PI_CURSOR_MCP_TOOL_TIMEOUT_MS` or `PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS`, and first-send initialize/listTools timeouts with `PI_CURSOR_MCP_CONNECT_TIMEOUT_MS` or `PI_CURSOR_MCP_CONNECT_TIMEOUT_SECONDS`. Bridged calls also have a local fail-closed deadline that defaults to the effective MCP tool timeout; lower it with `PI_CURSOR_PI_BRIDGE_CALL_TIMEOUT_MS` when a lost pi result should fail sooner. On expiry, the bridge rejects and removes the pending call and aborts active pi execution when available. The bridge's `listTools` handler returns its snapshot synchronously, so a Cursor UI label such as `GetMcpTools` does not by itself identify a `listTools` deadlock; the durable bridge waiter is `CallTool` awaiting its matching pi result.
+`PI_CURSOR_ASK_QUESTION=1` enables only `cursor_ask_question`, leaving the rest of the pi bridge available; it is off by default. `PI_CURSOR_PI_TOOL_BRIDGE=0` is the supported rollback flag and disables the bridge entirely. Both flags treat `false`, `off`, `none`, `no`, and `disabled` as off; `1`, `true`, `on`, `yes`, and `enabled` as on. `PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1` opts in to exposing overlapping pi tool names that Cursor already has native equivalents for. The installed Cursor SDK uses a 60-second MCP protocol default with no public per-server timeout option. pi-cursor-sdk overrides that seam in two directions by default: MCP `callTool` requests are extended to 3600 seconds for long-running local MCP tools (including the pi bridge and configured Cursor MCP servers), and known MCP initialize/listTools requests on first send are shortened to 10 seconds so unavailable configured MCP servers fail fast instead of blocking for a full minute. Unknown Cursor SDK MCP protocol timeout stacks keep the SDK default instead of being shortened. Override tool-call timeouts with `PI_CURSOR_MCP_TOOL_TIMEOUT_MS` or `PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS`, and first-send initialize/listTools timeouts with `PI_CURSOR_MCP_CONNECT_TIMEOUT_MS` or `PI_CURSOR_MCP_CONNECT_TIMEOUT_SECONDS`. Bridged calls also have a local fail-closed deadline that defaults to the effective MCP tool timeout; lower it with `PI_CURSOR_PI_BRIDGE_CALL_TIMEOUT_MS` when a lost pi result should fail sooner. On expiry, the bridge rejects and removes the pending call and aborts active pi execution when available. The bridge's `listTools` handler returns its snapshot synchronously, so a Cursor UI label such as `GetMcpTools` does not by itself identify a `listTools` deadlock; the durable bridge waiter is `CallTool` awaiting its matching pi result.
+
+Pending pi bridge calls keep their owning local Cursor live run active, including queued calls, long-running tools, and questions awaiting human input. After the last owned call settles and the provider drain lease ends, the full idle cleanup window (five minutes by default) restarts—even if cleanup was requested before the lease. A pending call in another session does not delay cleanup. This is not an answer timeout: explicit abort/shutdown/reset/compaction and the fail-closed MCP/bridge deadline (one hour by default) still clean up pending work. Abandoned display-only native replay retains its idle expiry.
 
-`PI_CURSOR_HTTP_1_1=true` maps to the Cursor SDK `Cursor.configure({ local: { useHttp1ForAgent: true } })` compatibility mode for corporate VPN/proxy environments where HTTP/2 streams fail. In interactive sessions, `/cursor-http on`, `/cursor-http off`, and `/cursor-http toggle` set the branch-scoped session preference and save the user default as `local.useHttp1ForAgent` in `~/.pi/agent/cursor-sdk.json`; `/cursor-http` with no argument reports the effective state. Precedence is session command/history, explicit `PI_CURSOR_HTTP_1_1`, user config, then the built-in unset default; project config is ignored for this user-level compatibility choice. Unset performs no SDK configuration, preserving the existing default path. Session shutdown clears extension-owned SDK transport state before module reload. Changing the effective setting splits the local agent pool so an agent created under another transport is not reused. When enabled, the local Cursor footer shows `http1` (for example `cursor:local · fast:on · http1`); cloud status never does. This affects Cursor SDK local-agent backend streams only; it does not configure HTTP proxies, TLS certificates, or HTTP/3.
+`PI_CURSOR_LIVE_RUN_IDLE_DISPOSE_MS` sets that window for eligible retained local replay runs. It defaults to `300000` (five minutes); only decimal digits representing an integer from `1` through `2147483647` are accepted. Unset, blank, malformed (including surrounding whitespace), and out-of-range values fall back to five minutes. For example, `PI_CURSOR_LIVE_RUN_IDLE_DISPOSE_MS=900000 pi --model cursor/grok-4.6` selects fifteen minutes. The full configured window restarts after the last owned pending call settles and the provider drain lease ends. This environment-only setting does not change bridge/MCP deadlines or explicit abort/shutdown cleanup, and is not a fix for backend authentication, transport, or lost-executor failures.
+
+`PI_CURSOR_HTTP_1_1=true` maps to the Cursor SDK `Cursor.configure({ local: { useHttp1ForAgent: true } })` compatibility mode for corporate VPN/proxy environments where HTTP/2 streams fail. In interactive sessions, `/cursor-http on`, `/cursor-http off`, and `/cursor-http toggle` set the branch-scoped session preference and save the user default as `local.useHttp1ForAgent` in `~/.pi/agent/cursor-sdk.json`; `/cursor-http` with no argument reports the effective state. Precedence is session command/history, explicit `PI_CURSOR_HTTP_1_1`, user config, then the built-in unset default; project config is ignored for this user-level compatibility choice. Unset performs no SDK configuration, preserving the existing default path. Session shutdown clears extension-owned SDK transport state before module reload. Changing the effective setting splits the local agent pool so an agent created under another transport is not reused. When enabled, the local Cursor footer shows `http1` (for example `cursor:local · fast:on · http1`); cloud status never does. This affects Cursor SDK local-agent backend streams only; it does not configure HTTP proxies, TLS certificates, or HTTP/3. SDK 1.0.37 vendors its patched Node ConnectRPC client; its HTTP/2 default ping interval is 59 seconds and idle connection timeout is 29 seconds. Those are connection settings, not a model-turn deadline or a promise of service recovery.
 
 `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.
 
+Interpret the bridge diagnostic records by their boundary:
+
+- `run_created` / `tools_exposed`: bridge exposure, not a client connection.
+- `mcp_initialized`: the server received a validated `notifications/initialized`.
+- `mcp_tools_list`: the catalog handler produced `toolCount` tools after request validation, not proof the client received or model consumed them.
+- `request_queued` / `request_resolved` / `request_rejected`: actual bridge call handling.
+
+These server observations do not identify the client as Cursor or prove ongoing connection health. Missing receipts do not diagnose why a client/model made no request. `/cursor-tools` cannot inspect an already captured run's surface. See [Cursor tool surfaces](docs/cursor-tool-surfaces.md#diagnosing-advertised-but-unused-bridge-tools).
+
 ### 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.
@@ -556,20 +633,22 @@ See [Cursor testing lessons](docs/cursor-testing-lessons.md#cursor-sdk-event-cap
 
 ## Fallback models
 
-If startup has no stored `/login` key or `CURSOR_API_KEY`, model discovery fails, or discovery returns no models, the extension registers a bundled fallback snapshot of the latest reviewed Cursor SDK model catalog and notifies interactive users when possible. Pi CLI `--api-key` remains available to provider turns but is not parsed independently during startup discovery.
+If no matching cached catalog is available in a cache-only phase, auth is missing, or live discovery fails or returns no models, the extension retains known bundled fallback identities and notifies interactive users when possible. By default these models remain available without auth. With `PI_CURSOR_HIDE_MODELS_WHEN_LOGGED_OUT=1`, unauthenticated picker/list availability is empty, but known CLI selection and native login remain functional. Pi owns `--api-key` parsing.
 
-The fallback snapshot includes Grok 4.6, Composer 2.5 (`composer-2.5` and `composer-2-5`), Composer 2, Cursor's GPT-5.6 Luna/Sol/Terra models, Claude, Gemini, Grok 4.5, Kimi, and other model IDs exposed by the reviewed `Cursor.models.list()` output. Recommended local/smoke runs use `cursor/grok-4.6`. Pi's separate `openai-codex` catalog is owned by Pi itself and includes native `gpt-5.6-luna`, `gpt-5.6-sol`, and `gpt-5.6-terra` support. The exact checked-in Cursor snapshot lives in `src/cursor-fallback-models.generated.ts`. A dated maintainer capture documents the assistant-visible [Cursor system prompts and tool guidance](https://github.com/fitchmultz/pi-cursor-sdk/blob/main/docs/evidence/cursor-system-prompts-2026-08-02/README.md) for Grok 4.5, Opus 5, Fable 5, and the GPT-5.6 Sol/Terra/Luna family.
+The fallback snapshot includes Grok 4.6, Composer 2.5 (`composer-2.5` and `composer-2-5`), Composer 2, Cursor's GPT-5.6 Luna/Sol/Terra models, Claude, Gemini, Grok 4.5, Kimi, and other model IDs exposed by the reviewed `Cursor.models.list()` output. Recommended local/smoke runs use `cursor/grok-4.6`. Pi's separate `openai-codex` catalog is owned by Pi itself and includes native `gpt-5.6-luna`, `gpt-5.6-sol`, and `gpt-5.6-terra` support. The exact checked-in Cursor snapshot lives in `src/cursor-fallback-models.generated.ts`; its generator provenance records SDK 1.0.37 and 46 models from the authenticated catalog-only refresh on 2026-10-07. That refresh added Claude Haiku 5.5 (`claude-haiku-5-5`), preserving all 45 prior model records from the SDK 1.0.36 capture on 2026-10-06. The 33 bundled checkpoint-derived entries were unchanged; no Agent/model turn or Cloud run was performed. A dated maintainer capture documents the assistant-visible [Cursor system prompts and tool guidance](https://github.com/fitchmultz/pi-cursor-sdk/blob/main/docs/evidence/cursor-system-prompts-2026-08-02/README.md) for Grok 4.5, Opus 5, Fable 5, and the GPT-5.6 Sol/Terra/Luna family.
 
 Actual Cursor runs still need a key from `/login`, `CURSOR_API_KEY`, or `--api-key`. If you add auth after startup, run `/cursor-refresh-models` to refresh the full live Cursor model catalog without restarting pi.
 
 ## Limits
 
+- **Commit/PR attribution has no supported opt-out.** SDK 1.0.37 exposes neither attribution control through public create/local/send/configure options. CLI-file edits and SDK-internal patches are not supported extension settings; [#302](https://github.com/fitchmultz/pi-cursor-sdk/issues/302) tracks both controls.
+
 - **Cloud runtime is explicit and minimal.** Local remains the default. Cloud runs create Cursor cloud agents only after first-use acknowledgement and safety preflight, use fresh context by default, do not expose the pi bridge or local MCP, do not forward pi env vars, support explicit Cursor-managed environment selection, name agents from the pi session title when available, stream display-only agent/run/branch/PR/artifact/raw-usage telemetry when available, and record only explicit session-branch lifecycle commands for cleanup (`/cursor-cloud list|archive|delete`).
 - **The pi tool bridge is local and MCP-backed.** Bridgeable active pi tools are exposed to local Cursor agents through a tokenized `127.0.0.1` MCP endpoint; internal Cursor replay activity names are excluded, and overlapping built-in pi tools are hidden by default. Set `PI_CURSOR_PI_TOOL_BRIDGE=0` to disable it or `PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1` to expose overlapping built-ins too.
 - **Cursor native tool replay is display-only.** Replay renders recorded Cursor SDK activity and never re-runs Cursor-side commands, reapplies Cursor edits, calls MCP servers, or mutates pi state. Workflow tools such as Cursor mode/task/todo/plan activity are not pi workflow controls. See [Cursor native tool replay](docs/cursor-native-tool-replay.md) for supported replay cards, ordering, conflict handling, and opt-out flags.
 - **Cursor run state can span tool-use turns.** Within a pi session, the extension reuses one Cursor SDK agent across compatible follow-up turns and sends incremental prompts when context still matches. It recreates the agent when context diverges, after compaction or `/tree` navigation, on API key changes, after send errors, or on session shutdown. For bridged pi tools, the matching pi `toolResult` resolves into the same live Cursor SDK run without creating a new `Agent`, unless the run was disposed, aborted, or cancelled. Replay can also split one live Cursor SDK run across pi `toolUse` turns for display.
 - **Final assistant text is the last non-empty text part.** Composer responses can produce one assistant message with early progress `text`, thinking/tool metadata, and a later final `text` report. Consumers that need a final answer should scan assistant message content from the end and use the last non-empty `text` part, not the first. Cursor `thinking` deltas are shown as thinking traces when the SDK emits them; those traces can include draft answers or copied exact-output targets and are intentionally not collapsed by this extension.
-- **Cursor setting sources default to all.** The extension passes `local.settingSources: ["all"]` by default so configured Cursor MCP servers, plugin tools, project/user settings, and related Cursor-native capabilities are available like they are in Cursor. To narrow loading, set a comma-separated list such as `PI_CURSOR_SETTING_SOURCES=project,user,plugins`. To disable ambient setting sources, set `PI_CURSOR_SETTING_SOURCES=none`. Direct Cursor SDK bootstrap logs (settings, skills, hook-load compatibility warnings, and similar) are suppressed so they do not pollute the TUI.
+- **Cursor setting sources default to all.** The extension passes `local.settingSources: ["all"]` by default so configured Cursor MCP servers, plugin tools, project/user settings, and related Cursor-native capabilities are available like they are in Cursor. To narrow loading, set a comma-separated list such as `PI_CURSOR_SETTING_SOURCES=project,user,plugins`. To disable ambient setting sources, set `PI_CURSOR_SETTING_SOURCES=none`. Verified framed SDK inventory/rules/skills completion logs and exact hook-compatibility notices are filtered without changing settings, hooks, plugin trust, or parser enforcement. An outside-root local-plugin symlink rejection or the exact native-parser-unavailable warning instead produces a bounded native notice with recovery guidance, recorded as non-model session data without raw paths. Outside the retained creation-only mute around `Agent.create()`, other failures (including hook symlink refusals, ignore-mapping errors, and missing ripgrep configuration) retain their original output. The two recognized capability notices escape that creation mute.
 - **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.
@@ -586,6 +665,8 @@ When a Cursor run fails after auth is configured, pi surfaces scrubbed provider
 
 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.
 
+SDK 1.0.37 source preserves SDK 1.0.36's client bearer refresh and unauthenticated handling, but those mechanisms do not establish the cause of [#247](https://github.com/fitchmultz/pi-cursor-sdk/issues/247)'s historical idle failure. Reloading filesystem config is not a public auth-reset API. No guessed idle TTL or extension-level automatic resend is added: resending can duplicate executed tool effects.
+
 Network failures from the Cursor SDK connect layer (for example `ConnectError: read ETIMEDOUT` or `ConnectError: [aborted] read ECONNRESET`) surface as scrubbed `Network error` messages instead of crashing pi, matching pi's native auto-retry classifier. The SDK-provenance `WriteIterableClosedError: WritableIterable is closed` race remains guarded for the Pi session lifecycle; Connect/network suppression remains active-turn scoped; raw Cursor SDK `AbortError` DOMExceptions are suppressed while any provider turn or session process-error guard is active. Unrelated failures remain fatal. The old raw child-stdin EPIPE workaround was removed because Cursor SDK fixed that path by 1.0.27. Persistent failures may indicate a transient Cursor service or network issue.
 
 You can also restart pi with a key in the same shell or launcher that starts pi:
@@ -603,7 +684,9 @@ 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).
+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 reload the intended session to restore its registration; catalog refresh does not replace a sibling's provider. 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).
+
+Independent SessionManagers opening the same persisted file have separate transient Cursor pools, generations and live-run ownership. Reload/tree/shutdown of one manager does not invalidate the other's resources. Durable store/resume/lineage identities remain unchanged; an atomic process-local agent claim prevents a sibling from resuming or deleting a still-owned handle. Failed or timed-out SDK disposal retains that claim until successful disposal or process exit. This fixes a reproduced same-file `Cursor session agent scope is closed` trigger, not every cause reported in [#282](https://github.com/fitchmultz/pi-cursor-sdk/issues/282). It is not a cross-process lock or qualification of concurrent real SQLite/journal writes to one file; use native forks or separate files for independent conversations.
 
 ### Native shell parsing or module loading fails
 
@@ -613,11 +696,15 @@ An explicitly set `CURSOR_TREE_SITTER_VENDOR_DIR` is left untouched. Use an abso
 
 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.
+A `ResolveMessage`, missing module, or missing `protoBase64` export is a loader problem, not evidence of a bad API key. The static SDK and bridge imports in 0.5.1 also repair the compiled-Bun extension graph. A packed installation reached expected invalid-key handling in official compiled Pi 1.0.3 on macOS arm64. The retained SDK 1.0.36 installed-package probe showed its nested Connect 1.7.0 / Protobuf 1.10.0 graph linking normally; forcing its Protobuf import to the root 2.16.0 package reproduces the exact missing export. That does not establish the unnamed Windows hosts' resolution in [#233](https://github.com/fitchmultz/pi-cursor-sdk/issues/233); their importer-relative paths and bootstrap remain necessary. The credential-free real-SDK first-send test reaches a blocked key-exchange boundary, not authenticated inference or every embedded loader.
+
+SDK 1.0.37 source retains the parser-unavailable branch returning `parsingFailed`; the retained SDK 1.0.36 private package probe still executed the command. It does not itself establish why Pi received SIGTERM in the non-Cursor/opencode report [#339](https://github.com/fitchmultz/pi-cursor-sdk/issues/339). Warning text alone cannot identify the emitting artifact or signal sender.
 
 ### `pi --list-models cursor` shows no Cursor models
 
-Confirm the package is installed:
+With `PI_CURSOR_HIDE_MODELS_WHEN_LOGGED_OUT=1`, this is expected until Cursor has effective native auth. Run `/login`, supply `CURSOR_API_KEY` or pi's `--api-key`, or unset the flag to restore default fallback availability. Known CLI model selection remains available either way.
+
+If the flag is not the cause, confirm the package is installed:
 
 ```bash
 pi list
@@ -635,7 +722,7 @@ That does not mean the model cannot think. It means the Cursor SDK does not expo
 
 ### I do not see `cursor:local` / `cursor:cloud` or `plan` in the footer
 
-The Cursor footer appears only while a Cursor model is active. Fast-capable local models show `cursor:local · fast:on` or `cursor:local · fast:off`; Cursor models without a fast parameter show `cursor:local · fast:n/a`. Cloud runtime shows `cursor:cloud · fast:n/a`. Cursor SDK mode is the default `agent` mode when `plan` is absent. When both are active, pi shows one combined Cursor status such as `cursor:local · fast:on · plan` or `cursor:cloud · fast:n/a · plan`.
+The Cursor footer appears only while a Cursor model is active and `PI_CURSOR_FOOTER` is enabled (the default). Remove `PI_CURSOR_FOOTER=0` or set it to `1` to restore the status. Fast-capable local models show `cursor:local · fast:on` or `cursor:local · fast:off`; Cursor models without a fast parameter show `cursor:local · fast:n/a`. Cloud runtime shows `cursor:cloud · fast:n/a`. Cursor SDK mode is the default `agent` mode when `plan` is absent. When both are active, pi shows one combined Cursor status such as `cursor:local · fast:on · plan` or `cursor:cloud · fast:n/a · plan`.
 
 ### My Cursor app settings or rules do not seem to apply
 
@@ -711,34 +798,48 @@ PI_CURSOR_PI_BRIDGE_CALL_TIMEOUT_MS=120000 pi --model cursor/grok-4.6
 
 This usually needs session JSONL to classify. Common cases:
 
-- **Model text echo:** Assistant `text` blocks contain lines like `Tool call`, `Cursor activity`, or `call cursor-replay-…` without matching `toolCall` blocks — the Cursor model narrated pi prompt transcript format instead of invoking SDK tools. See [Tool calls listed as plain text (#40 triage)](docs/cursor-testing-lessons.md#tool-calls-listed-as-plain-text-40-triage).
+- **Model text echo:** Assistant `text` blocks contain lines like `Tool call`, `Cursor activity`, or `call cursor-replay-…` without matching `toolCall` blocks — narration is not tool execution. Structured history now uses `Historical tool request/result/error` labels, retaining arguments, IDs and errors without implying an unmatched request completed. This reduces an imitable template; it does not prevent model narration or strip legitimate prose/code examples. Raw assistant history is preserved and prose is never converted into tool calls or automatically resent. See [Tool calls listed as plain text (#40 triage)](docs/cursor-testing-lessons.md#tool-calls-listed-as-plain-text-40-triage).
 - **Stale replay routing / plan-strip:** Error `toolResult` or error assistant messages contain `Tool grep/cursor/find/ls not found`, or provider debug shows `inactive_trace` after plan-mode execute stripped active tools — tracked in **#52** (distinct from model text echo and #55).
 - **Replay vs execution:** `cursor-replay-*` IDs and neutral **Cursor MCP** activity cards are display-only recorded Cursor results; they do not re-run browser/MCP work. See [Cursor native tool replay](docs/cursor-native-tool-replay.md).
 - **Run failure / discarded tools:** A red toast with scrubbed detail may indicate an SDK failure (#55). Started-but-never-completed Cursor tools surface neutral **Cursor … did not complete** activity cards with a bounded reason when the run failed/aborted, produced no assistant text, or involved external/side-effectful tools. Incomplete fast local discovery starts (`read`, `grep`, `glob`, `ls`) are debug-only after a successful text-producing run so stale SDK start events do not create red post-answer cards; maintainer debug for the same gap remains in **#52** (`PI_CURSOR_SDK_EVENT_DEBUG=1`).
 - **Hard SDK crash:** pi exited with an uncaught Cursor SDK `ConnectError` or `WriteIterableClosedError` instead of showing a normal run error — capture the stack/session tail as a process-guard regression, not #40 text echo.
 
+Shell correlation accepts legacy names (`shell`, `bash`, `run_terminal_cmd`) with different IDs only when exactly one pending shell has identical arguments; exact IDs take precedence. This is compatibility handling, not evidence that SDK 1.0.37 emits alias-changing callback pairs. Its public shell payload uses `type: "shell"`; retained SDK 1.0.36 installed-accumulator evidence shows `onStep` preserving that completed ToolCall without adding a step ID. Assistant text or stdout progress alone does not establish completion; unmatched shell starts still remain visible and debug capture is unchanged.
+
 Capture `pi --version`, extension version, model, flags, the exact prompt, and a redacted session dir before filing bugs.
 
 ### Cursor native tool cards conflict with another extension
 
 Cursor native replay is a display enhancement for TUI sessions and structured JSON/RPC consumers. It replays recorded Cursor SDK activity without re-running tools, and print mode remains text-first. See [Cursor native tool replay](docs/cursor-native-tool-replay.md) for conflict behavior and opt-out flags.
 
+## Automatic npm releases (maintainers)
+
+Follow the [shared release procedure](https://github.com/fitchmultz/.github#automatic-npm-releases): merge a reviewed PR into `main` with an intentional `package.json` version bump and a matching versioned `CHANGELOG.md` section. Automation never bumps versions, overwrites releases, or republishes an existing version. Once configured and enabled, it runs the existing offline compatibility and native macOS/Windows jobs, qualifies one candidate tarball, then waits for `fitchmultz` approval in the `npm` environment.
+
+Approve only after checking the exact source commit, version, downloaded candidate tarball and summary against the [release review gate](AGENTS.md#release-review-gate-maintainer) and [cost-conscious verification policy](#maintainer-cost-conscious-verification). Complete the exact-release-diff deep review with zero findings, the documented pre-release catalog check, and any genuinely necessary changed-behavior proof. Approval attests genuine satisfaction of existing requirements; it does not create proof. Authenticated checks remain outside CI; automated Cursor PR reviews remain unchanged, and no routine paid Cloud campaigns or paid retries are added. Automated publication disables npm hooks to publish the checked bytes; existing manual publisher instructions remain valid.
+
+Failed/unpublished candidates can retry daily at 12:17 UTC or via manual dispatch of `npm release` on `main` only while the current source still owns the same version, tag, draft, and candidate assets. Inspect their exact source/run identities first: an authentication repair alone does not authorize publishing an old candidate after `main` advances. When source advances beyond a reserved candidate, use the next unused stable version and fresh qualification; never move its tag, overwrite its draft/assets, or relabel old proof. The [0.5.1 changelog](CHANGELOG.md#051-unpublished-source-history) is unpublished source history carried into 0.5.2, not a successful publication record. Set repository variable `NPM_RELEASE_ENABLED` to anything other than `true` to stop new release plans; cancel pending runs separately when needed. Workflow validation is not evidence of a completed real OIDC publication.
+
+Publication records are independent: on 2026-10-07, npm listed 0.5.2 as published and `latest`, while GitHub's `v0.5.2` release remained a draft bound to source `9820ae7`. Preserve that tag, draft, and candidate assets unchanged. The 0.5.3 source uses a new version and candidate; its preparation is not proof of npm or GitHub publication.
+
 ## Development
 
-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.
+Required qualification targets are the latest stable official Pi and latest maintained `fitchmultz/pi` main, with optional wildcard Pi/TypeBox host peers and exact Cursor SDK **1.0.37**. CI resolves the official version/fork commit once and retains exact SDK/CLI provenance. Types, tests and package checks use each selected host's consistent dependency graph; the locked development Pi **1.0.4** dependencies are reproducible snapshots, not qualification targets. After `npm ci --ignore-scripts`, run `node scripts/ci-compatibility.mjs --automation /path/to/automation` in an empty HOME/agent profile for credential-free latest qualification. Native macOS/Windows checks select the same resolved latest official graph. 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.
+TypeScript 7 builds and checks package types. Build and typecheck commands invoke `node_modules/typescript/bin/tsc` explicitly to avoid npm's shared `tsc` shim selecting a different compiler. `@typescript/typescript6` is dev-only for AST architecture and installed-SDK contract tests 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.
+Pull-request CI runs that suite once per selected host: the latest stable official Pi and a source-built revision of the latest maintained fork `main`, each using its own consistent dependency graph and the version/commit resolved once for the run. It checks both npm and Git installations against both hosts 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.
 
 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
+node scripts/ci-compatibility.mjs --working-tree --official-only --versions 0.87.1,0.99.1,1.0.3
 ```
 
 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 manual snapshot mode retains explicit older-host qualification for the advertised floor; it is separate from CI's once-resolved latest-only targets. Do not combine manual selection flags with `--automation`.
+
 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: