@astrosheep/pi-context 0.25.2 → 0.26.0

package/dist/extension.js

@@ -1,5 +1,5 @@
 // <define:__PI_CONTEXT_BUILD__>
-var define_PI_CONTEXT_BUILD_default = { version: "0.25.2", sourceHash: "e240c1946d0f2b6d7b1d83ed658c348c7daed5fce5a374844215f1eebddcb25f" };
+var define_PI_CONTEXT_BUILD_default = { version: "0.26.0", sourceHash: "48dcba30fd66f729c046d9ec89214e69ada06592df8d464f3b8cc70562dd5174" };
 
 // src/index.ts
 import { VERSION as VERSION2 } from "@earendil-works/pi-coding-agent";
@@ -235,6 +235,10 @@ function estimateToolsTokens(tools) {
 // src/context/context-window.ts
 import { convertToLlm } from "@earendil-works/pi-coding-agent";
 
+// src/notes/constants.ts
+var MAX_NOTE_BYTES = 1e6;
+var MAX_NOTE_PATH_BYTES = 512;
+
 // src/protocol.ts
 var NOTE_TYPE = "pi-context/note";
 var BOOT_TYPE = "pi-context/boot";
@@ -242,13 +246,11 @@ var GUIDANCE_TYPE = "pi-context/guidance";
 var WARNING_TYPE = "pi-context/warning";
 var RESET_MARKER_TYPE = "pi-context/reset-marker";
 var CONTINUATION_TYPE = "pi-context/continuation";
-var MAX_NOTE_BYTES = 1e6;
 var POCKET_SESSION_LIMIT = 5;
 var POCKET_PROJECT_LIMIT = 2;
 var POCKET_HUMAN_LIMIT = 2;
 var POCKET_AGENT_LIMIT = 1;
 var POCKET_MODEL_LIMIT = 1;
-var MAX_NOTE_PATH_BYTES = 512;
 var CONTEXT_WINDOW_OPEN_TAG = "<context_window>";
 var CONTEXT_WINDOW_CLOSE_TAG = "</context_window>";
 var CONTEXT_WINDOW_PROTOCOL_OPEN_TAG = "<context_window_protocol>";
@@ -275,7 +277,10 @@ Session notes belong to this trip \u2014 the goal, the progress, the loose ends.
 @self notes are yours \u2014 your voice, your lessons, your gripes \u2014 for the next run of whoever you are. Other agents read yours by explicit address and never write them; you read theirs the same way. A note only its author would ever need belongs here, not in @human.
 @model notes capture the substrate \u2014 how the current model actually behaves: context honesty, tool quirks, fallback patterns. @model resolves live, so what you learn on one model is filed under that model even when a fallback moves you mid-window.
 ${CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG}`;
-var WARNING_PROMPT = "Your memory is about to be erased. Write the note. NOW. If it already exists, revise it with notes_edit (or rewrite it whole): the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. Do not continue any task. Then call wipe_memory IMMEDIATELY \u2014 anything not in the note dies with the window.";
+var WARNING_PROMPT = "Your memory is about to be erased. Stop the current task and write the note NOW. If it already exists, revise it with notes_edit (or rewrite it whole): the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. Use as many note/tool turns as needed to finish the checkpoint. When it is ready, call wipe_memory to reset immediately; otherwise finish normally and the extension will reset at your normal stop. Anything not in the note dies with the window.";
+var WARNING_CONTENT = `${GUIDANCE_OPEN_TAG}
+${WARNING_PROMPT}
+${GUIDANCE_CLOSE_TAG}`;
 
 // src/context/context-window.ts
 function isWindowMarker(entry) {
@@ -289,8 +294,15 @@ function currentReset(ctx) {
   }
   return void 0;
 }
-function rootWindowId(sessionId2) {
-  return `pcw:${sessionId2.slice(0, 8)}:root`;
+function isCheckpointBackedReset(ctx, marker = currentReset(ctx)) {
+  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;
+}
+function rootWindowId(sessionId) {
+  return `pcw:${sessionId.slice(0, 8)}:root`;
 }
 function hasWindowMessage(ctx, customType) {
   const branch = ctx.sessionManager.getBranch();
@@ -343,7 +355,8 @@ function windowUsage(ctx) {
   if (!contextWindow) return void 0;
   const windowId = reset.data.windowId;
   try {
-    const messages = projectWindow(ctx.sessionManager.buildSessionProjection().messages, windowId);
+    const canonicalMessages = ctx.sessionManager.buildSessionProjection().messages;
+    const messages = isCheckpointBackedReset(ctx, reset) ? canonicalMessages : projectWindow(canonicalMessages, windowId);
     const { tokens } = estimateContextTokens(convertToLlm(messages));
     return { tokens, contextWindow, percent: tokens / contextWindow * 100 };
   } catch {
@@ -405,8 +418,8 @@ function toolCallItems(windowId, entry, message) {
   return items;
 }
 function historyFromSession(ctx) {
-  const sessionId2 = ctx.sessionManager.getSessionId();
-  let window = { windowId: rootWindowId(sessionId2), items: [] };
+  const sessionId = ctx.sessionManager.getSessionId();
+  let window = { windowId: rootWindowId(sessionId), items: [] };
   const windows = [window];
   for (const entry of ctx.sessionManager.getBranch()) {
     if (isWindowMarker(entry)) {
@@ -570,16 +583,17 @@ function registerHistoryTools(pi) {
   }));
 }
 
-// src/notes/tools.ts
+// src/pi/notes/tools.ts
 import { Type as Type3 } from "@earendil-works/pi-ai";
-import { defineTool as defineTool2 } from "@earendil-works/pi-coding-agent";
+import { defineTool as defineTool2, generateDiffString } from "@earendil-works/pi-coding-agent";
 
 // src/notes/frontmatter.ts
 var SCOPES = ["session", "project", "human", "agent", "model"];
 var ORIGINS = ["user", "self", "external"];
 var STATUSES = ["active", "superseded", "pending", "archived"];
-var TIMESTAMP_KEYS = ["created_at", "updated_at", "last_accessed"];
-var KNOWN_KEYS = ["origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count", "source_window", "supersedes", "recurrence_count", "recurrence_windows"];
+var TIMESTAMP_KEYS = ["createdAt", "updatedAt", "lastAccessed"];
+var LEGACY_KNOWN_KEYS = ["created_at", "updated_at", "last_accessed", "access_count", "source_window", "recurrence_count", "recurrence_windows"];
+var KNOWN_KEYS = ["origin", "status", "stale", "createdAt", "updatedAt", "lastAccessed", "accessCount", "sourceWindow", "supersedes", "recurrenceCount", "recurrenceWindows"];
 var pad2 = (value) => String(value).padStart(2, "0");
 function localIso(epochMs) {
   const date = new Date(epochMs);
@@ -628,7 +642,7 @@ function parseFrontmatter(raw) {
     }
   }
   if (close === -1) return { fields: {}, body: raw };
-  const fields = {};
+  const fields = /* @__PURE__ */ Object.create(null);
   for (let index = 1; index < close; index++) {
     const line = lines[index];
     const match = /^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/.exec(line);
@@ -652,13 +666,15 @@ function parseFrontmatter(raw) {
 }
 function parseNote(raw, now = Date.now()) {
   const { fields, body } = parseFrontmatter(raw);
+  const legacyKeys = LEGACY_KNOWN_KEYS.filter((key) => Object.hasOwn(fields, key));
+  if (legacyKeys.length > 0) throw new Error(`legacy note metadata ${legacyKeys.join(", ")} requires manual migration to camelCase before this note can be used`);
   const meta = { ...fields };
   meta.scope = isScope(meta.scope) ? meta.scope : "session";
   meta.origin = isOrigin(meta.origin) ? meta.origin : "self";
   meta.status = isStatus(meta.status) ? meta.status : "active";
   meta.stale = meta.stale === true;
   for (const key of TIMESTAMP_KEYS) meta[key] = toEpoch(meta[key], now);
-  meta.access_count = typeof meta.access_count === "number" && Number.isFinite(meta.access_count) ? meta.access_count : 0;
+  meta.accessCount = typeof meta.accessCount === "number" && Number.isFinite(meta.accessCount) ? meta.accessCount : 0;
   return { meta, body };
 }
 function yamlScalar(value) {
@@ -691,67 +707,73 @@ function stripLeadingFrontmatter(content) {
   return parseFrontmatter(content).body;
 }
 
+// src/notes/store.ts
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir as readdir2, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname as dirname2, join as join2, resolve as resolve3 } from "node:path";
+
 // src/notes/paths.ts
 import { createHash } from "node:crypto";
-import { existsSync, readdirSync, renameSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
-function notesRoot() {
-  const override = process.env.PI_NOTES_HOME;
-  return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { basename, dirname, join, resolve, sep } from "node:path";
+var SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function slugify(value) {
+  const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug.length > 0 ? slug : "root";
 }
-function sessionHomesRoot(home = notesRoot()) {
-  return join(home, "pi", "session");
+function projectKey(cwd) {
+  const absolute = resolve(cwd);
+  const root = gitRoot(absolute) ?? absolute;
+  const digest = createHash("sha1").update(root).digest("hex").slice(0, 8);
+  return `${basename(root)}-${digest}`;
+}
+function repositoryRoot(dir) {
+  let stats;
+  try {
+    stats = statSync(join(dir, ".git"));
+  } catch {
+    return dir;
+  }
+  if (stats.isDirectory()) return dir;
+  let pointer;
+  try {
+    pointer = readFileSync(join(dir, ".git"), "utf8");
+  } catch {
+    return dir;
+  }
+  const match = /^gitdir:\s*(.+)$/m.exec(pointer);
+  if (!match) return dir;
+  const parts = resolve(dir, match[1].trim()).split(sep);
+  const worktrees = parts.lastIndexOf("worktrees");
+  if (worktrees <= 0 || worktrees !== parts.length - 2) return dir;
+  const common = parts.slice(0, worktrees).join(sep);
+  return basename(common) === ".git" ? dirname(common) : dir;
 }
 function gitRoot(cwd) {
   let dir = resolve(cwd);
   for (; ; ) {
-    if (existsSync(join(dir, ".git"))) return dir;
+    if (existsSync(join(dir, ".git"))) return repositoryRoot(dir);
     const parent = dirname(dir);
     if (parent === dir) return void 0;
     dir = parent;
   }
 }
-function projectKey(cwd) {
-  const absolute = resolve(cwd);
-  const root = gitRoot(absolute) ?? absolute;
-  const digest = createHash("sha1").update(root).digest("hex").slice(0, 8);
-  return `${basename(root)}-${digest}`;
-}
-function sessionId(ctx) {
-  return ctx.sessionManager.getSessionId();
-}
-var SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-function slugify(value) {
-  const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  return slug.length > 0 ? slug : "root";
-}
-function agentSlug(_ctx) {
-  return slugify(process.env.PI_NOTES_AGENT ?? "root");
-}
-function modelSlug(ctx) {
-  const id = ctx.model?.id;
-  if (!id) return "default";
-  return slugify(id.split("/").pop() ?? id);
-}
-function scopeDir(scope, ctx, who) {
-  if (scope === "human") return join(notesRoot(), "human");
-  if (scope === "project") return join(notesRoot(), "project", projectKey(ctx.cwd));
-  if (scope === "agent") return join(notesRoot(), "agents", who ?? agentSlug(ctx));
-  if (scope === "model") return join(notesRoot(), "models", who ?? modelSlug(ctx));
-  return join(sessionHomesRoot(), sessionId(ctx));
+function sessionHomesRoot(home) {
+  return join(home, "pi", "session");
 }
-function migrateLegacyHomes(home = notesRoot()) {
-  const legacy = join(home, "personal");
-  const modern = join(home, "human");
-  if (!existsSync(legacy)) return void 0;
-  if (existsSync(modern)) return "both personal/ and human/ exist under the notes home; migrate by hand, no automatic merge";
-  renameSync(legacy, modern);
-  return void 0;
+function scopeDir(scope, context, who) {
+  if (!["session", "project", "human", "agent", "model"].includes(scope)) throw new TypeError("invalid notes scope");
+  if (who !== void 0 && (scope !== "agent" && scope !== "model" || !SLUG_PATTERN.test(who))) throw new TypeError("who must be a canonical agent/model slug");
+  if (scope === "human") return join(context.home, "human");
+  if (scope === "project") return join(context.home, "project", context.projectKey);
+  if (scope === "agent") return join(context.home, "agents", who ?? context.agent);
+  if (scope === "model") return join(context.home, "models", who ?? context.model);
+  return join(sessionHomesRoot(context.home), context.sessionId);
 }
-function namespaceSlugs(namespace, home = notesRoot()) {
+async function namespaceSlugs(namespace, home) {
   try {
-    return readdirSync(join(home, namespace), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+    return (await readdir(join(home, namespace), { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
   } catch {
     return [];
   }
@@ -759,8 +781,10 @@ function namespaceSlugs(namespace, home = notesRoot()) {
 function noteFileName(vpath) {
   return vpath.endsWith(".md") ? vpath : `${vpath}.md`;
 }
-function physicalPath(scope, vpath, ctx, who) {
-  return join(scopeDir(scope, ctx, who), ...noteFileName(vpath).split("/"));
+function physicalPath(scope, vpath, context, who) {
+  if (typeof vpath !== "string" || vpath.length === 0 || vpath.includes("\0") || vpath.includes("\\") || vpath.startsWith("/")) throw new TypeError("path must be a safe virtual relative path");
+  if (vpath.split("/").some((part) => part.length === 0 || part === "." || part === "..")) throw new TypeError("path contains an unsupported component");
+  return join(scopeDir(scope, context, who), ...noteFileName(vpath).split("/"));
 }
 
 // src/notes/address.ts
@@ -827,52 +851,91 @@ function assertAddress(value) {
   assertVirtualPath(path);
   return { scope, path, who };
 }
-function addressFor(ctx, scope, path, who) {
+function addressFor(context, scope, path, who) {
   if (scope === "session") return path;
   if (scope === "project") return `@project/${path}`;
   if (scope === "human") return `@human/${path}`;
-  if (scope === "agent") return `@agents/${who ?? agentSlug(ctx)}/${path}`;
-  return `@models/${who ?? modelSlug(ctx)}/${path}`;
+  if (scope === "agent") return `@agents/${who ?? context.agent}/${path}`;
+  return `@models/${who ?? context.model}/${path}`;
+}
+
+// src/notes/context.ts
+import { resolve as resolve2 } from "node:path";
+function requireString(field, value) {
+  if (typeof value !== "string" || value.length === 0) throw new TypeError(`notes context ${field} must be a non-empty string`);
+  return value;
+}
+function assertDirectoryComponent(field, value) {
+  if (value === "." || value === ".." || /[\\/\0:]/.test(value)) {
+    throw new TypeError(`notes context ${field} must be a safe single directory component`);
+  }
+}
+function snapshotNotesContext(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError("notes context must be a plain object");
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) throw new TypeError("notes context must be a plain object");
+  const homeValue = requireString("home", value.home);
+  const sessionId = requireString("sessionId", value.sessionId);
+  const projectKey2 = requireString("projectKey", value.projectKey);
+  const agent = requireString("agent", value.agent);
+  const model = requireString("model", value.model);
+  assertDirectoryComponent("sessionId", sessionId);
+  assertDirectoryComponent("projectKey", projectKey2);
+  if (!SLUG_PATTERN.test(agent)) throw new TypeError("notes context agent must be a canonical lowercase slug");
+  if (!SLUG_PATTERN.test(model)) throw new TypeError("notes context model must be a canonical lowercase slug");
+  const home = resolve2(homeValue);
+  return Object.freeze({ home, sessionId, projectKey: projectKey2, agent, model });
 }
 
 // src/notes/store.ts
-import { randomUUID } from "node:crypto";
-import { existsSync as existsSync2, mkdirSync, readFileSync, readdirSync as readdirSync2, renameSync as renameSync2, rmSync, writeFileSync } from "node:fs";
-import { dirname as dirname2 } from "node:path";
-import { generateDiffString } from "@earendil-works/pi-coding-agent";
 var NoteError = class extends Error {
   code;
-  line_numbers;
-  edit_index;
+  lineNumbers;
+  editIndex;
   constructor(code, message, extra = {}) {
     super(message);
     this.name = "NoteError";
     this.code = code;
-    this.line_numbers = extra.line_numbers;
-    this.edit_index = extra.edit_index;
+    this.lineNumbers = extra.lineNumbers;
+    this.editIndex = extra.editIndex;
   }
 };
 var SCOPE_ORDER = ["session", "project", "human", "agent", "model"];
-function assertScope(value) {
-  if (!isScope(value)) throw new NoteError("invalid_scope", `scope must be one of session, project, human, agent, model (got ${JSON.stringify(value)})`);
-  return value;
+var pathQueues = /* @__PURE__ */ new Map();
+function withPathQueue(path, operation) {
+  const key = resolve3(path);
+  const previous = pathQueues.get(key) ?? Promise.resolve();
+  const result = previous.then(operation);
+  const tail = result.then(() => void 0, () => void 0);
+  pathQueues.set(key, tail);
+  void tail.then(() => {
+    if (pathQueues.get(key) === tail) pathQueues.delete(key);
+  });
+  return result;
 }
-function assertOrigin(value) {
-  if (!isOrigin(value)) throw new NoteError("invalid_origin", `origin must be one of user, self, external (got ${JSON.stringify(value)})`);
-  return value;
+function errno(error) {
+  return typeof error === "object" && error !== null ? error.code : void 0;
+}
+async function readFileIfExists(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (errno(error) === "ENOENT") return void 0;
+    throw error;
+  }
 }
-function walkMarkdown(dir, base = dir) {
+async function walkMarkdown(dir, base = dir) {
   let entries;
   try {
-    entries = readdirSync2(dir, { withFileTypes: true });
+    entries = await readdir2(dir, { withFileTypes: true });
   } catch (error) {
-    if (typeof error === "object" && error !== null && error.code === "ENOENT") return [];
+    if (errno(error) === "ENOENT") return [];
     throw error;
   }
   const paths = [];
   for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-    const child = `${dir}/${entry.name}`;
-    if (entry.isDirectory()) paths.push(...walkMarkdown(child, base));
+    const child = join2(dir, entry.name);
+    if (entry.isDirectory()) paths.push(...await walkMarkdown(child, base));
     else if (entry.isFile() && entry.name.endsWith(".md")) paths.push(child.slice(base.length + 1).split("\\").join("/"));
   }
   return paths;
@@ -881,36 +944,7 @@ function matcherFor(pattern) {
   const normalized = assertGlobPattern(pattern);
   return normalized === void 0 ? void 0 : globToRegExp(normalized);
 }
-function atomicWrite(path, content) {
-  mkdirSync(dirname2(path), { recursive: true });
-  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
-  try {
-    writeFileSync(tmp, content);
-    renameSync2(tmp, path);
-  } catch (error) {
-    rmSync(tmp, { force: true });
-    throw error;
-  }
-}
-function assertWritablePath(vpath) {
-  const bytes = Buffer.byteLength(vpath, "utf8");
-  if (bytes > MAX_NOTE_PATH_BYTES) throw new NoteError("too_large", `note path exceeds ${MAX_NOTE_PATH_BYTES} UTF-8 bytes (got ${bytes})`);
-}
-function assertSerializedSize(content) {
-  const bytes = Buffer.byteLength(content, "utf8");
-  if (bytes > MAX_NOTE_BYTES) throw new NoteError("too_large", `note exceeds ${MAX_NOTE_BYTES} UTF-8 bytes (serialized ${bytes})`);
-}
-function frontmatterOf(meta) {
-  return serializeNote(meta, "").slice(0, -2);
-}
-function assertWritableHome(scope, who, ctx) {
-  if (who === void 0) return;
-  const current = scope === "agent" ? agentSlug(ctx) : modelSlug(ctx);
-  if (who === current) return;
-  const home = scope === "agent" ? `@agents/${who}/` : `@models/${who}/`;
-  throw new NoteError("invalid_scope", `${home} is not your home: writable homes are this session, @project/, @human/, @self/, and the current @model/ home`);
-}
-function homesForPattern(pattern) {
+async function homesForPattern(pattern, context) {
   if (!pattern || !pattern.startsWith("@")) return void 0;
   const head = /^@([^/]+)\//.exec(pattern)?.[1];
   if (head === "project") return [{ scope: "project" }];
@@ -920,20 +954,43 @@ function homesForPattern(pattern) {
   if (head === "agents" || head === "models") {
     const scope = head === "agents" ? "agent" : "model";
     const name = pattern.slice(head.length + 2).split("/")[0] ?? "";
-    if (name.length > 0 && !/[*?]/.test(name)) return [{ scope, who: name }];
-    return namespaceSlugs(head).map((who) => ({ scope, who }));
+    if (name.length > 0 && !/[*?]/.test(name)) return [{ scope, who: assertWho(name) }];
+    return (await namespaceSlugs(head, context.home)).map((who) => ({ scope, who }));
   }
   return [];
 }
-function normalizePattern(pattern, ctx) {
+function normalizePattern(pattern, context) {
   if (!pattern) return pattern;
-  if (pattern.startsWith("@self/")) return `@agents/${agentSlug(ctx)}/${pattern.slice("@self/".length)}`;
-  if (pattern.startsWith("@model/")) return `@models/${modelSlug(ctx)}/${pattern.slice("@model/".length)}`;
+  if (pattern.startsWith("@self/")) return `@agents/${context.agent}/${pattern.slice("@self/".length)}`;
+  if (pattern.startsWith("@model/")) return `@models/${context.model}/${pattern.slice("@model/".length)}`;
   return pattern;
 }
-function homesFor(ctx, opts) {
-  if (opts.scope !== void 0) return [{ scope: opts.scope, who: opts.who }];
-  return homesForPattern(opts.pattern) ?? SCOPE_ORDER.map((scope) => ({ scope }));
+function assertScope(value) {
+  if (!isScope(value)) throw new NoteError("invalid_scope", `scope must be one of session, project, human, agent, model (got ${JSON.stringify(value)})`);
+  return value;
+}
+function assertOrigin(value) {
+  if (!isOrigin(value)) throw new NoteError("invalid_origin", `origin must be one of user, self, external (got ${JSON.stringify(value)})`);
+  return value;
+}
+function assertWho(value) {
+  if (typeof value !== "string" || !SLUG_PATTERN.test(value)) {
+    throw new NoteError("invalid_scope", "who must be a canonical lowercase slug");
+  }
+  return value;
+}
+async function homesFor(context, opts) {
+  if (opts.scope !== void 0) {
+    const scope = assertScope(opts.scope);
+    if (opts.who !== void 0) {
+      const who = assertWho(opts.who);
+      if (scope !== "agent" && scope !== "model") throw new NoteError("invalid_scope", "who is only valid with agent or model scope");
+      return [{ scope, who }];
+    }
+    return [{ scope }];
+  }
+  if (opts.who !== void 0) throw new NoteError("invalid_scope", "who requires agent or model scope");
+  return await homesForPattern(normalizePattern(opts.pattern, context), context) ?? SCOPE_ORDER.map((scope) => ({ scope }));
 }
 function matchLineNumbers(body, needle) {
   const lines = [];
@@ -946,141 +1003,246 @@ function matchLineNumbers(body, needle) {
   }
   return lines;
 }
-function writeNote(ctx, vpath, body, opts) {
-  assertVirtualPath(vpath);
-  assertWritablePath(vpath);
-  const scope = assertScope(opts.scope);
-  assertWritableHome(scope, opts.who, ctx);
-  const origin = assertOrigin(opts.origin);
-  const path = physicalPath(scope, vpath, ctx, opts.who);
-  const now = Date.now();
-  const cleanBody = stripLeadingFrontmatter(body);
-  const existing = existsSync2(path) ? parseNote(readFileSync(path, "utf8"), now).meta : void 0;
-  const meta = existing ?? {
-    scope,
-    origin,
-    status: "active",
-    stale: false,
-    created_at: now,
-    updated_at: now,
-    last_accessed: now,
-    access_count: 0
-  };
-  meta.scope = scope;
-  meta.origin = origin;
-  meta.status = "active";
-  meta.stale = opts.stale ?? false;
-  meta.updated_at = now;
-  const serialized = serializeNote(meta, cleanBody);
-  assertSerializedSize(serialized);
-  atomicWrite(path, serialized);
-  return { meta };
-}
-function editNote(ctx, vpath, scope, edits, opts = {}, who) {
-  assertVirtualPath(vpath);
-  assertWritablePath(vpath);
-  assertWritableHome(scope, who, ctx);
-  const operations = edits ?? [];
-  if (operations.length === 0 && opts.origin === void 0 && opts.stale === void 0) {
-    throw new NoteError("nothing_to_do", "nothing to do: provide edits or at least one of origin, stale");
+function earliestMatchOffsetChars2(text, queries) {
+  let earliest = -1;
+  for (const query of queries) {
+    const index = text.indexOf(query);
+    if (index < 0) continue;
+    if (earliest < 0 || index < earliest) earliest = index;
   }
-  const path = physicalPath(scope, vpath, ctx, who);
-  if (!existsSync2(path)) throw new NoteError("not_found", "note not found");
-  const raw = readFileSync(path, "utf8");
-  const { meta, body } = parseNote(raw);
-  meta.scope = scope;
-  const beforeMeta = { ...meta };
-  let next = body;
-  operations.forEach((edit, index) => {
-    const oldText = edit?.oldText;
-    const newText = edit?.newText;
-    if (typeof oldText !== "string" || oldText.length === 0) throw new NoteError("no_match", `edit ${index}: oldText must be a non-empty string`, { edit_index: index });
-    if (typeof newText !== "string") throw new NoteError("no_match", `edit ${index}: newText must be a string`, { edit_index: index });
-    const lines = matchLineNumbers(next, oldText);
-    if (lines.length === 0) throw new NoteError("no_match", `edit ${index}: oldText does not occur in the note body`, { edit_index: index });
-    if (lines.length > 1 && !opts.replaceAll) {
-      throw new NoteError("ambiguous_edit", `edit ${index}: oldText occurs ${lines.length} times (lines ${lines.join(", ")}); pass replace_all to replace every occurrence`, { line_numbers: lines, edit_index: index });
-    }
-    if (opts.replaceAll) {
-      next = next.split(oldText).join(newText);
-    } else {
-      const matchIndex = next.indexOf(oldText);
-      next = next.substring(0, matchIndex) + newText + next.substring(matchIndex + oldText.length);
+  return earliest <= 0 ? 0 : Array.from(text.slice(0, earliest)).length;
+}
+async function atomicWrite(path, content) {
+  await mkdir(dirname2(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmp, content);
+    await rename(tmp, path);
+  } catch (error) {
+    try {
+      await rm(tmp, { force: true });
+    } catch {
     }
-  });
-  if (opts.origin !== void 0) meta.origin = assertOrigin(opts.origin);
-  if (opts.stale !== void 0) meta.stale = opts.stale;
-  meta.updated_at = Date.now();
-  const serialized = serializeNote(meta, next);
-  assertSerializedSize(serialized);
-  const bodyChanged = body !== next;
-  const metadataChanged = beforeMeta.origin !== meta.origin || beforeMeta.stale !== meta.stale;
-  const diff = bodyChanged && metadataChanged ? generateDiffString(raw, serialized).diff : bodyChanged ? generateDiffString(body, next).diff : metadataChanged ? generateDiffString(frontmatterOf(beforeMeta), frontmatterOf(meta)).diff : "";
-  atomicWrite(path, serialized);
-  return { meta, applied: operations.length, resolved_scope: scope, diff };
+    throw error;
+  }
+}
+function assertWritablePath(vpath) {
+  const bytes = Buffer.byteLength(vpath, "utf8");
+  if (bytes > MAX_NOTE_PATH_BYTES) throw new NoteError("too_large", `note path exceeds ${MAX_NOTE_PATH_BYTES} UTF-8 bytes (got ${bytes})`);
+}
+function assertSerializedSize(content) {
+  const bytes = Buffer.byteLength(content, "utf8");
+  if (bytes > MAX_NOTE_BYTES) throw new NoteError("too_large", `note exceeds ${MAX_NOTE_BYTES} UTF-8 bytes (serialized ${bytes})`);
+}
+function frontmatterOf(meta) {
+  return serializeNote(meta, "").slice(0, -2);
+}
+function assertWritableHome(scope, who, context) {
+  if (who === void 0) return;
+  const current = scope === "agent" ? context.agent : context.model;
+  if (who === current) return;
+  const home = scope === "agent" ? `@agents/${who}/` : `@models/${who}/`;
+  throw new NoteError("invalid_scope", `${home} is not your home: writable homes are this session, @project/, @human/, @self/, and the current @model/ home`);
 }
 function accessedMeta(meta, scope, now) {
   const next = { ...meta, scope };
-  next.last_accessed = now;
-  next.access_count = (typeof next.access_count === "number" ? next.access_count : 0) + 1;
+  next.lastAccessed = now;
+  next.accessCount = (typeof next.accessCount === "number" ? next.accessCount : 0) + 1;
   return next;
 }
-function readNote(ctx, vpath, scope, who) {
-  assertVirtualPath(vpath);
-  const path = physicalPath(scope, vpath, ctx, who);
-  if (!existsSync2(path)) return void 0;
-  const now = Date.now();
-  const parsed = parseNote(readFileSync(path, "utf8"), now);
-  const meta = accessedMeta(parsed.meta, scope, now);
-  const text = serializeNote(meta, parsed.body);
-  atomicWrite(path, text);
-  return { meta, body: parsed.body, text, resolvedScope: scope };
-}
-function listNotes(ctx, opts = {}) {
-  const matcher = matcherFor(normalizePattern(opts.pattern, ctx));
-  const rows = [];
-  for (const home of homesFor(ctx, opts)) {
-    const scope = home.scope;
-    const root = scopeDir(scope, ctx, home.who);
-    for (const path of walkMarkdown(root)) {
-      const address = addressFor(ctx, scope, path, home.who);
-      if (matcher && !matcher.test(address)) continue;
-      const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
+function createNotesStore(input) {
+  const context = snapshotNotesContext(input);
+  async function write(address, content, options = {}) {
+    const stableAddress = address;
+    const stableContent = content;
+    const stableOptions = { ...options };
+    const destination = assertAddress(stableAddress);
+    assertWritablePath(destination.path);
+    const scope = assertScope(destination.scope);
+    assertWritableHome(scope, destination.who, context);
+    const origin = assertOrigin(stableOptions.origin ?? "self");
+    const path = physicalPath(scope, destination.path, context, destination.who);
+    return withPathQueue(path, async () => {
+      const now = Date.now();
+      const cleanBody = stripLeadingFrontmatter(stableContent);
+      const existingRaw = await readFileIfExists(path);
+      const existing = existingRaw === void 0 ? void 0 : parseNote(existingRaw, now).meta;
+      const meta = existing ?? {
+        scope,
+        origin,
+        status: "active",
+        stale: false,
+        createdAt: now,
+        updatedAt: now,
+        lastAccessed: now,
+        accessCount: 0,
+        ...scope === "session" ? { project: context.projectKey } : {}
+      };
       meta.scope = scope;
-      rows.push({ address, scope, path, meta, body, sizeBytes: Buffer.byteLength(body, "utf8") });
-    }
+      meta.origin = origin;
+      meta.status = "active";
+      meta.stale = stableOptions.stale ?? false;
+      meta.updatedAt = now;
+      const serialized = serializeNote(meta, cleanBody);
+      assertSerializedSize(serialized);
+      await atomicWrite(path, serialized);
+      return { meta };
+    });
+  }
+  async function read(address) {
+    const stableAddress = address;
+    const destination = assertAddress(stableAddress);
+    const scope = assertScope(destination.scope);
+    const path = physicalPath(scope, destination.path, context, destination.who);
+    return withPathQueue(path, async () => {
+      const raw = await readFileIfExists(path);
+      if (raw === void 0) return void 0;
+      const now = Date.now();
+      const parsed = parseNote(raw, now);
+      const meta = accessedMeta(parsed.meta, scope, now);
+      const text = serializeNote(meta, parsed.body);
+      await atomicWrite(path, text);
+      return { meta, body: parsed.body, text, resolvedScope: scope };
+    });
   }
-  rows.sort((a, b) => b.meta.updated_at - a.meta.updated_at || a.address.localeCompare(b.address));
-  return rows;
-}
-function searchNotes(ctx, queries, opts = {}) {
-  const matcher = matcherFor(normalizePattern(opts.pattern, ctx));
-  const rows = [];
-  for (const home of homesFor(ctx, opts)) {
-    const scope = home.scope;
-    const root = scopeDir(scope, ctx, home.who);
-    for (const path of walkMarkdown(root)) {
-      const address = addressFor(ctx, scope, path, home.who);
-      if (matcher && !matcher.test(address)) continue;
-      const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
+  async function edit(address, edits, options = {}) {
+    const stableAddress = address;
+    const operations = edits === void 0 ? [] : edits.map((operation) => ({ ...operation }));
+    const stableOptions = { ...options };
+    const destination = assertAddress(stableAddress);
+    assertWritablePath(destination.path);
+    const scope = assertScope(destination.scope);
+    assertWritableHome(scope, destination.who, context);
+    if (operations.length === 0 && stableOptions.origin === void 0 && stableOptions.stale === void 0) {
+      throw new NoteError("nothing_to_do", "nothing to do: provide edits or at least one of origin, stale");
+    }
+    const path = physicalPath(scope, destination.path, context, destination.who);
+    return withPathQueue(path, async () => {
+      const raw = await readFileIfExists(path);
+      if (raw === void 0) throw new NoteError("not_found", "note not found");
+      const { meta, body } = parseNote(raw);
       meta.scope = scope;
-      const serializedBodyOffset = Array.from(serializeNote(accessedMeta(meta, scope, Date.now()), "")).length;
-      let baseChars = 0;
-      const matches = [];
-      for (const [index, line] of body.split("\n").entries()) {
-        if (queries.some((query) => line.includes(query))) {
-          matches.push({ line: index + 1, text: line, offsetChars: serializedBodyOffset + baseChars + earliestMatchOffsetChars(line, queries) });
+      const beforeMeta = { ...meta };
+      let next = body;
+      operations.forEach((operation, index) => {
+        const oldText = operation?.oldText;
+        const newText = operation?.newText;
+        if (typeof oldText !== "string" || oldText.length === 0) throw new NoteError("no_match", `edit ${index}: oldText must be a non-empty string`, { editIndex: index });
+        if (typeof newText !== "string") throw new NoteError("no_match", `edit ${index}: newText must be a string`, { editIndex: index });
+        const lines = matchLineNumbers(next, oldText);
+        if (lines.length === 0) throw new NoteError("no_match", `edit ${index}: oldText does not occur in the note body`, { editIndex: index });
+        if (lines.length > 1 && !stableOptions.replaceAll) {
+          throw new NoteError("ambiguous_edit", `edit ${index}: oldText occurs ${lines.length} times (lines ${lines.join(", ")}); pass replace_all to replace every occurrence`, { lineNumbers: lines, editIndex: index });
+        }
+        if (stableOptions.replaceAll) next = next.split(oldText).join(newText);
+        else {
+          const matchIndex = next.indexOf(oldText);
+          next = next.substring(0, matchIndex) + newText + next.substring(matchIndex + oldText.length);
+        }
+      });
+      if (stableOptions.origin !== void 0) meta.origin = assertOrigin(stableOptions.origin);
+      if (stableOptions.stale !== void 0) meta.stale = stableOptions.stale;
+      meta.updatedAt = Date.now();
+      const serialized = serializeNote(meta, next);
+      assertSerializedSize(serialized);
+      const bodyChanged = body !== next;
+      const metadataChanged = beforeMeta.origin !== meta.origin || beforeMeta.stale !== meta.stale;
+      let change;
+      if (bodyChanged && metadataChanged) change = { kind: "file", before: raw, after: serialized };
+      else if (bodyChanged) change = { kind: "body", before: body, after: next };
+      else if (metadataChanged) change = { kind: "metadata", before: frontmatterOf(beforeMeta), after: frontmatterOf(meta) };
+      else change = { kind: "none", before: "", after: "" };
+      await atomicWrite(path, serialized);
+      return { meta, applied: operations.length, resolvedScope: scope, change };
+    });
+  }
+  async function list(options = {}) {
+    const stableOptions = { ...options };
+    const matcher = matcherFor(normalizePattern(stableOptions.pattern, context));
+    const rows = [];
+    for (const home of await homesFor(context, stableOptions)) {
+      const scope = home.scope;
+      const root = scopeDir(scope, context, home.who);
+      for (const path of await walkMarkdown(root)) {
+        const address = addressFor(context, scope, path, home.who);
+        if (matcher && !matcher.test(address)) continue;
+        const fullPath = join2(root, path);
+        const raw = await withPathQueue(fullPath, () => readFile(fullPath, "utf8"));
+        const { meta, body } = parseNote(raw);
+        meta.scope = scope;
+        rows.push({ address, scope, path, meta, body, sizeBytes: Buffer.byteLength(body, "utf8") });
+      }
+    }
+    rows.sort((a, b) => b.meta.updatedAt - a.meta.updatedAt || a.address.localeCompare(b.address));
+    return rows;
+  }
+  async function search(queries, options = {}) {
+    const stableQueries = [...queries];
+    const stableOptions = { ...options };
+    const matcher = matcherFor(normalizePattern(stableOptions.pattern, context));
+    const rows = [];
+    for (const home of await homesFor(context, stableOptions)) {
+      const scope = home.scope;
+      const root = scopeDir(scope, context, home.who);
+      for (const path of await walkMarkdown(root)) {
+        const address = addressFor(context, scope, path, home.who);
+        if (matcher && !matcher.test(address)) continue;
+        const fullPath = join2(root, path);
+        const raw = await withPathQueue(fullPath, () => readFile(fullPath, "utf8"));
+        const { meta, body } = parseNote(raw);
+        meta.scope = scope;
+        const serializedBodyOffset = Array.from(serializeNote(accessedMeta(meta, scope, Date.now()), "")).length;
+        let baseChars = 0;
+        const matches = [];
+        for (const [index, line] of body.split("\n").entries()) {
+          if (stableQueries.some((query) => line.includes(query))) {
+            matches.push({ line: index + 1, text: line, offsetChars: serializedBodyOffset + baseChars + earliestMatchOffsetChars2(line, stableQueries) });
+          }
+          baseChars += Array.from(line).length + 1;
         }
-        baseChars += Array.from(line).length + 1;
+        if (matches.length > 0) rows.push({ address, path, scope, meta, matches });
       }
-      if (matches.length > 0) rows.push({ address, path, scope, meta, matches });
     }
+    rows.sort((a, b) => a.address.localeCompare(b.address));
+    return rows;
   }
-  rows.sort((a, b) => a.address.localeCompare(b.address));
-  return rows;
+  return { write, read, edit, list, search };
 }
 
-// src/notes/tools.ts
+// src/pi/notes/adapter.ts
+import { existsSync as existsSync2, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join as join3, resolve as resolve4 } from "node:path";
+function notesRoot() {
+  const override = process.env.PI_NOTES_HOME;
+  return override && override.length > 0 ? resolve4(override) : join3(homedir(), ".agents", "notes");
+}
+function agentSlug(_ctx) {
+  return slugify(process.env.PI_NOTES_AGENT ?? "root");
+}
+function modelSlug(ctx) {
+  const id = ctx.model?.id;
+  return id ? slugify(id.split("/").pop() ?? id) : "default";
+}
+function notesContextFromPi(ctx, home = notesRoot()) {
+  return {
+    home,
+    sessionId: ctx.sessionManager.getSessionId(),
+    projectKey: projectKey(ctx.cwd),
+    agent: agentSlug(ctx),
+    model: modelSlug(ctx)
+  };
+}
+function migrateLegacyHomes(home = notesRoot()) {
+  const legacy = join3(home, "personal");
+  const modern = join3(home, "human");
+  if (!existsSync2(legacy)) return void 0;
+  if (existsSync2(modern)) return "both personal/ and human/ exist under the notes home; migrate by hand, no automatic merge";
+  renameSync(legacy, modern);
+  return void 0;
+}
+
+// src/pi/notes/tools.ts
 var ORIGIN = Type3.Optional(Type3.Union([Type3.Literal("user"), Type3.Literal("self"), Type3.Literal("external")], {
   description: "Where the note's content came from. user: written or dictated by the human. self: written by you, the agent (default). external: anything else \u2014 third-party text, tool output, fetched material."
 }));
@@ -1088,24 +1250,27 @@ var ADDRESS_DESCRIPTION = "Address forms are bare `<vpath>` for this session, `@
 function failure(error) {
   if (error instanceof NoteError) {
     const payload = { error: error.message };
-    if (error.line_numbers) payload.line_numbers = error.line_numbers;
-    if (error.edit_index !== void 0) payload.edit_index = error.edit_index;
+    if (error.lineNumbers) payload.line_numbers = error.lineNumbers;
+    if (error.editIndex !== void 0) payload.edit_index = error.editIndex;
     return output(payload);
   }
   throw error;
 }
+function renderDiff(change) {
+  if (change.kind === "none") return "";
+  return generateDiffString(change.before, change.after).diff;
+}
 function registerNotesTools(pi) {
   pi.registerTool(defineTool2({
     name: "notes_write",
     label: "Notes write",
-    description: `Create or replace a note as a real markdown file, and name it for what it holds: a fresh window sees only an index entry, never the note itself. ${ADDRESS_DESCRIPTION} Keep notes small and split by topic \u2014 by what the note is about, never by who said it (authorship is origin's job); a rewrite replaces the body whole while preserving created_at and every other frontmatter key. stale: true marks the note closed so it leaves the boot index but stays readable and searchable.`,
+    description: `Create or replace a note as a real markdown file, and name it for what it holds: a fresh window sees only an index entry, never the note itself. ${ADDRESS_DESCRIPTION} Keep notes small and split by topic \u2014 by what the note is about, never by who said it (authorship is origin's job); a rewrite replaces the body whole while preserving createdAt and every other frontmatter key. stale: true marks the note closed so it leaves the boot index but stays readable and searchable.`,
     parameters: Type3.Object({ address: Type3.String(), content: Type3.String(), origin: ORIGIN, stale: Type3.Optional(Type3.Boolean()) }, { additionalProperties: false }),
     executionMode: "sequential",
     async execute(_id, params, _signal, _update, ctx) {
       const content = params.content;
       try {
-        const destination = assertAddress(params.address);
-        writeNote(ctx, destination.path, content, { scope: destination.scope, who: destination.who, origin: params.origin ?? "self", stale: params.stale });
+        await createNotesStore(notesContextFromPi(ctx)).write(params.address, content, { origin: params.origin ?? "self", stale: params.stale });
         return output({ address: params.address, written: true });
       } catch (error) {
         return failure(error);
@@ -1120,8 +1285,8 @@ function registerNotesTools(pi) {
     executionMode: "sequential",
     async execute(_id, params, _signal, _update, ctx) {
       try {
-        const destination = assertAddress(params.address);
-        const { applied, diff } = editNote(ctx, destination.path, destination.scope, params.edits, { origin: params.origin, stale: params.stale, replaceAll: params.replace_all }, destination.who);
+        const { applied, change } = await createNotesStore(notesContextFromPi(ctx)).edit(params.address, params.edits, { origin: params.origin, stale: params.stale, replaceAll: params.replace_all });
+        const diff = renderDiff(change);
         return output({ address: params.address, applied, diff });
       } catch (error) {
         return failure(error);
@@ -1136,8 +1301,7 @@ function registerNotesTools(pi) {
     async execute(_id, params, _signal, _update, ctx) {
       let note;
       try {
-        const destination = assertAddress(params.address);
-        note = readNote(ctx, destination.path, destination.scope, destination.who);
+        note = await createNotesStore(notesContextFromPi(ctx)).read(params.address);
       } catch (error) {
         return failure(error);
       }
@@ -1159,11 +1323,11 @@ function registerNotesTools(pi) {
     async execute(_id, params, _signal, _update, ctx) {
       let rows;
       try {
-        rows = listNotes(ctx, { pattern: params.pattern ?? void 0 });
+        rows = await createNotesStore(notesContextFromPi(ctx)).list({ pattern: params.pattern ?? void 0 });
       } catch (error) {
         return failure(error);
       }
-      const files = rows.map((row) => ({ address: row.address, stale: row.meta.stale, updated_at: localIso(row.meta.updated_at) }));
+      const files = rows.map((row) => ({ address: row.address, stale: row.meta.stale, updated_at: localIso(row.meta.updatedAt) }));
       return output(page(files, params.cursor ?? 0, "files", params.max_results, (file, fits) => {
         if (fits(file)) return file;
         const address = middleTruncate(file.address, (candidate) => fits({ ...file, address: candidate, address_truncated: true }));
@@ -1180,14 +1344,14 @@ function registerNotesTools(pi) {
       const queries = searchQueries(params.query);
       let rows;
       try {
-        rows = searchNotes(ctx, queries, { pattern: params.pattern ?? void 0 });
+        rows = await createNotesStore(notesContextFromPi(ctx)).search(queries, { pattern: params.pattern ?? void 0 });
       } catch (error) {
         return failure(error);
       }
       const maxPerFile = params.max_matches_per_file ?? Number.POSITIVE_INFINITY;
       const result = rows.map((row) => {
         const matches = row.matches.map((match) => ({ line: match.line, text: match.text, truncated: false, offset_chars: match.offsetChars }));
-        return { address: row.address, updated_at: localIso(row.meta.updated_at), stale: row.meta.stale, matches_total: matches.length, matches: matches.slice(0, maxPerFile) };
+        return { address: row.address, updated_at: localIso(row.meta.updatedAt), stale: row.meta.stale, matches_total: matches.length, matches: matches.slice(0, maxPerFile) };
       });
       const fitFile = (file, fits) => {
         if (fits(file)) return file;
@@ -1243,7 +1407,7 @@ function deriveThresholds(reserveTokens, margins) {
   else {
     const parsed = validMargin(margins.reminderMarginTokens);
     if (parsed === void 0) {
-      warnings.push(`pi-context: ${reminderKey} must be a positive integer; using default ${DEFAULT_REMINDER_MARGIN_TOKENS}.`);
+      warnings.push(`pi-context: ${reminderKey} must be a positive integer; using the default reminder margin.`);
       reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
     } else reminderMargin = parsed;
   }
@@ -1330,7 +1494,7 @@ function notesIndex(snapshot) {
   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"));
   }
@@ -1361,7 +1525,8 @@ function remainingTokens(ctx) {
   const usage = windowUsage(ctx);
   return !usage || usage.tokens === null ? null : Math.max(0, usage.contextWindow - usage.tokens);
 }
-function registerBudget(pi, isEnabled, settingsManager) {
+function registerBudget(pi, isEnabled, settingsManager, onCloseOut = () => {
+}) {
   let cachedPolicy;
   const notifiedWarnings = /* @__PURE__ */ new Set();
   const resolvePolicy = (ctx) => {
@@ -1381,7 +1546,7 @@ function registerBudget(pi, isEnabled, settingsManager) {
   const automaticResetEnabled = (ctx) => {
     return resolvePolicy(ctx).automatic;
   };
-  const resetDue = (ctx) => {
+  const hardReserveDue = (ctx) => {
     if (!automaticResetEnabled(ctx)) return false;
     const usage = windowUsage(ctx);
     return usage !== void 0 && usage.tokens !== null && usage.contextWindow - usage.tokens <= thresholdsFor(ctx).reserve;
@@ -1389,7 +1554,6 @@ function registerBudget(pi, isEnabled, settingsManager) {
   const invalidateThresholds = () => {
     cachedPolicy = void 0;
   };
-  const formatRemaining = (remaining) => `${Math.max(0, Math.ceil(remaining / 1e3))}k`;
   let pendingGuidance;
   let pendingWarning;
   let pendingNotices = [];
@@ -1397,7 +1561,7 @@ function registerBudget(pi, isEnabled, settingsManager) {
     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 almost full \u2014 ${formatRemaining(notice.remaining)} remaining` : `pi-context: Context running low \u2014 ${formatRemaining(notice.remaining)} remaining`, "warning");
+      ctx.ui.notify(notice.customType === WARNING_TYPE ? "pi-context: Context almost full; close out the current memory window." : "pi-context: Context running low; checkpoint your notes soon.", "warning");
     }
     pendingNotices = [];
   };
@@ -1444,12 +1608,11 @@ function registerBudget(pi, isEnabled, settingsManager) {
     if (remaining === null) return void 0;
     const windowId = currentWindowId(ctx);
     const { reminder, warning } = thresholdsFor(ctx);
-    if (hasWindowMessage(ctx, WARNING_TYPE) || pendingWarning?.windowId === windowId) return void 0;
-    if (remaining <= warning) {
+    if (remaining <= warning && automaticResetEnabled(ctx)) {
+      onCloseOut(windowId);
+      if (hasWindowMessage(ctx, WARNING_TYPE) || pendingWarning?.windowId === windowId) return void 0;
       pendingGuidance = void 0;
-      const content = `${GUIDANCE_OPEN_TAG}
-${WARNING_PROMPT}
-${GUIDANCE_CLOSE_TAG}`;
+      const content = WARNING_CONTENT;
       pendingWarning = { windowId, content, remaining };
       const warningMessage = {
         role: "custom",
@@ -1460,6 +1623,7 @@ ${GUIDANCE_CLOSE_TAG}`;
       };
       return { messages: [..._event.messages, warningMessage] };
     }
+    if (hasWindowMessage(ctx, WARNING_TYPE) || pendingWarning?.windowId === windowId) return void 0;
     if (hasWindowMessage(ctx, GUIDANCE_TYPE) || pendingGuidance?.windowId === windowId) return void 0;
     if (remaining <= reminder) {
       const left = Math.max(0, remaining - warning);
@@ -1479,7 +1643,7 @@ ${GUIDANCE_CLOSE_TAG}`;
   }));
   return {
     automaticResetEnabled,
-    resetDue,
+    hardReserveDue,
     consumeTurnEnd,
     clear: () => {
       clearStaged();
@@ -1497,45 +1661,75 @@ function isOverflowLike(message, ctx) {
   if (message.role !== "assistant") return false;
   return isContextOverflow(message, ctx.model?.contextWindow) || ctx.model !== void 0 && isRecoverableLength(message, ctx.model.maxTokens);
 }
+var NO_REQUEST = { phase: "none" };
 function initialResetControl() {
-  return { request: "none", overflow: "idle" };
+  return { request: NO_REQUEST, overflow: "idle" };
+}
+function requestForWindow(request, windowId) {
+  return request.phase !== "none" && request.windowId === windowId ? request : NO_REQUEST;
 }
 function reduceResetControl(state, event) {
   switch (event.type) {
-    case "request": {
-      if (state.request === "explicit") return { state, effect: "already-requested" };
-      return { state: { ...state, request: "explicit" }, effect: "requested" };
+    case "close_out": {
+      const request = state.request;
+      if (request.phase === "tool-requested" && request.windowId === event.windowId) {
+        return { state, effect: "already-pending" };
+      }
+      if (request.phase === "close-out" && request.windowId === event.windowId) {
+        if (request.source === "manual" || event.source === "automatic") return { state, effect: "already-pending" };
+        return { state: { ...state, request: { ...request, source: "manual" } }, effect: "close-out-armed" };
+      }
+      return { state: { ...state, request: { phase: "close-out", windowId: event.windowId, source: event.source } }, effect: "close-out-armed" };
+    }
+    case "tool_request": {
+      const request = state.request;
+      if (request.phase === "tool-requested" && request.windowId === event.windowId) return { state, effect: "already-pending" };
+      return { state: { ...state, request: { phase: "tool-requested", windowId: event.windowId } }, effect: "close-out-armed" };
     }
     case "turn_end": {
       const facts = event.facts;
-      const requested = state.request === "explicit";
-      const request = "none";
-      if (facts.aborted) {
-        return { state: { request, overflow: "idle" }, effect: "none" };
-      }
+      const request = requestForWindow(state.request, facts.windowId);
+      if (facts.aborted) return { state: initialResetControl(), effect: "none" };
       if (facts.overflow) {
         const pending = !facts.queued && facts.enabled && facts.automaticResetEnabled;
         const spent = state.overflow === "pending-spent" || state.overflow === "spent";
-        const overflow2 = pending ? spent ? "pending-spent" : "pending" : spent ? "spent" : "idle";
-        return { state: { request, overflow: overflow2 }, effect: "none" };
+        const overflow = pending ? spent ? "pending-spent" : "pending" : spent ? "spent" : "idle";
+        return { state: { request: NO_REQUEST, overflow }, effect: "none" };
+      }
+      if (facts.failed) return { state: { request: NO_REQUEST, overflow: state.overflow }, effect: "none" };
+      if (!facts.enabled) {
+        return { state: { request: NO_REQUEST, overflow: "idle" }, effect: "none" };
+      }
+      if (request.phase === "tool-requested" || facts.hardReserveDue) {
+        return { state: { request: NO_REQUEST, overflow: "idle" }, effect: "commit-boundary" };
       }
-      const overflow = facts.failed ? state.overflow : "idle";
-      if (!facts.enabled || facts.failed) return { state: { request, overflow }, effect: "none" };
-      const commit = requested || facts.thresholdDue;
-      return { state: { request, overflow }, effect: commit ? "commit-boundary" : "none" };
+      return { state: { request, overflow: "idle" }, effect: "none" };
     }
     case "before_settle": {
       const facts = event.facts;
-      if (state.overflow !== "pending" && state.overflow !== "pending-spent") return { state, effect: "none" };
-      if (facts.queued) return { state, effect: "none" };
-      const spent = state.overflow === "pending-spent";
-      if (!facts.enabled || !facts.automaticResetEnabled || facts.aborted) {
-        return { state: { ...state, overflow: spent ? "spent" : "idle" }, effect: "none" };
+      if (facts.aborted) return { state: initialResetControl(), effect: "none" };
+      const request = requestForWindow(state.request, facts.windowId);
+      if (state.overflow === "pending" || state.overflow === "pending-spent") {
+        if (facts.queued) {
+          return { state: { ...state, request: facts.failed ? NO_REQUEST : request }, effect: "none" };
+        }
+        const spent = state.overflow === "pending-spent";
+        if (!facts.enabled || !facts.automaticResetEnabled) {
+          return { state: { request: facts.failed ? NO_REQUEST : request, overflow: spent ? "spent" : "idle" }, effect: "none" };
+        }
+        return { state: { request: NO_REQUEST, overflow: "spent" }, effect: spent ? "none" : "recover-overflow" };
+      }
+      if (facts.failed || !facts.enabled || request.phase !== "close-out") {
+        return { state: { ...state, request: NO_REQUEST }, effect: "none" };
       }
-      return { state: { ...state, overflow: "spent" }, effect: spent ? "none" : "recover-overflow" };
+      if (facts.queued) return { state: { ...state, request }, effect: "none" };
+      if (request.source === "automatic" && !facts.automaticResetEnabled) {
+        return { state: { ...state, request: NO_REQUEST }, effect: "none" };
+      }
+      return { state: { request: NO_REQUEST, overflow: "idle" }, effect: "commit-boundary" };
     }
     case "settled":
-      return { state: { ...state, overflow: "idle" }, effect: "none" };
+      return { state: initialResetControl(), effect: "none" };
     case "abort":
     case "clear":
       return { state: initialResetControl(), effect: "none" };
@@ -1543,27 +1737,38 @@ function reduceResetControl(state, event) {
 }
 function registerResetLifecycle(pi, options) {
   let sessionActive = true;
+  let lifecycleGeneration = 0;
   let control = initialResetControl();
   const clear = () => {
     control = reduceResetControl(control, { type: "clear" }).state;
   };
-  const resetBoundaryResult = (entries, ctx) => {
+  const resetBoundaryResult = async (entries, ctx) => {
+    const generation = lifecycleGeneration;
+    const outerGeneration = options.getLifecycleGeneration?.();
+    const sessionId = ctx.sessionManager.getSessionId();
+    const windowId = currentWindowId(ctx);
+    const isCurrent = () => sessionActive && lifecycleGeneration === generation && (outerGeneration === void 0 || options.getLifecycleGeneration?.() === outerGeneration) && options.isEnabled() && ctx.signal?.aborted !== true && ctx.sessionManager.getSessionId() === sessionId && currentWindowId(ctx) === windowId;
+    let resetDrafts;
     try {
-      return { entries: [...entries, ...options.buildReset(ctx)], continue: true };
+      resetDrafts = await options.buildReset(ctx, isCurrent);
     } catch (error) {
-      ctx.ui.notify(`pi-context: could not build reset (${String(error)}).`, "warning");
+      if (isCurrent()) ctx.ui.notify(`pi-context: could not build reset (${String(error)}).`, "warning");
       return entries.length > 0 ? { entries } : void 0;
     }
+    if (!isCurrent()) return entries.length > 0 ? { entries } : void 0;
+    options.onResetReady?.(ctx, resetDrafts);
+    return { entries: [...entries, ...resetDrafts], continue: true };
   };
-  pi.on("turn_end", (event, ctx) => {
+  pi.on("turn_end", async (event, ctx) => {
     if (!sessionActive) return void 0;
     const aborted = isAbort(event.message, event.outcome, ctx);
     const stagedBudgetEntries = options.budget.consumeTurnEnd(ctx);
-    const budgetEntries = options.isEnabled() && !aborted ? stagedBudgetEntries : [];
+    const budgetEntries = options.isEnabled() && !aborted && event.outcome !== "error" ? stagedBudgetEntries : [];
     const entries = [...event.entries ?? [], ...budgetEntries];
     const decision = reduceResetControl(control, {
       type: "turn_end",
       facts: {
+        windowId: currentWindowId(ctx),
         aborted,
         overflow: aborted ? false : isOverflowLike(event.message, ctx),
         failed: event.outcome === "error",
@@ -1574,20 +1779,21 @@ function registerResetLifecycle(pi, options) {
         get automaticResetEnabled() {
           return options.budget.automaticResetEnabled(ctx);
         },
-        get thresholdDue() {
-          return options.budget.resetDue(ctx);
+        get hardReserveDue() {
+          return options.budget.hardReserveDue(ctx);
         }
       }
     });
     control = decision.state;
-    if (decision.effect === "commit-boundary") return resetBoundaryResult(entries, ctx);
+    if (decision.effect === "commit-boundary") return await resetBoundaryResult(entries, ctx);
     return entries.length > 0 ? { entries } : void 0;
   });
-  pi.on("agent_before_settle", (event, ctx) => {
+  pi.on("agent_before_settle", async (event, ctx) => {
     if (!sessionActive) return void 0;
     const decision = reduceResetControl(control, {
       type: "before_settle",
       facts: {
+        windowId: currentWindowId(ctx),
         get queued() {
           return event.context.pendingMessages.length > 0 || ctx.hasPendingMessages();
         },
@@ -1597,14 +1803,13 @@ function registerResetLifecycle(pi, options) {
         get automaticResetEnabled() {
           return options.budget.automaticResetEnabled(ctx);
         },
-        get aborted() {
-          return event.outcome === "aborted" || ctx.signal?.aborted === true;
-        }
+        aborted: event.outcome === "aborted" || ctx.signal?.aborted === true,
+        failed: event.outcome === "error"
       }
     });
     control = decision.state;
-    if (decision.effect !== "recover-overflow") return void 0;
-    return resetBoundaryResult(event.entries, ctx);
+    if (decision.effect !== "commit-boundary" && decision.effect !== "recover-overflow") return void 0;
+    return await resetBoundaryResult(event.entries, ctx);
   });
   pi.on("session_before_compact", (event, ctx) => {
     if (!sessionActive) return void 0;
@@ -1619,26 +1824,36 @@ function registerResetLifecycle(pi, options) {
     return void 0;
   });
   pi.on("agent_end", (_event, ctx) => {
-    if (ctx.signal?.aborted) clear();
+    if (ctx.signal?.aborted) control = reduceResetControl(control, { type: "abort" }).state;
   });
   pi.on("agent_settled", () => {
     control = reduceResetControl(control, { type: "settled" }).state;
   });
   pi.on("session_start", () => {
+    lifecycleGeneration++;
     clear();
     sessionActive = true;
   });
-  pi.on("session_tree", clear);
+  pi.on("session_tree", () => {
+    lifecycleGeneration++;
+    clear();
+  });
   pi.on("session_shutdown", () => {
+    lifecycleGeneration++;
     clear();
     options.budget.clear();
     sessionActive = false;
   });
   return {
-    request() {
-      const decision = reduceResetControl(control, { type: "request" });
+    closeOut(windowId, source) {
+      const decision = reduceResetControl(control, { type: "close_out", windowId, source });
       control = decision.state;
-      return decision.effect === "already-requested" ? "rollover_already_pending" : "rollover_requested";
+      return decision.effect;
+    },
+    request(windowId) {
+      const decision = reduceResetControl(control, { type: "tool_request", windowId });
+      control = decision.state;
+      return decision.effect === "already-pending" ? "rollover_already_pending" : "rollover_requested";
     },
     clear
   };
@@ -1647,7 +1862,7 @@ function registerResetLifecycle(pi, options) {
 // src/context/reset-artifacts.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
 
-// src/notes/notes-snapshot.ts
+// src/pi/notes/snapshot.ts
 var NOTES_HOMES = [
   { scope: "session", label: "this session" },
   { scope: "project", label: "@project" },
@@ -1655,13 +1870,19 @@ var NOTES_HOMES = [
   { scope: "agent", label: "@self" },
   { scope: "model", label: "@model" }
 ];
-function loadNotesSnapshot(ctx, loadHome = (context, scope) => listNotes(context, { scope })) {
+function queryForScope(scope) {
+  if (scope === "agent" || scope === "model") return { scope };
+  return { scope };
+}
+async function loadNotesSnapshot(ctx, loadHome, identity = notesContextFromPi(ctx)) {
   const openedAt = Date.now();
+  const store = createNotesStore(identity);
+  const load = loadHome ?? ((_context, scope) => store.list(queryForScope(scope)));
   const homes = /* @__PURE__ */ new Map();
   const unavailable = [];
   for (const home of NOTES_HOMES) {
     try {
-      homes.set(home.scope, loadHome(ctx, home.scope));
+      homes.set(home.scope, await load(ctx, home.scope));
     } catch (error) {
       const code = typeof error === "object" && error !== null ? error.code : void 0;
       if (typeof code !== "string" || !/^E[A-Z0-9_]+$/.test(code) || code.startsWith("ERR_")) throw error;
@@ -1673,20 +1894,19 @@ function loadNotesSnapshot(ctx, loadHome = (context, scope) => listNotes(context
 }
 
 // src/context/boot.ts
-function bootContent(ctx, currentId, previousId, notes) {
-  return renderBootBlock({
-    agentName: agentSlug(ctx),
-    modelName: modelSlug(ctx),
-    firstWindowId: rootWindowId(ctx.sessionManager.getSessionId()),
-    currentWindowId: currentId,
-    previousWindowId: previousId,
-    notes
-  });
+function bootContent(agentName, modelName, firstWindowId, currentId, previousId, notes) {
+  return renderBootBlock({ agentName, modelName, firstWindowId, currentWindowId: currentId, previousWindowId: previousId, notes });
 }
-function buildBootMessage(ctx, windowId, previousId, notifyIncompleteNotes) {
-  const notes = loadNotesSnapshot(ctx);
-  notifyIncompleteNotes?.(ctx, windowId, notes);
-  return { customType: BOOT_TYPE, content: bootContent(ctx, windowId, previousId, notes), display: false, details: { windowId } };
+async function buildBootMessage(ctx, windowId, previousId, notifyIncompleteNotes, isCurrent = () => true) {
+  const identity = notesContextFromPi(ctx);
+  const notes = await loadNotesSnapshot(ctx, void 0, 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 }
+  };
 }
 function sendBoot(pi, boot) {
   pi.sendMessage(
@@ -1694,15 +1914,20 @@ function sendBoot(pi, boot) {
     { triggerTurn: false }
   );
 }
-function ensureBoot(pi, ctx, notifyIncompleteNotes) {
+async function ensureBoot(pi, ctx, notifyIncompleteNotes, isCurrent = () => true) {
+  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, void 0, notifyIncompleteNotes));
+  const boot = await buildBootMessage(ctx, windowId, void 0, notifyIncompleteNotes, stillCurrent);
+  if (!stillCurrent()) return;
+  if (ctx.sessionManager.buildSessionProjection().messages.some((message) => isWindowBoot(message, windowId))) return;
+  sendBoot(pi, boot);
 }
 
 // src/context/reset-artifacts.ts
@@ -1715,8 +1940,10 @@ function sendContinuation(pi) {
     { triggerTurn: false }
   );
 }
-function buildResetDrafts(ctx, notifyIncompleteNotes) {
-  const sessionPrefix = ctx.sessionManager.getSessionId().slice(0, 8);
+async function buildResetDrafts(ctx, notifyIncompleteNotes, isCurrent = () => true) {
+  const sessionId = ctx.sessionManager.getSessionId();
+  const previousId = currentWindowId(ctx);
+  const sessionPrefix = sessionId.slice(0, 8);
   const usedWindowIds = new Set(
     ctx.sessionManager.getBranch().filter(isWindowMarker).map((entry) => entry.data.windowId)
   );
@@ -1724,26 +1951,14 @@ function buildResetDrafts(ctx, notifyIncompleteNotes) {
   do {
     windowId = `pcw:${sessionPrefix}:${randomUUID2().slice(0, 8)}`;
   } while (usedWindowIds.has(windowId));
-  const boot = buildBootMessage(ctx, windowId, currentWindowId(ctx), notifyIncompleteNotes);
+  const boot = await buildBootMessage(ctx, windowId, previousId, notifyIncompleteNotes, isCurrent);
   return [
+    { type: "compaction", summary: "", firstKeptEntryId: null },
     { type: "custom", customType: RESET_MARKER_TYPE, data: { windowId } },
     { type: "custom_message", customType: BOOT_TYPE, content: boot.content, display: false, details: { windowId } },
     { type: "custom_message", customType: CONTINUATION_TYPE, content: CONTINUATION, display: false }
   ];
 }
-function persistManualReset(pi, ctx, notifyIncompleteNotes) {
-  const [marker, boot, continuation] = buildResetDrafts(ctx, notifyIncompleteNotes);
-  pi.appendEntry(marker.customType, marker.data);
-  pi.sendMessage(
-    { customType: boot.customType, content: boot.content, display: boot.display, details: boot.details },
-    { triggerTurn: false }
-  );
-  pi.sendMessage(
-    { customType: continuation.customType, content: continuation.content, display: continuation.display },
-    { triggerTurn: false }
-  );
-  return boot.details.windowId;
-}
 function inspectResetTail(ctx, markerId, windowId) {
   const branch = ctx.sessionManager.getBranch();
   const markerIndex = branch.findIndex((entry) => entry.id === markerId);
@@ -1771,11 +1986,15 @@ function resetTailCommitted(ctx, markerId, windowId) {
   const tail = inspectResetTail(ctx, markerId, windowId);
   return tail?.boot === true && tail.continuation === true;
 }
-function repairResetTail(pi, ctx, marker, notifyIncompleteNotes) {
+async function repairResetTail(pi, ctx, marker, notifyIncompleteNotes, isCurrent = () => true) {
   const tail = inspectResetTail(ctx, marker.id, marker.data.windowId);
   if (!tail || tail.boot && tail.continuation) return;
-  if (!tail.boot) sendBoot(pi, buildBootMessage(ctx, marker.data.windowId, previousWindowId(ctx, marker.id), notifyIncompleteNotes));
-  if (!tail.continuation) sendContinuation(pi);
+  const boot = tail.boot ? void 0 : await buildBootMessage(ctx, marker.data.windowId, previousWindowId(ctx, marker.id), notifyIncompleteNotes, isCurrent);
+  if (!isCurrent()) return;
+  const latest = inspectResetTail(ctx, marker.id, marker.data.windowId);
+  if (!latest) return;
+  if (!latest.boot && boot) sendBoot(pi, boot);
+  if (!latest.continuation && (latest.boot || boot)) sendContinuation(pi);
 }
 
 // src/context/runtime.ts
@@ -1785,6 +2004,7 @@ function branchHasWindowMarker(ctx, fromId) {
 }
 function registerContext(pi, settingsManager) {
   let enabled = true;
+  let lifecycleGeneration = 0;
   let missingBootNotice;
   const incompleteNotesNotified = /* @__PURE__ */ new Set();
   const pendingResetNotices = /* @__PURE__ */ new Set();
@@ -1794,7 +2014,7 @@ function registerContext(pi, settingsManager) {
     const branch = ctx.sessionManager.getBranch();
     for (const windowId of pendingResetNotices) {
       const marker = branch.find((entry) => isWindowMarker(entry) && entry.data.windowId === windowId);
-      if (!marker || !resetTailCommitted(ctx, marker.id, windowId)) continue;
+      if (!marker || !isCheckpointBackedReset(ctx, marker) || !resetTailCommitted(ctx, marker.id, windowId)) continue;
       pendingResetNotices.delete(windowId);
       ctx.ui.notify(`pi-context: memory cleared \xB7 ${windowId}`, "info");
     }
@@ -1812,17 +2032,23 @@ function registerContext(pi, settingsManager) {
   };
   const migrationWarning = migrateLegacyHomes();
   if (migrationWarning) console.warn(`pi-context: ${migrationWarning}`);
-  const budget = registerBudget(pi, () => enabled, settingsManager);
-  pi.on("session_start", (_event, ctx) => {
+  const budget = registerBudget(pi, () => enabled, settingsManager, (windowId) => resets.closeOut(windowId, "automatic"));
+  pi.on("session_start", async (_event, ctx) => {
+    const generation = ++lifecycleGeneration;
     if (!enabled) return;
     missingBootNotice = void 0;
     pendingResetNotices.clear();
-    ensureBoot(pi, ctx, notifyIncompleteNotes);
+    await ensureBoot(pi, ctx, notifyIncompleteNotes, () => generation === lifecycleGeneration && enabled);
   });
-  pi.on("session_tree", (_event, ctx) => {
+  pi.on("session_tree", async (_event, ctx) => {
+    const generation = ++lifecycleGeneration;
     missingBootNotice = void 0;
     pendingResetNotices.clear();
-    if (enabled) ensureBoot(pi, ctx, notifyIncompleteNotes);
+    if (enabled) await ensureBoot(pi, ctx, notifyIncompleteNotes, () => generation === lifecycleGeneration && enabled);
+  });
+  pi.on("session_shutdown", () => {
+    lifecycleGeneration++;
+    pendingResetNotices.clear();
   });
   pi.on("session_before_tree", (event, ctx) => {
     if (!event.preparation.userWantsSummary) return void 0;
@@ -1834,7 +2060,11 @@ function registerContext(pi, settingsManager) {
     const reset = currentReset(ctx);
     const windowId = reset?.data.windowId ?? rootWindowId(ctx.sessionManager.getSessionId());
     try {
-      return { messages: reset ? projectWindow(event.messages, windowId) : projectRootWindow(event.messages, windowId) };
+      if (reset) {
+        if (!event.messages.some((message) => isWindowBoot(message, windowId))) throw new Error(`Missing boot for context window ${windowId}`);
+        return { messages: isCheckpointBackedReset(ctx, reset) ? event.messages : projectWindow(event.messages, windowId) };
+      }
+      return { messages: projectRootWindow(event.messages, windowId) };
     } catch (error) {
       if (missingBootNotice !== windowId) {
         missingBootNotice = windowId;
@@ -1852,9 +2082,12 @@ function registerContext(pi, settingsManager) {
       const arg = args.trim().toLowerCase();
       if (arg === "on") {
         enabled = true;
-        ensureBoot(pi, cmdCtx, notifyIncompleteNotes);
+        const generation = ++lifecycleGeneration;
+        await ensureBoot(pi, cmdCtx, notifyIncompleteNotes, () => generation === lifecycleGeneration && enabled);
       } else if (arg === "off") {
         enabled = false;
+        lifecycleGeneration++;
+        pendingResetNotices.clear();
         budget.clear();
         resets.clear();
       } else if (arg !== "") {
@@ -1865,16 +2098,25 @@ function registerContext(pi, settingsManager) {
     }
   });
   pi.registerCommand("wipe-memory", {
-    description: "Persist a fresh context window without calling the model",
+    description: "Ask the agent to close out its notes, then start a fresh context window",
     handler: async (_args, cmdCtx) => {
       if (!enabled) {
         cmdCtx.ui.notify("pi-context: /wipe-memory requires /pi-context on.", "error");
         return;
       }
+      const requestedWindowId = currentWindowId(cmdCtx);
+      await cmdCtx.waitForIdle();
+      if (!enabled || currentWindowId(cmdCtx) !== requestedWindowId) return;
+      const armed = resets.closeOut(requestedWindowId, "manual");
+      if (armed === "already-pending") return;
+      try {
+        pi.sendMessage({ customType: WARNING_TYPE, content: WARNING_CONTENT, display: false }, { triggerTurn: true });
+      } catch (error) {
+        resets.clear();
+        cmdCtx.ui.notify(`pi-context: could not start manual close-out (${String(error)}).`, "error");
+        return;
+      }
       await cmdCtx.waitForIdle();
-      if (!enabled) return;
-      resets.clear();
-      notifyCommittedResets(cmdCtx, persistManualReset(pi, cmdCtx, notifyIncompleteNotes));
     }
   });
   pi.registerTool(defineTool4({
@@ -1882,23 +2124,27 @@ function registerContext(pi, settingsManager) {
     label: "Wipe memory",
     description: "Wipe your in-context memory and start a fresh context window. Your session, notes, and history survive.",
     parameters: Type5.Object({}, { additionalProperties: false }),
-    async execute() {
+    async execute(_id, _params, _signal, _update, ctx) {
       if (!enabled) return output({ error: "pi-context is off (/pi-context on to enable)" });
-      return output({ status: resets.request() }, void 0, true);
+      return output({ status: resets.request(currentWindowId(ctx)) }, void 0, true);
     }
   }));
   const resets = registerResetLifecycle(pi, {
     isEnabled: () => enabled,
-    buildReset: (ctx) => {
-      const drafts = buildResetDrafts(ctx, notifyIncompleteNotes);
-      pendingResetNotices.add(drafts[1].details.windowId);
-      return drafts;
+    buildReset: (ctx, isCurrent) => buildResetDrafts(ctx, notifyIncompleteNotes, isCurrent),
+    getLifecycleGeneration: () => lifecycleGeneration,
+    onResetReady: (_ctx, drafts) => {
+      const boot = drafts.find((draft) => draft.type === "custom_message" && draft.customType === BOOT_TYPE);
+      if (boot?.type === "custom_message" && boot.details && typeof boot.details === "object") {
+        const windowId = boot.details.windowId;
+        if (typeof windowId === "string") pendingResetNotices.add(windowId);
+      }
     },
     budget
   });
 }
 
-// src/notes/session-replay.ts
+// src/pi/notes/session-replay.ts
 function isNoteOperation(data) {
   if (typeof data !== "object" || data === null) return false;
   const op = data;
@@ -1941,7 +2187,7 @@ function createPiContext(options = {}) {
 function piContext(pi) {
   registerPiContext(pi);
 }
-var internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, CONTINUATION_TYPE, WARNING_PROMPT, WARNING_RUNWAY_TOKENS, RESET_MARKER_TYPE, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, assertVirtualPath };
+var internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, CONTINUATION_TYPE, WARNING_PROMPT, WARNING_CONTENT, WARNING_RUNWAY_TOKENS, RESET_MARKER_TYPE, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, assertVirtualPath };
 export {
   createPiContext,
   piContext as default,