@astrosheep/pi-context 0.24.0 → 0.25.1

package/docs/architecture.md

@@ -6,36 +6,53 @@ pi-context uses Pi's session branch as the durable source of truth. It does not
 
 | Module | Responsibility | Boundary |
 | --- | --- | --- |
-| `index.ts` | Compose features, expose toggle/reset tool, construct reset boundary | Pi extension API |
-| `history.ts` | Project branch entries into windows/items; identify active window | `SessionReader`, read-only branch and session ID |
-| `notes.ts` | Replay note operations, validate paths/timestamps | `SessionReader`; no scheduling or writes |
-| `history-tools.ts`, `note-tools.ts` | Public schemas and tool results; append validated note operations | Pi tool API plus read projections |
-| `budget.ts` | Resolve settings, report usable budget, persist guidance once | Pi settings/context hooks |
-| `thresholds.ts` | Derive the reminder/reserve/warning lines from Pi's reserve plus the pi-context margins | Pi `SettingsManager`, read-only; session-scoped cache |
-| `warning.ts` | Steer the final checkpoint warning once per window | Pi context hook |
-| `prompts.ts` | Render static boot block, note index, reminder and warning | Read projections and protocol text |
-| `reset-lifecycle.ts` | Own reset requests, completion and continuation | Pi lifecycle hooks and injected boundary builder |
+| `index.ts` | Thin public entrypoint: register the context runtime and tool adapters, and preserve public history/notes re-exports | Pi extension API |
+| `context/runtime.ts` | Compose runtime hooks, toggle/reset commands, boot construction, marker/boot boundaries, and provider projection | Pi extension API plus context and notes modules |
+| `history/history.ts` | Project branch entries into windows/items using the shared window identity | `SessionReader`, read-only branch and session ID |
+| `context/context-window.ts` | Own durable window identity, select the active boot, project provider context, and account for active-window usage | `SessionReader` plus Pi context/system projection APIs |
+| `notes/session-replay.ts` | Replay persisted note operations from session entries | `SessionReader`; no filesystem acquisition |
+| `notes/address.ts` | Validate virtual note paths and resolve address/glob forms | Note address syntax; no session-branch selection |
+| `notes/notes-snapshot.ts` | Acquire the five notes homes once into a closed boot snapshot and isolate filesystem-home failures | Filesystem-backed notes homes; no rendering or UI effects |
+| `notes/store.ts` | Read and mutate the filesystem-backed homes; distinguish an absent home from a real read failure | Notes filesystem only; boot acquisition isolates one home at a time |
+| `history/history-tools.ts` | Public history schemas and tool results over branch projections | Pi tool API plus read projections |
+| `notes/tools.ts` | Filesystem note tool adapters; validate and perform note reads, writes, edits, listings, and searches | Pi tool API plus notes filesystem |
+| `context/budget.ts` | Own the default-path per-extension-instance settings cache, read injected policy live, report usable budget, stage guidance/warning drafts, and resolve automatic reset decisions | Pi settings/context hooks plus protocol warning text |
+| `context/thresholds.ts` | Read the selected public settings authority and derive reminder/reserve/warning thresholds from Pi's reserve plus the pi-context margins | Pi `SettingsManager`, read-only; no mutable cache or UI effects |
+| `settings.ts` | Merge the global and project `pi-context` settings object per key | Parsed Pi settings scopes; no I/O or runtime state |
+| `dream/settings.ts` | Validate and resolve the configured dreamer model from the shared settings merge | Pi `SettingsManager`; no runtime context state |
+| `context/prompts.ts` | Render the static boot block, note index, and low-budget reminder from explicit data | Snapshot data and protocol text; no filesystem acquisition or UI effects |
+| `context/reset-lifecycle.ts` | Own reset requests, turn-end batching, recovery and continuation | Pi lifecycle hooks and injected boundary builder |
 | `protocol.ts` | Persisted entry tags, protocol text and defaults | No imports or effects |
 | `tool-schema.ts`, `tool-output.ts` | Shared wire-schema primitives and JSON result encoding | No session state |
 
-Dependencies flow from the composition root and tool adapters to projections and protocol constants. Projections cannot send messages, compact, notify, or mutate the session. A runtime framework or generic event bus would add indirection without strengthening these boundaries.
+Dependencies flow from the composition root and tool adapters to projections and protocol constants. The published Pi entry is `dist/extension.js`, built from `src/index.ts`; its public `pi-ai/utils/estimate` dependency is inlined so Pi's root-package aliases cannot misresolve the utility subpath. Host-owned package APIs remain external. Projections cannot send messages, compact, notify, or mutate the session. A runtime framework or generic event bus would add indirection without strengthening these boundaries.
 
 ## State and persistence
 
-Reset requests are a discriminated union: `idle`, `requested`, or `compacting` with an identified attempt. A request cannot simultaneously be pending and in flight. Each attempt records its originating session, whether it was explicit, and whether a matching boundary completed. Callback identity prevents an old attempt from consuming a newer one. See [reset lifecycle](reset-lifecycle.md).
+`turn_end` has one composer in `reset-lifecycle.ts`: it accepts the incoming drafts, drains the budget instance's staged guidance/warning drafts, and only then appends reset drafts. Reset requests are committed after the complete tool batch with `continue: true`, so Pi owns queue scheduling. Repeated `wipe_memory` requests in one batch deduplicate; a later window may still request another reset. Aborts and reset-construction failures preserve already-built drafts without manufacturing a continuation. See [reset lifecycle](reset-lifecycle.md).
 
-Manual, threshold and overflow compactions all build the reset boundary on the spot, idle or streaming: `session_before_compact` returns the reset immediately, never cancels and never takes a model turn, and only an aborted signal cancels. The final checkpoint warning was already steered from the context hook (see [reset lifecycle](reset-lifecycle.md)), so the model had its chance to write a note; what crosses the line now is the wipe itself. `agent_settled` services only explicit `wipe_memory` requests, whose `ctx.compact` route needs the completion callback.
+The durable boundary is one `pi-context/reset-marker` custom entry with `{ windowId: string }`, followed by one hidden `pi-context/boot` custom message with `details.windowId` equal to the marker identity. The marker is the only window boundary. `context/context-window.ts` owns the marker predicate, active-branch scan, root/current IDs, and per-window message lookup; `history/history.ts` consumes those identity primitives while projecting entries. The scan never uses a global entry tail. Native compaction and branch-summary entries remain history items in the current window, so the old compaction-entry identity is not a window identity.
 
-Boot and reminder deduplication inspect messages in the current persisted window. Reloading the extension or the JSONL file therefore does not duplicate either message. Reminder reservation in memory covers Pi's deferred message write; navigation clears that reservation, while persisted branch-local messages remain authoritative. A sibling branch cannot suppress a reminder it never received.
+The runtime in `context/runtime.ts` performs final context projection by selecting the active boot through `details.windowId` and folding only the dropped system prefix through Pi's `getCurrentSystemMessage`. Later prompt patches and new messages stay in order. A missing boot aborts the hook with a safe head and notice rather than silently sending raw history. Startup/tree handling repairs only a genuinely incomplete marker tail: a missing boot with no later raw message, custom message, compaction, branch summary, or authoritative raw boot. If later work exists, boot creation is refused and `/wipe-memory` is the explicit recovery path; it does not parse or migrate the legacy reset-v2 protocol.
 
-Note replay accepts only supported operations, safe virtual paths, representable timestamps and results within the UTF-8 size limit. Invalid operations are ignored; they cannot replace a valid note. Reads reconstruct the current branch without a cache, so navigating a branch cannot expose notes from a sibling.
+Boot and reminder deduplication inspect the current branch-local window. Reloading JSONL therefore does not duplicate messages, while navigation to a sibling branch cannot inherit another branch's window state. A fork/clone receives a new session ID while copying its selected path, so startup must also verify that a root boot's `details.windowId` matches the new `rootWindowId(sessionId)` before treating it as present.
 
-Reset IDs are opaque strings tagged with `reset-v2`; newly minted IDs use `pcw:<session>:<8 lowercase hex digits>`. Unsupported details fall back to Pi's compaction-entry identity for history lookup. Minting checks existing branch window IDs, which are independent of Pi entry IDs. A reset adds a marker via the public append API, then uses its real entry ID as `firstKeptEntryId`; old conversation remains searchable in the durable branch.
+Startup and idle manual resets use `pi.sendMessage(..., { triggerTurn: false })` for the boot. Pi appends it to the session and refreshes context without initiating a model request; during streaming the same call is deferred until the completed tool batch. This is session persistence, not a promise of immediate disk durability: Pi 0.87 defers a new session file until its first assistant message, and the extension API reports send failures through extension errors rather than an awaitable result. Running resets therefore use boundary drafts for ordering and continuation, not `sendMessage`. Drafts are validated together but disk writes are not transactional.
+
+Boot is a fixed snapshot for its window, stored as an extension custom message and converted by Pi to a user-role model message. History's `developer` classification records extension authorship, not provider instruction priority. A system-role projection is technically possible through `context_with_system`, but would change the authority of the mixed protocol/MAP content and provider-specific prompt/cache behavior; it is not a prerequisite for persistence. Boot injection is silent, including startup, reload, and boot repair. Only an actual context reset produces `pi-context: memory cleared · <windowId>` through `ctx.ui.notify`, after both marker and boot are present in the session. Manual clear is checked immediately; running resets are checked at the next turn start or final settlement. Uncommitted reset drafts never announce success. Boot and continuation messages retain `display: false`.
+
+History reads reconstruct the selected session branch on demand without a cache, so branch navigation cannot expose history from a sibling.
+
+The boot notes index in `notes/notes-snapshot.ts` is a closed snapshot: the current session, project, human, agent, and model homes are each loaded at most once while constructing a boot. `context/prompts.ts` then renders that explicit snapshot without reading the filesystem or consulting the clock. MAP bodies and pocket metadata are derived from the same snapshot, so a boot cannot mix two filesystem reads. A missing home (`ENOENT`) is normal. A real read failure omits only that home's index, preserves healthy homes, adds a model-facing `notes_list` recovery notice, and notifies the human once for that window. The window identity, reset/protocol text, and lifecycle boundary are still constructed through the normal runtime path; note reads never mutate files or create fallback state.
+
+`notes/session-replay.ts` accepts only supported operations, safe virtual paths, representable timestamps and results within the UTF-8 size limit. Invalid operations are ignored; they cannot replace a valid note. Notes remain in their filesystem-backed homes, unchanged by session branch navigation.
+
+The `/wipe-memory` command waits for idle, appends the marker and boot with Pi's public `appendEntry`/`sendMessage` APIs, and never calls a model. While enabled, `/compact` is cancelled with an actionable `/wipe-memory` notice. Disabling pi-context stops new automatic resets, but an existing marker still excludes earlier history and native compaction is still cancelled on that marked branch; a fresh root may use native Pi semantics. Threshold and warning accounting use active-window provider usage rather than pre-reset global usage. Budget policy and staged prompts are instance-owned, so concurrent sessions cannot share reserve/enablement or uncommitted drafts; default file-backed policy is cached per instance, while injected policy is resolved live on each decision and model/session transitions reset the diagnostic lifecycle.
 
 ## Evidence and limits
 
-The integration suite uses real SessionManager and SettingsManager instances, including JSONL restoration, branch navigation, Unicode content, malformed note operations and settings precedence. Lifecycle event tests cover duplicate/stale callbacks, native scheduling, disabled state, abort and failed compaction.
+The retained integration tests use real SessionManager and SettingsManager instances. They check reset-window history retention, bounded history/notes reads with resumable cursors, notes-home isolation, and settings precedence. The suite is a representative regression set; the standalone coherence, pagination property, history, and threshold suites were removed during test reduction.
 
-Scripted SDK tests execute the real Pi agent loop with no model network request. They cover explicit reset, instant automatic reset, rejected compaction, steering and follow-up delivery before reset without replay, consecutive distinct windows, and cancellation followed by a new user prompt. They inspect actual provider contexts and durable entries. They do not establish reliability of an external provider or every possible interleaving between unrelated extensions.
+Scripted SDK tests execute the real Pi agent loop with no model network request. They inspect provider contexts and durable entries for reset boundaries, mixed-tool completion, queued steering/follow-up delivery, overflow recovery, and settings authority. Smaller dream tests retain lock exclusion/ownership, jailed writes, CLI audit/report failure propagation, and read-only doctor behavior. Removing duplicate scenarios and edge-case matrices reduces coverage; the remaining tests do not establish every malformed-input case, branch interleaving, external-provider behavior, or filesystem failure mode.
 
-Pi decides compaction eligibility before the boundary hook. A short uncompactable session therefore cannot be force-reset with the public API. Mixed tool batches and queued messages may finish before `agent_settled`; the extension preserves their delivery rather than clearing the queue. Native compaction owns its subsequent scheduling, while extension-requested compaction resumes from `onComplete` after Pi clears compaction state.
+Mixed tool batches finish before the marker/boot boundary. Queued steering/follow-up messages are delivered exactly once in the new window; they are neither dropped nor replayed. Runtime overflow recovery is bounded to one reset/retry per failure chain, while ordinary retryable provider errors remain Pi-owned. When either the source or destination branch has a reset marker, `/tree` navigation still succeeds but its generated summary is replaced by an empty summary plus a notice; raw history and branch selection remain available. If neither branch has a marker, Pi's native tree summary is retained.

package/docs/reset-lifecycle.md

@@ -1,24 +1,83 @@
 # Reset lifecycle
 
-`src/reset-lifecycle.ts` owns reset requests, compaction attempts, and continuation. `src/index.ts` composes the features and constructs reset boundaries; projections, tools, budget policy, and prompt rendering have separate modules described in [Architecture](architecture.md).
+`src/context/reset-lifecycle.ts` owns reset requests, turn-end batching, recovery, and continuation. It is the sole `turn_end` composer: incoming drafts, budget drafts, and reset drafts are ordered here. `src/context/budget.ts` owns the default-path instance-local policy cache, resolves injected policy live, stages guidance/warning drafts, and keeps the final warning text in the budget/protocol path; `src/context/thresholds.ts` only reads settings and derives values, using the shared merge in `src/settings.ts`. `src/index.ts` is the thin public entrypoint; `src/context/runtime.ts` composes the runtime hooks and constructs marker/boot boundaries. `src/notes/notes-snapshot.ts` acquires the notes snapshot, while `src/context/prompts.ts` only renders the explicit boot data and low-budget reminder. Projections and tools have separate modules described in [Architecture](architecture.md).
 
 | Event | Transition / owner |
 | --- | --- |
-| `wipe_memory` | Mark explicit request; repeated calls report already pending. Tool returns terminal output. |
-| Manual, threshold or overflow `session_before_compact`, idle or streaming | Build the reset boundary immediately and return it. Never cancel and never take a model turn; an aborted signal returns `{ cancel: true }`. |
-| `agent_end` | No-op for an instant reset. |
-| `agent_settled` | If idle and an explicit request is pending, create one identified attempt and request `ctx.compact`. The originating handler owns and awaits that attempt through its continuation's settlement. |
-| Matching `session_compact` | Confirm boundary, persist window state. Native compaction retains its own scheduling. |
-| Attempt `onComplete` | Consume attempt; for a confirmed boundary when idle with no queued messages, register continuation ownership before sending it. Its nested `agent_settled` settles that owner; a reset requested by the continuation completes its own handoff before releasing its predecessor. |
-| Attempt `onError` or synchronous throw | Clear attempt/request, warn, retain history. No automatic retry loop. |
-| Shutdown / start / tree / toggle off | Invalidate outstanding attempt. Identity checks reject callbacks from older attempts. |
+| `wipe_memory` | Record an explicit reset request. Repeated calls in one tool batch deduplicate; the tool returns terminal output. |
+| `turn_end` | The sole composer drains current-window budget drafts after the event entries, then appends reset drafts: one `pi-context/reset-marker` with `{ windowId }`, one hidden boot message with matching `details.windowId`, and the continuation marker; continue the turn through Pi's public queue. |
+| Abort before the boundary | Drop the pending boundary. Never manufacture a continuation for an aborted turn. |
+| Threshold / provider overflow | Request the same marker/boot boundary for the active provider window. Actual overflow/length recovery retries at most once per failure chain; ordinary retryable provider errors stay Pi-owned. |
+| `/wipe-memory` | Wait for idle, append marker and boot through public session APIs, and do not call a model. |
+| `/compact` while enabled | Cancel with an actionable `/wipe-memory` notice so native compaction cannot summarize erased canonical history back into the active window. |
+| Startup / tree / partial append | Repair only a marker followed by an otherwise empty metadata tail; refuse hidden/absent boots once later work exists, leaving `/wipe-memory` as the explicit recovery path. Do not interpret legacy reset-v2 details. |
+| `/pi-context off` | Stop new automatic resets, but retain the boundary of an existing marker. Marked branches still cancel native compaction; a fresh root may use Pi's native semantics. |
 
-The final checkpoint warning is steered earlier from the context hook (`warning.ts`) once per window at reserve+12288 tokens remaining. After it, the model either ends the window itself with `wipe_memory` or rides into Pi's automatic compaction, which resets on the spot with no turn.
+## Reset-control state machine
 
-The completion callback is the scheduling boundary: `session_compact` fires before Pi clears manual compaction state. Sending a prompt inside that hook is too early. An explicit reset uses the manual `ctx.compact` route and therefore needs this completion logic; an automatic compaction is already the reset and resumes through Pi's own caller.
+`registerResetLifecycle` is the effect adapter. `reduceResetControl` in `src/context/reset-lifecycle.ts` is the pure transition surface: given the current state and one lifecycle event it returns the next state and one named effect, performing no writes, policy resolution, or UI work of its own. The adapter captures Pi's events, supplies the guards only in the branches that consult them, then performs the marker/boot/continuation writes, continuation requests, and notices.
 
-`sendMessage(..., { triggerTurn: true })` starts its run detached from the extension API. The explicit attempt therefore retains an attempt-owned waiter before sending it, and its originating `agent_settled` handler awaits that waiter. The continuation's `agent_settled` releases the waiter without awaiting itself. If that continuation calls `wipe_memory`, its settled handler starts and awaits the next attempt before it releases the prior waiter, forming a bounded reset chain. Failure, cancellation, shutdown, tree navigation, and toggling off release the relevant waiter exactly once.
+State is a single value with two explicitly typed axes. There are no independently combinable lifecycle booleans.
 
-Public APIs cannot guarantee immediate reset inside mixed tool batches or before queued steering/follow-up messages finish. `terminate` ends the tool-followup path; `agent_settled` remains the safe point to request compaction. The scheduler does not manipulate user queues. Pi also determines compaction eligibility before the extension hook; an uncompactable session produces a warning and waits for a new prompt.
+| Axis | Value | Meaning |
+| --- | --- | --- |
+| `request` | `none` | no explicit wipe request pending |
+| | `explicit` | one explicit request is pending and will commit at the next `turn_end` |
+| `overflow` | `idle` | no overflow failure pending; a future recovery is available |
+| | `pending` | active-provider overflow failure pending; recovery still available |
+| | `pending-spent` | overflow failure pending, but its one recovery was already spent |
+| | `spent` | recovery spent and the failure is no longer pending |
 
-Validation is split into persisted-data integration tests, isolated lifecycle event tests, and scripted SDK tests running Pi's actual agent loop. The SDK tests cover explicit success, instant automatic reset, and core compaction rejection followed by a user prompt. Lifecycle tests cover callback races and queue guards without pretending to exercise provider/network behavior.
+All eight combinations of the two axes are reachable and each has a defined transition.
+
+| Event | Guard | Next state | Effect |
+| --- | --- | --- | --- |
+| `request` | `request=none` | `request=explicit`, overflow unchanged | `requested` |
+| `request` | `request=explicit` | unchanged | `already-requested` |
+| `turn_end` | turn aborted | `(request=none, overflow=idle)` | `none` |
+| `turn_end` | overflow-like and `!queued && enabled && automaticResetEnabled` | `request=none`; overflow `pending`, or `pending-spent` if already spent | `none` |
+| `turn_end` | overflow-like and (`queued \|\| !enabled \|\| !automaticResetEnabled`) | `request=none`; overflow `idle`, or `spent` if already spent | `none` |
+| `turn_end` | completed, `enabled`, and (`explicit` requested or `thresholdDue`) | `(request=none, overflow=idle)` | `commit-boundary` |
+| `turn_end` | completed, `enabled`, but neither trigger | `(request=none, overflow=idle)` | `none` |
+| `turn_end` | non-overflow `failed` | `request=none`; overflow unchanged | `none` |
+| `turn_end` | `!enabled` | `request=none`; completed clears overflow, error keeps it | `none` |
+| `before_settle` | `overflow=pending`, not queued, `enabled`, `automaticResetEnabled`, not aborted | `overflow=spent` | `recover-overflow` |
+| `before_settle` | `overflow=pending-spent` | `overflow=spent` | `none` |
+| `before_settle` | `overflow` not pending, or queued | unchanged | `none` |
+| `before_settle` | pending but `!enabled`, `!automaticResetEnabled`, or aborted | disarms to `idle` (`spent` if already spent) | `none` |
+| `settled` | — | `overflow=idle`; `request` unchanged | `none` |
+| `abort` / `clear` | — | `(request=none, overflow=idle)` | `none` |
+
+### Invariants
+
+1. At most one explicit request is pending at a time; duplicate requests in one tool batch dedupe and never queue a second boundary.
+2. Every `turn_end` consumes a pending explicit request, whether or not that turn commits a reset.
+3. A committed reset is exactly `marker -> boot -> continuation`, and ordinary and budget drafts are ordered before the marker. Budget staging is drained once per turn and discarded on abort or disabled mode.
+4. Reset drafts are built once per commit. If construction throws, already-built incoming and budget drafts survive and no continuation is requested.
+5. Overflow recovery is one attempt per failure chain: a failure arms `pending` only when nothing is queued, the extension is enabled, and automatic reset is enabled; a settle spends it to `spent`; a later failure becomes `pending-spent` and cannot recover again until settlement ends the chain.
+6. Aborted turns never manufacture a continuation and clear both axes. Non-overflow errors keep the armed overflow chain for the settle boundary.
+7. A successful non-overflow turn clears the overflow chain first, so a queued success supersedes a stale overflow failure before settle recovery can act.
+8. `settled` ends the failure chain but preserves a pending explicit request; `clear` (session start, tree navigation, shutdown, `/pi-context off`, `/wipe-memory`) resets both axes.
+9. Disabled mode never commits a reset and never arms or spends overflow recovery; an existing persisted marker stays authoritative for native-compaction cancellation.
+10. Policy guards (`queued`, `automaticResetEnabled`, `thresholdDue`) are consulted only in the branch that needs them, preserving the adapter's original resolution order.
+
+### Critical sequences
+
+- **Normal reset.** A completed, enabled turn whose explicit request is pending or whose usage is due returns `commit-boundary`. The adapter drains budget drafts, keeps incoming drafts in order, appends `marker -> boot -> continuation`, and requests continuation. A second request in the same batch returns `already-requested`; the next turn commits it alone.
+- **Overflow recovery.** An overflow-like `turn_end` with no queued message, enabled mode, and automatic reset arms `pending`; a `before_settle` with no queued message returns `recover-overflow` and spends the attempt to `spent`. A repeated settle is a no-op, and a later overflow failure re-arms only `pending-spent`.
+- **Abort.** An aborted `turn_end` returns only the drafts already collected for that boundary, clears both axes, and never appends reset drafts.
+- **Queued success.** A queued message defers `before_settle`; the queued turn's successful `turn_end` clears the stale overflow chain, so no recovery fires.
+- **Process interruption.** If Pi stops between the marker and the later reset messages, the marker remains the authoritative boundary. On the next start, startup repair may append only the missing boot and continuation when the tail is otherwise repairable; it never moves or reinterprets the boundary.
+- **Startup tail repair.** On `session_start` / `session_tree`, `ensureBoot` asks `repairResetTail` to inspect the marker tail and emit only the missing artifacts in the closed order: the boot, then the continuation. A boot/continuation sequence that is already complete, or a tail containing real conversation, a foreign message, a later marker, or a misordered/duplicate artifact, refuses repair and leaves `/wipe-memory` as the explicit recovery path.
+
+The budget owner stages the early guidance and final checkpoint warning from active-window usage. The warning is visible in the current provider request, while both drafts are committed only by the lifecycle composer and are discarded on abort, settlement without a `turn_end`, transition, or window mismatch. After the warning, the model either writes its note and calls `wipe_memory`, or runtime recovery requests the same marker/boot boundary. Guidance and warning drafts precede reset drafts so stale reminders cannot be queued into the new window; durable entries remain the authority for redelivery. Their UI notices are emitted at the next turn start or settlement only after the matching reminder is committed in the active window, so aborted requests and retries cannot repeat an uncommitted reminder's notification.
+
+The turn-end commit is the scheduling boundary: Pi receives the finished tool batch and then the marker/boot drafts as one append operation. Pi owns queue scheduling and deduplication of the next request; the extension does not run a parallel compaction state machine or use a compaction completion callback.
+
+Boot construction reads the five note homes into one closed snapshot before rendering the hidden boot. An absent home is empty; a real read failure removes only that home's MAP/pocket rows. The boot retains its identity, reset line, notes-home instructions, and recovery protocol, and includes a concise `notes_list` retry notice. The human receives one incomplete-index notification per boot. This notes failure isolation does not bypass the marker/boot commit, alter raw history, or turn a partial boot into an empty fallback.
+
+The hidden boot is selected by its durable `details.windowId`, not by timestamp or content equality. The context hook folds only the dropped system prefix before that boot and preserves later prompt patches and messages in order. If the boot is missing, the hook aborts with a safe head and notice rather than sending raw history. Startup/tree repair is deliberately narrow: it appends a boot only when the marker tail is otherwise incomplete metadata; later conversation or an authoritative raw boot causes safe refusal. `/wipe-memory` is the recovery path for that refused branch. A fork/clone creates a new session ID while copying branch entries, so startup refreshes the root boot identity while retaining copied root messages.
+
+Public APIs let a mixed tool batch finish before the marker/boot boundary. Queued steering/follow-up messages are delivered exactly once in the new window, neither dropped nor replayed. `/tree` navigation remains available, but when either source or destination branch contains a reset marker, Pi's raw summary generator is bypassed: the summary is empty and a notice explains why, preventing erased history from re-entering through a path outside the context hook. With no marker on either branch, native summaries remain unchanged.
+
+Validation uses a reduced set of persisted-data integration tests, isolated lifecycle event tests, and scripted SDK tests running Pi's actual agent loop. Representative cases check reset-window history retention, resumable reads, native-compaction cancellation, mixed-tool completion, steering/follow-up delivery, bounded overflow recovery, and settings authority. Tree-summary suppression no longer has a dedicated retained test. The separate coherence and pagination property suites have been removed; the retained cases do not cover the previous full matrix of branch, cancellation, malformed-input, and pagination edges.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "type": "module",
-  "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
+  "description": "Codex-style context windows for Pi: durable reset windows, session history tools, and persistent notes.",
   "license": "MIT",
   "keywords": [
     "pi-package",
@@ -15,7 +15,7 @@
   },
   "pi": {
     "extensions": [
-      "./src/index.ts"
+      "./dist/extension.js"
     ]
   },
   "files": [
@@ -30,22 +30,23 @@
     "dream": "dist/src/dream/cli.js"
   },
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/src/dream/cli.js', 0o755)\"",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node scripts/build-extension.mjs && node -e \"require('node:fs').chmodSync('dist/src/dream/cli.js', 0o755)\"",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test dist/test/*.test.js",
     "prepublishOnly": "npm run typecheck",
     "prepack": "npm run build"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-agent-core": "^0.87.0",
+    "@earendil-works/pi-ai": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "^0.87.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.86.0",
-    "@earendil-works/pi-ai": "^0.86.0",
-    "@earendil-works/pi-coding-agent": "^0.86.0",
+    "@earendil-works/pi-agent-core": "^0.87.0",
+    "@earendil-works/pi-ai": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "^0.87.0",
     "@types/node": "^22.19.19",
+    "esbuild": "^0.28.2",
     "typescript": "^5.9.3"
   },
   "publishConfig": {

package/src/context/boot.ts

@@ -0,0 +1,68 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadNotesSnapshot, type NotesSnapshot } from "../notes/notes-snapshot.js";
+import { agentSlug, modelSlug } from "../notes/paths.js";
+import { BOOT_TYPE } from "../protocol.js";
+import { renderBootBlock } from "./prompts.js";
+import { currentReset, isWindowBoot, rootWindowId } from "./context-window.js";
+import { repairResetTail } from "./reset-artifacts.js";
+
+export type IncompleteNotesNotifier = (ctx: ExtensionContext, windowId: string, snapshot: NotesSnapshot) => void;
+
+/** The boot custom message: identity, notes snapshot, and static protocol; never reset prose. */
+export type BootMessage = {
+	readonly customType: string;
+	readonly content: string;
+	readonly display: false;
+	readonly details: { windowId: string };
+};
+
+/** Render the boot block from the live context; acquisition stays with loadNotesSnapshot. */
+function bootContent(ctx: ExtensionContext, currentId: string, previousId: string | undefined, notes: NotesSnapshot): string {
+	return renderBootBlock({
+		agentName: agentSlug(ctx),
+		modelName: modelSlug(ctx),
+		firstWindowId: rootWindowId(ctx.sessionManager.getSessionId()),
+		currentWindowId: currentId,
+		previousWindowId: previousId,
+		notes,
+	});
+}
+
+/**
+ * Acquire one notes snapshot and build the boot custom message for a window. The caller
+ * supplies `previousId` only when a reset boundary needs the prior window identity.
+ */
+export function buildBootMessage(
+	ctx: ExtensionContext,
+	windowId: string,
+	previousId: string | undefined,
+	notifyIncompleteNotes?: IncompleteNotesNotifier,
+): BootMessage {
+	const notes = loadNotesSnapshot(ctx);
+	notifyIncompleteNotes?.(ctx, windowId, notes);
+	return { customType: BOOT_TYPE, content: bootContent(ctx, windowId, previousId, notes), display: false, details: { windowId } };
+}
+
+/** Persist one hidden boot message without triggering a model turn. */
+export function sendBoot(pi: ExtensionAPI, boot: BootMessage): void {
+	pi.sendMessage(
+		{ customType: boot.customType, content: boot.content, display: boot.display, details: boot.details },
+		{ triggerTurn: false },
+	);
+}
+
+/**
+ * Boot entry point for `session_start` / `session_tree`. Ordinary startup ensures one root
+ * boot; a reset marker instead asks reset-artifact repair to complete its persisted tail.
+ * Boot idempotence lives here: an already-projected root boot or a complete reset tail emits nothing.
+ */
+export function ensureBoot(pi: ExtensionAPI, ctx: ExtensionContext, notifyIncompleteNotes?: IncompleteNotesNotifier): void {
+	const reset = currentReset(ctx);
+	if (reset) {
+		repairResetTail(pi, ctx, reset, notifyIncompleteNotes);
+		return;
+	}
+	const windowId = rootWindowId(ctx.sessionManager.getSessionId());
+	if (ctx.sessionManager.buildSessionProjection().messages.some((message) => isWindowBoot(message, windowId))) return;
+	sendBoot(pi, buildBootMessage(ctx, windowId, undefined, notifyIncompleteNotes));
+}

package/src/context/budget.ts

@@ -0,0 +1,148 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI, type ExtensionContext, type SessionBoundaryDraft, type SettingsManager } from "@earendil-works/pi-coding-agent";
+import { GUIDANCE_CLOSE_TAG, GUIDANCE_OPEN_TAG, GUIDANCE_TYPE, WARNING_PROMPT, WARNING_TYPE } from "../protocol.js";
+import { readThresholdSettings, type ResolvedThresholds, type ThresholdSettingsResolution } from "./thresholds.js";
+import { currentWindowId, hasWindowMessage, windowUsage } from "./context-window.js";
+import { tokenBudgetGuidance } from "./prompts.js";
+import { output } from "../tool-output.js";
+
+/** Remaining tokens in the provider's active window, or null without a usable estimate. */
+export function remainingTokens(ctx: Pick<ExtensionContext, "sessionManager" | "getContextUsage" | "model">): number | null {
+	const usage = windowUsage(ctx);
+	return !usage || usage.tokens === null ? null : Math.max(0, usage.contextWindow - usage.tokens);
+}
+
+export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, settingsManager?: SettingsManager) {
+	let cachedPolicy: { thresholds: ResolvedThresholds; automatic: boolean } | undefined;
+	const notifiedWarnings = new Set<string>();
+	const resolvePolicy = (ctx: ExtensionContext): ThresholdSettingsResolution => {
+		if (!settingsManager && cachedPolicy) return { ...cachedPolicy, warnings: [] };
+		const resolution = readThresholdSettings(ctx, settingsManager);
+		for (const warning of resolution.warnings) {
+			if (notifiedWarnings.has(warning)) continue;
+			notifiedWarnings.add(warning);
+			ctx.ui.notify(warning, "warning");
+		}
+		if (!settingsManager) cachedPolicy = { thresholds: resolution.thresholds, automatic: resolution.automatic };
+		return resolution;
+	};
+	const thresholdsFor = (ctx: ExtensionContext): ResolvedThresholds => {
+		return resolvePolicy(ctx).thresholds;
+	};
+	const automaticResetEnabled = (ctx: ExtensionContext): boolean => {
+		return resolvePolicy(ctx).automatic;
+	};
+	const resetDue = (ctx: ExtensionContext): boolean => {
+		if (!automaticResetEnabled(ctx)) return false;
+		const usage = windowUsage(ctx);
+		return usage !== undefined && usage.tokens !== null && usage.contextWindow - usage.tokens <= thresholdsFor(ctx).reserve;
+	};
+	const invalidateThresholds = () => { cachedPolicy = undefined; };
+	let pendingGuidance: { windowId: string; content: string } | undefined;
+	let pendingWarning: { windowId: string; content: string } | undefined;
+	let pendingNotices: Array<{ windowId: string; customType: string }> = [];
+	const notifyCommittedReminders = (ctx: ExtensionContext) => {
+		const windowId = currentWindowId(ctx);
+		for (const notice of pendingNotices) {
+			if (notice.windowId !== windowId || !hasWindowMessage(ctx, notice.customType)) continue;
+			ctx.ui.notify(notice.customType === WARNING_TYPE
+				? "pi-context: context budget critical — final checkpoint warning recorded for the model."
+				: "pi-context: context budget low — checkpoint reminder recorded for the model, kept out of the chat view.", "warning");
+		}
+		pendingNotices = [];
+	};
+
+	const clearStaged = () => {
+		pendingGuidance = undefined;
+		pendingWarning = undefined;
+	};
+	const resetForTransition = () => {
+		clearStaged();
+		pendingNotices = [];
+		invalidateThresholds();
+		notifiedWarnings.clear();
+	};
+
+	const consumeTurnEnd = (ctx: ExtensionContext): SessionBoundaryDraft[] => {
+		const staged = [
+			pendingGuidance ? { ...pendingGuidance, customType: GUIDANCE_TYPE } : undefined,
+			pendingWarning ? { ...pendingWarning, customType: WARNING_TYPE } : undefined,
+		];
+		clearStaged();
+		const windowId = currentWindowId(ctx);
+		const drafts = staged.filter((draft): draft is NonNullable<typeof draft> => draft !== undefined && draft.windowId === windowId);
+		pendingNotices = drafts.map(({ windowId, customType }) => ({ windowId, customType }));
+		return drafts.map((draft) => ({
+			type: "custom_message" as const,
+			customType: draft.customType,
+			content: draft.content,
+			display: false,
+		}));
+	};
+
+	pi.on("session_start", (_event, ctx) => { resetForTransition(); thresholdsFor(ctx); });
+	pi.on("session_tree", resetForTransition);
+	pi.on("model_select", resetForTransition);
+	pi.on("session_shutdown", resetForTransition);
+	// A request can fail before Pi emits turn_end. agent_settled is the public
+	// lifecycle point that must discard an uncommitted draft before the next prompt.
+	// UI notices follow committed reminders. Aborted requests can retry their drafts
+	// without showing the same low-budget notification twice.
+	pi.on("turn_start", (_event, ctx) => notifyCommittedReminders(ctx));
+	pi.on("agent_settled", (_event, ctx) => {
+		notifyCommittedReminders(ctx);
+		clearStaged();
+	});
+	pi.on("context", (_event, ctx) => {
+		if (!isEnabled()) return undefined;
+		// The early reminder persists once per window the first time remaining crosses
+		// reserve+margin. It never edits the outgoing request.
+		const remaining = remainingTokens(ctx);
+		if (remaining === null) return undefined;
+		const windowId = currentWindowId(ctx);
+		const { reminder, warning } = thresholdsFor(ctx);
+		if (hasWindowMessage(ctx, WARNING_TYPE) || pendingWarning?.windowId === windowId) return undefined;
+		if (remaining <= warning) {
+			// A not-yet-committed shallow reminder is superseded by the final warning.
+			pendingGuidance = undefined;
+			const content = `${GUIDANCE_OPEN_TAG}\n${WARNING_PROMPT}\n${GUIDANCE_CLOSE_TAG}`;
+			pendingWarning = { windowId, content };
+			const warningMessage = {
+				role: "custom" as const,
+				customType: WARNING_TYPE,
+				content,
+				display: false,
+				timestamp: Date.now(),
+			};
+			return { messages: [..._event.messages, warningMessage] };
+		}
+		if (hasWindowMessage(ctx, GUIDANCE_TYPE) || pendingGuidance?.windowId === windowId) return undefined;
+		if (remaining <= reminder) {
+			// Persist at turn_end, before any reset drafts. A queued sendMessage could
+			// otherwise cross the marker and leak the old window's reminder forward.
+			const left = Math.max(0, remaining - warning);
+			pendingGuidance = { windowId, content: tokenBudgetGuidance(left) };
+		}
+		return undefined;
+	});
+
+	pi.registerTool(defineTool({
+		name: "get_context_remaining",
+		label: "Get context remaining",
+		description: "Return estimated context tokens left before your memory is wiped; null when Pi cannot estimate usage.",
+		parameters: Type.Object({}, { additionalProperties: false }),
+		async execute(_id, _params, _signal, _update, ctx) {
+			// The countdown the model sees ends at the warning line (reserve + runway);
+			// the runway below it is overdraft the model never sees. See protocol.ts.
+			const remaining = remainingTokens(ctx);
+			return output({ remaining_tokens: remaining === null ? null : Math.max(0, remaining - thresholdsFor(ctx as ExtensionContext).warning) });
+		},
+	}));
+
+	return {
+		automaticResetEnabled,
+		resetDue,
+		consumeTurnEnd,
+		clear: () => { clearStaged(); pendingNotices = []; },
+	};
+}

package/src/context/context-window.ts

@@ -0,0 +1,118 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { getCurrentSystemMessage } from "@earendil-works/pi-ai";
+import { estimateContextTokens } from "@earendil-works/pi-ai/utils/estimate";
+import { convertToLlm, type CustomEntry, type ExtensionContext, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import { BOOT_TYPE, RESET_MARKER_TYPE } from "../protocol.js";
+import type { SessionReader } from "../session-reader.js";
+
+export type WindowMarker = CustomEntry<{ windowId: string }> & { data: { windowId: string } };
+
+export function isWindowMarker(entry: SessionEntry): entry is WindowMarker {
+	return entry.type === "custom" && entry.customType === RESET_MARKER_TYPE &&
+		typeof entry.data === "object" && entry.data !== null &&
+		typeof (entry.data as { windowId?: unknown }).windowId === "string" &&
+		(entry.data as { windowId: string }).windowId.length > 0;
+}
+
+/** Only the active branch can supply a window boundary. */
+export function currentReset(ctx: SessionReader): WindowMarker | undefined {
+	const branch = ctx.sessionManager.getBranch();
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (entry && isWindowMarker(entry)) return entry;
+	}
+	return undefined;
+}
+
+/** Mint the durable identity of a session's root history window. */
+export function rootWindowId(sessionId: string): string {
+	return `pcw:${sessionId.slice(0, 8)}:root`;
+}
+
+/** Persisted messages in the active window, excluding earlier windows on this branch. */
+export function hasWindowMessage(ctx: SessionReader, customType: string): boolean {
+	const branch = ctx.sessionManager.getBranch();
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (isWindowMarker(entry)) break;
+		if (entry.type === "custom_message" && entry.customType === customType) return true;
+	}
+	return false;
+}
+
+/** The root or latest durable marker on the active branch. */
+export function currentWindowId(ctx: SessionReader): string {
+	return currentReset(ctx)?.data.windowId ?? rootWindowId(ctx.sessionManager.getSessionId());
+}
+
+/** The durable window active just before the marker: the last earlier marker, else the root window. */
+export function previousWindowId(ctx: SessionReader, markerId: string): string {
+	let previousId = rootWindowId(ctx.sessionManager.getSessionId());
+	for (const entry of ctx.sessionManager.getBranch()) {
+		if (entry.id === markerId) break;
+		if (isWindowMarker(entry)) previousId = entry.data.windowId;
+	}
+	return previousId;
+}
+
+function hasWindowId(details: unknown, windowId: string): boolean {
+	return typeof details === "object" && details !== null &&
+		typeof (details as { windowId?: unknown }).windowId === "string" &&
+		(details as { windowId: string }).windowId === windowId;
+}
+
+/** Match a provider-facing boot message, optionally by window identity. */
+export function isWindowBoot(message: AgentMessage, windowId?: string): boolean {
+	return message.role === "custom" && message.customType === BOOT_TYPE && (windowId === undefined || hasWindowId(message.details, windowId));
+}
+
+/** Match a persisted boot entry by raw identity, even when a later edit hides it from projection. */
+export function isWindowBootEntry(entry: SessionEntry, windowId: string): boolean {
+	return entry.type === "custom_message" && entry.customType === BOOT_TYPE && hasWindowId(entry.details, windowId);
+}
+
+/**
+ * The durable marker selects a boot message by identity, never by wall-clock time.
+ * The boot is the first conversation message of the window. Folding only its prefix
+ * preserves later prompt/tool patches in place, including their cacheable ordering.
+ */
+export function projectWindow(messages: AgentMessage[], windowId: string): AgentMessage[] {
+	const cut = messages.findIndex((message) => isWindowBoot(message, windowId));
+	if (cut < 0) throw new Error(`Missing boot for context window ${windowId}`);
+	const head = getCurrentSystemMessage(messages.slice(0, cut));
+	const suffix = messages.slice(cut);
+	return head ? [head, ...suffix] : suffix;
+}
+
+/**
+ * Root windows are not reset boundaries. A forked session can copy a root boot whose
+ * details name the source session; refresh that boot in-place in the provider projection
+ * while retaining every user/assistant/tool message from the copied root transcript.
+ */
+export function projectRootWindow(messages: AgentMessage[], windowId: string): AgentMessage[] {
+	const matching = messages.filter((message) => isWindowBoot(message, windowId));
+	if (matching.length === 0) return messages;
+	const activeBoot = matching[matching.length - 1];
+	const firstBoot = messages.findIndex((message) => isWindowBoot(message));
+	const withoutBoots = messages.filter((message) => !isWindowBoot(message));
+	return [...withoutBoots.slice(0, firstBoot), activeBoot, ...withoutBoots.slice(firstBoot)];
+}
+
+/** Usage for the selected window, excluding provider usage recorded before its marker. */
+export function windowUsage(ctx: Pick<ExtensionContext, "sessionManager" | "getContextUsage" | "model">) {
+	const reset = currentReset(ctx);
+	if (!reset) return ctx.getContextUsage();
+	const contextWindow = ctx.model?.contextWindow ?? ctx.getContextUsage()?.contextWindow;
+	if (!contextWindow) return undefined;
+	const windowId = reset.data.windowId;
+	try {
+		const messages: AgentMessage[] = projectWindow(ctx.sessionManager.buildSessionProjection().messages, windowId);
+		const { tokens } = estimateContextTokens(convertToLlm(messages));
+		return { tokens, contextWindow, percent: tokens / contextWindow * 100 };
+	} catch {
+		// A marker can be durable before its boot when a process stops between the two
+		// public writes. Startup/tree repair will append the missing boot; until then the
+		// budget hook must not turn a recoverable partial append into a swallowed error.
+		return undefined;
+	}
+}