@astrosheep/pi-context 0.25.1 → 0.26.0

package/docs/reset-lifecycle.md

@@ -1,83 +1,67 @@
 # Reset lifecycle
 
-`src/context/reset-lifecycle.ts` owns reset requests, turn-end batching, recovery, and continuation. It is the sole `turn_end` composer: incoming drafts, budget drafts, and reset drafts are ordered here. `src/context/budget.ts` owns the default-path instance-local policy cache, resolves injected policy live, stages guidance/warning drafts, and keeps the final warning text in the budget/protocol path; `src/context/thresholds.ts` only reads settings and derives values, using the shared merge in `src/settings.ts`. `src/index.ts` is the thin public entrypoint; `src/context/runtime.ts` composes the runtime hooks and constructs marker/boot boundaries. `src/notes/notes-snapshot.ts` acquires the notes snapshot, while `src/context/prompts.ts` only renders the explicit boot data and low-budget reminder. Projections and tools have separate modules described in [Architecture](architecture.md).
+`src/context/reset-lifecycle.ts` owns the close-out request phases, turn-end batching, bounded overflow recovery, and reset scheduling. `src/context/budget.ts` owns budget policy and stages the early reminder/final warning; `src/context/reset-artifacts.ts` builds the checkpoint, marker, boot, and continuation drafts; `src/context/context-window.ts` validates and projects the active window. `src/context/runtime.ts` wires these parts to Pi's public lifecycle hooks and `/wipe-memory` command.
 
-| Event | Transition / owner |
+## Lifecycle at a glance
+
+| Trigger | Behavior |
 | --- | --- |
-| `wipe_memory` | Record an explicit reset request. Repeated calls in one tool batch deduplicate; the tool returns terminal output. |
-| `turn_end` | The sole composer drains current-window budget drafts after the event entries, then appends reset drafts: one `pi-context/reset-marker` with `{ windowId }`, one hidden boot message with matching `details.windowId`, and the continuation marker; continue the turn through Pi's public queue. |
-| Abort before the boundary | Drop the pending boundary. Never manufacture a continuation for an aborted turn. |
-| Threshold / provider overflow | Request the same marker/boot boundary for the active provider window. Actual overflow/length recovery retries at most once per failure chain; ordinary retryable provider errors stay Pi-owned. |
-| `/wipe-memory` | Wait for idle, append marker and boot through public session APIs, and do not call a model. |
-| `/compact` while enabled | Cancel with an actionable `/wipe-memory` notice so native compaction cannot summarize erased canonical history back into the active window. |
-| Startup / tree / partial append | Repair only a marker followed by an otherwise empty metadata tail; refuse hidden/absent boots once later work exists, leaving `/wipe-memory` as the explicit recovery path. Do not interpret legacy reset-v2 details. |
-| `/pi-context off` | Stop new automatic resets, but retain the boundary of an existing marker. Marked branches still cancel native compaction; a fresh root may use Pi's native semantics. |
-
-## Reset-control state machine
-
-`registerResetLifecycle` is the effect adapter. `reduceResetControl` in `src/context/reset-lifecycle.ts` is the pure transition surface: given the current state and one lifecycle event it returns the next state and one named effect, performing no writes, policy resolution, or UI work of its own. The adapter captures Pi's events, supplies the guards only in the branches that consult them, then performs the marker/boot/continuation writes, continuation requests, and notices.
-
-State is a single value with two explicitly typed axes. There are no independently combinable lifecycle booleans.
-
-| Axis | Value | Meaning |
-| --- | --- | --- |
-| `request` | `none` | no explicit wipe request pending |
-| | `explicit` | one explicit request is pending and will commit at the next `turn_end` |
-| `overflow` | `idle` | no overflow failure pending; a future recovery is available |
-| | `pending` | active-provider overflow failure pending; recovery still available |
-| | `pending-spent` | overflow failure pending, but its one recovery was already spent |
-| | `spent` | recovery spent and the failure is no longer pending |
-
-All eight combinations of the two axes are reachable and each has a defined transition.
-
-| Event | Guard | Next state | Effect |
-| --- | --- | --- | --- |
-| `request` | `request=none` | `request=explicit`, overflow unchanged | `requested` |
-| `request` | `request=explicit` | unchanged | `already-requested` |
-| `turn_end` | turn aborted | `(request=none, overflow=idle)` | `none` |
-| `turn_end` | overflow-like and `!queued && enabled && automaticResetEnabled` | `request=none`; overflow `pending`, or `pending-spent` if already spent | `none` |
-| `turn_end` | overflow-like and (`queued \|\| !enabled \|\| !automaticResetEnabled`) | `request=none`; overflow `idle`, or `spent` if already spent | `none` |
-| `turn_end` | completed, `enabled`, and (`explicit` requested or `thresholdDue`) | `(request=none, overflow=idle)` | `commit-boundary` |
-| `turn_end` | completed, `enabled`, but neither trigger | `(request=none, overflow=idle)` | `none` |
-| `turn_end` | non-overflow `failed` | `request=none`; overflow unchanged | `none` |
-| `turn_end` | `!enabled` | `request=none`; completed clears overflow, error keeps it | `none` |
-| `before_settle` | `overflow=pending`, not queued, `enabled`, `automaticResetEnabled`, not aborted | `overflow=spent` | `recover-overflow` |
-| `before_settle` | `overflow=pending-spent` | `overflow=spent` | `none` |
-| `before_settle` | `overflow` not pending, or queued | unchanged | `none` |
-| `before_settle` | pending but `!enabled`, `!automaticResetEnabled`, or aborted | disarms to `idle` (`spent` if already spent) | `none` |
-| `settled` | — | `overflow=idle`; `request` unchanged | `none` |
-| `abort` / `clear` | — | `(request=none, overflow=idle)` | `none` |
-
-### Invariants
-
-1. At most one explicit request is pending at a time; duplicate requests in one tool batch dedupe and never queue a second boundary.
-2. Every `turn_end` consumes a pending explicit request, whether or not that turn commits a reset.
-3. A committed reset is exactly `marker -> boot -> continuation`, and ordinary and budget drafts are ordered before the marker. Budget staging is drained once per turn and discarded on abort or disabled mode.
-4. Reset drafts are built once per commit. If construction throws, already-built incoming and budget drafts survive and no continuation is requested.
-5. Overflow recovery is one attempt per failure chain: a failure arms `pending` only when nothing is queued, the extension is enabled, and automatic reset is enabled; a settle spends it to `spent`; a later failure becomes `pending-spent` and cannot recover again until settlement ends the chain.
-6. Aborted turns never manufacture a continuation and clear both axes. Non-overflow errors keep the armed overflow chain for the settle boundary.
-7. A successful non-overflow turn clears the overflow chain first, so a queued success supersedes a stale overflow failure before settle recovery can act.
-8. `settled` ends the failure chain but preserves a pending explicit request; `clear` (session start, tree navigation, shutdown, `/pi-context off`, `/wipe-memory`) resets both axes.
-9. Disabled mode never commits a reset and never arms or spends overflow recovery; an existing persisted marker stays authoritative for native-compaction cancellation.
-10. Policy guards (`queued`, `automaticResetEnabled`, `thresholdDue`) are consulted only in the branch that needs them, preserving the adapter's original resolution order.
-
-### Critical sequences
-
-- **Normal reset.** A completed, enabled turn whose explicit request is pending or whose usage is due returns `commit-boundary`. The adapter drains budget drafts, keeps incoming drafts in order, appends `marker -> boot -> continuation`, and requests continuation. A second request in the same batch returns `already-requested`; the next turn commits it alone.
-- **Overflow recovery.** An overflow-like `turn_end` with no queued message, enabled mode, and automatic reset arms `pending`; a `before_settle` with no queued message returns `recover-overflow` and spends the attempt to `spent`. A repeated settle is a no-op, and a later overflow failure re-arms only `pending-spent`.
-- **Abort.** An aborted `turn_end` returns only the drafts already collected for that boundary, clears both axes, and never appends reset drafts.
-- **Queued success.** A queued message defers `before_settle`; the queued turn's successful `turn_end` clears the stale overflow chain, so no recovery fires.
-- **Process interruption.** If Pi stops between the marker and the later reset messages, the marker remains the authoritative boundary. On the next start, startup repair may append only the missing boot and continuation when the tail is otherwise repairable; it never moves or reinterprets the boundary.
-- **Startup tail repair.** On `session_start` / `session_tree`, `ensureBoot` asks `repairResetTail` to inspect the marker tail and emit only the missing artifacts in the closed order: the boot, then the continuation. A boot/continuation sequence that is already complete, or a tail containing real conversation, a foreign message, a later marker, or a misordered/duplicate artifact, refuses repair and leaves `/wipe-memory` as the explicit recovery path.
-
-The budget owner stages the early guidance and final checkpoint warning from active-window usage. The warning is visible in the current provider request, while both drafts are committed only by the lifecycle composer and are discarded on abort, settlement without a `turn_end`, transition, or window mismatch. After the warning, the model either writes its note and calls `wipe_memory`, or runtime recovery requests the same marker/boot boundary. Guidance and warning drafts precede reset drafts so stale reminders cannot be queued into the new window; durable entries remain the authority for redelivery. Their UI notices are emitted at the next turn start or settlement only after the matching reminder is committed in the active window, so aborted requests and retries cannot repeat an uncommitted reminder's notification.
-
-The turn-end commit is the scheduling boundary: Pi receives the finished tool batch and then the marker/boot drafts as one append operation. Pi owns queue scheduling and deduplication of the next request; the extension does not run a parallel compaction state machine or use a compaction completion callback.
-
-Boot construction reads the five note homes into one closed snapshot before rendering the hidden boot. An absent home is empty; a real read failure removes only that home's MAP/pocket rows. The boot retains its identity, reset line, notes-home instructions, and recovery protocol, and includes a concise `notes_list` retry notice. The human receives one incomplete-index notification per boot. This notes failure isolation does not bypass the marker/boot commit, alter raw history, or turn a partial boot into an empty fallback.
-
-The hidden boot is selected by its durable `details.windowId`, not by timestamp or content equality. The context hook folds only the dropped system prefix before that boot and preserves later prompt patches and messages in order. If the boot is missing, the hook aborts with a safe head and notice rather than sending raw history. Startup/tree repair is deliberately narrow: it appends a boot only when the marker tail is otherwise incomplete metadata; later conversation or an authoritative raw boot causes safe refusal. `/wipe-memory` is the recovery path for that refused branch. A fork/clone creates a new session ID while copying branch entries, so startup refreshes the root boot identity while retaining copied root messages.
-
-Public APIs let a mixed tool batch finish before the marker/boot boundary. Queued steering/follow-up messages are delivered exactly once in the new window, neither dropped nor replayed. `/tree` navigation remains available, but when either source or destination branch contains a reset marker, Pi's raw summary generator is bypassed: the summary is empty and a notice explains why, preventing erased history from re-entering through a path outside the context hook. With no marker on either branch, native summaries remain unchanged.
-
-Validation uses a reduced set of persisted-data integration tests, isolated lifecycle event tests, and scripted SDK tests running Pi's actual agent loop. Representative cases check reset-window history retention, resumable reads, native-compaction cancellation, mixed-tool completion, steering/follow-up delivery, bounded overflow recovery, and settings authority. Tree-summary suppression no longer has a dedicated retained test. The separate coherence and pagination property suites have been removed; the retained cases do not cover the previous full matrix of branch, cancellation, malformed-input, and pagination edges.
+| `wipe_memory` tool | Mark the current window tool-requested. At `turn_end`, after the complete tool batch and any accepted budget drafts, append the reset boundary and ask Pi to continue. Repeated requests for that window deduplicate. |
+| `/wipe-memory` | Capture the current window, wait for idle, and stop if another invocation has already moved the branch to a new window. Arm a manual close-out, persist the shared hidden warning, and trigger an ordinary model turn. The agent can write notes/use tools over several turns. A `wipe_memory` call commits at `turn_end`; otherwise a successful normal stop commits at `agent_before_settle` after queued messages drain. |
+| Budget warning | When automatic compaction is enabled and remaining active-window budget reaches reserve plus the warning runway, put the same hidden warning in the request and arm an automatic close-out. An explicit `wipe_memory` commits the boundary; a successful normal stop is the fallback. |
+| Hard reserve | Independent safety path: if automatic resets are enabled and completed-turn usage reaches Pi's reserve, commit a boundary at `turn_end`. |
+| Abort or error | Never count as successful close-out. Abort clears lifecycle state. An ordinary close-out error is dropped without reset; provider-overflow recovery remains separately bounded. |
+| `/compact` while active | Cancel native compaction, which could otherwise summarize pre-reset history back into the active window. A manual attempt receives an actionable `/wipe-memory` notice. |
+
+A new boundary is ordered as:
+
+1. A native `compaction` entry with `summary: ""` and `firstKeptEntryId` set to its own ID. This is Pi's retain-none canonical checkpoint; it is not a generated summary request.
+2. A `pi-context/reset-marker` custom entry with `{ windowId }`.
+3. A hidden `pi-context/boot` custom message with matching `details.windowId`.
+4. A hidden continuation message.
+
+The raw session branch is preserved for history. New checkpoint-backed branches use Pi's canonical retain-none projection, which preserves the empty summary wrapper and system/tool state while excluding earlier conversational context. Older marker-only sessions use marker slicing as a narrow compatibility fallback. A marker is trusted as checkpoint-backed only when it directly follows an empty native compaction whose `firstKeptEntryId` is the compaction's own ID; a generic preceding compaction is not enough.
+
+`turn_end` is the sole composer for completed turns. It preserves incoming entries, consumes current-window budget drafts, and appends the ordered reset boundary only when the reducer requests one. `agent_before_settle` handles successful close-out fallback after Pi has drained queued work. Pi owns the ensuing continuation and request scheduling. Reset construction awaits the asynchronous notes snapshot; the handler captures its session/window generation before awaiting, then rechecks generation, session, window, enabled state, and abort status before returning drafts. A stale completion is discarded while incoming/budget entries survive, and success notices are staged only after that guard. Construction failures notify only while the initiating lifecycle is still current and preserve already-collected entries without claiming a continuation.
+
+## Reducer state
+
+`reduceResetControl` is pure: the adapter supplies all lifecycle facts, and the reducer returns the next state plus a named effect. Its state combines a request phase with a bounded overflow phase:
+
+| State | Meaning |
+| --- | --- |
+| `{ phase: "none" }` | No close-out/tool request is pending. |
+| `{ phase: "close-out", windowId, source }` | Manual or automatic warning close-out remains armed across ordinary note/tool turns. |
+| `{ phase: "tool-requested", windowId }` | A direct `wipe_memory` request will commit after its complete turn batch. |
+| `overflow: "idle"` | No overflow recovery is pending. |
+| `overflow: "pending"` | An overflow failure may recover once at pre-settlement. |
+| `overflow: "pending-spent"` | Recovery was already spent in this failure chain. |
+| `overflow: "spent"` | The one recovery has been used until the chain settles. |
+
+### Transition rules
+
+- `close_out(windowId, source)` arms a close-out for that window. Repeating an already-pending request deduplicates; a manual request can upgrade an automatic request for the same window.
+- `tool_request(windowId)` marks that window for a turn-end reset. A matching duplicate is reported as already pending.
+- `turn_end` first clears everything on abort. Overflow-like errors disarm the reset request and arm overflow recovery only when there is no queued work, the extension is enabled, and automatic reset is enabled. Other failures drop the request but preserve the overflow chain. A successful, enabled turn commits for a tool request or hard-reserve condition; a close-out alone remains armed.
+- `agent_before_settle` clears state on actual abort. Pending overflow recovery gets its one bounded attempt when enabled and unqueued. Otherwise a close-out commits only if the outcome is successful, the request belongs to the current window, the extension is enabled, and no queued work remains. Automatic close-outs also require automatic resets to remain enabled.
+- `agent_settled`, session start/tree navigation/shutdown, `/pi-context off`, and abort clear transient request state. Durable checkpoint/marker history remains authoritative after transient state is gone.
+
+This separation is intentional: a note write or ordinary tool turn during a close-out must not consume it. Direct `wipe_memory` is not armed by the shared warning and remains valid without one. A user abort, an assistant message with a synthetic `stopReason: "aborted"`, and a generic provider error are distinct cases; none commits an ordinary close-out, while only Pi's actual operation cancellation is a user abort.
+
+## Budget staging and notifications
+
+The early reminder is staged once per window when remaining budget reaches `reserve + reminderMarginTokens`. The final close-out warning is staged/attached at `reserve + WARNING_RUNWAY_TOKENS`, only when automatic compaction is enabled. The hard reserve itself remains a separate safety cutoff. The warning text is shared with `/wipe-memory`; after it is durable, the extension does not repeat it in that window. Warning persistence deduplicates only injection: each eligible low-budget request re-arms transient automatic close-out before checking for the durable warning, so an abort/error can clear its attempt and the next request can retry without another warning.
+
+Budget drafts are instance-local and are consumed at turn end. They are discarded on abort, failed turn, transition, or window mismatch. UI reminder notices are emitted only after the matching hidden entry is durable, so failed requests do not report an uncommitted warning. Active-window usage and the exact `SettingsManager` authority drive threshold checks; default file-backed policy is cached per extension instance, while injected managers are read through their public API.
+
+## Projection, repair, and history
+
+`context_with_system` selects the active boot by durable `details.windowId`. For a verified native checkpoint, Pi's canonical projection is used directly; for a legacy marker-only reset, the compatibility projection slices at the matching boot. The projection preserves system/tool state and later prompt patches. If the boot is absent, the runtime aborts safely instead of sending raw history. Usage estimation uses the same checkpoint-aware projection decision.
+
+Startup/tree repair is narrow: it may complete a repairable marker tail when later conversation does not make the missing metadata ambiguous. It awaits the notes snapshot and rechecks lifecycle/window identity before sending a repaired boot or continuation. Legacy marker-only tails remain supported; repair never moves a boundary or promotes an arbitrary compaction to a retain-none checkpoint. `/tree` summary generation is suppressed with an empty summary when either branch crosses a reset, because the raw summary generator bypasses the provider projection.
+
+## Validation and known limits
+
+The test suite combines isolated reducer tests with scripted SDK tests executing Pi's real agent loop without model/network calls. The agent-loop coverage includes manual warning plus multi-turn note writes and explicit wipe, direct wipe without warning, normal-stop fallback, same-window concurrent command deduplication, actual and synthetic abort/error cleanup, queued steering/follow-up delivery, hard-reserve and bounded-overflow recovery, successive resets, and real SessionManager file reopen after two retain-none checkpoints. It also checks raw-history preservation, canonical projection, empty-summary retention, system/tool state, warning/marker order, and fresh-window continuation.
+
+The broader coherence and pagination property suites were removed during test reduction; retained cases are representative rather than exhaustive. Tree-summary suppression has no dedicated retained test, and external-provider behavior, every malformed persisted shape, and every filesystem failure mode are not established by this suite.

package/package.json

@@ -1,7 +1,24 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./notes": {
+      "types": "./dist/src/notes/index.d.ts",
+      "import": "./dist/src/notes/index.js"
+    },
+    "./dist/src/index.js": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "description": "Codex-style context windows for Pi: durable reset windows, session history tools, and persistent notes.",
   "license": "MIT",
   "keywords": [
@@ -16,6 +33,9 @@
   "pi": {
     "extensions": [
       "./dist/extension.js"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "files": [
@@ -24,7 +44,8 @@
     "docs",
     "LICENSE",
     "README.md",
-    "playbook.md"
+    "playbook.md",
+    "skills"
   ],
   "bin": {
     "dream": "dist/src/dream/cli.js"
@@ -33,6 +54,7 @@
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node scripts/build-extension.mjs && node -e \"require('node:fs').chmodSync('dist/src/dream/cli.js', 0o755)\"",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test dist/test/*.test.js",
+    "test:notes-package": "npm run build && node scripts/check-notes-package.mjs",
     "prepublishOnly": "npm run typecheck",
     "prepack": "npm run build"
   },
@@ -41,6 +63,17 @@
     "@earendil-works/pi-ai": "^0.87.0",
     "@earendil-works/pi-coding-agent": "^0.87.0"
   },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.87.0",
     "@earendil-works/pi-ai": "^0.87.0",

package/playbook.md

@@ -1,32 +1,33 @@
-I am dreaming over my notes. They are plain markdown files in three homes, addressed as:
-
-- bare `<vpath>` for this session
-- `@project/<vpath>` for this project
-- `@personal/<vpath>` for personal notes
-
-Every note has this frontmatter block:
-
-```yaml
----
-origin: user | self | external
-status: active
-stale: false
-created_at: <timestamp>
-updated_at: <timestamp>
-last_accessed: <timestamp>
-access_count: 0
----
-```
-
-## Dream rules
-
-1. **Probe before you trust.** Before keeping or promoting a note, verify its world referents with read-only file tools: paths in the body — do they still exist? branches — still present? Dead referents are why a note gets merged away or marked stale, never promoted.
-2. **Merge threshold.** Supersede another note only when all three hold: same topic (name it in the survivor's body), same kind of note (checkpoint/design/log…), and the survivor is strictly newer or strictly more specific. Otherwise keep both and record the open conflict in the survivor.
-3. **Size budget.** Keep every note under ~200 lines / ~8KB. Oversized notes get split by topic with a one-line cross-link in each (`see also: @home/<vpath>`). Checkpoints may exceed the budget — trim prose, never facts.
-4. **Keep the maps.** Each home's `MAP.md` maps that home's durable notes: one line per entry — its address and a short gist in your own words, never a mechanical body slice. Project notes go on `@project/MAP.md`, cross-project knowledge on `@personal/MAP.md`; session notes are never mapped — the pocket covers them. When a note is promoted across homes, move its line to the destination map; when a note goes stale, drop its line. Maps obey the same size budget as any note.
-5. **Jurisdiction.** Read the whole store, including every session home, to extract durable knowledge. `pi/session/**` is a live agent's write-ahead log: never write or edit anything there, including frontmatter or stale markers. Promote useful facts by writing to project or personal instead. Other notes are never physically deleted and every run is bracketed by git commits, so the human gate can audit and revert whatever you touch. Group your report by home so the gate can see what moved. In writable homes: map entry lines are yours to maintain, but prose that carries rules or guidance is not — flag it in your report instead of rewriting it.
-6. **Leave stable notes alone.** Change notes to incorporate new evidence, resolve verified errors, merge genuine duplicates, or split oversized files—not merely to shorten or rephrase them. Preserve facts, conditions, exceptions, and uncertainty. No change is a valid outcome.
-
-Read the files and merge genuinely duplicate notes in writable homes by editing the survivor, then set `stale: true` in the absorbed note's frontmatter if it is writable. Session notes remain untouched even when promoted; record their source in the destination. Nothing is physically deleted; stale notes remain readable. Promote durable cross-project knowledge by writing or editing at `@personal/<vpath>`. Keep notes compact and preserve useful provenance in the body.
-
-Do not write skill ideas as files. Put skill ideas and unresolved questions in your final assistant message as proposals for the human. Your final message should be a concise report of what you inspected, changed, and left unresolved. If you made no file writes, say so.
+# Dream
+
+I am reviewing my notes: keeping what is useful, connecting what belongs together, and leaving a clearer record for whoever comes next. Notes are record, not memory.
+
+## Scope
+
+Work within the readable sources and writable homes established for this run. Do not broaden that scope while exploring. If a boundary is unclear, ask before crossing it.
+
+A project dream draws from that project's material, project notes, and session notes identified as belonging to the project; it organizes only that project's notes. A store-wide dream may inspect across homes, but authorship and write permissions still apply. Unknown ownership is a coverage gap to report, not a reason to guess or repair ownership.
+
+The homes serve different readers:
+
+- Session notes are a trip's working record. Read them as sources where permitted; never edit them, even after promoting a useful finding.
+- Project notes hold knowledge for whoever next works on that project.
+- Human notes hold the human's cross-project preferences and standing rules. Do not turn project facts or your own lessons into rules in the human's voice.
+- Agent notes belong to their author. Other agents' notes are read-only unless the human authorizes revision.
+- Model notes describe the substrate's behavior. Other models' notes are read-only unless the human authorizes revision.
+
+## Review and consolidate
+
+1. **Leave stable notes alone.** Change a note to incorporate new evidence, resolve a verified error, merge a genuine duplicate, or split an oversized file—not merely to shorten or rephrase it. No change is a valid outcome.
+2. **Verify only what the proposed change depends on.** Before correcting or promoting a conclusion, check the relevant evidence as needed. Do not revalidate every stable note or turn dream into a source-code audit. An unavailable referent is unverified, not proof that it is dead; do not promote an unsupported claim as current fact.
+3. **Merge only genuine duplicates.** Supersede a note only when both notes have the same topic and kind (checkpoint, design, log…), and the survivor is strictly newer or more specific. Name the shared topic in the survivor. Otherwise keep both and record any unresolved conflict.
+4. **Preserve meaning and provenance.** Keep facts, conditions, exceptions, uncertainty, authorship, and sources. When promoting a finding, cite its source. Do not relabel agent-authored material as human-authored. If its destination or authority is unclear, propose the promotion instead.
+5. **Keep notes manageable.** Aim below about 200 lines / 8KB per note. Split oversized notes by topic with one-line cross-links. Checkpoints may exceed the budget: trim prose, never facts.
+6. **Keep maps useful.** Each writable home's MAP.md lists its durable notes, one line per entry, with an unambiguous address and a short gist in your own words. Add promoted notes and drop stale entries. Session notes are never mapped. Maps follow the same size budget.
+7. **Preserve the record.** Never physically delete notes. After merging, mark the absorbed note stale only if it is writable. Preserve existing metadata and provenance. Map entry lines are yours to maintain within the writable scope.
+
+## Report
+
+Give a concise report grouped by home: what you inspected, changed, promoted, and left unresolved. Mention coverage gaps and partial failures. If no notes changed, say so. Distinguish actual note changes from execution or audit artifacts; do not claim success for an incomplete run.
+
+Put skill ideas and unresolved questions in the final message as proposals for the human, not new skill files.

package/skills/dream/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: dream
+description: Review and consolidate durable notes using pi-context's shared dream playbook. Use when the human asks to dream over notes, merge genuine duplicates, update maps, or promote durable learning.
+---
+
+# Dream
+
+Read `../../playbook.md` completely, resolving the path from this skill's directory. It is the shared guide to reviewing and organizing notes.
+
+Dream in this agent's current session. Do not start another agent or model unless the human asks.
+
+Work within the supplied readable and writable scope. If the scope or permission to write has not been established, ask rather than inventing it or setting up execution machinery yourself.

package/src/context/boot.ts

@@ -1,9 +1,9 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { loadNotesSnapshot, type NotesSnapshot } from "../notes/notes-snapshot.js";
-import { agentSlug, modelSlug } from "../notes/paths.js";
+import { notesContextFromPi } from "../pi/notes/adapter.js";
+import { loadNotesSnapshot, type NotesSnapshot } from "../pi/notes/snapshot.js";
 import { BOOT_TYPE } from "../protocol.js";
 import { renderBootBlock } from "./prompts.js";
-import { currentReset, isWindowBoot, rootWindowId } from "./context-window.js";
+import { currentReset, currentWindowId, isWindowBoot, rootWindowId } from "./context-window.js";
 import { repairResetTail } from "./reset-artifacts.js";
 
 export type IncompleteNotesNotifier = (ctx: ExtensionContext, windowId: string, snapshot: NotesSnapshot) => void;
@@ -16,31 +16,38 @@ export type BootMessage = {
 	readonly details: { windowId: string };
 };
 
-/** Render the boot block from the live context; acquisition stays with loadNotesSnapshot. */
-function bootContent(ctx: ExtensionContext, currentId: string, previousId: string | undefined, notes: NotesSnapshot): string {
-	return renderBootBlock({
-		agentName: agentSlug(ctx),
-		modelName: modelSlug(ctx),
-		firstWindowId: rootWindowId(ctx.sessionManager.getSessionId()),
-		currentWindowId: currentId,
-		previousWindowId: previousId,
-		notes,
-	});
+/** Render the boot block from one pre-await identity and acquired notes snapshot. */
+function bootContent(
+	agentName: string,
+	modelName: string,
+	firstWindowId: string,
+	currentId: string,
+	previousId: string | undefined,
+	notes: NotesSnapshot,
+): string {
+	return renderBootBlock({ agentName, modelName, firstWindowId, currentWindowId: currentId, previousWindowId: previousId, notes });
 }
 
 /**
- * Acquire one notes snapshot and build the boot custom message for a window. The caller
- * supplies `previousId` only when a reset boundary needs the prior window identity.
+ * Acquire one notes snapshot and build the boot custom message for a window. All identity
+ * fields are captured synchronously before the first filesystem await.
  */
-export function buildBootMessage(
+export async function buildBootMessage(
 	ctx: ExtensionContext,
 	windowId: string,
 	previousId: string | undefined,
 	notifyIncompleteNotes?: IncompleteNotesNotifier,
-): BootMessage {
-	const notes = loadNotesSnapshot(ctx);
-	notifyIncompleteNotes?.(ctx, windowId, notes);
-	return { customType: BOOT_TYPE, content: bootContent(ctx, windowId, previousId, notes), display: false, details: { windowId } };
+	isCurrent: () => boolean = () => true,
+): Promise<BootMessage> {
+	const identity = notesContextFromPi(ctx);
+	const notes = await loadNotesSnapshot(ctx, undefined, identity);
+	if (isCurrent()) notifyIncompleteNotes?.(ctx, windowId, notes);
+	return {
+		customType: BOOT_TYPE,
+		content: bootContent(identity.agent, identity.model, rootWindowId(identity.sessionId), windowId, previousId, notes),
+		display: false,
+		details: { windowId },
+	};
 }
 
 /** Persist one hidden boot message without triggering a model turn. */
@@ -54,15 +61,27 @@ export function sendBoot(pi: ExtensionAPI, boot: BootMessage): void {
 /**
  * Boot entry point for `session_start` / `session_tree`. Ordinary startup ensures one root
  * boot; a reset marker instead asks reset-artifact repair to complete its persisted tail.
- * Boot idempotence lives here: an already-projected root boot or a complete reset tail emits nothing.
  */
-export function ensureBoot(pi: ExtensionAPI, ctx: ExtensionContext, notifyIncompleteNotes?: IncompleteNotesNotifier): void {
+export async function ensureBoot(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	notifyIncompleteNotes?: IncompleteNotesNotifier,
+	isCurrent: () => boolean = () => true,
+): Promise<void> {
+	const sessionId = ctx.sessionManager.getSessionId();
 	const reset = currentReset(ctx);
+	const windowId = reset?.data.windowId ?? rootWindowId(sessionId);
+	const stillCurrent = () => isCurrent() &&
+		ctx.signal?.aborted !== true &&
+		ctx.sessionManager.getSessionId() === sessionId &&
+		currentWindowId(ctx) === windowId;
 	if (reset) {
-		repairResetTail(pi, ctx, reset, notifyIncompleteNotes);
+		await repairResetTail(pi, ctx, reset, notifyIncompleteNotes, stillCurrent);
 		return;
 	}
-	const windowId = rootWindowId(ctx.sessionManager.getSessionId());
 	if (ctx.sessionManager.buildSessionProjection().messages.some((message) => isWindowBoot(message, windowId))) return;
-	sendBoot(pi, buildBootMessage(ctx, windowId, undefined, notifyIncompleteNotes));
+	const boot = await buildBootMessage(ctx, windowId, undefined, notifyIncompleteNotes, stillCurrent);
+	if (!stillCurrent()) return;
+	if (ctx.sessionManager.buildSessionProjection().messages.some((message) => isWindowBoot(message, windowId))) return;
+	sendBoot(pi, boot);
 }

package/src/context/budget.ts

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI, type ExtensionContext, type SessionBoundaryDraft, type SettingsManager } from "@earendil-works/pi-coding-agent";
-import { GUIDANCE_CLOSE_TAG, GUIDANCE_OPEN_TAG, GUIDANCE_TYPE, WARNING_PROMPT, WARNING_TYPE } from "../protocol.js";
+import { GUIDANCE_TYPE, WARNING_CONTENT, WARNING_TYPE } from "../protocol.js";
 import { readThresholdSettings, type ResolvedThresholds, type ThresholdSettingsResolution } from "./thresholds.js";
 import { currentWindowId, hasWindowMessage, windowUsage } from "./context-window.js";
 import { tokenBudgetGuidance } from "./prompts.js";
@@ -12,7 +12,12 @@ export function remainingTokens(ctx: Pick<ExtensionContext, "sessionManager" | "
 	return !usage || usage.tokens === null ? null : Math.max(0, usage.contextWindow - usage.tokens);
 }
 
-export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, settingsManager?: SettingsManager) {
+export function registerBudget(
+	pi: ExtensionAPI,
+	isEnabled: () => boolean,
+	settingsManager?: SettingsManager,
+	onCloseOut: (windowId: string) => void = () => {},
+) {
 	let cachedPolicy: { thresholds: ResolvedThresholds; automatic: boolean } | undefined;
 	const notifiedWarnings = new Set<string>();
 	const resolvePolicy = (ctx: ExtensionContext): ThresholdSettingsResolution => {
@@ -32,22 +37,22 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, setti
 	const automaticResetEnabled = (ctx: ExtensionContext): boolean => {
 		return resolvePolicy(ctx).automatic;
 	};
-	const resetDue = (ctx: ExtensionContext): boolean => {
+	const hardReserveDue = (ctx: ExtensionContext): boolean => {
 		if (!automaticResetEnabled(ctx)) return false;
 		const usage = windowUsage(ctx);
 		return usage !== undefined && usage.tokens !== null && usage.contextWindow - usage.tokens <= thresholdsFor(ctx).reserve;
 	};
 	const invalidateThresholds = () => { cachedPolicy = undefined; };
-	let pendingGuidance: { windowId: string; content: string } | undefined;
-	let pendingWarning: { windowId: string; content: string } | undefined;
-	let pendingNotices: Array<{ windowId: string; customType: string }> = [];
+	let pendingGuidance: { windowId: string; content: string; remaining: number } | undefined;
+	let pendingWarning: { windowId: string; content: string; remaining: number } | undefined;
+	let pendingNotices: Array<{ windowId: string; customType: string; remaining: number }> = [];
 	const notifyCommittedReminders = (ctx: ExtensionContext) => {
 		const windowId = currentWindowId(ctx);
 		for (const notice of pendingNotices) {
 			if (notice.windowId !== windowId || !hasWindowMessage(ctx, notice.customType)) continue;
 			ctx.ui.notify(notice.customType === WARNING_TYPE
-				? "pi-context: context budget critical — final checkpoint warning recorded for the model."
-				: "pi-context: context budget low — checkpoint reminder recorded for the model, kept out of the chat view.", "warning");
+				? "pi-context: Context almost full; close out the current memory window."
+				: "pi-context: Context running low; checkpoint your notes soon.", "warning");
 		}
 		pendingNotices = [];
 	};
@@ -71,7 +76,7 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, setti
 		clearStaged();
 		const windowId = currentWindowId(ctx);
 		const drafts = staged.filter((draft): draft is NonNullable<typeof draft> => draft !== undefined && draft.windowId === windowId);
-		pendingNotices = drafts.map(({ windowId, customType }) => ({ windowId, customType }));
+		pendingNotices = drafts.map(({ windowId, customType, remaining }) => ({ windowId, customType, remaining }));
 		return drafts.map((draft) => ({
 			type: "custom_message" as const,
 			customType: draft.customType,
@@ -88,7 +93,6 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, setti
 	// lifecycle point that must discard an uncommitted draft before the next prompt.
 	// UI notices follow committed reminders. Aborted requests can retry their drafts
 	// without showing the same low-budget notification twice.
-	pi.on("turn_start", (_event, ctx) => notifyCommittedReminders(ctx));
 	pi.on("agent_settled", (_event, ctx) => {
 		notifyCommittedReminders(ctx);
 		clearStaged();
@@ -101,12 +105,15 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, setti
 		if (remaining === null) return undefined;
 		const windowId = currentWindowId(ctx);
 		const { reminder, warning } = thresholdsFor(ctx);
-		if (hasWindowMessage(ctx, WARNING_TYPE) || pendingWarning?.windowId === windowId) return undefined;
-		if (remaining <= warning) {
-			// A not-yet-committed shallow reminder is superseded by the final warning.
+		if (remaining <= warning && automaticResetEnabled(ctx)) {
+			// Re-arm close-out on each eligible request. A prior request may have aborted
+			// after persisting the warning, so warning deduplication must not own this state.
+			onCloseOut(windowId);
+			if (hasWindowMessage(ctx, WARNING_TYPE) || pendingWarning?.windowId === windowId) return undefined;
+			// The critical close-out starts at reserve + runway, not at the hard reserve.
 			pendingGuidance = undefined;
-			const content = `${GUIDANCE_OPEN_TAG}\n${WARNING_PROMPT}\n${GUIDANCE_CLOSE_TAG}`;
-			pendingWarning = { windowId, content };
+			const content = WARNING_CONTENT;
+			pendingWarning = { windowId, content, remaining };
 			const warningMessage = {
 				role: "custom" as const,
 				customType: WARNING_TYPE,
@@ -116,12 +123,13 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, setti
 			};
 			return { messages: [..._event.messages, warningMessage] };
 		}
+		if (hasWindowMessage(ctx, WARNING_TYPE) || pendingWarning?.windowId === windowId) return undefined;
 		if (hasWindowMessage(ctx, GUIDANCE_TYPE) || pendingGuidance?.windowId === windowId) return undefined;
 		if (remaining <= reminder) {
 			// Persist at turn_end, before any reset drafts. A queued sendMessage could
 			// otherwise cross the marker and leak the old window's reminder forward.
 			const left = Math.max(0, remaining - warning);
-			pendingGuidance = { windowId, content: tokenBudgetGuidance(left) };
+			pendingGuidance = { windowId, content: tokenBudgetGuidance(left), remaining };
 		}
 		return undefined;
 	});
@@ -141,7 +149,7 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, setti
 
 	return {
 		automaticResetEnabled,
-		resetDue,
+		hardReserveDue,
 		consumeTurnEnd,
 		clear: () => { clearStaged(); pendingNotices = []; },
 	};

package/src/context/context-window.ts

@@ -24,6 +24,16 @@ export function currentReset(ctx: SessionReader): WindowMarker | undefined {
 	return undefined;
 }
 
+/** A reset is checkpoint-backed only when its marker directly follows a native compaction. */
+export function isCheckpointBackedReset(ctx: SessionReader, marker = currentReset(ctx)): boolean {
+	if (!marker?.parentId) return false;
+	const branch = ctx.sessionManager.getBranch();
+	const markerIndex = branch.findIndex((entry) => entry.id === marker.id);
+	const checkpoint = branch[markerIndex - 1];
+	return markerIndex > 0 && checkpoint?.id === marker.parentId && checkpoint.type === "compaction" &&
+		checkpoint.summary === "" && checkpoint.firstKeptEntryId === checkpoint.id;
+}
+
 /** Mint the durable identity of a session's root history window. */
 export function rootWindowId(sessionId: string): string {
 	return `pcw:${sessionId.slice(0, 8)}:root`;
@@ -106,7 +116,12 @@ export function windowUsage(ctx: Pick<ExtensionContext, "sessionManager" | "getC
 	if (!contextWindow) return undefined;
 	const windowId = reset.data.windowId;
 	try {
-		const messages: AgentMessage[] = projectWindow(ctx.sessionManager.buildSessionProjection().messages, windowId);
+		const canonicalMessages = ctx.sessionManager.buildSessionProjection().messages;
+		// New resets already cut the durable Pi projection. Marker slicing is retained only
+		// for sessions written before native reset checkpoints existed.
+		const messages: AgentMessage[] = isCheckpointBackedReset(ctx, reset)
+			? canonicalMessages
+			: projectWindow(canonicalMessages, windowId);
 		const { tokens } = estimateContextTokens(convertToLlm(messages));
 		return { tokens, contextWindow, percent: tokens / contextWindow * 100 };
 	} catch {

package/src/context/prompts.ts

@@ -1,4 +1,4 @@
-import type { NotesHome, NotesSnapshot } from "../notes/notes-snapshot.js";
+import type { NotesHome, NotesSnapshot } from "../pi/notes/snapshot.js";
 import { CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, POCKET_AGENT_LIMIT, POCKET_HUMAN_LIMIT, POCKET_MODEL_LIMIT, POCKET_PROJECT_LIMIT, POCKET_SESSION_LIMIT, PROTOCOL_BLOCK, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG } from "../protocol.js";
 
 /** Codex-style <context_window> identity block: the resolved agent and model names plus first/current/previous window ids. */
@@ -62,7 +62,7 @@ function notesIndex(snapshot: NotesSnapshot): string {
 	if (recentNotes.length > 0) {
 		const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (by prefix, most recent first within each: up to ${POCKET_SESSION_LIMIT} from this session, ${POCKET_PROJECT_LIMIT} from @project, ${POCKET_HUMAN_LIMIT} from @human, ${POCKET_AGENT_LIMIT} from @self, ${POCKET_MODEL_LIMIT} from @model). A note's content never appears here, so its name has to say what the note is about:`];
 		for (const row of recentNotes) {
-			lines.push(`- ${row.address} (${row.body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${relativeTime(row.meta.updated_at, snapshot.openedAt)})`);
+			lines.push(`- ${row.address} (${row.body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${relativeTime(row.meta.updatedAt, snapshot.openedAt)})`);
 		}
 		sections.push(lines.join("\n"));
 	}