pi-posthorse 0.9.0 → 0.9.2

package/README.md

@@ -1,135 +1,91 @@
 # Posthorse
 
-**Fresh context. Same journey.** (POST-horse)
+Posthorse starts fresh context windows for long [Pi](https://github.com/earendil-works/pi) tasks and keeps earlier conversation recoverable. Each rollover uses a handoff or recovery record without a model-generated summary.
 
-No-summary context rollover for [Pi](https://github.com/earendil-works/pi), on official Pi and on the [`fitchmultz/pi`](https://github.com/fitchmultz/pi) fork. A post-horse was swapped in at relay stations so the courier and the message could continue on fresh legs. Posthorse does the same for a model: fresh context, same work, complete recoverable transcript.
+![A Pi conversation rolls into a fresh context window. Task notes and the complete session transcript remain available.](.github/readme/context-rollover.png)
 
-![Posthorse flow](https://raw.githubusercontent.com/fitchmultz/pi-posthorse/main/diagram.png)
+## Install and start
 
-Pi owns the persisted boundary. Posthorse owns the policy: stable window guidance, one best-effort checkpoint reminder, `new_context`, `get_context_remaining`, durable `notes`, and window-aware `history`. A rollover removes the old window from active model context while the JSONL transcript stays append-only and complete.
+Use Node 24.12.0 or later and Pi 1.0.0 or later. Posthorse supports official Pi and [fitchmultz/pi](https://github.com/fitchmultz/pi).
 
-## Requirements
-
-- Node `>=24.12.0`.
-- 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.
-
-Required qualification targets: latest stable official Pi and latest maintained fork `main`, resolved once per workflow run and retained with exact SDK/CLI identity evidence. Locked development dependencies are reproducible build snapshots, not validation targets. Historical official Pi `1.0.0` ([source `a13d35a`](https://github.com/earendil-works/pi/commit/a13d35a742c6ef8462812a28fbe1d8c8b7431c32)), TypeBox `1.3.27` and Node `24.21.0` evidence does not certify newer hosts. Qualification does not install, activate, or restart the live runtime.
-
-## Install
-
-Posthorse `0.9.0` requires Pi `>=1.0.0`. Update the host before installing this release; do not activate it on an older live fork.
+Update an older Pi installation before you install Posthorse. Run these commands:
 
 ```bash
-pi install npm:pi-posthorse@0.9.0                        # from npm
-pi install git:github.com/fitchmultz/pi-posthorse@v0.9.0 # from Git
-pi -e npm:pi-posthorse@0.9.0                             # try it for one run without installing
+pi install npm:pi-posthorse
+pi
 ```
 
-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.
-
-Keep exactly one copy loaded. `pi list` shows every package source; if a second source or a local checkout is listed, `pi remove` it, otherwise two copies register the same tools and compete for the same rollover hook.
-
-## Official Pi and the fork
-
-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.
-
-- **Automatic eligibility on both hosts:** Pi's compaction preparation must succeed before the automatic hook runs. Posthorse's custom compaction result bypasses the default summarizer and its credential lookup. In fresh compaction windows without a subsequent projected turn-start input, Posthorse owns threshold rollover at completed turn end when known usage reaches the enabled, supported threshold; it preserves normal continuation and never requests another response after a final answer. Other threshold spans and overflow/truncated-response recovery stay Pi-owned. Tiny overflow/truncated responses can still miss native recovery, and oversized initial input can reach the provider before recovery.
-- **Policy:** guidance, reminders and budget reports use Pi's live effective settings, including runtime and per-model compaction overrides, defaults and validation; the turn-end threshold fallback uses this same policy reader, while the native automatic hook uses the live settings in its event. Manual settings-file edits take effect when Pi refreshes its live settings, just like Pi's own compaction, not on Posthorse's next evaluation. SDK hosts can inject policy with `createPosthorse(getPolicy)`. Handoffs appear as compaction-summary messages. Background work owned outside the foreground batch is not serialized or stopped by Posthorse.
-
-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
+Restart Pi after installation or an update. To try Posthorse for one session, run `pi -e npm:pi-posthorse`.
 
-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 arrive at the end of a working turn inside the checkpoint band before Pi's rollover line, never on a turn that ends the run. It cannot wake a finished agent or replace its final answer. The reminder asks 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. Across consecutive automatic boundaries, a window with no owner inputs carries the same first/latest owner anchors from the nearest earlier owner window, labeled as earlier, possibly already handled, and not current progress. The walk stops at that window or an explicit/native compaction checkpoint; context edits still omit or replace carried inputs, and `ask_question` answers keep the same provenance checks. The newest non-automatic checkpoint reached replaces nested automatic text, with bounded history pointers to skipped automatic record ids. Carried anchors share the existing payload budget; earlier automatic tool evidence is never nested. 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.
+Give Pi your task. For example:
 
-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.
+> Save task state in a note. Start a fresh context window with the next steps.
 
-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.
+## How rollover works
 
-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.
+Posthorse can remind the model to save task state before rollover. Large turns can reach rollover before this reminder. The reminder does not wake an agent after its final answer.
 
-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.
+Automatic rollover creates a recovery record from session inputs and tool results. The model must restore notes and check live state before it continues. Manual `/compact` uses Pi's normal summarization.
 
-## Settings
-
-Posthorse follows Pi's effective `compaction` settings, including Pi's decision about whether project settings are trusted. Disabling `compaction.enabled` disables reminders and automatic rollover; `new_context` stays available.
-
-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 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.
-
-The fresh-window threshold fallback builds its recovery record from the boundary preview when its `turn_end` handler runs. Earlier turn-start drafts keep compaction Pi-owned; earlier context-edit drafts defer the fallback until usage can be re-evaluated after commit. Unlike the native automatic hook (which runs after all turn-end handlers), the eager fallback cannot observe later handlers' edits. Later projection-editing handlers must explicitly replace/remove its drafted compaction if they change its source evidence; ordering an editor before Posthorse lets its drafts defer rollover safely. A host post-boundary hook would be needed to include arbitrary later same-phase edits automatically.
+See [rollover and recovery details](docs/reference.md#how-it-works).
 
 ## Tools
 
-- `new_context({ handoff? })`
-- `get_context_remaining()`
-- `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. It also skips files over 1 MiB and says how many it skipped. Search stops reading once the requested page is decided, so a broad query reports that more matches follow instead of a total; its pages end before offset 1,000,000. `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.
+These tools are available to the model:
 
-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.
+| Tool                        | Use                                                                                                                                          |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `new_context({ handoff? })` | Request a fresh window after every foreground tool succeeds. Aborted turns and failed tools prevent the reset.                               |
+| `get_context_remaining()`   | Estimate tokens left until rollover and the configured context limit. Usage can be unknown before a model response.                          |
+| `notes({ op, ... })`        | List, read, search, write, or append task notes.                                                                                             |
+| `history({ op, ... })`      | Search earlier conversation and read entries, including images. `all: true` includes this project's other sessions and nested subagent runs. |
 
-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.
+Expand a tool card with Ctrl+O. In fullscreen mode, click a tool card to expand it. A `new_context` card shows a request. Pi's `Compacted from … tokens` card confirms the rollover.
 
-`history search` puts matching original content before recovery material: handoffs, compaction and branch summaries, checkpoint reminders, and `notes`, `new_context`, and `history` calls/results. Ordinary prose or another tool call in the same assistant entry keeps its priority when that content matches. Every entry remains searchable; `history read` returns the complete normalized entry, including any recovery content omitted from a search excerpt.
+See [tool examples and paging details](docs/reference.md#tools).
 
-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.
+## Settings and limits
 
-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.
+Posthorse uses Pi's effective `compaction` settings. It has no separate settings.
 
-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.
+| Pi setting                 | Effect                                                                                                                                                             |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `compaction.enabled`       | Set to `false` to disable reminders and automatic rollover. `new_context` remains available.                                                                       |
+| `compaction.reserveTokens` | Automatic Posthorse rollover needs at least 10,000 tokens after this reserve. Smaller budgets use Pi's own compaction. Lower the reserve or choose a larger model. |
 
-`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.
+Two Posthorse copies can register the same tools and compete for rollover. Keep one copy loaded. Check installed sources with `pi list`.
 
-## Data and privacy
+Multiple compaction-policy extensions can make rollover depend on load order. Enable only one.
 
-- 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.
-- History can return user text, assistant text and thinking, assistant failure status and error messages, tool arguments and results, handoffs, custom messages, and images. Direct shell entries Pi marked `excludeFromContext` come back as a placeholder only.
-- Returned history content enters the currently selected model and provider context.
-- Removing Posthorse does not remove notes or Pi session history.
+Oversized input and some overflow or truncated responses can reach the provider before automatic recovery. Save task state in notes. Background work outside the foreground tool batch continues across rollover.
 
-For latest-host qualification, run `node /path/to/automation/scripts/qualify.mjs --repo pi-posthorse --source "$PWD" --host official --target latest --output /tmp/pi-posthorse-official`, then qualify the packed latest maintained fork with `--host fork --target /path/to/fork-package`. Plain `npm ci` checks only the locked development snapshot, not latest qualification.
+See [size limits and extension order](docs/reference.md#settings).
+Check the [legacy-session details](docs/reference.md#official-pi-and-the-fork) before you move old fork sessions to official Pi.
 
-## Automatic npm releases (maintainers)
+## Update or remove
 
-Follow the [shared release procedure](https://github.com/fitchmultz/.github#automatic-npm-releases): merge a reviewed PR into `main` with an intentional `package.json` version bump and a matching versioned `CHANGELOG.md` section. Once configured and enabled, publication is unattended after the full existing CI workflow and candidate-tarball qualification pass. Complete any applicable package-specific release evidence before merging the bump. Automation never bumps versions, overwrites releases, or republishes an existing version; existing manual publisher instructions remain valid.
+```bash
+pi update npm:pi-posthorse
+pi remove npm:pi-posthorse
+```
 
-Failed/unpublished candidates can retry daily at 12:17 UTC or via manual dispatch of `npm release` on `main`, without another bump. Set repository variable `NPM_RELEASE_ENABLED` to anything other than `true` to stop new release plans; cancel pending runs separately when needed. Workflow validation is not evidence of a completed real OIDC publication.
+Removal leaves notes and Pi session history in place. See the [installation reference](docs/reference.md#install) for Git sources.
 
-## Develop
+## Data and privacy
 
-```bash
-npm ci --ignore-scripts
-npm run verify                        # strict policy, lint, formatting, typecheck, tests, package build
-npm run check:compat                   # typecheck, unit tests, and the real-SDK suite for the installed host
-```
+Posthorse makes no network requests. Notes are plaintext files under `.pi/notes/`; linked Git worktrees share them. Add `.pi/notes/` to `.gitignore` if the notes must stay private.
 
-Oxlint owns code quality; Oxfmt owns formatting. See [Code quality](docs/quality.md) for coverage,
-exception governance, editor setup, and the enforced acceptance workflow.
+History can include user messages, assistant thinking, tool arguments, errors, and images. Content you retrieve enters the context of your selected model and provider.
 
-`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.
+See [storage and privacy details](docs/reference.md#data-and-privacy).
+For cost diagnosis, see the [cached-token investigation](ARTIFACTS/investigation-report.md).
+It does not establish the cause of a production bill or a measured cost improvement.
 
-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.
+## Development
 
-Native session suites own registration, question-outcome provenance, reminder delivery, and active-context history exclusions (both Posthorse rollover and native compaction). Unit tests retain distinct policy arithmetic, archive/storage edge cases, and performance bounds; renderer tests exercise actual native cards.
+See [development and host qualification](docs/development.md) for setup, tests, and releases.
+See [code quality](docs/quality.md) for the required checks.
 
-`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.
+## License
 
-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.
+[MIT](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.9.0",
+	"version": "0.9.2",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. No-summary context rollover for Pi, with sparse budget reminders, handoffs, notes, and history.",
 	"keywords": [
@@ -32,7 +32,7 @@
 	},
 	"scripts": {
 		"check": "tsc",
-		"quality:prepare": "node scripts/setup-oxlint-engine.ts && node scripts/setup-quality-engine.ts",
+		"quality:prepare": "node scripts/quality-prepare.ts",
 		"quality:policy": "node scripts/quality-policy.ts",
 		"quality:probes": "npm run quality:prepare && node --test test/quality*.test.ts",
 		"lint": "npm run quality:prepare && npm run quality:policy && oxlint --deny-warnings .",
@@ -42,9 +42,9 @@
 		"format:check": "oxfmt --check .",
 		"build": "npm pack --dry-run",
 		"verify": "npm run lint && npm run format:check && npm run check:compat && npm run build",
-		"check:compat": "npm run check && npm test && npm run test:native",
+		"check:compat": "npm run check && npm test",
 		"test:native": "node --import ./test/pi-loader.ts --test test/host.test.mjs",
-		"test": "npm run quality:prepare && node --import ./test/pi-loader.ts --test test/*.test.ts",
+		"test": "npm run quality:prepare && node --import ./test/pi-loader.ts --test test/*.test.ts test/host.test.mjs",
 		"prepublishOnly": "npm run verify"
 	},
 	"peerDependencies": {

package/src/files.ts

@@ -112,25 +112,31 @@ export async function publishFile(
 		throw error;
 	}
 }
-/** Split on LF only; Unicode line separators are valid inside JSONL strings and notes. */
-export async function* lfLines(file: string, signal?: AbortSignal): AsyncGenerator<string> {
-	const stream = createReadStream(file, { encoding: "utf8", signal });
-	let pending: string[] = [];
+/** Raw LF-delimited lines; UTF-8 never encodes LF inside another character. */
+export async function* lfLines(
+	file: string,
+	signal?: AbortSignal,
+	highWaterMark = 64 * 1024,
+): AsyncGenerator<Buffer> {
+	const stream = createReadStream(file, { signal, highWaterMark });
+	let pending: Buffer[] = [];
 	for await (const chunk of stream) {
-		if (typeof chunk !== "string") {
-			throw new Error("Expected a UTF-8 text stream.");
+		if (!Buffer.isBuffer(chunk)) {
+			throw new Error("Expected a byte stream.");
+		}
+		let start = 0;
+		for (let end = chunk.indexOf(10); end !== -1; end = chunk.indexOf(10, start)) {
+			const line = chunk.subarray(start, end);
+			yield pending.length === 0 ? line : Buffer.concat([...pending, line]);
+			pending = [];
+			start = end + 1;
 		}
-		const lines = chunk.split("\n");
-		pending.push(lines[0] ?? "");
-		if (lines.length > 1) {
-			yield pending.join("");
-			yield* lines.slice(1, -1);
-			pending = [lines.at(-1) ?? ""];
+		if (start < chunk.length) {
+			pending.push(chunk.subarray(start));
 		}
 	}
-	const last = pending.join("");
-	if (last !== "") {
-		yield last;
+	if (pending.length > 0) {
+		yield Buffer.concat(pending);
 	}
 }
 /** Git's heuristic: a NUL in the first 8,000 bytes marks binary content. */

package/src/history-search.ts

@@ -10,8 +10,9 @@ import {
 import { historyHit, seenText, reverseWindowEntries } from "./history-entries.ts";
 import { shortKey } from "./message-text.ts";
 import {
-	filesContaining,
+	needleLines,
 	prefilterNeedles,
+	type RawLine,
 	scopedSessionFiles,
 	sessionWindowEntries,
 } from "./session-files.ts";
@@ -192,13 +193,14 @@ async function scanArchive(
 		readonly source: string;
 		readonly query: string;
 		readonly signal?: AbortSignal;
+		readonly wanted?: (bytes: RawLine) => boolean;
 		readonly inContext: (entry: EntryLike) => boolean;
 	},
 	accumulator: SearchProgress,
 ): Promise<{ readonly groups: readonly (readonly HistoryHit[])[]; readonly skipped: number }> {
 	const collector = archiveCollector(accumulator);
 	let skipped = 0;
-	for await (const item of sessionWindowEntries(file, options.signal)) {
+	for await (const item of sessionWindowEntries(file, options.signal, options.wanted)) {
 		const hit = historyHit(item, options.query, options.source);
 		if (hit === undefined) {
 			continue;
@@ -221,10 +223,7 @@ async function archivedMatches(
 	accumulator: SearchProgress,
 ): Promise<number> {
 	const needles = prefilterNeedles(search.query);
-	const candidates =
-		needles === undefined
-			? undefined
-			: await filesContaining(source.dir, needles, search.signal);
+	const wanted = needles === undefined ? undefined : needleLines(needles);
 	const current =
 		source.currentFile === undefined || source.currentFile === ""
 			? undefined
@@ -235,7 +234,7 @@ async function archivedMatches(
 		cwd: source.cwd,
 		currentFile: source.currentFile,
 		signal: search.signal,
-		candidates: candidates === undefined ? undefined : (candidate) => candidates.has(candidate),
+		needles,
 	})) {
 		const inCurrent = resolve(file) === current;
 		const recent = await scanArchive(
@@ -244,6 +243,7 @@ async function archivedMatches(
 				source: relative(source.dir, file),
 				query: search.query,
 				signal: search.signal,
+				wanted,
 				inContext: (entry) => inCurrent && search.inContext(entry),
 			},
 			accumulator,

package/src/history.ts

@@ -7,7 +7,7 @@ import { toWindowedEntry, windowProjection } from "./history-entries.ts";
 import { historyReadPage, searchPage } from "./history-pages.ts";
 import { historyMatches, type HistorySource } from "./history-search.ts";
 import type { PageAccess } from "./paging.ts";
-import { filesContaining, scopedSessionFiles, sessionWindowEntries } from "./session-files.ts";
+import { scopedSessionFiles, sessionWindowEntries } from "./session-files.ts";
 
 type LocatedEntry = { readonly item: WindowedEntry; readonly source: string };
 function entryReference(id: string): { readonly entryId: string; readonly fileKey?: string } {
@@ -38,19 +38,20 @@ async function findEntry(
 	if (current !== undefined) {
 		return { item: current, source: "" };
 	}
-	const candidates =
-		fileKey === undefined && /^[\w-]+$/.test(entryId)
-			? await filesContaining(source.dir, [`"id":"${entryId}"`], signal)
-			: undefined;
 	for await (const file of scopedSessionFiles({
 		dir: source.dir,
 		cwd: source.cwd,
 		currentFile: source.currentFile,
 		signal,
 		fileKey,
-		candidates: candidates === undefined ? undefined : (candidate) => candidates.has(candidate),
+		needles:
+			fileKey === undefined && /^[\w-]+$/.test(entryId) ? [`"id":"${entryId}"`] : undefined,
 	})) {
-		for await (const item of sessionWindowEntries(file, signal, entryId)) {
+		for await (const item of sessionWindowEntries(
+			file,
+			signal,
+			(_bytes, entry) => entry.id === entryId,
+		)) {
 			return { item, source: relative(source.dir, file) };
 		}
 	}

package/src/rollover.ts

@@ -41,6 +41,10 @@ function registerGuidance(pi: ExtensionAPI, policy: SnapshotReader): void {
 	pi.on("before_agent_start", (event) => {
 		promptOptions = event.systemPromptOptions;
 	});
+	pi.on("agent_settled", () => {
+		// Older hosts skip the start hook for custom runs; do not reuse a settled run's options.
+		promptOptions = undefined;
+	});
 	pi.on("context_with_system", (event, ctx) => {
 		const guidance = buildGuidance(policy(ctx));
 		const system =

package/src/session-files.ts

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
 import { join, relative, resolve, sep } from "node:path";
 
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
@@ -14,13 +15,21 @@ import { lfLines } from "./files.ts";
 import { toWindowedEntry, windowProjection } from "./history-entries.ts";
 import { shortKey } from "./message-text.ts";
 
+/** Newest archive bytes searched before the rest; common queries finish within them. */
+const FIRST_SEARCH_BYTES = 256 * 1024 * 1024;
+/** File-list characters per ripgrep run, within Windows' 32,767 and POSIX ARG_MAX limits. */
+const ARGUMENT_CHARS = process.platform === "win32" ? 30_000 : 256 * 1024;
+/** Pi writes these keys first, so most lines yield window metadata without JSON.parse. */
+const ENTRY_HEAD = /^\{"type":"([^"\\]*)","id":"([^"\\]*)","parentId":(null|"[^"\\]*")[,}]/u;
+
 function execFileText(
 	file: string,
 	args: readonly string[],
+	cwd: string,
 	signal?: AbortSignal,
 ): Promise<string> {
 	return new Promise((resolveOutput, reject) => {
-		execFile(file, args, { signal, maxBuffer: 64 * 1024 * 1024 }, (error, stdout) => {
+		execFile(file, args, { cwd, signal, maxBuffer: 64 * 1024 * 1024 }, (error, stdout) => {
 			if (error !== null) {
 				const failure: Error = error;
 				reject(failure);
@@ -30,65 +39,127 @@ function execFileText(
 		});
 	});
 }
-/** Raw JSONL needles must cover every match in normalized text; otherwise scan all files. */
+/** Label text normalization adds, and raw JSONL that every entry showing it contains. */
+const LABEL_SOURCES: readonly (readonly [label: string, needles: readonly string[]])[] = [
+	["call id", ['"type":"toolCall"', '"toolCallId"']],
+	["execution arguments", ['"executionArguments"']],
+	["no handoff", ['"type":"context_window"']],
+	["excluded from model context by pi", ['"excludeFromContext":true']],
+	["images", ['"type":"image"']],
+	["unknown type", ['"type":"image"']],
+	["unknown", ['"type":"custom_message"']],
+];
+/**
+ * Raw JSONL needles, one of which every line rendering the lowercase query contains; undefined
+ * means every line must be scanned.
+ */
 export function prefilterNeedles(query: string): string[] | undefined {
-	if (/["\\[\](){}:$\p{Cc}]/u.test(query) || query.trim() !== query) {
+	// A match contains every fragment between characters that JSON escapes or labels may add.
+	const [fragment] = query
+		.split(/["\\[\](){}:$\p{Cc}\p{Cs}]/u)
+		.map((part) => part.trim())
+		.sort((a, b) => b.length - a.length);
+	if (fragment === "") {
 		return undefined;
 	}
-	if (
-		["call id", "execution arguments", "no handoff", "excluded from model context by pi"].some(
-			(phrase) => phrase.includes(query),
-		)
-	) {
-		return undefined;
+	const image = fragment.includes(",") || /^\d+ ?i?m?a?g?e?s?$/.test(fragment);
+	return [
+		fragment,
+		...LABEL_SOURCES.filter(([label]) => label.includes(fragment)).flatMap(
+			([, needles]) => needles,
+		),
+		...(image ? ['"type":"image"'] : []),
+		// İ lowercases to i + U+0307, which case-insensitive raw matching cannot see.
+		...(/i|\u0307/u.test(fragment) ? ["\u0130"] : []),
+	];
+}
+/** UTF-8 of the only non-ASCII characters that case-fold to ASCII letters, read as Latin-1. */
+const ASCII_FOLDS: Readonly<Partial<Record<string, string>>> = {
+	k: "\u00e2\u0084\u00aa",
+	s: "\u00c5\u00bf",
+};
+const DOTTED_I = Buffer.from("\u0130");
+/** The read capabilities line filters need from a raw journal line. */
+export type RawLine = Readonly<Pick<Buffer, "includes" | "toString">>;
+/** Whether a raw line contains one of prefilterNeedles' needles, ignoring case like its text would. */
+export function needleLines(needles: readonly string[]): (bytes: RawLine) => boolean {
+	const others = needles.filter((needle) => needle !== "\u0130");
+	const dotted = others.length < needles.length;
+	if (others.every((needle) => /^[\0-\x7f]*$/u.test(needle))) {
+		// ASCII text matches its Latin-1 byte view, so most lines are never decoded as UTF-8.
+		const latin1 = others.map((needle) =>
+			needle
+				.split("")
+				.map((char) => {
+					const fold = ASCII_FOLDS[char.toLowerCase()];
+					return fold === undefined ? RegExp.escape(char) : `(?:${char}|${fold})`;
+				})
+				.join(""),
+		);
+		const pattern = new RegExp(latin1.join("|"), "i");
+		return (bytes) =>
+			(dotted && bytes.includes(DOTTED_I)) || pattern.test(bytes.toString("latin1"));
 	}
-	const image =
-		query.includes(",") ||
-		/^\d+ ?i?m?a?g?e?s?$/.test(query) ||
-		["images", "unknown type"].some((phrase) => phrase.includes(query));
-	return image ? [query, '"type":"image"'] : [query];
+	const pattern = new RegExp(needles.map((needle) => RegExp.escape(needle)).join("|"), "iu");
+	return (bytes) => pattern.test(bytes.toString("utf8"));
 }
-export async function filesContaining(
+/** File lists that each fit one ripgrep command line. */
+function commandGroups(paths: readonly string[]): string[][] {
+	const groups: string[][] = [];
+	let group: string[] = [];
+	let chars = 0;
+	for (const path of paths) {
+		if (group.length > 0 && chars + path.length > ARGUMENT_CHARS) {
+			groups.push(group);
+			group = [];
+			chars = 0;
+		}
+		group.push(path);
+		chars += path.length + 1;
+	}
+	return group.length > 0 ? [...groups, group] : groups;
+}
+/** Files containing a needle, per ripgrep; files of a failed run stay candidates. */
+function ripgrepFilter(
 	dir: string,
 	needles: readonly string[],
 	signal?: AbortSignal,
-): Promise<Set<string> | undefined> {
-	const args = [
+): (files: readonly string[]) => Promise<string[]> {
+	let binaries = [join(getAgentDir(), "bin", "rg"), "rg"];
+	const flags = [
 		"--files-with-matches",
+		"--null",
 		"--fixed-strings",
 		"--ignore-case",
-		"--no-ignore",
-		"--hidden",
 		"--no-messages",
-		"--glob",
-		"*.jsonl",
 		...needles.flatMap((needle) => ["--regexp", needle]),
-		dir,
+		"--",
 	];
-	for (const rg of [join(getAgentDir(), "bin", "rg"), "rg"]) {
-		try {
-			// Try the host-managed binary first; PATH is a fallback only when it is unavailable.
-			// oxlint-disable-next-line no-await-in-loop
-			const stdout = await execFileText(rg, args, signal);
-			return new Set(
-				stdout
-					.split("\n")
-					.filter((file) => file !== "")
-					.map((file) => resolve(file)),
-			);
-		} catch (error) {
-			const code = isRecord(error) ? error.code : undefined;
-			if (code === 1) {
-				return new Set();
+	const matching = async (paths: readonly string[]): Promise<readonly string[]> => {
+		for (const binary of binaries) {
+			try {
+				// Try the host-managed binary first; PATH is a fallback only when it is unavailable.
+				// oxlint-disable-next-line no-await-in-loop
+				return (await execFileText(binary, [...flags, ...paths], dir, signal)).split("\0");
+			} catch (error) {
+				const code = isRecord(error) ? error.code : undefined;
+				if (code === 1) {
+					return [];
+				}
+				if (code !== "ENOENT") {
+					signal?.throwIfAborted();
+					return paths;
+				}
+				binaries = binaries.filter((candidate) => candidate !== binary);
 			}
-			if (code === "ENOENT") {
-				continue;
-			}
-			signal?.throwIfAborted();
-			return undefined;
 		}
-	}
-	return;
+		return paths;
+	};
+	return async (files) => {
+		const paths = files.map((file) => relative(dir, file));
+		const found = new Set((await Promise.all(commandGroups(paths).map(matching))).flat());
+		return files.filter((_file, index) => found.has(paths[index]));
+	};
 }
 function messageFrom(value: unknown): MessageLike | undefined {
 	if (!isRecord(value)) {
@@ -138,40 +209,90 @@ function parsedEntry(line: string): EntryLike | undefined {
 		return undefined;
 	} // Pi skips malformed journal lines too.
 }
+/** Window metadata of a Pi-ordered line that cannot open a window, without parsing it. */
+function entryHead(bytes: RawLine): EntryLike | undefined {
+	const head = ENTRY_HEAD.exec(bytes.toString("utf8", 0, 512));
+	if (head === null || head[1] === "compaction" || head[1] === "context_window") {
+		return undefined;
+	}
+	return {
+		type: head[1],
+		id: head[2],
+		parentId: head[3] === "null" ? null : head[3].slice(1, -1),
+	};
+}
+/** Whether a caller may need a line; other lines only advance window ancestry. */
+type LineFilter = (bytes: RawLine, entry: EntryLike) => boolean;
 export async function* sessionWindowEntries(
 	file: string,
 	signal?: AbortSignal,
-	entryId?: string,
+	wanted: LineFilter = () => true,
 ): AsyncGenerator<WindowedEntry> {
 	if (!existsSync(file)) {
 		return;
 	}
 	const project = windowProjection();
-	for await (const line of lfLines(file, signal)) {
-		const entry = parsedEntry(line);
-		if (entry === undefined) {
+	for await (const bytes of lfLines(file, signal, 1024 * 1024)) {
+		const head = entryHead(bytes);
+		if (head !== undefined && !wanted(bytes, head)) {
+			project(head);
 			continue;
 		}
-		const windowId = project(entry);
-		if (entryId !== undefined && entry.id !== entryId) {
+		const entry = parsedEntry(bytes.toString("utf8"));
+		if (entry === undefined) {
 			continue;
 		}
-		const item = toWindowedEntry(entry, windowId);
+		const windowId = project(entry);
+		const item =
+			head !== undefined || wanted(bytes, entry)
+				? toWindowedEntry(entry, windowId)
+				: undefined;
 		if (item !== undefined) {
 			yield item;
 		}
 	}
 }
-function sessionFiles(dir: string): string[] {
-	if (!existsSync(dir)) {
-		return [];
+/** Breadth-first, like readdirSync's recursive order, reading each level concurrently. */
+async function sessionFiles(dir: string): Promise<string[]> {
+	const files: string[] = [];
+	let level = existsSync(dir) ? [dir] : [];
+	while (level.length > 0) {
+		// Each level lists the directories the previous level found.
+		// oxlint-disable-next-line no-await-in-loop
+		const listings = await Promise.all(
+			level.map((path) => readdir(path, { withFileTypes: true })),
+		);
+		level = [];
+		for (const entry of listings.flat()) {
+			const path = join(entry.parentPath, entry.name);
+			if (entry.isDirectory()) {
+				level.push(path);
+			} else if (
+				entry.isFile() &&
+				entry.name.endsWith(".jsonl") &&
+				!entry.name.includes(".intent.")
+			) {
+				files.push(path);
+			}
+		}
 	}
-	return readdirSync(dir, { recursive: true, withFileTypes: true })
-		.filter(
-			(entry) =>
-				entry.isFile() && entry.name.endsWith(".jsonl") && !entry.name.includes(".intent."),
-		)
-		.map((entry) => join(entry.parentPath, entry.name));
+	return files;
+}
+type SessionFile = { readonly file: string; readonly size: number; readonly mtime: number };
+async function newestFirst(files: readonly string[]): Promise<SessionFile[]> {
+	const stats = await Promise.all(files.map((file) => stat(file)));
+	return files
+		.map((file, index) => ({ file, size: stats[index].size, mtime: stats[index].mtimeMs }))
+		.sort((a, b) => b.mtime - a.mtime);
+}
+/** The newest files up to FIRST_SEARCH_BYTES, then the rest. */
+function searchPhases(files: readonly SessionFile[]): readonly (readonly string[])[] {
+	let count = 0;
+	for (let bytes = 0; count < files.length && bytes < FIRST_SEARCH_BYTES; count++) {
+		bytes += files[count].size;
+	}
+	const paths = files.map(({ file }) => file);
+	return [paths.slice(0, count), paths.slice(count)];
 }
 async function sessionHeader(
 	file: string,
@@ -179,7 +300,7 @@ async function sessionHeader(
 ): Promise<{ readonly cwd?: string } | undefined> {
 	for await (const line of lfLines(file, signal)) {
 		try {
-			const value: unknown = JSON.parse(line);
+			const value: unknown = JSON.parse(line.toString("utf8"));
 			if (value === null) {
 				continue;
 			}
@@ -212,7 +333,8 @@ export type SessionScope = {
 	readonly currentFile?: string;
 	readonly signal?: AbortSignal;
 	readonly fileKey?: string;
-	readonly candidates?: (file: string) => boolean;
+	/** Raw-text needles; files without any of them are skipped. */
+	readonly needles?: readonly string[];
 };
 /** Scope memoization is owned by one enumeration; nested runs inherit their parent's project. */
 function membership(
@@ -240,25 +362,31 @@ function membership(
 	};
 	return belongs;
 }
-/** Newest modified project session files, optionally limited by file key or prefilter. */
+/** Newest modified project session files, optionally limited by file key or needles. */
 export async function* scopedSessionFiles(scope: SessionScope): AsyncGenerator<string> {
-	const files = sessionFiles(scope.dir);
+	const files = await sessionFiles(scope.dir);
 	const fileSet = new Set(files);
 	const belongs = membership(scope, (file) => fileSet.has(file));
-	const selected = files
-		.filter(
+	const selected = await newestFirst(
+		files.filter(
 			(file) =>
-				(scope.candidates === undefined || scope.candidates(resolve(file))) &&
-				(scope.fileKey === undefined ||
-					scope.fileKey.startsWith(shortKey(relative(scope.dir, file)))),
-		)
-		.map((file) => ({ file, mtime: statSync(file).mtimeMs }))
-		.sort((a, b) => b.mtime - a.mtime);
-	for (const { file } of selected) {
-		// Preserve newest-first traversal while closing each header stream before opening another.
+				scope.fileKey === undefined ||
+				scope.fileKey.startsWith(shortKey(relative(scope.dir, file))),
+		),
+	);
+	const prefilter =
+		scope.needles === undefined
+			? undefined
+			: ripgrepFilter(scope.dir, scope.needles, scope.signal);
+	for (const phase of searchPhases(selected)) {
+		// Older files are searched only when the newest ones did not satisfy the caller.
 		// oxlint-disable-next-line no-await-in-loop
-		if (await belongs(file)) {
-			yield file;
+		for (const file of prefilter === undefined ? phase : await prefilter(phase)) {
+			// Preserve newest-first traversal while closing each header stream before opening another.
+			// oxlint-disable-next-line no-await-in-loop
+			if (await belongs(file)) {
+				yield file;
+			}
 		}
 	}
 }

package/src/ui/cards.ts

@@ -9,7 +9,16 @@ import {
 	type HistorySection,
 	type PosthorseDisplay,
 } from "./display.ts";
-import { argsOf, argument, clean, hint, textBlock, textOf, type OutputColor } from "./text.ts";
+import {
+	argsOf,
+	argument,
+	clean,
+	hint,
+	leadingRows,
+	textBlock,
+	textOf,
+	type OutputColor,
+} from "./text.ts";
 
 export type ToolName = "notes" | "history" | "get_context_remaining" | "new_context";
 const titles: Readonly<Record<ToolName, string>> = {
@@ -197,45 +206,6 @@ function previewBody(facts: ResultFacts, sections: readonly HistorySection[] | u
 		: body;
 }
 
-interface ResultLayout {
-	readonly full: Component;
-	readonly summary: Component;
-	readonly preview: Component;
-	readonly submitted: Component;
-	readonly attachment: string;
-	readonly attachmentBlock: Component;
-	readonly footer: Component;
-	readonly searchPreviews: readonly string[] | undefined;
-	readonly hasDetails: boolean;
-}
-
-function resultLayout(
-	facts: ResultFacts,
-	sections: readonly HistorySection[] | undefined,
-	theme: Theme,
-): ResultLayout {
-	const color = resultColor(facts);
-	const submission = submittedText(facts);
-	const attachment = attachmentSummary(facts);
-	const { display } = facts;
-	const footerLength = display?.kind === "history-search" ? (display.footerLength ?? 0) : 0;
-	return {
-		full: fullBody(facts, sections, theme),
-		summary: textBlock(resultSummary(facts, sections), theme, color),
-		preview: textBlock(previewBody(facts, sections), theme, color),
-		submitted: textBlock(submission, theme),
-		attachment,
-		attachmentBlock: textBlock(attachment, theme, "muted"),
-		footer: textBlock(
-			sections !== undefined && footerLength > 0 ? facts.raw.slice(-footerLength) : "",
-			theme,
-			"muted",
-		),
-		searchPreviews: searchPreviews(facts, sections, theme),
-		hasDetails: sections !== undefined || submission.length > 0 || noteHeaderLength(facts) > 0,
-	};
-}
-
 function attachmentSummary(facts: ResultFacts): string {
 	if (facts.imageCount === 0) {
 		return "";
@@ -275,58 +245,83 @@ function searchPreviews(
 		: undefined;
 }
 
-function previewRows(facts: ResultFacts, layout: ResultLayout, width: number): string[] {
+type RowView = (width: number) => string[];
+
+function expandedView(
+	facts: ResultFacts,
+	sections: readonly HistorySection[] | undefined,
+	theme: Theme,
+): RowView {
+	const full = fullBody(facts, sections, theme);
+	const attachment = textBlock(attachmentSummary(facts), theme, "muted");
+	const { display } = facts;
+	const footerLength = display?.kind === "history-search" ? (display.footerLength ?? 0) : 0;
+	const footer = textBlock(
+		sections !== undefined && footerLength > 0 ? facts.raw.slice(-footerLength) : "",
+		theme,
+		"muted",
+	);
+	const submission = submittedText(facts);
+	const submitted = textBlock(submission, theme);
+	return (width) => [
+		...full.render(width),
+		...attachment.render(width),
+		...footer.render(width),
+		...(submission.length > 0 ? ["", ...submitted.render(width)] : []),
+	];
+}
+
+function previewSource(
+	facts: ResultFacts,
+	sections: readonly HistorySection[] | undefined,
+	theme: Theme,
+): (width: number) => readonly string[] {
 	if (summaryOnly(facts.display) && !facts.isError && !facts.isPartial) {
-		return [];
+		return () => [];
 	}
-	return (
-		layout.searchPreviews?.map((line) => truncateToWidth(line, width)) ??
-		layout.preview.render(width)
-	);
+	const searches = searchPreviews(facts, sections, theme);
+	if (searches !== undefined) {
+		return (width) => searches.map((line) => truncateToWidth(line, width));
+	}
+	return leadingRows(previewBody(facts, sections), theme, resultColor(facts), 3);
 }
 
-function collapsedRows(
+function collapsedView(
 	facts: ResultFacts,
-	layout: ResultLayout,
+	sections: readonly HistorySection[] | undefined,
 	theme: Theme,
-	width: number,
-): string[] {
-	const summaryRows = layout.summary.render(width).slice(0, 5);
-	const previews = previewRows(facts, layout, width);
-	const shown = previews.slice(
-		0,
-		Math.max(0, Math.min(3, 5 - summaryRows.length - (layout.attachment.length > 0 ? 1 : 0))),
-	);
-	const hidden =
-		summaryOnly(facts.display) || previews.length > shown.length || layout.hasDetails;
-	const attachments =
-		layout.attachment.length > 0
-			? [truncateToWidth(theme.fg("muted", layout.attachment), width)]
-			: [];
-	return [...summaryRows, ...shown, ...attachments, ...(hidden ? [hint(theme, width)] : [])];
+): RowView {
+	const summary = textBlock(resultSummary(facts, sections), theme, resultColor(facts));
+	const previews = previewSource(facts, sections, theme);
+	const attachment = attachmentSummary(facts);
+	const details =
+		summaryOnly(facts.display) ||
+		sections !== undefined ||
+		submittedText(facts).length > 0 ||
+		noteHeaderLength(facts) > 0;
+	return (width) => {
+		const summaryRows = summary.render(width).slice(0, 5);
+		const rows = previews(width);
+		const shown = rows.slice(
+			0,
+			Math.max(0, Math.min(3, 5 - summaryRows.length - (attachment.length > 0 ? 1 : 0))),
+		);
+		const attachments =
+			attachment.length > 0 ? [truncateToWidth(theme.fg("muted", attachment), width)] : [];
+		const hidden = details || rows.length > shown.length;
+		return [...summaryRows, ...shown, ...attachments, ...(hidden ? [hint(theme, width)] : [])];
+	};
 }
 
 function resultComponent(facts: ResultFacts, theme: Theme): Component {
 	const sections =
 		!facts.isError && !facts.isPartial ? historySections(facts.raw, facts.display) : undefined;
-	const layout = resultLayout(facts, sections, theme);
+	const render = (facts.expanded ? expandedView : collapsedView)(facts, sections, theme);
 	return {
 		invalidate() {
-			// Pi creates this presentation for each result/theme update; it keeps no width cache.
-		},
-		render(width) {
-			if (facts.expanded) {
-				const submitted =
-					submittedText(facts).length > 0 ? ["", ...layout.submitted.render(width)] : [];
-				return [
-					...layout.full.render(width),
-					...layout.attachmentBlock.render(width),
-					...layout.footer.render(width),
-					...submitted,
-				];
-			}
-			return collapsedRows(facts, layout, theme, width);
+			// Pi creates this presentation for each result, theme, and expansion update.
 		},
+		render,
 	};
 }
 

package/src/ui/text.ts

@@ -44,6 +44,44 @@ export function textBlock(text: string, theme: Theme, color: OutputColor = "tool
 	return new Text(text.length > 0 ? theme.fg(color, clean(text)) : "", 0, 0);
 }
 
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/**
+ * Rows of `textBlock(text)` wrapped only as far as a preview needs, so resizing long text stays
+ * cheap: the first `count` rows are exact, and any further row means the full text has more.
+ */
+export function leadingRows(
+	text: string,
+	theme: Theme,
+	color: OutputColor,
+	count: number,
+): (width: number) => readonly string[] {
+	// One line past `count` already wraps to more rows when the text continues.
+	const head = clean(text)
+		.split("\n", count + 1)
+		.join("\n");
+	const segments = graphemes.segment(head);
+	const wrap = (width: number): readonly string[] => {
+		for (let limit = (count + 1) * width + 1024; ; limit *= 2) {
+			// pi-tui wraps greedily by grapheme, so text cut between graphemes wraps like the
+			// whole text in every row but its last.
+			const end = segments.containing(limit)?.index ?? head.length;
+			const prefix = theme.fg(color, head.slice(0, end));
+			const rows = new Text(text.length > 0 ? prefix : "", 0, 0).render(width);
+			if (end === head.length || rows.length > count) {
+				return rows;
+			}
+		}
+	};
+	let cached: { readonly width: number; readonly rows: readonly string[] } | undefined;
+	return (width) => {
+		if (cached?.width !== width) {
+			cached = { width, rows: wrap(width) };
+		}
+		return cached.rows;
+	};
+}
+
 export function hint(theme: Theme, width: number): string {
 	const key = keyText("app.tools.expand");
 	return truncateToWidth(

package/ui.ts

@@ -1,6 +1,12 @@
 import type { ExtensionAPI, MessageRenderer } from "@earendil-works/pi-coding-agent";
-import { Box, MouseRegion, truncateToWidth, type Component } from "@earendil-works/pi-tui";
-import { clean, hint, textBlock, textOf } from "./src/ui/text.ts";
+import {
+	Box,
+	MouseRegion,
+	truncateToWidth,
+	type Component,
+	type Text,
+} from "@earendil-works/pi-tui";
+import { clean, hint, leadingRows, textBlock, textOf } from "./src/ui/text.ts";
 
 export type { PosthorseDisplay } from "./src/ui/display.ts";
 export { toolCards } from "./src/ui/cards.ts";
@@ -27,12 +33,13 @@ export function registerPosthorseMessages(pi: ExtensionAPI): void {
 		const preview = window
 			? raw.slice(handoffAt < 0 ? raw.length : handoffAt + handoffLabel.length)
 			: raw;
-		const fullText = textBlock(raw, theme);
-		const previewText = textBlock(preview, theme);
+		const previewRows = window ? 2 : 3;
+		const previewText = leadingRows(preview, theme, "toolOutput", previewRows);
+		let fullText: Text | undefined;
 		const historyText = textBlock("Earlier conversation remains in history.", theme, "muted");
 		const content: Component = {
 			invalidate() {
-				// Message layout is recomputed for the supplied width without cached rows.
+				// Pi calls the renderer again on invalidation, so cached rows never outlive a theme.
 			},
 			render(width) {
 				const padding = Math.min(
@@ -46,10 +53,10 @@ export function registerPosthorseMessages(pi: ExtensionAPI): void {
 					inner,
 				);
 				const body = view.expanded
-					? fullText.render(inner)
+					? (fullText ??= textBlock(raw, theme)).render(inner)
 					: [
 							...(window ? historyText.render(inner).slice(0, 2) : []),
-							...previewText.render(inner).slice(0, window ? 2 : 3),
+							...previewText(inner).slice(0, previewRows),
 							hint(theme, inner),
 						];
 				const box = new Box(padding, 1, (line) => theme.bg("customMessageBg", line));