pi-posthorse 0.7.0 → 0.8.0

package/README.md

@@ -11,19 +11,23 @@ Pi owns the persisted boundary. Posthorse owns the policy: stable window guidanc
 ## Requirements
 
 - Node `>=24.12.0`.
-- Official Pi (`@earendil-works/pi-coding-agent`) or the `fitchmultz/pi` fork. Posthorse detects the host when it loads; no configuration is needed.
+- Pi `>=1.0.0`, official (`@earendil-works/pi-coding-agent`) or a maintained fork with the same public compaction contracts. No checkpoint, metadata iterator, or native context-window API is required.
 
-Qualified against official Pi `0.87.1` and fork commit [`b1b4ac34d807b577d66f5879119a9ed4833c8ed7`](https://github.com/fitchmultz/pi/commit/b1b4ac34d807b577d66f5879119a9ed4833c8ed7). CI uses these exact versions.
+Development baseline: exact official Pi `1.0.0` ([source `a13d35a`](https://github.com/earendil-works/pi/commit/a13d35a742c6ef8462812a28fbe1d8c8b7431c32)), TypeBox `1.3.27`, tested on Node `24.21.0`. Host identities, not version strings alone, select compatibility checks. A future fork 1.0 artifact must be qualified separately; this update does not install, activate, or restart the live runtime.
 
 ## Install
 
+Posthorse `0.8.0` requires Pi `>=1.0.0`. Update the host before installing this release; do not activate it on an older live fork.
+
 ```bash
-pi install npm:pi-posthorse                             # from npm
-pi install git:github.com/fitchmultz/pi-posthorse        # from Git; add @<tag> to pin a release
-pi -e npm:pi-posthorse                                  # try it for one run without installing
+pi install npm:pi-posthorse@0.8.0                        # from npm
+pi install git:github.com/fitchmultz/pi-posthorse@v0.8.0 # from Git
+pi -e npm:pi-posthorse@0.8.0                             # try it for one run without installing
 ```
 
-Update with `pi update npm:pi-posthorse` or `pi update --extensions`; move a pinned Git install with `pi install git:github.com/fitchmultz/pi-posthorse@<new tag>`. Uninstall with `pi remove npm:pi-posthorse` (or the Git source you installed). Removing the package leaves `.pi/notes` and Pi's session history in place.
+Omit the version or tag to follow the latest release.
+
+Update an unpinned install with `pi update npm:pi-posthorse` or `pi update --extensions`. Move a pinned install with `pi install npm:pi-posthorse@<new version>` or `pi install git:github.com/fitchmultz/pi-posthorse@<new tag>`. Uninstall with `pi remove` followed by the source you installed. Removing the package leaves `.pi/notes` and Pi's session history in place.
 
 Restart Pi after installing or updating Posthorse to load the new extension code.
 
@@ -31,32 +35,28 @@ Keep exactly one copy loaded. `pi list` shows every package source; if a second
 
 ## Official Pi and the fork
 
-Both hosts get the same tools, guidance, reminders, notes, history, and recovery records. The rollover itself differs:
-
-- **Fork.** Rollover is a native `context_window` entry: the old window leaves model context and only a short boundary message plus the handoff remains. Posthorse claims automatic rollover through `session_before_auto_compact`, before Pi prepares a summary or resolves summarization credentials, bounds retained tool receipts before the fresh window is published, reads Pi's live compaction settings, and lets native background tool calls continue across the reset.
-- **Official Pi.** Rollover is a compaction entry that keeps no earlier conversation and whose summary is the handoff; no summary model is called. `new_context` commits at turn end after every tool in the batch succeeds. Automatic rollover answers Pi's `session_before_compact` for threshold and overflow triggers; manual `/compact` stays Pi's own summary.
+Both hosts get the same tools, guidance, reminders, notes, history, and recovery records. Rollover is a public compaction entry retaining no earlier conversation, with the handoff as its summary; no summary model is called. `new_context` commits at turn end only after Posthorse's own callback succeeds and every sibling tool succeeds. A foreign tool with the same name cannot authorize a rollover. Automatic rollover handles `session_before_compact`; manual `/compact` stays Pi's own summarization.
 
-Official Pi limits that the fork removes:
+- **Native eligibility on both 1.0 targets:** Pi's compaction preparation must succeed before the automatic hook runs. Posthorse's custom compaction result bypasses the default summarizer and its credential lookup. With default `keepRecentTokens`, tiny overflow/truncated responses and a second large result without a new user turn can miss the hook. Lowering `keepRecentTokens` narrows, but does not eliminate, that gap. Oversized initial input can reach the provider before recovery.
+- **Policy:** reminders and budget reports use persisted settings by default; automatic rollover uses the live settings in the event. SDK hosts can inject live policy with `createPosthorse(getPolicy)`. Handoffs appear as compaction-summary messages. Background work owned outside the foreground batch is not serialized or stopped by Posthorse.
 
-- The handoff appears as Pi's compaction-summary message.
-- Automatic rollover runs only when Pi's compaction preparation finds something to compact and summarization credentials resolve. With the default `keepRecentTokens`, a small overflow or truncated response, or a second large tool result without a new user turn, can skip it; lowering `keepRecentTokens` narrows that gap.
-- Reminders and `get_context_remaining` read persisted settings (a CLI snapshot), because extensions cannot read Pi's live settings. Automatic rollover itself uses the live settings Pi passes to the hook. SDK hosts can pass their live settings with `createPosthorse(getPolicy)`.
-- Retained tool receipts are not shortened before the fresh window.
-- Sessions are not migrated between hosts. Official Pi ignores fork `context_window` entries, so a fork session opened in official Pi can bring earlier history back into context.
+Legacy fork `context_window` entries remain readable for history recovery. New boundaries do not use the retired native-window/async ABI. Opening legacy fork journals in official Pi can reintroduce earlier context because official Pi does not interpret those old markers; do not assume cross-host session migration.
 
 ## How it works
 
-1. **Stable guidance.** Window behavior lives in a native system-prompt section. There is no per-request meter. Posthorse preserves custom prompts and falls back to appending guidance when an earlier extension replaces the full prompt; that compatibility path can prevent Pi from preserving an additive prompt prefix.
-2. **One best-effort checkpoint.** While Pi compaction is enabled, one reminder may appear shortly before Pi's rollover line, asking the model to rewrite its current-state note in place and call `new_context`. A large turn, overflow, restart, or smaller model can reach rollover without it. Reminders are fingerprinted by window, context size, and reserve, so switching to a different context size gets a fresh reminder. Stale reminders and reminders left after disabling compaction are filtered from model input while remaining in history.
-3. **`get_context_remaining`.** Reports the best available native estimate of tokens until Pi's automatic rollover line and until the configured context limit. That configured limit is not a measured provider rejection boundary. Pi's value is an estimate until the active model reports usage. The checkpoint reminder marks the deadline, so the guidance does not prompt routine budget checks; the tool is described for use before a large step late in a window.
-4. **`new_context`.** Requests an atomic rollover after the current foreground (synchronous) tools succeed. Items 4–6 and the receipt bounding below describe the fork; official Pi differences are listed above. An optional handoff is persisted and becomes the first state of the fresh window. A failed synchronous checkpoint save or other foreground sibling prevents Pi from committing the boundary; the checkpoint reminder still applies. Native asynchronous background calls continue across the reset without delaying it. Pi preserves their call provenance and delivers their results in the fresh context.
-5. **Automatic rollover without summaries.** With a supported context budget and room for a recovery record, Posthorse claims Pi's automatic threshold and overflow trigger through `session_before_auto_compact`, before Pi resolves summarization credentials or prepares a summary. Oversized first turns and tool results can then roll over even without summarization credentials. Native asynchronous background calls can remain in progress across automatic rollover too. When a recovery record cannot fit but Pi will retain native receipts in the next window, Posthorse claims a window without a handoff so Pi can prepare and bound those receipts or refuse the window. Already-consumed receipts do not trigger an empty rollover. Otherwise Pi's own compaction remains in control. Manual `/compact` is unchanged.
-6. **Bounded recovery record.** The automatic handoff quotes the window's first owner request, its latest owner input (a direct user input or `ask_question` outcome), and its latest input of any kind, including visible coordination messages. It adds tool result evidence: tool names and namespaces, call ids, requested and admitted execution arguments when available, result excerpts of up to 1,500 characters, and entry ids to recover the rest. Every other current-window input gets one index line with its label, time, and entry id; owner inputs keep a one-line preview there. Native async results from the current projected window remain eligible even across later complete assistant responses, since a result can arrive during a response that never received it. A result Pi still projects is also eligible when its call was edited out or predates the window, without attributing it to another call. These results may already have been received or handled; they are not proof of current progress. Synchronous results with projected call provenance are kept only from the trailing batch without a later complete response. Pi context edits also apply to these inputs and results: omitted entries stay out, and replacements supersede their original content. A clearly labeled, possibly stale older checkpoint comes last. Older assistant prose is not treated as current state. Newly submitted input stays separate and is saved after the boundary, not copied into the handoff.
+1. **Stable guidance.** Each request gets a native system-prompt section stating the best available native context capacity and, when automatic rollover is supported and enabled, its token threshold from the available Pi settings. Fresh windows get the same guidance, refreshed if the model or available settings change during a continuing turn. For virtual models, native limits can come from the routed physical model. These are capacity and policy limits, not remaining space. The guidance distinguishes context capacity from response-token limits and reasoning budgets, and requires a `get_context_remaining` check before reporting remaining tokens or changing plans because of context limits. Unknown usage stays unknown. There is no per-request meter or routine budget check. When an extension forces an opaque full prompt, Posthorse preserves it and supplies guidance as a request-local conversation message, because official Pi applies forced text after system-context hooks. Guidance is regenerated from current state rather than persisted in the transcript.
+2. **One best-effort checkpoint.** While Pi compaction is enabled, one reminder may appear shortly before Pi's rollover line, asking the model to update its current-state note with available file-editing tools and call `new_context`. Already-current notes need no rewrite; `notes write` remains the fallback for creation, substantial restructuring, or unavailable editing tools. A large turn, overflow, restart, or smaller model can reach rollover without it. Reminders are fingerprinted by window, context size, and reserve, so switching to a different context size gets a fresh reminder. Stale reminders and reminders left after disabling compaction are filtered from model input while remaining in history.
+3. **`get_context_remaining`.** Reports the best available native estimate of tokens until Pi's automatic rollover line and until the configured context limit. That configured limit is not a measured provider rejection boundary. Pi's value is an estimate until the active model reports usage. Check before claiming a remaining-token count or changing plans because of context limits. The checkpoint reminder marks the deadline, so routine budget checks are unnecessary.
+4. **`new_context`.** Requests an atomic retain-none rollover once the current foreground tool batch succeeds. An optional handoff becomes the first state of the fresh window. Failed sibling writes, aborted turns, or a handoff that no longer fits after queued input prevent commitment. The request card is not proof that the boundary committed. Own successful callback IDs and admitted handoffs are consumed once at settlement; transcript names alone cannot request a reset.
+5. **Automatic rollover without summaries.** When Pi reaches the public automatic hook with a supported budget, Posthorse builds a bounded recovery record and retains only an invisible boundary sentinel. Cancellation or recovery construction failure leaves active context intact rather than silently invoking a summarizer. Unsupported small-model budgets retain Pi's native fallback. Manual `/compact` is unchanged. Native eligibility limits are listed above.
+6. **Bounded recovery record.** The automatic handoff quotes the window's first owner request, its latest owner input (a direct user input or `ask_question` outcome), and its latest input of any kind, including visible coordination messages. It adds tool result evidence: tool names and namespaces, call ids, requested and admitted execution arguments when available, result excerpts of up to 1,500 characters, and entry ids to recover the rest. Every other current-window input gets one index line with its label, time, and entry id; owner inputs keep a one-line preview there. Only a successful result positively linked to a projected unnamespaced `ask_question` call **and** an effective registered unnamespaced `ask_question` definition is an owner answer. Providers can omit call namespaces, so call metadata alone is insufficient. Namespaced, unregistered or unresolved-provenance results remain tool evidence, never owner approval. Legacy async results still visible in a projected journal remain eligible even across later complete assistant responses; this is history compatibility, not a new native-async execution path. A result Pi still projects is also eligible when its call was edited out or predates the window, without attributing it to another call. These results may already have been received or handled; they are not proof of current progress. Synchronous results with projected call provenance are kept only from the trailing batch without a later complete response. Pi context edits also apply to these inputs and results: omitted entries stay out, and replacements supersede their original content. A clearly labeled, possibly stale older checkpoint comes last. Older assistant prose is not treated as current state. Newly submitted input stays separate and is saved after the boundary, not copied into the handoff.
 7. **`notes` and `history`.** Notes are shared across linked worktrees, at the main checkout for conventional Git layouts or inside the common Git directory when metadata is stored separately. History searches normalized transcript text, skips entries whose full text the model already sees in its active context (and says how many), and returns stored images for a requested entry. Edited-away originals and checkpoint reminders stay searchable. Tool calls and results retain names, namespaces, and call ids; admitted execution arguments are labeled separately from requested arguments when present. When a handoff carries edited content, its entry ID points to the replacement; `history read` of that ID returns the replacement text or images. Reading the original entry ID still returns the raw journal content.
 
-Before each fresh window becomes active, Posthorse bounds oversized retained native receipts through append-only context edits. It shares the available capacity across all receipts after accounting for the prompt, tools, pending input, handoff, carried calls, Pi's configured reserve when automatic rollover is enabled and supported, and a safety margin. Pi separately clamps each provider request's output limit to its remaining context capacity. When receipts need shortening, excerpts use half the remaining capacity so the next response has working room. Excerpts retain the native call/result identity and error state, with `history read` references for complete recovery, including images. Existing replacements remain the recovery source across later windows; raw pre-edit content is never used for a new excerpt. Already-fitting receipts stay unchanged. If fixed input and recovery references cannot fit, rollover fails visibly without publishing a window marker or any proposed edits. Later prompts retry preparation against the unchanged window; correcting the configuration allows ordinary rollover to proceed. Pi independently refuses estimated native transcript input that exceeds physical context capacity, including when compaction is disabled. Its output clamp still permits fitting requests with reduced output, even above the compaction reserve line. Raw wire replacements through `onPayload` / `before_provider_request` and custom transport implementations retain responsibility for their own request sizing.
+Retain-none compaction removes prior tool receipts from active input; recovery records carry bounded excerpts and history IDs, while complete raw or edited receipts remain recoverable from the append-only journal. Posthorse no longer registers a native receipt-bounding hook. The host owns physical request sizing and output clamping; custom transports and raw payload replacements remain responsible for their request sizes.
 
-At turn end, Posthorse checks whether usage is in the reminder band before explicitly looking up the full branch. Context filtering skips its branch lookup when model input contains no `posthorse-reminder` messages, and on the fork while the window's marker message is present. Complete history remains available through paged searches and reads.
+Each synchronous safety evaluation lazily reads native usage and settings at most once, sharing them through guidance and page sizing. Requests, sibling tools, and final handoff admission each get a fresh snapshot; snapshots never survive an await. Official Pi still performs one uncached native usage acquisition when an evaluation needs it. Routed limits come only from that native reading, not a guessed virtual-model declaration.
+
+Reminder lookup follows by-id ancestry to the latest Posthorse boundary and the entire native compaction kept range. It reuses certified append-only state, including negative results, and rebuilds on navigation, session changes, or changed entry identity. No history is capped or dropped. Below-band turns and reminder-free input skip that lookup; legacy window markers can identify the window directly. Automatic recovery reuses the branch supplied by Pi's compaction event. Complete history remains available through unchanged paged searches and reads.
 
 Automatic recovery is an emergency input record, not proof of progress. The fresh model is told to restore notes and todo state, inspect history when needed, and verify live state before taking stateful or external action.
 
@@ -66,7 +66,7 @@ Posthorse follows Pi's effective `compaction` settings, including Pi's decision
 
 The model's context window minus `compaction.reserveTokens` must leave at least 10,000 usable tokens. Below that (for example an 8K or 16K model with the default 16,384 reserve) Posthorse reports an unsupported configuration in the guidance and in `get_context_remaining`, turns automatic behavior off for that model, and leaves Pi's own compaction in place. Lower the reserve or use a larger model. The checkpoint reminder band is the last 10% of usable context, capped at 32,000 tokens, so a large reserve cannot trigger a reminder immediately in a fresh window.
 
-Explicit and automatic handoffs are capped at 20,000 characters and half the active model's fresh operational capacity after prompt/tool overhead and any pending input, whichever is smaller. Oversized explicit handoffs are rejected with an instruction to save fuller state in notes; automatic rollover stays with Pi when no safe recovery record fits and no native receipts require fresh-window preparation. Notes and history pages are capped at 40,000 characters and shrink to the remaining budget; when usage is not known yet, they also leave half the fresh operational capacity free.
+Explicit and automatic handoffs are capped at 20,000 characters and half the native context limit's fresh operational capacity after prompt/tool overhead and any pending input, whichever is smaller. Oversized explicit handoffs are rejected with an instruction to save fuller state in notes; automatic rollover cancels visibly when a supported configuration has no room for a safe recovery record. Notes and history pages are capped at 40,000 characters and shrink to the remaining budget; when usage is not known yet, they also leave half the fresh operational capacity free. Payload budgets reserve Posthorse's request-local guidance too, because native estimates can omit it.
 
 Only one automatic compaction or rollover policy extension should be enabled at a time. Pi keeps the last non-cancel result from multiple handlers of the same hook, so load order would otherwise decide which policy wins.
 
@@ -74,12 +74,12 @@ Only one automatic compaction or rollover policy extension should be enabled at
 
 - `new_context({ handoff? })`
 - `get_context_remaining()`
-- `notes({ op, ... })`: `list`, `read`, and `search` are paged; continue with the returned character `offset`. `list` shows notes newest first with size and modification time (UTC) and takes an optional folder `path`; `read` of a folder returns its listing. `search` covers text notes, skipping binary files (a NUL byte in the first 8,000 bytes, as Git decides), and its excerpts center on the match. `write` replaces content (empty content clears); `append` adds one newline-terminated record.
+- `notes({ op, ... })`: `list`, `read`, and `search` are paged; continue with the returned character `offset`. `list` shows the absolute shared notes directory, then relative note names newest first with size and modification time (UTC), and takes an optional folder `path`; `read` of a folder returns its listing. File reads show the absolute file path before the content. Offsets refer to note content or listing rows, excluding path headers. `search` covers text notes, skipping binary files (a NUL byte in the first 8,000 bytes, as Git decides), and its excerpts center on the match. `write` replaces content (empty content clears); `append` adds one newline-terminated record.
 - `history({ op, ... })`: `search` skips entries whose full text is already in the active context, continues with the returned `cursor` and the same `query` and `all` scope, and treats `limit` as the maximum results per page. `read` pages text and stored images; continue with the returned character `offset` and `imageOffset`. An image-only continuation can use an `offset` equal to the text length. If a page needs fresh context, retry with both offsets unchanged. Results keep native entry and window ids.
 
 In the TUI, tools use Pi's native expandable cards. Collapsed cards show the operation and target, a short content preview, and counts or page ranges with the next offset when more remains. Expand with Pi's tool-output shortcut (`Ctrl+O` by default), or click the card's header or body in fullscreen mode. Expanded cards show the complete returned page and its metadata, not content the tool has not fetched yet. Writes and context requests also show the submitted content or handoff.
 
-Committed context-window messages and checkpoint reminders are compact, expandable cards too. The `new_context` tool card describes a request; only the committed context-window message says a fresh window has started.
+The `new_context` tool card describes a request, not a completed reset. Pi's native compaction card (`Compacted from … tokens`) shows the committed current boundary and expands to its handoff. Context-window cards are historical fork boundaries only; checkpoint reminders remain compact, expandable cards too.
 
 Notes list/search and history search share the remaining context budget with read pages and returned images. Search/list headers, continuation text, no-match responses, and parallel sibling results count toward that budget; pages already counted by Pi are not counted twice. Before usage is known, pages reserve prompt/tool overhead and leave half the rest free. Unsafe pages are refused with the offset or cursor preserved in the call; call `new_context` and retry. Refusal text uses the same budget, so later failures omit repeated guidance once no more fits.
 
@@ -87,12 +87,15 @@ Notes list/search and history search share the remaining context budget with rea
 
 Within each group, current-branch matches are newest first. With `all: true`, Posthorse searches session files in the active Pi session directory whose saved working directory matches the current one, along with their nested subagent sessions and the selected current session file when it is in that directory. Files without a valid session header or an attributable working directory are excluded; the active branch remains available. Within that scope, sessions are ordered newest-modified first and entries newest first; this is not a global timestamp sort. All-session hits use a file-qualified ID (`native-id@file-key`, with a 10-character key); pass the complete ID to `history read`. Full-length keys printed by earlier releases still read. Hits from nested subagent runs are tagged `[subagent]`, because their user-role input came from a parent agent. A read that resolves a bare ID in another session file prints that entry's qualified ID, so continuations reopen the same file. When ripgrep is available (Pi's managed copy, then `PATH`), all-session search and bare-ID reads skip session files that cannot contain the query or ID. A query that could match text session files store escaped (quotes, backslashes) or label text that exists only in normalized entries (brackets, parentheses, braces, colons, `$`, leading or trailing spaces, or phrases such as "Call ID" and "No handoff") scans every file instead. Image summaries come only from entries with an image block, so image-count and comma queries also search every file that has one. Either way, results match a full scan. The per-page result limit applies after priority, so newer echoes cannot displace older original matches. Each included session file contributes its own matches, including fork copies, so unrelated entries sharing a native ID are never hidden. Search cursors advance past the previous entry, including partial headers or excerpts, so appending lookup calls and results does not keep pagination alive forever. Searches are live: external session edits or file reordering can change results; start a new search to include newer sources.
 
-Notes live in `.pi/notes/` at the main checkout for conventional Git layouts, or the current directory outside Git. When Git metadata is stored separately, including in submodules, all checkouts use `.pi/notes/` inside Git's common directory instead; no configuration is needed. If that metadata is unavailable, notes stay local to the checkout. Writes report the actual storage path. Add `.pi/notes/` to `.gitignore` when the project should not track it.
+Notes live in `.pi/notes/` at the main checkout for conventional Git layouts, or the current directory outside Git. When Git metadata is stored separately, including in submodules, all checkouts use `.pi/notes/` inside Git's common directory instead; no configuration is needed. If that metadata is unavailable, notes stay local to the checkout. Reads, listings, and writes report the actual storage location. Add `.pi/notes/` to `.gitignore` when the project should not track it.
+
+Keep one concise current-state note per task, preserving decisions and safety constraints and linking fuller evidence or history. For existing notes, edit changed sections with an available file-editing tool (`apply_patch`, `replace_text`, or Pi's `edit`) rather than resending the whole file. Use the absolute path returned by `notes read`, or join the directory from `notes list` with the relative note name: a worktree's local `.pi/notes/` may not be the shared location. The notes tool's own `path` argument remains relative to the shared notes directory. No Posthorse-specific editor is required, and failed sibling edits still prevent an explicit `new_context` reset.
 
 `write` is a complete-file replacement in the note's directory: a failed write before publication leaves the previous note intact. It follows symlink targets and preserves ordinary permissions and ownership, or fails before publication. Hardlink aliases and already-open handles keep the previous file; ACLs, extended attributes, and power-loss durability are not guaranteed. Within one Pi process, writes and appends to the same note run in order; across processes, full replacements do not merge concurrent appends or other replacements. `append` retains one `O_APPEND` write per newline-terminated record.
 
 ## Data and privacy
 
+- For cached-token cost diagnosis and a safe stock-compaction comparison, see the [cached-token investigation](https://github.com/fitchmultz/pi-posthorse/blob/main/ARTIFACTS/investigation-report.md). It does not establish the cause of a production bill or claim a measured cost improvement.
 - Posthorse makes no network requests.
 - Notes are plaintext files under `.pi/notes`. They survive package removal and may be committed unless ignored.
 - `history` with `all: true` scans project-matching JSONL files and their nested subagent sessions in the active Pi session directory, not unrelated projects that share that directory. It runs ripgrep locally over that directory when available.
@@ -105,11 +108,12 @@ Notes live in `.pi/notes/` at the main checkout for conventional Git layouts, or
 ```bash
 npm ci --ignore-scripts
 npm run check:compat                   # typecheck, unit tests, and the real-SDK suite for the installed host
-PI_FORK=../pi scripts/integration.sh   # additional full source-harness integration (disposable fork built)
 ```
 
 `npm run check` type-checks the extension, renderers, and tests against the official npm declarations. `npm test` covers reminder policy, notes/history behavior, failed note replacement, and real native card components, including width and expansion.
 
-`test:native` runs the real-SDK suite for whichever host is installed: `test/official.test.mjs` for official Pi, `test/native.test.mjs` when the fork SDK is installed. Both cover real SDK loading, prompt composition, explicit and automatic rollover without a summary request, recovery records, notes, and history; the fork suite adds receipt bounding, native async calls, and checkpoint restore. When `PI_COMPAT_HOST` is `fork` or `official`, a mismatch with the installed SDK fails instead of running the other suite. The shared compatibility runner installs each host's SDK cohort in this checkout's `node_modules` so both `tsc` and SDK imports resolve that graph; `PI_HOST_INDEX` and `PI_COMPAT_EXPECTED_PACKAGE_DIR` are verified against it, and `PI_COMPAT_EXPECTED_VERSION` verifies the version.
+Development dependency policy: update TypeBox alongside the Pi cohort to match the host's version, not independently. Official 1.0 uses 1.3.27. The earlier 0.99.2 startup investigation is historical, not a current support target or a claim about 1.0 performance. Qualify later releases against their actual packaged SDK/CLI and companion graph; resolve companions relative to coding-agent because its shrinkwrap nests dependencies. Revisit the TypeBox pin when the host changes its dependency.
+
+`test:native` runs public-API suites against the installed real SDK, covering native recovery eligibility and physical request boundaries, real loading, prompt composition, explicit/automatic rollover without a summary call, owner-provenance safety, failed siblings, cancellation, queued input, recovery records, notes and history. The 1.0 fork starts from official semantics; old fork checkpoint and early-compaction customizations are not current contracts. Legacy saved-window and async-result data remain recoverable; no retired runtime ABI or blanket skips are needed. `PI_COMPAT_HOST` labels the selected distribution; `PI_HOST_INDEX`, `PI_COMPAT_EXPECTED_PACKAGE_DIR` and `PI_COMPAT_EXPECTED_VERSION` validate the actual selected graph. Typechecking uses that graph too, never an optional fork method as a distribution heuristic.
 
-For a focused read-only SDK diagnostic only, `PI_HOST_INDEX=/absolute/fork/dist/index.js node --test test/native.test.mjs` can inspect an immutable host; this does not qualify this checkout's types. The larger source integration suite remains available through `scripts/integration.sh`; use a disposable built fork checkout because it briefly copies a test into that host. All native fixtures must use an isolated HOME/agent directory with offline mode and no provider credentials. These checks do not claim native Windows support.
+For a focused read-only SDK diagnostic only, `PI_HOST_INDEX=/absolute/fork/dist/index.js node --test test/native.test.mjs` can inspect an immutable host; this does not qualify this checkout's types. The canonical real-SDK suites replace the obsolete source-copying fork harness; validation never needs to write into a host checkout. All native fixtures must use an isolated HOME/agent directory and short TMPDIR outside real-home ancestry, with no project markers in temporary-path ancestors, offline mode and no provider credentials. These checks do not claim native Windows support.

package/index.ts

@@ -1,8 +1,8 @@
 /**
  * Posthorse — fresh context, same journey.
  *
- * No-summary context rollover for Pi. On the fitchmultz/pi fork, Pi persists native context
- * windows; on official Pi, rollover is a retain-none compaction whose summary is the handoff.
+ * No-summary context rollover for Pi: a retain-none public compaction whose summary is
+ * the handoff, on official Pi and the maintained fork.
  * Pi owns the persisted boundary. Posthorse owns the policy: sparse budget reminders, rollover
  * tools, durable notes, and history recovery.
  */
@@ -46,31 +46,13 @@ const EMPTY_HANDOFF = "Fresh context. Restore relevant notes and history before
 type CompactionPolicy = { enabled: boolean; reserveTokens: number };
 type ContextUsage = { tokens: number | null; contextWindow: number; percent: number | null };
 
-/** The fork exposes live settings on the context; official Pi gets them from the injected policy. */
+/** Settings come from the injected policy; the compaction hook provides Pi's live policy. */
 type PolicyContext = {
-	model?: { contextWindow: number };
 	getCompactionSettings(): CompactionPolicy;
 	getContextUsage(): ContextUsage | undefined;
 	getSystemPrompt(): string;
 };
 
-/** Fork-only extension API; the published Pi types do not declare it. */
-type NativeExtensionAPI = {
-	registerContextWindowHook(
-		handler: (
-			event: { contextEntries: ProjectedEntry[]; pendingMessages: MessageLike[] },
-			ctx: ExtensionContext,
-		) => ReceiptEdit[] | undefined,
-	): void;
-	on(
-		event: "session_before_auto_compact",
-		handler: (
-			event: { reason: "overflow" | "threshold"; branchEntries: EntryLike[]; pendingMessages?: MessageLike[]; retainedToolResultIds: string[] },
-			ctx: unknown,
-		) => { newContext: { handoff?: string } } | undefined,
-	): void;
-};
-
 type ImageLike = { type: "image"; data: string; mimeType: string };
 type ToolCallLike = {
 	type?: string;
@@ -114,7 +96,6 @@ type EntryLike = {
 
 type WindowedEntry = { entry: EntryLike; windowId: string; text: string; images: ImageLike[] };
 type ProjectedEntry = { sourceEntry: EntryLike; messages: MessageLike[] };
-type ReceiptEdit = { type: "context_edit"; targetId: string; replacement: { content: string } };
 type HistoryHit = { id: string; text: string; headerLength: number; priority: 0 | 1 };
 type RecoveryRecord = {
 	id: string;
@@ -134,7 +115,7 @@ type Budget = {
 	supported: boolean;
 };
 
-/** A fork context window, or the retain-none compaction Posthorse commits on official Pi. */
+/** A legacy fork context window, or the retain-none compaction Posthorse commits on both hosts. */
 function isWindow(entry: EntryLike): boolean {
 	return entry.type === "context_window" || (entry.type === "compaction" && (entry.details as { posthorse?: unknown } | undefined)?.posthorse === 1);
 }
@@ -574,14 +555,6 @@ async function* scopedSessionFiles(
 	}
 }
 
-function currentWindowId(entries: readonly EntryLike[]): string {
-	for (let i = entries.length - 1; i >= 0; i--) {
-		const entry = entries[i];
-		if (isWindow(entry) && entry.id) return entry.id;
-	}
-	return "initial";
-}
-
 function excerpt(text: string, limit: number): string {
 	if (text.length <= limit) return text;
 	const marker = "\n… middle omitted …\n";
@@ -595,7 +568,7 @@ function boundedBlock(header: string, text: string, limit: number): string {
 	return textLimit ? `${header}\n${excerpt(text, textLimit)}` : header;
 }
 
-function recoveryRecord(entry: EntryLike): RecoveryRecord | undefined {
+function recoveryRecord(entry: EntryLike, ownerQuestion: boolean): RecoveryRecord | undefined {
 	let kind: RecoveryRecord["kind"];
 	let label: string;
 	let text: string;
@@ -610,6 +583,7 @@ function recoveryRecord(entry: EntryLike): RecoveryRecord | undefined {
 		entry.message?.role === "toolResult" &&
 		entry.message.toolName === "ask_question" &&
 		entry.message.namespace === undefined &&
+		ownerQuestion &&
 		entry.message.isError !== true
 	) {
 		kind = "owner";
@@ -717,7 +691,7 @@ function recoverableToolResults(
 	return { callId: allLinked ? (call?.id ?? "unknown").slice(0, 120) : undefined, blocks };
 }
 
-function buildAutoHandoff(entries: readonly EntryLike[], projected: readonly ProjectedEntry[], maxChars: number): string {
+function buildAutoHandoff(entries: readonly EntryLike[], projected: readonly ProjectedEntry[], maxChars: number, ownerQuestionRegistered: boolean): string {
 	const { start, boundary: priorWindow } = contextStart(entries);
 	const current = entries.slice(start);
 	const edits = contextEdits(entries);
@@ -731,8 +705,15 @@ function buildAutoHandoff(entries: readonly EntryLike[], projected: readonly Pro
 		if (entry.type === "custom_message") return [{ ...entry, id: edit.id, content: edit.replacement.content }];
 		return [entry];
 	});
+	const projectedCalls = new Map(projected.flatMap(({ messages }) => messages.flatMap((message) =>
+		message.role === "assistant" && Array.isArray(message.content)
+			? (message.content as ToolCallLike[]).filter((call) => call.type === "toolCall").map((call) => [call.id, call] as const) : [])));
 	const records = edited
-		.map((entry) => recoveryRecord(entry))
+		.map((entry) => {
+			// Providers can omit call namespaces; both registration and projected call must prove ownership.
+			const call = projectedCalls.get(entry.message?.toolCallId);
+			return recoveryRecord(entry, ownerQuestionRegistered && call?.name === "ask_question" && call.namespace === undefined);
+		})
 		.filter((record): record is RecoveryRecord => record !== undefined);
 	const firstOwnerRequest = records.find((record) => record.label === "owner input") ?? records[0];
 	const latestOwner = [...records].reverse().find((record) => record.kind === "owner");
@@ -851,7 +832,7 @@ function hasReminder(entries: readonly EntryLike[], fingerprint: ReminderFingerp
 	);
 }
 
-function budgetFor(ctx: PolicyContext, contextWindow = ctx.model?.contextWindow): Budget | undefined {
+function budgetFor(ctx: PolicyContext, contextWindow = ctx.getContextUsage()?.contextWindow): Budget | undefined {
 	if (!contextWindow || contextWindow <= 0) return undefined;
 	const { enabled, reserveTokens } = ctx.getCompactionSettings();
 	const usable = contextWindow - reserveTokens;
@@ -860,11 +841,10 @@ function budgetFor(ctx: PolicyContext, contextWindow = ctx.model?.contextWindow)
 
 /** Half the fresh capacity after prompt/tool/input overhead remains for continued work. */
 function freshPayloadChars(ctx: PolicyContext, toolTokens: number, pendingMessages: readonly MessageLike[] = [], cap = MAX_HANDOFF_CHARS): number {
-	const contextWindow = ctx.model?.contextWindow;
-	if (!contextWindow || contextWindow <= 0) return cap;
-	const budget = budgetFor(ctx, contextWindow);
-	const line = budget?.enabled && budget.supported ? budget.rolloverAt : contextWindow;
-	const promptTokens = Math.ceil(ctx.getSystemPrompt().length / 4);
+	const budget = budgetFor(ctx);
+	if (!budget) return cap;
+	const line = budget.enabled && budget.supported ? budget.rolloverAt : budget.contextWindow;
+	const promptTokens = Math.ceil(ctx.getSystemPrompt().length / 4) + guidanceTokens(ctx);
 	const pendingTokens = pendingMessages.reduce(
 		(total, message) => total + Math.ceil(textOf(message).length / 4) + imagesOf(message.content).length * (ESTIMATED_IMAGE_CHARS / 4),
 		0,
@@ -875,74 +855,9 @@ function freshPayloadChars(ctx: PolicyContext, toolTokens: number, pendingMessag
 	);
 }
 
-/** Bound only the carried receipts; edits preserve the journal and native call/result identity. */
-function boundWindowReceipts(
-	ctx: ExtensionContext & PolicyContext,
-	projected: readonly ProjectedEntry[],
-	pending: readonly MessageLike[],
-	toolTokens: number,
-): ReceiptEdit[] | undefined {
-	if (!ctx.model) return undefined;
-	const estimate = estimateTokens as unknown as (message: MessageLike) => number;
-	const messages = projected.flatMap((entry) => entry.messages);
-	const budget = budgetFor(ctx);
-	const reserve = budget?.enabled && budget.supported ? budget.reserveTokens : 0;
-	const overhead =
-		reserve +
-		PAGE_MARGIN_TOKENS +
-		Math.max(
-			Math.ceil(ctx.getSystemPrompt().length / 4) + toolTokens,
-			messages.filter((message) => message.role === "system").reduce((sum, message) => sum + estimate(message), 0),
-		) +
-		pending.reduce((sum, message) => sum + estimate(message), 0);
-	const fixed = messages.filter((message) => message.role !== "system" && message.role !== "toolResult");
-	const available = ctx.model.contextWindow - overhead - fixed.reduce((sum, message) => sum + estimate(message), 0);
-	const edits = contextEdits(ctx.sessionManager.getBranch() as EntryLike[]);
-	const receipts = projected.flatMap(({ sourceEntry, messages }) =>
-		messages.filter((message) => message.role === "toolResult").map((message) => {
-			if (!sourceEntry.id) throw new Error("Posthorse: retained receipt has no history entry");
-			const recoveryId = edits.get(sourceEntry.id)?.id ?? sourceEntry.id;
-			const images = imageSummary(imagesOf(message.content));
-			const header = `Retained ${message.isError ? "error" : "result"} excerpt. Full content: history read id ${recoveryId}.${images ? `\n${images}` : ""}\n`;
-			const cost = estimate(message);
-			const minimum = Math.min(cost, Math.ceil(header.length / 4));
-			return { id: sourceEntry.id, message, header, cost, minimum };
-		}),
-	);
-	if (receipts.reduce((sum, receipt) => sum + receipt.cost, 0) <= available) return undefined;
-	let extra = available - receipts.reduce((sum, receipt) => sum + receipt.minimum, 0);
-	if (extra < 0) throw new Error("Posthorse: fresh context cannot fit fixed input and receipt recovery references");
-	// Like handoffs, oversized receipt excerpts leave half the remaining capacity for continued work.
-	extra = Math.floor(extra / 2);
-	const drafts: ReceiptEdit[] = [];
-	receipts.sort((a, b) => a.cost - a.minimum - (b.cost - b.minimum));
-	for (const [index, receipt] of receipts.entries()) {
-		const allowance = receipt.minimum + Math.min(receipt.cost - receipt.minimum, Math.floor(extra / (receipts.length - index)));
-		extra -= allowance - receipt.minimum;
-		if (receipt.cost <= allowance) continue;
-		const content = receipt.header + excerpt(textOf(receipt.message), allowance * 4 - receipt.header.length);
-		drafts.push({ type: "context_edit", targetId: receipt.id, replacement: { content } });
-	}
-	const replacements = new Map(drafts.map((draft) => [draft.targetId, draft.replacement.content]));
-	const total = projected.reduce(
-		(sum, entry) =>
-			sum + entry.messages.reduce(
-				(tokens, message) => tokens + (message.role === "system" ? 0 : estimate(
-					replacements.has(entry.sourceEntry.id ?? "")
-						? { ...message, content: replacements.get(entry.sourceEntry.id!) }
-						: message,
-				)),
-				0,
-			),
-		overhead,
-	);
-	if (total > ctx.model.contextWindow) throw new Error("Posthorse: retained receipts exceed fresh context capacity");
-	return drafts;
-}
-
 /** Official Pi cannot expose its live settings to extensions; budget reports say when they used the persisted snapshot. */
 const SNAPSHOT_NOTE = "Reminder and budget policy uses available settings (a persisted CLI snapshot by default); Pi's live settings control automatic compaction.";
-const CHECKPOINT_STEPS = "rewrite the task's current-state note in place with notes write (goal, progress, decisions, next steps), then call new_context";
+const CHECKPOINT_STEPS = "update the task's current-state note (goal, progress, decisions, next steps) with available file-editing tools at its absolute path; use notes write only for creation, substantial restructuring, or when editing tools are unavailable. If the note is already current, leave it unchanged. Then call new_context";
 
 function unsupportedMessage(budget: Budget): string {
 	const n = (value: number) => value.toLocaleString("en-US");
@@ -955,28 +870,34 @@ function pageCapacity(ctx: PolicyContext, toolTokens: number): number {
 	if (!usage || usage.tokens == null) return freshPayloadChars(ctx, toolTokens, [], MAX_PAGE_CHARS) / 4 + PAGE_MARGIN_TOKENS;
 	const budget = budgetFor(ctx, usage.contextWindow);
 	const line = budget?.enabled && budget.supported ? budget.rolloverAt : usage.contextWindow;
-	return line - usage.tokens;
+	return line - usage.tokens - guidanceTokens(ctx);
 }
 
-function buildGuidance(ctx: PolicyContext, official: boolean): string {
+function buildGuidance(ctx: PolicyContext): string {
 	const budget = budgetFor(ctx);
 	const enabled = budget?.enabled ?? ctx.getCompactionSettings().enabled;
+	const n = (value: number) => value.toLocaleString("en-US");
+	const capacity = budget
+		? `Configured context capacity: ${n(budget.contextWindow)} tokens. This is Pi's best available native limit, not remaining space or a measured provider boundary. Fresh windows use the active configuration; system instructions, tools, the handoff, and new messages consume part of it.`
+		: "Configured context capacity is unknown.";
 	let automatic: string;
 	if (!enabled) {
-		automatic = official
-			? "Pi compaction is disabled in the available settings, so Posthorse sends no checkpoint reminder. new_context remains available."
-			: "Pi compaction is disabled, so Posthorse sends no checkpoint reminder and performs no automatic rollover. new_context remains available.";
+		automatic = "Pi compaction is disabled in the available settings, so Posthorse sends no checkpoint reminder. new_context remains available.";
 	} else if (budget && !budget.supported) {
 		automatic = unsupportedMessage(budget);
 	} else {
 		const deadline = budget
 			? `${Math.max(1, Math.round((budget.rolloverAt / budget.contextWindow) * 100))}% used`
 			: "the configured Pi context limit";
-		automatic = `Automatic rollover follows Pi's compaction setting. At most one checkpoint reminder may arrive before the rollover line (${deadline}); when it does, stop normal work, ${CHECKPOINT_STEPS}.`;
+		const line = budget ? ` The rollover line is ${n(budget.rolloverAt)} tokens used under the available Pi settings.` : "";
+		automatic = `Automatic rollover follows Pi's compaction setting.${line} At most one checkpoint reminder may arrive before the rollover line (${deadline}); when it does, stop normal work, ${CHECKPOINT_STEPS}.`;
 	}
 	return `## Context self-management (Posthorse)
+${capacity}
+Do not guess context capacity or remaining space from response-token limits or reasoning budgets. Before reporting a remaining-token count or changing your work plan because of context limits, call get_context_remaining. If usage is unknown, report it as unknown. No routine budget checks are needed.
 ${automatic}
 After a rollover, earlier conversation stays in history. Restore notes and todos, then verify live state before stateful or external work; automatic handoffs record inputs, not progress.
+Keep one concise current-state note per task. Preserve decisions and safety constraints; link fuller evidence and history instead of copying them. Edit changed sections rather than resending unchanged content.
 Write handoffs and notes as normal readable prose; notes and history search match literal text.`;
 }
 
@@ -987,24 +908,74 @@ function persistedPolicy(ctx: ExtensionContext): CompactionPolicy {
 	return settings.getCompactionSettings(ctx.model);
 }
 
-/** SDK hosts on official Pi can inject their live settings instead of the persisted snapshot; the fork always uses its own. */
+/** ponytail: native estimates can omit request-local guidance; reserve its full section until post-transform usage is exposed. */
+function guidanceTokens(ctx: PolicyContext): number {
+	return estimateTokens({ role: "system", content: `<posthorse>\n${buildGuidance(ctx)}\n</posthorse>`, timestamp: 0 });
+}
+
+/** SDK hosts can inject live settings instead of the persisted CLI snapshot. */
 export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => CompactionPolicy = persistedPolicy) => (pi: ExtensionAPI) => {
-	const nativePi = pi as unknown as NativeExtensionAPI;
-	const native = typeof nativePi.registerContextWindowHook === "function";
-	const policy = (ctx: ExtensionContext): PolicyContext =>
-		native ? (ctx as ExtensionContext & PolicyContext) : {
-			model: ctx.model,
-			getCompactionSettings: () => getPolicy(ctx),
-			getContextUsage: () => ctx.getContextUsage(),
+	const resetRequests = new Map<string, string>();
+	// One synchronous safety evaluation only. Never carry this snapshot across an await.
+	const policy = (ctx: ExtensionContext, livePolicy?: CompactionPolicy): PolicyContext => {
+		let usageRead = false;
+		let usage: ContextUsage | undefined;
+		let settings: CompactionPolicy | undefined;
+		return {
+			getCompactionSettings: () => settings ??= { ...(livePolicy ?? getPolicy(ctx)) },
+			getContextUsage: () => {
+				if (!usageRead) {
+					usage = ctx.getContextUsage();
+					usageRead = true;
+				}
+				return usage;
+			},
 			getSystemPrompt: () => ctx.getSystemPrompt(),
 		};
+	};
+	type ReminderState = {
+		manager: ExtensionContext["sessionManager"];
+		sessionId: string;
+		file: string | undefined;
+		leaf: EntryLike | undefined;
+		windowId: string;
+		reminders: EntryLike[];
+	};
+	let reminderState: ReminderState | undefined;
+	const remindersFor = (ctx: ExtensionContext): ReminderState => {
+		const manager = ctx.sessionManager;
+		const sessionId = manager.getSessionId(), file = manager.getSessionFile();
+		const leaf = manager.getEntry(manager.getLeafId() ?? "") as EntryLike | undefined;
+		const previous = reminderState?.manager === manager && reminderState.sessionId === sessionId && reminderState.file === file
+			? reminderState : undefined;
+		if (previous && previous.leaf === leaf) return previous;
+		const reversed: EntryLike[] = [];
+		let boundary: EntryLike | undefined, window: EntryLike | undefined;
+		let kept = false;
+		for (let entry = leaf; entry; entry = entry.parentId ? manager.getEntry(entry.parentId) as EntryLike | undefined : undefined) {
+			// Certify append-only ancestry by entry identity, not just a reusable id.
+			if (!boundary && previous?.leaf === entry) {
+				return reminderState = { manager, sessionId, file, leaf, windowId: previous.windowId,
+					reminders: [...previous.reminders, ...reversed.reverse().filter((entry) => entry.type === "custom_message" && isReminderType(entry.customType))] };
+			}
+			reversed.push(entry);
+			if (!boundary && (entry.type === "compaction" || entry.type === "context_window")) boundary = entry;
+			if (!window && isWindow(entry)) window = entry;
+			if (boundary && (boundary.type === "context_window" || entry.id === boundary.firstKeptEntryId)) kept = true;
+			// An ordinary compaction can keep a tail preceding the Posthorse boundary.
+			// Missing kept ids or a negative window lookup must reach the root once.
+			if (window && kept) break;
+		}
+		const entries = reversed.reverse();
+		return reminderState = { manager, sessionId, file, leaf, windowId: window?.id ?? "initial",
+			reminders: entries.slice(contextStart(entries).start).filter((entry) => entry.type === "custom_message" && isReminderType(entry.customType)) };
+	};
 	registerPosthorseMessages(pi);
 	const activeToolTokens = () => {
 		const active = new Set(pi.getActiveTools());
 		return pi
 			.getAllTools()
-			// The fork identifies namespaced tools by id; official Pi only has names.
-			.filter((tool) => active.has((tool as typeof tool & { id?: string }).id ?? tool.name))
+			.filter((tool) => active.has(tool.name))
 			.reduce(
 				(total, tool) =>
 					total +
@@ -1016,12 +987,6 @@ export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => Compaction
 			);
 	};
 
-	if (native) {
-		nativePi.registerContextWindowHook((event, ctx) =>
-			boundWindowReceipts(ctx as ExtensionContext & PolicyContext, event.contextEntries, event.pendingMessages, activeToolTokens()),
-		);
-	}
-
 	let pendingPageTokens = 0;
 	let previousPageUsage: number | null | undefined;
 	const pageSize = (ctx: PolicyContext, offset: number, imageCount: number, cursor?: string, imageOffset?: number) => {
@@ -1055,12 +1020,13 @@ export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => Compaction
 		pendingPageTokens += Math.ceil(message.length / 4);
 		throw new Error(message);
 	};
-	const notesPage = (ctx: PolicyContext, rows: string[], offset: number, kind: "notes-list" | "notes-search", empty: string) => {
+	const notesPage = (ctx: PolicyContext, rows: string[], offset: number, kind: "notes-list" | "notes-search", empty: string, header = "") => {
 		const text = rows.length ? rows.join("\n") : empty;
-		const chars = pageSize(ctx, offset, 0);
-		if (offset && offset >= text.length) pageError(ctx, "Offset is past the end; restart with offset 0.");
+		const chars = pageSize(ctx, offset, 0) - header.length;
 		// Reserve the complete continuation, even when one path or excerpt needs several pages.
 		const footer = (end: number) => `\n[chars ${offset}-${end} of ${text.length}; continue with offset ${end}]`;
+		if (chars <= footer(text.length).length) pageError(ctx, `Too little context remains to include the notes path. Call new_context first, then retry with offset ${offset}.`);
+		if (offset && offset >= text.length) pageError(ctx, "Offset is past the end; restart with offset 0.");
 		let end = Math.min(text.length, offset + chars);
 		let start = 0;
 		const starts: number[] = [];
@@ -1073,44 +1039,56 @@ export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => Compaction
 		}
 		// A result-count cap can require continuation even when the character cap did not.
 		if (end < text.length) end = Math.min(end, offset + chars - footer(text.length).length);
-		return pageResult(text.slice(offset, end) + (end < text.length ? footer(end) : ""), [], { kind, count: starts.filter((start) => start < end).length, page: { offset, end, total: text.length } });
+		return pageResult(header + text.slice(offset, end) + (end < text.length ? footer(end) : ""), [], { kind, headerLength: header.length, count: starts.filter((start) => start < end).length, page: { offset, end, total: text.length } });
 	};
 	pi.on("turn_start", () => {
+		resetRequests.clear();
 		pendingPageTokens = 0;
 		previousPageUsage = undefined;
 	});
 
 	pi.on("session_start", () => {
+		resetRequests.clear();
 		pendingPageTokens = 0;
 		previousPageUsage = undefined;
+		reminderState = undefined;
+	});
+	pi.on("session_tree", () => { reminderState = undefined; });
+
+	let runPromptOptions: { forceSystemPrompt?: string } | undefined;
+	pi.on("before_agent_start", (event) => {
+		runPromptOptions = event.systemPromptOptions;
 	});
 
-	pi.on("before_agent_start", (event, ctx) => {
-		const guidance = buildGuidance(policy(ctx), !native);
-		// An earlier full-prompt override makes section edits invisible to Pi.
-		if (event.systemPromptOptions.forceSystemPrompt !== undefined) {
-			return { systemPrompt: `${event.systemPrompt}\n\n${guidance}` };
+	// Continuations do not rerun before_agent_start, even after a model switch or reset.
+	pi.on("context_with_system", (event, ctx) => {
+		const guidance = buildGuidance(policy(ctx));
+		const system = event.messages.findLast((message) => message.role === "system" && typeof message.sections?.posthorse === "string")
+			?? event.messages.find((message) => message.role === "system");
+		if (!system || system.role !== "system") return;
+		if (runPromptOptions?.forceSystemPrompt !== undefined) {
+			// ponytail: official Pi applies forced prompts after these hooks; keep guidance in
+			// request-local conversation until the host projects forced text before the hooks.
+			event.messages.splice(1, 0, { role: "custom", customType: "posthorse-guidance", content: guidance, display: false, timestamp: 0 });
+		} else {
+			system.sections = { ...system.sections, posthorse: `<posthorse>\n${guidance}\n</posthorse>` };
 		}
-		event.systemPromptOptions.sections.posthorse = guidance;
 	});
 
 	pi.on("turn_end", (event, ctx) => {
+		const requested = event.toolResults.find((result) => result.toolName === "new_context" && resetRequests.has(result.toolCallId));
+		const summary = requested ? resetRequests.get(requested.toolCallId) : undefined;
+		resetRequests.clear();
 		const host = policy(ctx);
 		if (
 			event.message.role === "assistant" &&
 			(event.message.stopReason === "error" || event.message.stopReason === "aborted")
 		)
 			return;
-		const requested = event.toolResults.find((result) => result.toolName === "new_context");
 		// Suppress clear successes; turn_end can also include unrelated background errors.
 		// If Pi still rolls over, context filtering below removes any stale reminder.
-		if (requested && !event.toolResults.some((result) => result.isError)) {
-			// The fork commits new_context from the tool result; official Pi needs a retain-none compaction draft.
-			if (native || event.outcome === "aborted" || ctx.signal?.aborted) return;
-			const content = (event.message as MessageLike).content;
-			const call = (Array.isArray(content) ? content as ToolCallLike[] : []).find((block) => block?.type === "toolCall" && block.id === requested.toolCallId);
-			const handoff = (call?.arguments as { handoff?: unknown } | undefined)?.handoff;
-			const summary = (typeof handoff === "string" && handoff.trim()) || EMPTY_HANDOFF;
+		if (summary !== undefined && !event.toolResults.some((result) => result.isError)) {
+			if (event.outcome === "aborted" || ctx.signal?.aborted) return;
 			// Input steered in after execute() checked capacity can leave too little room.
 			if (summary.length > freshPayloadChars(host, activeToolTokens(), event.context.pendingMessages)) {
 				return { entries: [...event.entries, { type: "custom_message" as const, customType: "posthorse-reset-deferred", display: true,
@@ -1127,14 +1105,14 @@ export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => Compaction
 		const remindAt = budget.rolloverAt - reminderBuffer;
 		if (usage.tokens < remindAt) return;
 
-		const branch = ctx.sessionManager.getBranch() as EntryLike[];
+		const state = remindersFor(ctx);
 		const fingerprint: ReminderFingerprint = {
-			windowId: currentWindowId(branch),
+			windowId: state.windowId,
 			contextWindow: budget.contextWindow,
 			reserveTokens: budget.reserveTokens,
 		};
 		// A reminder a compaction summarized away no longer reaches the model.
-		if (hasReminder(branch.slice(contextStart(branch).start), fingerprint)) return;
+		if (hasReminder(state.reminders, fingerprint)) return;
 		pi.sendMessage(
 			{
 				customType: REMINDER_TYPE,
@@ -1153,7 +1131,7 @@ export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => Compaction
 		const marker = event.messages.find((message) => message.role === "custom" && message.customType === "context-window");
 		const windowId = marker?.role === "custom"
 			? (marker.details as { windowId?: unknown } | undefined)?.windowId
-			: currentWindowId(ctx.sessionManager.getBranch() as EntryLike[]);
+			: remindersFor(ctx).windowId;
 		if (typeof windowId !== "string") return;
 		const host = policy(ctx);
 		const budget = budgetFor(host);
@@ -1162,60 +1140,44 @@ export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => Compaction
 			contextWindow: budget?.contextWindow,
 			reserveTokens: budget?.reserveTokens,
 		};
+		const enabled = host.getCompactionSettings().enabled;
 		const stale = (message: (typeof event.messages)[number]) =>
 			message.role === "custom" &&
 			isReminderType(message.customType) &&
-			(!host.getCompactionSettings().enabled || !reminderMatches(message.details, fingerprint));
+			(!enabled || !reminderMatches(message.details, fingerprint));
 		if (event.messages.some(stale)) return { messages: event.messages.filter((message) => !stale(message)) };
 	});
 
-	if (native) {
-		// Claim Pi's automatic threshold/overflow trigger with a fresh window: no summary, no summarization auth.
-		nativePi.on("session_before_auto_compact", (event, ctx) => {
-			const host = policy(ctx as ExtensionContext);
-			const budget = budgetFor(host);
-			// An unsupported budget would roll over every turn; leave Pi's own behavior in place instead.
-			if (budget && !budget.supported) return undefined;
-			const limit = freshPayloadChars(host, activeToolTokens(), event.pendingMessages);
-			const projected = (ctx as ExtensionContext).sessionManager.buildSessionProjection().entries;
-			const handoff = limit >= MIN_PAGE_CHARS ? buildAutoHandoff(event.branchEntries, projected, limit) : "";
-			if (!handoff || handoff.length > limit) {
-				// Only receipts Pi will retain require shaping; consumed results must not force an empty cut.
-				return event.retainedToolResultIds.length ? { newContext: {} } : undefined;
-			}
-			return { newContext: { handoff } };
-		});
-	} else {
-		// Official Pi owns thresholds, recovery retries, and whether another request follows.
-		pi.on("session_before_compact", (event, ctx) => {
-			if (event.reason === "manual") return;
-			const cancelled = () => event.signal.aborted || ctx.signal?.aborted;
+	// Pi owns thresholds, recovery retries, and whether another request follows.
+	pi.on("session_before_compact", (event, ctx) => {
+		if (event.reason === "manual") return;
+		const cancelled = () => event.signal.aborted || ctx.signal?.aborted;
+		if (cancelled()) return { cancel: true };
+		try {
+			// The event carries Pi's live settings; prefer them over the persisted snapshot.
+			const host = policy(ctx, event.preparation.settings);
+			// Small/unknown context windows deliberately keep Pi's own compaction.
+			if (!budgetFor(host)?.supported) return;
+			const limit = freshPayloadChars(host, activeToolTokens());
+			const ownerQuestionRegistered = pi.getAllTools().some((tool) => tool.name === "ask_question" && tool.namespace === undefined);
+			const handoff = buildAutoHandoff(event.branchEntries, ctx.sessionManager.buildSessionProjection().entries, limit, ownerQuestionRegistered);
+			if (limit < MIN_PAGE_CHARS || handoff.length > limit) throw new Error("Too little fresh context capacity for an automatic recovery record.");
 			if (cancelled()) return { cancel: true };
-			try {
-				// The event carries Pi's live settings; prefer them over the persisted snapshot.
-				const host: PolicyContext = { ...policy(ctx), getCompactionSettings: () => event.preparation.settings };
-				// Small/unknown context windows deliberately keep Pi's own compaction.
-				if (!budgetFor(host)?.supported) return;
-				const limit = freshPayloadChars(host, activeToolTokens());
-				const handoff = buildAutoHandoff(ctx.sessionManager.getBranch() as EntryLike[], ctx.sessionManager.buildSessionProjection().entries, limit);
-				if (limit < MIN_PAGE_CHARS || handoff.length > limit) throw new Error("Too little fresh context capacity for an automatic recovery record.");
-				if (cancelled()) return { cancel: true };
-				// firstKeptEntryId must name an entry; an invisible sentinel retains no prior conversation.
-				pi.appendEntry("posthorse-boundary", {});
-				const firstKeptEntryId = ctx.sessionManager.getLeafId();
-				if (!firstKeptEntryId) throw new Error("Pi did not persist the context boundary.");
-				return { compaction: { summary: handoff, firstKeptEntryId, tokensBefore: event.preparation.tokensBefore, details: { posthorse: 1, reason: event.reason } } };
-			} catch (error) {
-				// Pi swallows handler errors and would then run its summarizer; cancel instead.
-				if (!cancelled()) {
-					const message = `Posthorse automatic rollover cancelled: ${error instanceof Error ? error.message : String(error)}`;
-					if (ctx.hasUI) ctx.ui.notify(message, "error");
-					else console.error(message);
-				}
-				return { cancel: true };
+			// firstKeptEntryId must name an entry; an invisible sentinel retains no prior conversation.
+			pi.appendEntry("posthorse-boundary", {});
+			const firstKeptEntryId = ctx.sessionManager.getLeafId();
+			if (!firstKeptEntryId) throw new Error("Pi did not persist the context boundary.");
+			return { compaction: { summary: handoff, firstKeptEntryId, tokensBefore: event.preparation.tokensBefore, details: { posthorse: 1, reason: event.reason } } };
+		} catch (error) {
+			// Pi swallows handler errors and would then run its summarizer; cancel instead.
+			if (!cancelled()) {
+				const message = `Posthorse automatic rollover cancelled: ${error instanceof Error ? error.message : String(error)}`;
+				if (ctx.hasUI) ctx.ui.notify(message, "error");
+				else console.error(message);
 			}
-		});
-	}
+			return { cancel: true };
+		}
+	});
 
 	pi.registerTool({
 		name: "new_context",
@@ -1245,8 +1207,8 @@ export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => Compaction
 				[],
 				{ kind: "new-context" },
 			);
-			// Official Pi ignores this field; its reset is committed at turn_end from the call arguments.
-			return native ? { ...result, newContext: { handoff: trimmed } } : result;
+			resetRequests.set(_id, trimmed || EMPTY_HANDOFF);
+			return result;
 		},
 	});
 
@@ -1255,8 +1217,8 @@ export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => Compaction
 		label: "Context Remaining",
 		...toolCards("get_context_remaining"),
 		description:
-			"Estimate tokens left before Pi's automatic rollover and the configured context limit. A checkpoint reminder already arrives before rollover; use this only before a large step late in a window.",
-		promptSnippet: "check the context budget before a large step late in a window",
+			"Estimate tokens left before Pi's automatic rollover and the configured context limit. Check before reporting remaining space or changing your work plan because of context limits. A checkpoint reminder already arrives before rollover; no routine checks are needed.",
+		promptSnippet: "verify remaining context before reporting a token count or changing plans because of context limits",
 		parameters: Type.Object({}),
 		async execute(_id, _params, _signal, _onUpdate, ctx) {
 			const host = policy(ctx);
@@ -1269,8 +1231,8 @@ export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => Compaction
 				rollover: !budget?.enabled ? "disabled" : budget.supported ? "enabled" : "unsupported",
 				rolloverAt: budget?.rolloverAt,
 			};
-			const configured = `≈${n(Math.max(0, usage.contextWindow - usage.tokens))} tokens until the configured context limit (${n(usage.tokens)}/${n(usage.contextWindow)} used, ${Math.round(usage.percent ?? 0)}%). Best available native estimate.${native ? "" : ` ${SNAPSHOT_NOTE}`}`;
-			if (!budget?.enabled) return textResult(`Automatic rollover is disabled${native ? "" : " in the available settings"} (Pi compaction.enabled=false). ${configured}`, [], display);
+			const configured = `≈${n(Math.max(0, usage.contextWindow - usage.tokens))} tokens until the configured context limit (${n(usage.tokens)}/${n(usage.contextWindow)} used, ${Math.round(usage.percent ?? 0)}%). Best available native estimate. ${SNAPSHOT_NOTE}`;
+			if (!budget?.enabled) return textResult(`Automatic rollover is disabled in the available settings (Pi compaction.enabled=false). ${configured}`, [], display);
 			if (!budget.supported) return textResult(`${unsupportedMessage(budget)} ${configured}`, [], display);
 			return textResult(
 				`≈${n(Math.max(0, budget.rolloverAt - usage.tokens))} tokens until automatic rollover (line at ${n(budget.rolloverAt)}); ${configured}`,
@@ -1284,7 +1246,7 @@ export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => Compaction
 		label: "Notes",
 		...toolCards("notes"),
 		description:
-			"Durable notes in .pi/notes/, shared across Git worktrees and kept across context resets. Ops: list (newest first, with size and date; optional folder path), read, search (case-insensitive substring over text notes), write (replace; empty content clears), append (adds one line-terminated record). list/read/search are paged; continue with the returned offset. Keep one current-state note per task and rewrite it in place.",
+			"Durable notes shared across Git worktrees and context resets. Ops: list (newest first, size/date; optional folder), read, search (case-insensitive text), write (replace; empty clears), append (one newline-terminated record). list/read/search are paged; continue with the returned offset. list shows the absolute notes directory; read shows the absolute file path. Prefer available file-editing tools for changed sections of one concise current-state note; write for creation or substantial restructuring. Link fuller evidence instead of copying it.",
 		promptSnippet: "save and recall durable state that survives context resets",
 		parameters: Type.Object({
 			op: Type.Union(
@@ -1333,6 +1295,7 @@ export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => Compaction
 				params.offset ?? 0,
 				"notes-list",
 				folder ? `(no notes in ${folder})` : "(no notes yet)",
+				`Notes directory: ${dir}\n`,
 			);
 
 			switch (params.op) {
@@ -1350,10 +1313,14 @@ export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => Compaction
 					if (offset && offset >= text.length) {
 						throw new Error(`Offset ${offset} is past the end of ${relative} (${text.length} chars).`);
 					}
-					const end = Math.min(text.length, offset + pageSize(policy(ctx), offset, 0));
+					const header = `File: ${path}\n`;
+					const host = policy(ctx);
+					const chars = pageSize(host, offset, 0) - header.length;
+					if (chars <= 0) pageError(host, `Too little context remains to include the note path. Call new_context first, then retry with offset ${offset}.`);
+					const end = Math.min(text.length, offset + chars);
 					const more =
 						end < text.length ? `\n[chars ${offset}-${end} of ${text.length}; continue with offset ${end}]` : "";
-					return pageResult(`${text.slice(offset, end)}${more}`, [], { kind: "note-read", offset, end, total: text.length });
+					return pageResult(`${header}${text.slice(offset, end)}${more}`, [], { kind: "note-read", headerLength: header.length, offset, end, total: text.length });
 				}
 				case "write": {
 					const relative = requireValue(params.path, "path", params.op);
@@ -1507,13 +1474,14 @@ export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => Compaction
 						if (hits[0].length > limit) break;
 					}
 				}
-				const chars = pageSize(policy(ctx), 0, 0, params.cursor);
-				if (!found) pageError(policy(ctx), "History cursor entry no longer matches; restart the search without it.", params.cursor);
+				const host = policy(ctx);
+				const chars = pageSize(host, 0, 0, params.cursor);
+				if (!found) pageError(host, "History cursor entry no longer matches; restart the search without it.", params.cursor);
 				const results = hits.flat();
 				const cursorFor = (hit: HistoryHit, offset: number) => Buffer.from(JSON.stringify([hit.id, hit.priority, offset, searchKey])).toString("base64url");
 				const footer = (next: string) => `\n[More results; continue with cursor "${next}" and the same query/scope.]`;
 				const reserve = Math.max(0, ...results.map((hit) => footer(cursorFor(hit, hit.text.length)).length));
-				if (reserve >= chars) pageError(policy(ctx), "History entry id is too large for pagination.", params.cursor);
+				if (reserve >= chars) pageError(host, "History entry id is too large for pagination.", params.cursor);
 				const skippedNote = skipped && !params.cursor
 					? `\n[Skipped ${skipped} match${skipped === 1 ? "" : "es"} already in your active context.]`
 					: "";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. No-summary context rollover for Pi, with sparse budget reminders, handoffs, notes, and history.",
 	"keywords": ["pi-package", "pi-extension", "context", "posthorse", "rollover"],
@@ -13,7 +13,7 @@
 	"engines": {
 		"node": ">=24.12.0"
 	},
-	"packageManager": "npm@12.1.0",
+	"packageManager": "npm@12.2.0",
 	"pi": {
 		"extensions": ["./index.ts"],
 		"image": "https://raw.githubusercontent.com/fitchmultz/pi-posthorse/main/diagram.png"
@@ -42,11 +42,11 @@
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "0.87.1",
-		"@earendil-works/pi-coding-agent": "0.87.1",
-		"@earendil-works/pi-tui": "0.87.1",
+		"@earendil-works/pi-ai": "1.0.0",
+		"@earendil-works/pi-coding-agent": "1.0.0",
+		"@earendil-works/pi-tui": "1.0.0",
 		"@types/node": "24.19.0",
-		"typebox": "1.3.34",
+		"typebox": "1.3.27",
 		"typescript": "7.0.2"
 	}
 }

package/ui.ts

@@ -4,8 +4,8 @@ import { Box, MouseRegion, Text, stripTerminalSequences, truncateToWidth, type C
 /** Display-only facts and offsets into content, never a second copy of a note or history page. */
 export type PosthorseDisplay =
 	| { kind: "context"; usage?: { tokens: number | null; contextWindow: number; percent: number | null }; rollover?: "enabled" | "disabled" | "unsupported"; rolloverAt?: number }
-	| { kind: "notes-list" | "notes-search"; count: number; page?: { offset: number; end: number; total: number } }
-	| { kind: "note-read"; offset: number; end: number; total: number }
+	| { kind: "notes-list" | "notes-search"; count: number; headerLength?: number; page?: { offset: number; end: number; total: number } }
+	| { kind: "note-read"; headerLength?: number; offset: number; end: number; total: number }
 	| { kind: "note-write" | "note-append" | "new-context" }
 	| { kind: "history-search"; entries: Array<{ headerLength: number; length: number }>; footerLength?: number; more?: boolean; skipped?: number }
 	| { kind: "history-read"; headerLength: number; offset: number; end: number; total: number; imageOffset?: number; imageEnd?: number; imageTotal?: number };
@@ -127,7 +127,8 @@ export function toolCards(name: ToolName): Pick<ToolDefinition, "renderCall" | "
 			const submittedText = textBlock(submitted, theme);
 			const attachmentText = textBlock(attachment, theme, "muted");
 			// Old results have no spans. Only the preview sheds the known history prefix.
-			const preview = sections ? sections.map(({ body }) => body).join("\n") : name === "history" && !context.isError ? body.replace(/^[^\n]*?\[window [^\]\n]+\] \[[^\]\n]+\](?: \[chars \d+-\d+ of \d+\])? /gm, "") : body;
+			const noteHeaderLength = !context.isError && (display?.kind === "note-read" || display?.kind === "notes-list") ? display.headerLength ?? 0 : 0;
+			const preview = sections ? sections.map(({ body }) => body).join("\n") : noteHeaderLength ? body.slice(noteHeaderLength) : name === "history" && !context.isError ? body.replace(/^[^\n]*?\[window [^\]\n]+\] \[[^\]\n]+\](?: \[chars \d+-\d+ of \d+\])? /gm, "") : body;
 			const previewText = textBlock(preview, theme, color);
 			const searchPreviews = sections && display?.kind === "history-search" ? sections.slice(0, 3).map(({ body }) => theme.fg("toolOutput", clean(body).replace(/\s+/g, " "))) : undefined;
 			const summaryOnly = display?.kind === "context" || display?.kind === "new-context" || display?.kind === "note-write" || display?.kind === "note-append" || ((display?.kind === "notes-list" || display?.kind === "notes-search") && display.count === 0) || (display?.kind === "note-read" && display.total === 0) || (display?.kind === "history-search" && Array.isArray(display.entries) && display.entries.length === 0);
@@ -142,7 +143,7 @@ export function toolCards(name: ToolName): Pick<ToolDefinition, "renderCall" | "
 						? searchPreviews.map((line) => truncateToWidth(line, width))
 						: previewText.render(width);
 					const shown = previewRows.slice(0, Math.max(0, Math.min(3, 5 - summaryRows.length - (attachment ? 1 : 0))));
-					const hidden = summaryOnly || previewRows.length > shown.length || Boolean(sections || submitted);
+					const hidden = summaryOnly || previewRows.length > shown.length || Boolean(sections || submitted || noteHeaderLength);
 					return [...summaryRows, ...shown, ...(attachment ? [truncateToWidth(theme.fg("muted", attachment), width)] : []), ...(hidden ? [hint(theme, width)] : [])];
 				},
 			};