@astrosheep/pi-context 0.20.0 → 0.22.0

package/src/dream/gates.ts

@@ -1,19 +1,26 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { sessionHomesRoot } from "../notes/paths.js";
 
 export type GateResult = { ok: boolean; reason: string };
-export function timeGate(lockPath: string, minHours: number, now = Date.now()): GateResult {
-	if (!existsSync(lockPath)) return { ok: true, reason: "time gate: no prior lock" };
-	const age = now - statSync(lockPath).mtimeMs;
-	return age >= minHours * 3600000 ? { ok: true, reason: "time gate: stale" } : { ok: false, reason: "time gate: lock is too fresh" };
+
+/**
+ * The scheduler reads the last-run sidecar, not the lock: the lock's lifetime says
+ * nothing about when the last dream ran, while the sidecar records exactly that.
+ */
+export function timeGate(stampPath: string, minHours: number, now = Date.now()): GateResult {
+	if (!existsSync(stampPath)) return { ok: true, reason: "time gate: no prior dream" };
+	const age = now - statSync(stampPath).mtimeMs;
+	return age >= minHours * 3600000 ? { ok: true, reason: "time gate: stale" } : { ok: false, reason: "time gate: last dream is too recent" };
 }
-export function materialGate(home: string, lockMtime: number, minSessions: number): GateResult {
-	const root = join(home, "pi", "session");
+
+export function materialGate(home: string, sinceMtime: number, minSessions: number): GateResult {
+	const root = sessionHomesRoot(home);
 	let changed = 0;
 	if (existsSync(root)) for (const dir of readdirSync(root, { withFileTypes: true })) {
 		if (!dir.isDirectory()) continue;
 		const files = readdirSync(join(root, dir.name), { withFileTypes: true });
-		if (files.some((f) => f.isFile() && statSync(join(root, dir.name, f.name)).mtimeMs > lockMtime)) changed++;
+		if (files.some((f) => f.isFile() && statSync(join(root, dir.name, f.name)).mtimeMs > sinceMtime)) changed++;
 	}
 	return changed >= minSessions ? { ok: true, reason: `material gate: ${changed} changed sessions` } : { ok: false, reason: `material gate: only ${changed} changed sessions` };
 }

package/src/dream/git.ts

@@ -0,0 +1,73 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/**
+ * Outcome of one audit commit. `ok: true` always carries a real `commit` snapshot;
+ * `empty: true` only means no files changed (an empty baseline commit or no commit was
+ * needed). `ok: false` means the audit layer could not guarantee a snapshot.
+ */
+export type AuditResult =
+	| { ok: true; commit: string; empty: boolean }
+	| { ok: false; error: string };
+
+/** Lock runtime artifacts are not notes and must not appear in snapshots or `git status`. */
+const RUNTIME_IGNORE = ".dream.lock*";
+
+/** Add the runtime-artifact pattern to the repository's local exclude, once. */
+function ensureRuntimeIgnored(home: string): void {
+	try {
+		const exclude = join(home, ".git", "info", "exclude");
+		const current = existsSync(exclude) ? readFileSync(exclude, "utf8") : "";
+		if (current.split(/\r?\n/).includes(RUNTIME_IGNORE)) return;
+		mkdirSync(dirname(exclude), { recursive: true });
+		const prefix = current.length > 0 && !current.endsWith("\n") ? `${current}\n` : current;
+		writeFileSync(exclude, `${prefix}${RUNTIME_IGNORE}\n`);
+	} catch { /* best effort: an unignored lock only adds noise to the audit */ }
+}
+
+/**
+ * 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`. The caller decides how loud a failure is; this function only reports it.
+ * A clean tree on an established repository commits nothing; a repository with no HEAD
+ * gets an empty baseline commit, because an audit run with no snapshot is not a success.
+ */
+export function gitCommit(home: string, message: string): AuditResult {
+	try {
+		if (!existsSync(join(home, ".git"))) {
+			execFileSync("git", ["init", "-q"], { cwd: home, stdio: "ignore" });
+		}
+		ensureRuntimeIgnored(home);
+		execFileSync("git", ["add", "-A"], { cwd: home, stdio: "ignore" });
+		let clean = false;
+		try {
+			execFileSync("git", ["diff", "--cached", "--quiet"], { cwd: home, stdio: "ignore" });
+			clean = true; // clean tree — no empty commit on an established repository
+		} catch { clean = false; }
+		const before = headCommit(home);
+		if (!clean) {
+			execFileSync("git", ["commit", "-q", "-m", message], { cwd: home, stdio: "ignore" });
+			console.log(`git: committed "${message}"`);
+		} else if (before === undefined) {
+			// A newly initialized repository has no snapshot at all; give the audit one.
+			execFileSync("git", ["commit", "-q", "--allow-empty", "-m", message], { cwd: home, stdio: "ignore" });
+			console.log(`git: committed "${message}"`);
+		}
+		const commit = headCommit(home);
+		if (commit === undefined) return { ok: false, error: "audit commit produced no snapshot (no HEAD)" };
+		return { ok: true, commit, empty: clean };
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		console.log(`git audit layer failed: ${reason}`);
+		return { ok: false, error: reason };
+	}
+}
+
+/** HEAD sha, or undefined when the repository has no commit yet. */
+function headCommit(home: string): string | undefined {
+	try {
+		const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: home, encoding: "utf8" }).trim();
+		return head.length > 0 ? head : undefined;
+	} catch { return undefined; }
+}

package/src/dream/lock.ts

@@ -1,39 +1,82 @@
-import { existsSync, readFileSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { readFileSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
 
-export type LockState = { path: string; held: boolean; reason?: string; startedAt: number; priorMtime?: number };
-const HOUR = 60 * 60 * 1000;
+export type LockState = {
+	path: string;
+	held: boolean;
+	reason?: string;
+	startedAt: number;
+	/** mtime of the last-run sidecar before this run took the lock; failLock restores it. */
+	priorStampMtime?: number;
+	/** Random identity written into the lock file; cleanup only removes the lock it wrote. */
+	token?: string;
+};
 
-function live(pid: number): boolean {
-	if (!Number.isInteger(pid) || pid <= 0) return false;
-	try { process.kill(pid, 0); return true; } catch { return false; }
+/**
+ * The scheduler's last-run timestamp lives in a sidecar beside the lock, never in the
+ * lock file itself: acquiring, releasing or cleaning up the lock touches only the PID
+ * marker, so lock lifecycle does not destroy the timestamp the time gate reads.
+ */
+export function lastRunPath(lockPath: string): string {
+	return `${lockPath}.last-run`;
 }
 
+function readText(path: string): string | undefined {
+	try { return readFileSync(path, "utf8"); } catch { return undefined; }
+}
+
+function stampMtime(stampPath: string): number | undefined {
+	try { return statSync(stampPath).mtimeMs; } catch { return undefined; }
+}
+
+/**
+ * Cleanup ownership: only the exact marker this run wrote may be removed. The token is
+ * diagnostic and guards cleanup; it never grants permission to take an existing lock.
+ */
+function ownsLock(lock: LockState): boolean {
+	if (!lock.held || !lock.token) return false;
+	return readText(lock.path)?.trim() === `${process.pid} ${lock.token}`;
+}
+
+/**
+ * Acquire the dream lock with Git-style exclusive existence locking: one O_CREAT|O_EXCL
+ * creation. An existing path refuses acquisition regardless of its contents, PID, or age,
+ * and is never read for permission, replaced, or removed. There is no automatic stale
+ * recovery; a crash-left lock is human cleanup after confirming no dream is running.
+ */
 export function acquireLock(path: string): LockState {
 	const now = Date.now();
-	let priorMtime: number | undefined;
-	if (existsSync(path)) {
-		const stat = statSync(path);
-		priorMtime = stat.mtimeMs;
-		let pid = 0;
-		try { pid = Number.parseInt(readFileSync(path, "utf8").trim(), 10); } catch { /* reclaim */ }
-		if (now - stat.mtimeMs <= HOUR && live(pid)) return { path, held: false, reason: "lock gate: live process holds the lock", startedAt: now };
-		try { unlinkSync(path); } catch { return { path, held: false, reason: "lock gate: lock could not be reclaimed", startedAt: now }; }
+	const priorStampMtime = stampMtime(lastRunPath(path));
+	const token = randomUUID();
+	try {
+		writeFileSync(path, `${process.pid} ${token}`, { flag: "wx" });
+	} catch {
+		return { path, held: false, reason: "lock gate: lock already exists", startedAt: now };
 	}
-	writeFileSync(path, String(process.pid), { flag: "wx" });
-	return { path, held: true, startedAt: now, priorMtime };
+	// Only a held lock advances the scheduler timestamp.
+	try { writeFileSync(lastRunPath(path), new Date(now).toISOString()); } catch { /* advisory */ }
+	return { path, held: true, startedAt: now, priorStampMtime, token };
 }
 
+/** Release only the lock this run acquired. Idempotent: repeated cleanup does nothing. */
 export function releaseLock(lock: LockState): void {
-	// The lock is also the durable last-dream timestamp. Leave the PID marker in place;
-	// the next acquisition reclaims it once the PID is dead or it is older than an hour.
-}
-
-export function restoreMtime(path: string, mtimeMs: number): void {
-	try { utimesSync(path, new Date(), new Date(mtimeMs)); } catch { /* advisory */ }
+	if (!lock.held) return;
+	if (ownsLock(lock)) { try { unlinkSync(lock.path); } catch { /* best effort */ } }
+	lock.held = false;
 }
 
+/**
+ * A failed run must not advance the scheduler: restore the previous timestamp, or remove
+ * the one this run wrote when there was none. Only this run's own marker is removed, and
+ * the state is marked released so a later cleanup attempt is harmless.
+ */
 export function failLock(lock: LockState): void {
 	if (!lock.held) return;
-	if (lock.priorMtime === undefined) { try { unlinkSync(lock.path); } catch { /* best effort */ } }
-	else restoreMtime(lock.path, lock.priorMtime);
+	if (ownsLock(lock)) {
+		const stampPath = lastRunPath(lock.path);
+		if (lock.priorStampMtime === undefined) { try { unlinkSync(stampPath); } catch { /* best effort */ } }
+		else { try { utimesSync(stampPath, new Date(), new Date(lock.priorStampMtime)); } catch { /* best effort */ } }
+		try { unlinkSync(lock.path); } catch { /* best effort */ }
+	}
+	lock.held = false;
 }

package/src/dream/runner.ts

@@ -1,12 +1,77 @@
-import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { createAgentSession, ModelRuntime, resolveModelScopeWithDiagnostics, SessionManager, type AgentSession } from "@earendil-works/pi-coding-agent";
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { createAgentSession, createEditToolDefinition, createWriteToolDefinition, ModelRuntime, resolveModelScopeWithDiagnostics, SessionManager, type AgentSession, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { Api, Model } from "@earendil-works/pi-ai";
-import { parseManifest, type Manifest } from "./manifest.js";
+import { contentText } from "../history.js";
 
+export type DreamWrite = { tool: "write" | "edit"; path: string };
+export type DreamResult = { report: string; writes: DreamWrite[]; error?: string };
 export type DreamerSession = Pick<AgentSession, "prompt" | "subscribe" | "dispose">;
 export type DreamerSessionFactory = (options: { cwd: string; modelPattern?: string; tools: string[] }) => Promise<DreamerSession>;
-export const READ_ONLY_TOOLS = ["read", "grep", "find", "ls", "notes_read", "notes_list", "notes_search"];
+export const DREAMER_TOOLS = ["read", "grep", "find", "ls", "write", "edit"];
+
+function isOutside(notesHome: string, target: string): boolean {
+	const fromHome = relative(notesHome, target);
+	return fromHome === ".." || fromHome.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || isAbsolute(fromHome);
+}
+
+async function jailWritePath(notesHome: string, path: string): Promise<void> {
+	let realNotesHome: string;
+	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: string;
+	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: any) {
+		if (error.code !== "ENOENT") throw new Error(`write jail: cannot inspect target in notes home ${notesHome}`);
+	}
+	if (targetStats?.isSymbolicLink()) {
+		let realTarget: string;
+		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<T extends ToolDefinition<any, any, any>>(definition: T, notesHome: string): T {
+	const execute = definition.execute;
+	return {
+		...definition,
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			await jailWritePath(notesHome, (params as { path: string }).path);
+			return execute(toolCallId, params, signal, onUpdate, ctx);
+		},
+	} as T;
+}
+
+/** The only custom definitions in the dream session replace the two built-ins with jailed versions. */
+export function dreamerWriteToolDefinitions(notesHome: string): ToolDefinition<any, any, any>[] {
+	return [
+		jailToolDefinition(createWriteToolDefinition(notesHome), notesHome),
+		jailToolDefinition(createEditToolDefinition(notesHome), notesHome),
+	];
+}
 
 export const defaultDreamerSessionFactory: DreamerSessionFactory = async ({ cwd, modelPattern, tools }) => {
 	let model: Model<Api> | undefined;
@@ -16,38 +81,40 @@ export const defaultDreamerSessionFactory: DreamerSessionFactory = async ({ cwd,
 		model = result.scopedModels[0]?.model;
 		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: string, playbook: string, cwd: string): Manifest {
-	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: string, cwd: string, options: { command?: string; modelPattern?: string; sessionFactory?: DreamerSessionFactory } = {}): Promise<Manifest> {
-	if (options.command) return runExternalDreamer(options.command, playbook, cwd);
-	const session = await (options.sessionFactory ?? defaultDreamerSessionFactory)({ cwd, modelPattern: options.modelPattern, tools: READ_ONLY_TOOLS });
+/**
+ * Run one dream turn. A dreamer failure is returned as `error` together with the partial
+ * writes observed so far, so the caller can record partial state instead of losing it;
+ * only a failure to even start the session throws.
+ */
+export async function runDreamer(playbook: string, cwd: string, options: { modelPattern?: string; sessionFactory?: DreamerSessionFactory } = {}): Promise<DreamResult> {
+	const session = await (options.sessionFactory ?? defaultDreamerSessionFactory)({ cwd, modelPattern: options.modelPattern, tools: DREAMER_TOOLS });
 	let answer = "";
 	let providerError: string | undefined;
+	const writes: DreamWrite[] = [];
 	const unsubscribe = session.subscribe((event: any) => {
+		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: any) => part.type === "text").map((part: any) => 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);
+			await session.prompt(playbook);
 		} catch (error) {
-			if (providerError) throw new Error(`dreamer failed: ${providerError}`);
-			throw error;
+			return { report: answer, writes, error: error instanceof Error ? error.message : String(error) };
 		}
+		if (providerError) return { report: answer, writes, error: `dreamer failed: ${providerError}` };
+		return { report: answer, writes };
 	} finally {
 		unsubscribe?.();
 		session.dispose();
 	}
 }
+
 export function loadPlaybook(path: string): string { return readFileSync(path, "utf8"); }

package/src/history-tools.ts

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } 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";
 
@@ -53,7 +53,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 			if (invalid) return output({ error: invalid, role: params.role, tool_name: params.tool_name });
 			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));
 		},
 	}));
@@ -62,7 +62,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 		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) return output({ error: "unknown item_id or window_id" });
@@ -72,7 +72,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 			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 });
@@ -93,7 +93,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 			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/src/history.ts

@@ -2,6 +2,7 @@ import type { TextContent, ToolCall } from "@earendil-works/pi-ai";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { SessionReader } from "./session-reader.js";
 import { RESET_V2 } from "./protocol.js";
+import { HISTORY_PREVIEW_CHARS } from "./tool-output.js";
 
 type HistoryItem = {
 	windowId: string;
@@ -29,9 +30,9 @@ function isTextContent(part: unknown): part is TextContent {
 	return typeof part === "object" && part !== null && (part as TextContent).type === "text" && typeof (part as TextContent).text === "string";
 }
 
-function contentText(content: string | unknown[]): string {
+export function contentText(content: unknown): string {
 	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: AgentMessage["role"]): HistoryItem["role"] | undefined {
@@ -102,14 +103,19 @@ export function resetV2WindowId(details: unknown): string | undefined {
 }
 
 /** A compaction entry's window id: the extension-minted id for reset-v2, else Pi's entry id. */
-function windowIdOf(sessionId: string, entry: { id: string; details?: unknown }): string {
+export function windowIdOf(sessionId: string, entry: { id: string; details?: unknown }): string {
 	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: string): string {
+	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: SessionReader): HistoryWindow[] {
 	const sessionId = ctx.sessionManager.getSessionId();
-	let window: HistoryWindow = { windowId: `pcw:${sessionId.slice(0, 8)}:root`, items: [] };
+	let window: HistoryWindow = { windowId: rootWindowId(sessionId), items: [] };
 	const windows = [window];
 	for (const entry of ctx.sessionManager.getBranch()) {
 		if (entry.type === "compaction") {
@@ -153,7 +159,7 @@ export function historyFromSession(ctx: SessionReader): HistoryWindow[] {
 	return windows;
 }
 
-export function visibleItem(item: HistoryItem, maxChars = 1200) {
+export function visibleItem(item: HistoryItem, maxChars = HISTORY_PREVIEW_CHARS) {
 	const characters = Array.from(item.content);
 	const truncated = characters.length > maxChars;
 	return {
@@ -230,6 +236,5 @@ export function currentWindowId(ctx: SessionReader): string {
 		const entry = branch[i];
 		if (entry?.type === "compaction") return windowIdOf(sessionId, entry);
 	}
-	return `pcw:${sessionId.slice(0, 8)}:root`;
+	return rootWindowId(sessionId);
 }
-

package/src/index.ts

@@ -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";
@@ -25,8 +25,7 @@ export default function piContext(pi: ExtensionAPI) {
 		// 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 });
 	});
@@ -48,7 +47,7 @@ export default function piContext(pi: ExtensionAPI) {
 	});
 
 	registerHistoryTools(pi);
-	registerMemoryTools(pi);
+	registerNotesTools(pi);
 
 	pi.registerTool(defineTool({
 		name: "new_context",
@@ -70,15 +69,15 @@ export default function piContext(pi: ExtensionAPI) {
 		},
 		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/src/notes/address.ts

@@ -0,0 +1,33 @@
+import { assertVirtualPath } from "./model.js";
+import type { Scope } from "./paths.js";
+
+export type NoteAddress = { scope: Scope; path: string };
+
+const ADDRESS_FORMS = "legal prefixes are @project/ and @personal/; 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: unknown): NoteAddress {
+	if (typeof value !== "string") throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+	let scope: Scope = "session";
+	let path = value;
+	if (value.startsWith("@project/")) {
+		scope = "project";
+		path = value.slice("@project/".length);
+	} else if (value.startsWith("@personal/")) {
+		scope = "personal";
+		path = value.slice("@personal/".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: Scope, path: string): string {
+	return scope === "session" ? path : `@${scope}/${path}`;
+}

package/src/{memory → notes}/frontmatter.ts

@@ -1,4 +1,4 @@
-import { localIso } from "../notes.js";
+import { localIso } from "./model.js";
 import type { Scope } from "./paths.js";
 
 export type NoteStatus = "active" | "superseded" | "pending" | "archived";
@@ -25,12 +25,12 @@ export type NoteMeta = {
 	[key: string]: unknown;
 };
 
-const SCOPES: readonly Scope[] = ["session", "project", "global"];
+const SCOPES: readonly Scope[] = ["session", "project", "personal"];
 const ORIGINS: readonly Origin[] = ["user", "self", "external"];
 const STATUSES: readonly NoteStatus[] = ["active", "superseded", "pending", "archived"];
 const TIMESTAMP_KEYS = ["created_at", "updated_at", "last_accessed"] as const;
 /** 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"] as const;
+const KNOWN_KEYS = ["origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count", "source_window", "supersedes", "recurrence_count", "recurrence_windows"] as const;
 
 export function isScope(value: unknown): value is Scope {
 	return typeof value === "string" && (SCOPES as readonly string[]).includes(value);
@@ -112,7 +112,7 @@ function parseFrontmatter(raw: string): { fields: Record<string, unknown>; body:
 export function parseNote(raw: string, now = Date.now()): { meta: NoteMeta; body: string } {
 	const { fields, body } = parseFrontmatter(raw);
 	const meta = { ...fields } as Record<string, unknown>;
-	meta.scope = isScope(meta.scope) ? meta.scope : "global";
+	meta.scope = isScope(meta.scope) ? meta.scope : "personal";
 	meta.origin = isOrigin(meta.origin) ? meta.origin : "self";
 	meta.status = isStatus(meta.status) ? meta.status : "active";
 	meta.stale = meta.stale === true;
@@ -140,7 +140,9 @@ export function serializeNote(meta: NoteMeta, body: string): string {
 		else lines.push(`${key}: ${yamlScalar(value)}`);
 	}
 	for (const key of Object.keys(meta)) {
-		if ((KNOWN_KEYS as readonly string[]).includes(key)) continue;
+		// 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 as readonly string[]).includes(key)) continue;
 		if (meta[key] === undefined) continue;
 		lines.push(`${key}: ${yamlScalar(meta[key])}`);
 	}

package/src/{notes.ts → notes/model.ts}

@@ -1,5 +1,5 @@
-import type { SessionReader } from "./session-reader.js";
-import { MAX_NOTE_BYTES, NOTE_TYPE } from "./protocol.js";
+import type { SessionReader } from "../session-reader.js";
+import { MAX_NOTE_BYTES, NOTE_TYPE } from "../protocol.js";
 
 export type NoteFile = { text: string; stale: boolean; createdAt: number; updatedAt: number };
 export type NoteOperation = {