@astrosheep/pi-context 0.20.0 → 0.21.0

package/dist/src/budget.js

@@ -5,7 +5,11 @@ import { thresholdsFor, resetThresholds } from "./thresholds.js";
 import { currentWindowId, hasWindowMessage } from "./history.js";
 import { tokenBudgetGuidance } from "./prompts.js";
 import { output } from "./tool-output.js";
-export { deriveThresholds, mergePiContextSettings } from "./thresholds.js";
+/** Remaining tokens in the current context window, or null when Pi has no usage estimate. */
+export function remainingTokens(ctx) {
+    const usage = ctx.getContextUsage();
+    return !usage || usage.tokens === null ? null : Math.max(0, usage.contextWindow - usage.tokens);
+}
 export function registerBudget(pi, isEnabled) {
     let guidancePersistedInWindow;
     pi.on("session_start", (_event, ctx) => { guidancePersistedInWindow = undefined; resetThresholds(); thresholdsFor(ctx); });
@@ -15,10 +19,9 @@ export function registerBudget(pi, isEnabled) {
             return undefined;
         // The early reminder persists once per window the first time remaining crosses
         // reserve+margin. It never edits the outgoing request.
-        const usage = ctx.getContextUsage();
-        if (!usage || usage.tokens === null)
+        const remaining = remainingTokens(ctx);
+        if (remaining === null)
             return undefined;
-        const remaining = Math.max(0, usage.contextWindow - usage.tokens);
         const windowId = currentWindowId(ctx);
         const { reminder, reserve, warning } = thresholdsFor(ctx);
         // The final warning owns the deep band: when it has fired (or is due now),
@@ -26,7 +29,7 @@ export function registerBudget(pi, isEnabled) {
         // the wipe, at a worse position. See warning.ts.
         if (remaining <= warning || hasWindowMessage(ctx, WARNING_TYPE))
             return undefined;
-        if (remaining <= reminder && guidancePersistedInWindow !== windowId && !hasWindowMessage(ctx, GUIDANCE_TYPE)) {
+        if (remaining <= reminder && guidancePersistedInWindow !== windowId) {
             guidancePersistedInWindow = windowId;
             // Persist once per window — no transient copy. A transient bridge would
             // cover the crossing request, but history would record the reminder after
@@ -53,11 +56,10 @@ export function registerBudget(pi, isEnabled) {
         description: "Return estimated context tokens left before your memory is wiped; null when Pi cannot estimate usage.",
         parameters: Type.Object({}, { additionalProperties: false }),
         async execute(_id, _params, _signal, _update, ctx) {
-            const usage = ctx.getContextUsage();
             // The countdown the model sees ends at the warning line (reserve + runway);
             // the runway below it is overdraft the model never sees. See protocol.ts.
-            const remaining = usage?.tokens === null || usage === undefined ? null : Math.max(0, usage.contextWindow - usage.tokens - thresholdsFor(ctx).warning);
-            return output({ remaining_tokens: remaining });
+            const remaining = remainingTokens(ctx);
+            return output({ remaining_tokens: remaining === null ? null : Math.max(0, remaining - thresholdsFor(ctx).warning) });
         },
     }));
 }

package/dist/src/dream/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { acquireLock, failLock, releaseLock } from "./lock.js";
 import { materialGate, timeGate } from "./gates.js";
 import { loadPlaybook, runDreamer } from "./runner.js";
-import { applyManifest } from "./apply.js";
+import { gitCommit } from "./git.js";
+import { notesRoot } from "../notes/paths.js";
 function args(argv) { const out = {}; for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force" || a === "--help")
@@ -27,10 +27,10 @@ function packageRoot() {
 export async function main(argv = process.argv.slice(2)) {
     const a = args(argv);
     if (a.help) {
-        console.log("dream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <cmd>] [--dreamer-model <pattern>] [--playbook <path>]\nDefault dreamer: in-process pi SDK session with read-only tools; use a cheap model in production. Default playbook: <installed package root>/playbook.md; --playbook overrides it.");
+        console.log("dream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <model pattern>] [--playbook <path>]\nDefault dreamer: in-process pi SDK session with jailed file tools. Default playbook: <installed package root>/playbook.md; --playbook overrides it.");
         return 0;
     }
-    const home = resolve(String(a["notes-home"] ?? process.env.PI_NOTES_HOME ?? join(homedir(), ".agents", "notes")));
+    const home = resolve(String(a["notes-home"] ?? notesRoot()));
     process.env.PI_NOTES_HOME = home;
     mkdirSync(home, { recursive: true });
     const lockPath = join(home, ".dream.lock");
@@ -58,15 +58,16 @@ export async function main(argv = process.argv.slice(2)) {
     }
     const stamp = new Date(lock.startedAt).toISOString().replace(/[:.]/g, "-");
     const reportPath = join(home, "dreams", `${stamp}.md`);
+    gitCommit(home, `baseline ${stamp}`);
     try {
         const defaultBook = join(packageRoot(), "playbook.md");
         const playbookPath = String(a.playbook ?? defaultBook);
         const playbook = loadPlaybook(playbookPath);
-        const manifest = await runDreamer(playbook, home, { command: a.dreamer ? String(a.dreamer) : undefined, modelPattern: a["dreamer-model"] ? String(a["dreamer-model"]) : undefined });
-        const ctx = { cwd: home, sessionManager: { getSessionId: () => "dream" } };
-        const actions = applyManifest(ctx, home, stamp, manifest);
+        const result = await runDreamer(playbook, home, { modelPattern: a.dreamer ? String(a.dreamer) : undefined });
+        const writes = result.writes.length ? result.writes.map((w) => `- ${w.tool}: ${w.path}`).join("\n") : "- no changes";
         mkdirSync(join(home, "dreams"), { recursive: true });
-        writeFileSync(reportPath, `# Dream ${stamp}\n\n${manifest.report}\n\n${actions.map((x) => `- ${x}`).join("\n")}\n`);
+        writeFileSync(reportPath, `# Dream ${stamp}\n\n${result.report}\n\n${writes}\n`);
+        gitCommit(home, `dream ${stamp}`);
         console.log(reportPath);
         return 0;
     }

package/dist/src/dream/gates.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { sessionHomesRoot } from "../notes/paths.js";
 export function timeGate(lockPath, minHours, now = Date.now()) {
     if (!existsSync(lockPath))
         return { ok: true, reason: "time gate: no prior lock" };
@@ -7,7 +8,7 @@ export function timeGate(lockPath, minHours, now = Date.now()) {
     return age >= minHours * 3600000 ? { ok: true, reason: "time gate: stale" } : { ok: false, reason: "time gate: lock is too fresh" };
 }
 export function materialGate(home, lockMtime, minSessions) {
-    const root = join(home, "pi", "session");
+    const root = sessionHomesRoot(home);
     let changed = 0;
     if (existsSync(root))
         for (const dir of readdirSync(root, { withFileTypes: true })) {

package/dist/src/dream/git.js

@@ -0,0 +1,28 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Git audit layer for a dream run: one commit before (baseline) and one after
+ * (dream), so the human gate reviews `git show` instead of trusting a report,
+ * and rollback is `git revert`. This layer is a garnish, never load-bearing:
+ * every failure is logged and swallowed — a notes home without git, or a
+ * broken repo, still dreams. Nothing is committed when the tree is clean.
+ */
+export function gitCommit(home, message) {
+    try {
+        if (!existsSync(join(home, ".git"))) {
+            execFileSync("git", ["init", "-q"], { cwd: home, stdio: "ignore" });
+        }
+        execFileSync("git", ["add", "-A"], { cwd: home, stdio: "ignore" });
+        try {
+            execFileSync("git", ["diff", "--cached", "--quiet"], { cwd: home, stdio: "ignore" });
+            return; // clean tree — no empty commit
+        }
+        catch { /* staged changes exist — fall through to commit */ }
+        execFileSync("git", ["commit", "-q", "-m", message], { cwd: home, stdio: "ignore" });
+        console.log(`git: committed "${message}"`);
+    }
+    catch (error) {
+        console.log(`git audit layer skipped: ${error instanceof Error ? error.message : error}`);
+    }
+}

package/dist/src/dream/runner.js

@@ -1,8 +1,76 @@
-import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { createAgentSession, ModelRuntime, resolveModelScopeWithDiagnostics, SessionManager } from "@earendil-works/pi-coding-agent";
-import { parseManifest } from "./manifest.js";
-export const READ_ONLY_TOOLS = ["read", "grep", "find", "ls", "notes_read", "notes_list", "notes_search"];
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { createAgentSession, createEditToolDefinition, createWriteToolDefinition, ModelRuntime, resolveModelScopeWithDiagnostics, SessionManager } from "@earendil-works/pi-coding-agent";
+import { contentText } from "../history.js";
+export const DREAMER_TOOLS = ["read", "grep", "find", "ls", "write", "edit"];
+function isOutside(notesHome, target) {
+    const fromHome = relative(notesHome, target);
+    return fromHome === ".." || fromHome.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || isAbsolute(fromHome);
+}
+async function jailWritePath(notesHome, path) {
+    let realNotesHome;
+    try {
+        realNotesHome = await realpath(notesHome);
+    }
+    catch {
+        throw new Error(`write jail: cannot resolve notes home ${notesHome}`);
+    }
+    const target = resolve(realNotesHome, path);
+    const targetParent = dirname(target);
+    if (isOutside(realNotesHome, targetParent))
+        throw new Error(`write jail: ${path} is outside notes home ${notesHome}`);
+    // write creates parent directories itself. Create only after the lexical check, then
+    // canonicalize the parent so a symlink cannot lead the underlying tool out of home.
+    await mkdir(targetParent, { recursive: true });
+    let realTargetParent;
+    try {
+        realTargetParent = await realpath(targetParent);
+    }
+    catch {
+        throw new Error(`write jail: cannot resolve target parent in notes home ${notesHome}`);
+    }
+    if (isOutside(realNotesHome, realTargetParent))
+        throw new Error(`write jail: ${path} is outside notes home ${notesHome}`);
+    let targetStats;
+    try {
+        targetStats = await lstat(target);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw new Error(`write jail: cannot inspect target in notes home ${notesHome}`);
+    }
+    if (targetStats?.isSymbolicLink()) {
+        let realTarget;
+        try {
+            realTarget = await realpath(target);
+        }
+        catch {
+            throw new Error(`write jail: cannot resolve target in notes home ${notesHome}`);
+        }
+        if (isOutside(realNotesHome, realTarget))
+            throw new Error(`write jail: ${path} is outside notes home ${notesHome}`);
+    }
+    if (targetStats && targetStats.nlink > 1)
+        throw new Error(`write jail: ${path} has hard links and is not allowed in notes home ${notesHome}`);
+}
+function jailToolDefinition(definition, notesHome) {
+    const execute = definition.execute;
+    return {
+        ...definition,
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+            await jailWritePath(notesHome, params.path);
+            return execute(toolCallId, params, signal, onUpdate, ctx);
+        },
+    };
+}
+/** The only custom definitions in the dream session replace the two built-ins with jailed versions. */
+export function dreamerWriteToolDefinitions(notesHome) {
+    return [
+        jailToolDefinition(createWriteToolDefinition(notesHome), notesHome),
+        jailToolDefinition(createEditToolDefinition(notesHome), notesHome),
+    ];
+}
 export const defaultDreamerSessionFactory = async ({ cwd, modelPattern, tools }) => {
     let model;
     if (modelPattern) {
@@ -12,41 +80,32 @@ export const defaultDreamerSessionFactory = async ({ cwd, modelPattern, tools })
         if (!model)
             throw new Error(`dreamer model pattern "${modelPattern}" did not resolve to an available model`);
     }
-    const { session } = await createAgentSession({ cwd, sessionManager: SessionManager.inMemory(cwd), tools, noTools: "all", model });
+    const { session } = await createAgentSession({ cwd, sessionManager: SessionManager.inMemory(cwd), tools, customTools: dreamerWriteToolDefinitions(cwd), noTools: "all", model, thinkingLevel: "off" });
     return session;
 };
-export function runExternalDreamer(command, playbook, cwd) {
-    const result = spawnSync(command, { shell: true, cwd, input: playbook, encoding: "utf8" });
-    if (result.error || result.status !== 0)
-        throw new Error(`dreamer failed: ${result.error?.message ?? result.stderr ?? `exit ${result.status}`}`);
-    return parseManifest(result.stdout);
-}
 export async function runDreamer(playbook, cwd, options = {}) {
-    if (options.command)
-        return runExternalDreamer(options.command, playbook, cwd);
-    const session = await (options.sessionFactory ?? defaultDreamerSessionFactory)({ cwd, modelPattern: options.modelPattern, tools: READ_ONLY_TOOLS });
+    const session = await (options.sessionFactory ?? defaultDreamerSessionFactory)({ cwd, modelPattern: options.modelPattern, tools: DREAMER_TOOLS });
     let answer = "";
     let providerError;
+    const writes = [];
     const unsubscribe = session.subscribe((event) => {
+        const tool = event.toolName ?? event.tool?.name;
+        const args = event.args ?? event.arguments ?? event.tool?.arguments;
+        if ((tool === "write" || tool === "edit") && args && typeof args === "object" && typeof args.path === "string")
+            writes.push({ tool, path: args.path });
         if (event.type !== "message_end" || event.message?.role !== "assistant")
             return;
         if (event.message.stopReason === "error") {
             providerError = event.message.errorMessage ?? "unknown provider error";
             return;
         }
-        const content = event.message.content;
-        answer = typeof content === "string" ? content : Array.isArray(content) ? content.filter((part) => part.type === "text").map((part) => part.text).join("") : "";
+        answer = contentText(event.message.content);
     });
     try {
-        await session.prompt(`${playbook}\n\nReturn exactly one JSON manifest matching this schema: { merge?, promote?, trash?, pending?, skillCandidates?, report }.`);
-        try {
-            return parseManifest(answer);
-        }
-        catch (error) {
-            if (providerError)
-                throw new Error(`dreamer failed: ${providerError}`);
-            throw error;
-        }
+        await session.prompt(playbook);
+        if (providerError)
+            throw new Error(`dreamer failed: ${providerError}`);
+        return { report: answer, writes };
     }
     finally {
         unsubscribe?.();

package/dist/src/history-tools.js

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
-import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget } from "./tool-output.js";
+import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget, DEFAULT_READ_WINDOW_CHARS, HISTORY_PREVIEW_CHARS, MAX_READ_WINDOW_CHARS } from "./tool-output.js";
 import { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "./tool-schema.js";
 import { historyFromSession, filteredItems, visibleItem, allItems, vacuousRoleToolCombo, unknownWindowId } from "./history.js";
 /**
@@ -57,7 +57,7 @@ export function registerHistoryTools(pi) {
             const badWindow = unknownWindowId(ctx, params);
             if (badWindow)
                 return output({ error: badWindow.message, window_id: params.window_id, known_windows: badWindow.known });
-            const items = filteredItems(ctx, params).map((item) => visibleItem(item, params.max_chars_per_item ?? 1200));
+            const items = filteredItems(ctx, params).map((item) => visibleItem(item, params.max_chars_per_item ?? HISTORY_PREVIEW_CHARS));
             return output(page(items, params.cursor ?? 0, "items", params.limit, truncateHistoryItem));
         },
     }));
@@ -65,7 +65,7 @@ export function registerHistoryTools(pi) {
         name: "history_read",
         label: "History read item",
         description: "Read a bounded character range from one session item. Each response delivers the longest contiguous prefix of the requested window that fits the wire budget: follow the resume cursor to reconstruct the item exactly. A negative offset_chars counts back from the item's end. Offsets and counts are code points (an emoji or CJK character counts as one). The response is the raw item text behind a one-line [bracketed] header naming the item, the resolved offset, the delivered char range, and the resume cursor (continue at offset_chars=N, or end).",
-        parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from. A negative value counts back from the end; the response echoes the resolved absolute offset. Pass the previous next_offset_chars back unchanged to continue." })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: 50000, description: "Largest requested window in code points (default 12000). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes." })), window_id: Type.String() }, { additionalProperties: false }),
+        parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from. A negative value counts back from the end; the response echoes the resolved absolute offset. Pass the previous next_offset_chars back unchanged to continue." })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_READ_WINDOW_CHARS, description: `Largest requested window in code points (default ${DEFAULT_READ_WINDOW_CHARS}). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes.` })), window_id: Type.String() }, { additionalProperties: false }),
         async execute(_id, params, _signal, _update, ctx) {
             const item = allItems(ctx).find((candidate) => candidate.windowId === params.window_id && candidate.itemId === params.item_id);
             if (!item)
@@ -76,7 +76,7 @@ export function registerHistoryTools(pi) {
             if (typeof params.offset_chars === "number" && params.offset_chars > totalChars) {
                 return output({ error: `offset_chars ${params.offset_chars} is past the end: the item has ${totalChars} chars; the largest legal offset is ${totalChars} (an empty end-read)`, window_id: item.windowId, item_id: item.itemId, offset_chars: params.offset_chars, total_chars: totalChars });
             }
-            const limit_chars = Math.min(params.limit_chars ?? 12000, 50000);
+            const limit_chars = Math.min(params.limit_chars ?? DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS);
             return readCharacterWindow(item.content, params.offset_chars, params.limit_chars, (window) => {
                 const { content, ...cursor } = window;
                 return outputRaw(characterWindowHeader(`${item.windowId} · item ${item.itemId}`, window), content, { window_id: item.windowId, item_id: item.itemId, ...cursor, limit_chars });
@@ -98,7 +98,7 @@ export function registerHistoryTools(pi) {
             const queries = searchQueries(params.query);
             const matching = filteredItems(ctx, params)
                 .filter((item) => queries.some((query) => item.content.includes(query)))
-                .map((item) => ({ ...visibleItem(item, params.max_chars_per_item ?? 1200), match_offset_chars: earliestMatchOffsetChars(item.content, queries) }));
+                .map((item) => ({ ...visibleItem(item, params.max_chars_per_item ?? HISTORY_PREVIEW_CHARS), match_offset_chars: earliestMatchOffsetChars(item.content, queries) }));
             return output(page(matching, params.cursor ?? 0, "items", params.limit, truncateHistoryItem));
         },
     }));

package/dist/src/history.js

@@ -1,11 +1,12 @@
 import { RESET_V2 } from "./protocol.js";
+import { HISTORY_PREVIEW_CHARS } from "./tool-output.js";
 function isTextContent(part) {
     return typeof part === "object" && part !== null && part.type === "text" && typeof part.text === "string";
 }
-function contentText(content) {
+export function contentText(content) {
     if (typeof content === "string")
         return content;
-    return content.filter(isTextContent).map((part) => part.text).join("\n");
+    return Array.isArray(content) ? content.filter(isTextContent).map((part) => part.text).join("\n") : "";
 }
 function mapRole(role) {
     if (role === "user" || role === "assistant")
@@ -78,13 +79,17 @@ export function resetV2WindowId(details) {
     return candidate.windowId;
 }
 /** A compaction entry's window id: the extension-minted id for reset-v2, else Pi's entry id. */
-function windowIdOf(sessionId, entry) {
+export function windowIdOf(sessionId, entry) {
     return resetV2WindowId(entry.details) ?? `pcw:${sessionId.slice(0, 8)}:${entry.id}`;
 }
+/** Mint the durable identity of a session's root history window. */
+export function rootWindowId(sessionId) {
+    return `pcw:${sessionId.slice(0, 8)}:root`;
+}
 /** Build durable, on-demand history directly from every entry on the current session branch. */
 export function historyFromSession(ctx) {
     const sessionId = ctx.sessionManager.getSessionId();
-    let window = { windowId: `pcw:${sessionId.slice(0, 8)}:root`, items: [] };
+    let window = { windowId: rootWindowId(sessionId), items: [] };
     const windows = [window];
     for (const entry of ctx.sessionManager.getBranch()) {
         if (entry.type === "compaction") {
@@ -128,7 +133,7 @@ export function historyFromSession(ctx) {
     }
     return windows;
 }
-export function visibleItem(item, maxChars = 1200) {
+export function visibleItem(item, maxChars = HISTORY_PREVIEW_CHARS) {
     const characters = Array.from(item.content);
     const truncated = characters.length > maxChars;
     return {
@@ -206,5 +211,5 @@ export function currentWindowId(ctx) {
         if (entry?.type === "compaction")
             return windowIdOf(sessionId, entry);
     }
-    return `pcw:${sessionId.slice(0, 8)}:root`;
+    return rootWindowId(sessionId);
 }

package/dist/src/index.js

@@ -1,14 +1,14 @@
 import { registerHistoryTools } from "./history-tools.js";
-import { registerMemoryTools } from "./memory/tools.js";
-import { registerBudget, deriveThresholds, mergePiContextSettings } from "./budget.js";
+import { registerNotesTools } from "./notes/tools.js";
+import { registerBudget } from "./budget.js";
 import { output } from "./tool-output.js";
-export { deriveThresholds, mergePiContextSettings };
+import { deriveThresholds, mergePiContextSettings } from "./thresholds.js";
 import { STATE_TYPE, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, RESET_V2, MAX_NOTE_BYTES, 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, WARNING_RUNWAY_TOKENS, RESET_SUMMARY, CONTINUATION, WARNING_PROMPT } from "./protocol.js";
-import { historyFromSession, hasWindowMessage, currentWindowId, resetV2WindowId } from "./history.js";
-import { assertVirtualPath } from "./notes.js";
+import { historyFromSession, hasWindowMessage, currentWindowId, resetV2WindowId, rootWindowId, windowIdOf } from "./history.js";
+import { assertVirtualPath } from "./notes/model.js";
 import { bootBlock } from "./prompts.js";
 export { historyFromSession } from "./history.js";
-export { notesFromSession } from "./notes.js";
+export { notesFromSession } from "./notes/model.js";
 import { registerResetLifecycle } from "./reset-lifecycle.js";
 import { registerWarning } from "./warning.js";
 import { randomUUID } from "node:crypto";
@@ -24,8 +24,7 @@ export default function piContext(pi) {
         // The root window has no compaction entry to carry the boot block, so persist
         // it once as a hidden custom message. Reset windows already carry theirs at
         // position 0 in the compaction summary, so a resumed session adds nothing.
-        const sessionId = ctx.sessionManager.getSessionId();
-        const rootId = `pcw:${sessionId.slice(0, 8)}:root`;
+        const rootId = rootWindowId(ctx.sessionManager.getSessionId());
         if (currentWindowId(ctx) !== rootId || hasWindowMessage(ctx, BOOT_TYPE))
             return;
         pi.sendMessage({ customType: BOOT_TYPE, content: bootBlock(ctx, rootId, undefined, false), display: false }, { triggerTurn: false });
@@ -49,7 +48,7 @@ export default function piContext(pi) {
         },
     });
     registerHistoryTools(pi);
-    registerMemoryTools(pi);
+    registerNotesTools(pi);
     pi.registerTool(defineTool({
         name: "new_context",
         label: "New context",
@@ -70,16 +69,16 @@ export default function piContext(pi) {
         },
         onReset: (entryId) => pi.appendEntry(STATE_TYPE, { version: 1, lastResetEntryId: entryId }),
         buildReset: (event, ctx, explicit) => {
-            const session8 = ctx.sessionManager.getSessionId().slice(0, 8);
+            const sessionId = ctx.sessionManager.getSessionId();
             // Window IDs are independent of Pi entry IDs. Avoid reusing a window
             // identity already present on this branch.
             const windows = historyFromSession(ctx);
             const usedIds = new Set(windows.map((window) => window.windowId));
-            let minted = randomUUID().slice(0, 8);
-            while (usedIds.has(`pcw:${session8}:${minted}`))
-                minted = randomUUID().slice(0, 8);
-            const windowId = `pcw:${session8}:${minted}`;
-            const previousId = windows[windows.length - 1]?.windowId ?? `pcw:${session8}:root`;
+            let minted = { id: randomUUID().slice(0, 8) };
+            while (usedIds.has(windowIdOf(sessionId, minted)))
+                minted = { id: randomUUID().slice(0, 8) };
+            const windowId = windowIdOf(sessionId, minted);
+            const previousId = windows[windows.length - 1]?.windowId ?? rootWindowId(sessionId);
             // The reset marker stays as firstKeptEntryId; it no longer names the window.
             pi.appendEntry(RESET_MARKER_TYPE, { version: 1, reason: event.reason, requested: explicit });
             const markerId = ctx.sessionManager.getLeafId();

package/dist/src/notes/address.js

@@ -0,0 +1,31 @@
+import { assertVirtualPath } from "./model.js";
+const ADDRESS_FORMS = "legal prefixes are @project/ and @global/; bare names are the session home";
+/**
+ * Decode the one public note address into its physical home and virtual path. This is a
+ * tool-boundary rule: replay paths keep using assertVirtualPath directly and are untouched.
+ */
+export function assertAddress(value) {
+    if (typeof value !== "string")
+        throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+    let scope = "session";
+    let path = value;
+    if (value.startsWith("@project/")) {
+        scope = "project";
+        path = value.slice("@project/".length);
+    }
+    else if (value.startsWith("@global/")) {
+        scope = "global";
+        path = value.slice("@global/".length);
+    }
+    else if (value.startsWith("@")) {
+        throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+    }
+    if (path.includes("@"))
+        throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+    assertVirtualPath(path);
+    return { scope, path };
+}
+/** Render a virtual path in its one unambiguous public address form. */
+export function addressFor(scope, path) {
+    return scope === "session" ? path : `@${scope}/${path}`;
+}

package/dist/src/{memory → notes}/frontmatter.js

@@ -1,10 +1,10 @@
-import { localIso } from "../notes.js";
+import { localIso } from "./model.js";
 const SCOPES = ["session", "project", "global"];
 const ORIGINS = ["user", "self", "external"];
 const STATUSES = ["active", "superseded", "pending", "archived"];
 const TIMESTAMP_KEYS = ["created_at", "updated_at", "last_accessed"];
 /** Emission order, exactly the Design's key list. */
-const KNOWN_KEYS = ["scope", "origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count", "source_window", "supersedes", "recurrence_count", "recurrence_windows"];
+const KNOWN_KEYS = ["origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count", "source_window", "supersedes", "recurrence_count", "recurrence_windows"];
 export function isScope(value) {
     return typeof value === "string" && SCOPES.includes(value);
 }
@@ -120,7 +120,9 @@ export function serializeNote(meta, body) {
             lines.push(`${key}: ${yamlScalar(value)}`);
     }
     for (const key of Object.keys(meta)) {
-        if (KNOWN_KEYS.includes(key))
+        // scope is a legacy on-disk field. Store callers derive it from the home's location,
+        // but serialization intentionally drops it on the next write.
+        if (key === "scope" || KNOWN_KEYS.includes(key))
             continue;
         if (meta[key] === undefined)
             continue;

package/dist/src/{notes.js → notes/model.js}

@@ -1,4 +1,4 @@
-import { MAX_NOTE_BYTES, NOTE_TYPE } from "./protocol.js";
+import { MAX_NOTE_BYTES, NOTE_TYPE } from "../protocol.js";
 export function assertVirtualPath(value) {
     if (typeof value !== "string" || value.length === 0)
         throw new Error("path must be a non-empty virtual relative path");

package/dist/src/{memory → notes}/paths.js

@@ -7,6 +7,10 @@ export function notesRoot() {
     const override = process.env.PI_NOTES_HOME;
     return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
 }
+/** Absolute directory holding the per-session note homes. */
+export function sessionHomesRoot(home = notesRoot()) {
+    return join(home, "pi", "session");
+}
 /**
  * Absolute git root for `cwd`, walking upward until a directory holds a `.git` entry.
  * No git root yields undefined, which projectKey then replaces with the cwd itself.
@@ -39,7 +43,7 @@ export function scopeDir(scope, ctx) {
         return join(notesRoot(), "global");
     if (scope === "project")
         return join(notesRoot(), "project", projectKey(ctx.cwd));
-    return join(notesRoot(), "pi", "session", sessionId(ctx));
+    return join(sessionHomesRoot(), sessionId(ctx));
 }
 /**
  * Notes are markdown files: a virtual path without an `.md` suffix gains one, an explicit