@astrosheep/pi-context 0.18.0 → 0.20.0

package/docs/reset-lifecycle.md

@@ -13,7 +13,7 @@
 | Attempt `onError` or synchronous throw | Clear attempt/request, warn, retain history. No automatic retry loop. |
 | Shutdown / start / tree / toggle off | Invalidate outstanding attempt. Identity checks reject callbacks from older attempts. |
 
-The final checkpoint warning is steered earlier from the context hook (`warning.ts`) once per window at reserve+8192 tokens remaining. After it, the model either ends the window itself with `new_context` or rides into Pi's automatic compaction, which resets on the spot with no turn.
+The final checkpoint warning is steered earlier from the context hook (`warning.ts`) once per window at reserve+12288 tokens remaining. After it, the model either ends the window itself with `new_context` or rides into Pi's automatic compaction, which resets on the spot with no turn.
 
 The completion callback is the scheduling boundary: `session_compact` fires before Pi clears manual compaction state. Sending a prompt inside that hook is too early. An explicit reset uses the manual `ctx.compact` route and therefore needs this completion logic; an automatic compaction is already the reset and resumes through Pi's own caller.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",
@@ -20,15 +20,21 @@
   },
   "files": [
     "src",
+    "dist",
     "docs",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "playbook.md"
   ],
+  "bin": {
+    "dream": "dist/src/dream/cli.js"
+  },
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test dist/test/*.test.js",
-    "prepublishOnly": "npm run typecheck"
+    "prepublishOnly": "npm run typecheck",
+    "prepack": "npm run build"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",

package/playbook.md

@@ -0,0 +1,5 @@
+I am dreaming over my notes, speaking in my own first-person voice. I inspect the supplied notes and return exactly one JSON manifest, with no commentary outside it.
+
+I do seven chores: merge genuinely repeated notes; preserve provenance and recurrence windows; propose (but never execute) global promotions; move only clearly obsolete notes to reversible trash; identify pending ambiguities; propose skill candidates without installing them; and write a concise report of my reasoning and choices. I anchor every temporal claim to an absolute calendar date (YYYY-MM-DD), never to vague words like “today”. I stay aware of the index budget: prefer compact, deduplicated durable notes and avoid swelling the index with repetition. Skill-promotion proposals are proposals only. Judgment belongs here, not in the harness.
+
+My final output is the manifest schema documented by the command: merge, promote, trash, pending, skillCandidates, and a required report string.

package/src/dream/apply.ts

@@ -0,0 +1,47 @@
+import { mkdirSync, renameSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, relative } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { editNote, peekNote, resolveNoteScope, updateNoteMeta, writeNote, type Scope } from "../memory/store.js";
+import { physicalPath, scopeDir } from "../memory/paths.js";
+import { parseNote } from "../memory/frontmatter.js";
+import type { Manifest } from "./manifest.js";
+
+type Target = { scope: Scope; path: string };
+function target(ctx: ExtensionContext, value: string, required = true): Target | undefined {
+	const m = /^(session|project|global):(.*)$/.exec(value);
+	if (m) { const scope = m[1] as Scope; const path = m[2]!; const physical = physicalPath(scope, path, ctx); if (!existsSync(physical)) { if (required) throw new Error(`unknown path: ${value}`); return undefined; } return { scope, path }; }
+	const found = resolveNoteScope(ctx, value);
+	if (!found && required) throw new Error(`unknown path: ${value}`);
+	return found ? { scope: found.scope, path: value } : undefined;
+}
+function body(ctx: ExtensionContext, t: Target) { return peekNote(ctx, t.scope, t.path); }
+export function applyManifest(ctx: ExtensionContext, home: string, stamp: string, manifest: Manifest): string[] {
+	const actions: string[] = [];
+	// Resolve every referenced note and promotion destination before the first mutation.
+	for (const m of manifest.merge ?? []) { target(ctx, m.into); for (const p of m.from) target(ctx, p); }
+	for (const p of manifest.promote ?? []) { const from = target(ctx, p.path)!; if (p.to !== "global") { if (!["session", "project"].includes(p.to)) throw new Error(`invalid promotion scope: ${p.to}`); if (existsSync(physicalPath(p.to as Scope, p.path, ctx))) throw new Error(`promotion collision: ${p.path}`); } void from; }
+	for (const p of manifest.trash ?? []) target(ctx, p.path);
+	for (const merge of manifest.merge ?? []) {
+		const into = target(ctx, merge.into)!;
+		const sources = merge.from.map((p) => target(ctx, p)!);
+		const base = body(ctx, into); const chunks = [base.body, ...sources.map((s) => body(ctx, s).body)].filter(Boolean);
+		const dedup = [...new Set(chunks)].join("\n\n");
+		writeNote(ctx, into.path, dedup, { scope: into.scope, origin: base.meta.origin });
+		updateNoteMeta(ctx, into.path, into.scope, (meta) => { meta.recurrence_count = (meta.recurrence_count ?? 0) as number + sources.length; meta.recurrence_windows = [...new Set([...(meta.recurrence_windows ?? []), ...sources.map((s) => body(ctx, s).meta.source_window).filter((x): x is string => typeof x === "string")])]; });
+		for (const source of sources) updateNoteMeta(ctx, source.path, source.scope, (meta) => { meta.status = "superseded"; meta.supersedes = merge.into; });
+		actions.push(`merged ${merge.from.join(", ")} into ${merge.into}`);
+	}
+	for (const p of manifest.promote ?? []) {
+		const from = target(ctx, p.path)!; const m = body(ctx, from); const scope = p.to as Scope;
+		if (!["session", "project", "global"].includes(scope)) throw new Error(`invalid promotion scope: ${p.to}`);
+		if (scope === "global") { actions.push(`proposal: promote ${p.path} to global (${p.reason})`); continue; }
+		const dest = physicalPath(scope, p.path, ctx); if (existsSync(dest)) throw new Error(`promotion collision: ${p.path}`);
+		editNote(ctx, from.path, undefined, { scope });
+		actions.push(`promoted ${p.path} to ${scope}`);
+	}
+	const trashRoot = join(home, "trash", stamp); mkdirSync(trashRoot, { recursive: true });
+	for (const item of manifest.trash ?? []) { const t = target(ctx, item.path)!; const source = physicalPath(t.scope, t.path, ctx); const dest = join(trashRoot, t.scope, t.path.endsWith(".md") ? t.path : `${t.path}.md`); mkdirSync(dirname(dest), { recursive: true }); renameSync(source, dest); actions.push(`trashed ${item.path}: ${item.reason}`); }
+	for (const p of manifest.pending ?? []) actions.push(`pending ${p.path}: ${p.reason}`);
+	for (const p of manifest.skillCandidates ?? []) actions.push(`skill proposal ${p.title}: ${p.rationale}`);
+	return actions;
+}

package/src/dream/cli.ts

@@ -0,0 +1,33 @@
+#!/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 type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+function args(argv: string[]) { const out: Record<string, string | boolean> = {}; for (let i=0;i<argv.length;i++) { const a=argv[i]!; if (a === "--force" || a === "--help") out[a.slice(2)] = true; else if (a.startsWith("--")) out[a.slice(2)] = argv[++i] ?? ""; } return out; }
+function packageRoot(): string {
+	let dir = dirname(new URL(import.meta.url).pathname);
+	while (true) { if (existsSync(join(dir, "package.json"))) return dir; const parent = dirname(dir); if (parent === dir) throw new Error("could not locate installed package root"); dir = parent; }
+}
+
+export async function main(argv = process.argv.slice(2)): Promise<number> {
+	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."); return 0; }
+	const home = resolve(String(a["notes-home"] ?? process.env.PI_NOTES_HOME ?? join(homedir(), ".agents", "notes"))); process.env.PI_NOTES_HOME = home; mkdirSync(home, { recursive: true });
+	const lockPath = join(home, ".dream.lock"); const minHours = Number(a["min-hours"] ?? 24); const minSessions = Number(a["min-sessions"] ?? 3);
+	const time = timeGate(lockPath, minHours); console.log(time.reason); if (!a.force && !time.ok) return 0;
+	const material = materialGate(home, existsSync(lockPath) ? statSync(lockPath).mtimeMs : 0, minSessions); console.log(material.reason); if (!a.force && !material.ok) return 0;
+	let lock; try { lock = acquireLock(lockPath); } catch (e) { console.log(`lock gate: ${e instanceof Error ? e.message : e}`); return 0; } if (!lock.held) { console.log(lock.reason); return 0; }
+	const stamp = new Date(lock.startedAt).toISOString().replace(/[:.]/g, "-"); const reportPath = join(home, "dreams", `${stamp}.md`);
+	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" } } as unknown as ExtensionContext; const actions = applyManifest(ctx, home, stamp, manifest);
+		mkdirSync(join(home, "dreams"), { recursive: true }); writeFileSync(reportPath, `# Dream ${stamp}\n\n${manifest.report}\n\n${actions.map((x) => `- ${x}`).join("\n")}\n`); console.log(reportPath); return 0;
+	} catch (e) { failLock(lock); console.error(e instanceof Error ? e.message : e); return 1; } finally { releaseLock(lock); }
+}
+main().then((code) => { process.exitCode = code; });

package/src/dream/gates.ts

@@ -0,0 +1,19 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+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" };
+}
+export function materialGate(home: string, lockMtime: number, minSessions: number): GateResult {
+	const root = join(home, "pi", "session");
+	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++;
+	}
+	return changed >= minSessions ? { ok: true, reason: `material gate: ${changed} changed sessions` } : { ok: false, reason: `material gate: only ${changed} changed sessions` };
+}

package/src/dream/lock.ts

@@ -0,0 +1,39 @@
+import { existsSync, 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;
+
+function live(pid: number): boolean {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+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 }; }
+	}
+	writeFileSync(path, String(process.pid), { flag: "wx" });
+	return { path, held: true, startedAt: now, priorMtime };
+}
+
+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 */ }
+}
+
+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);
+}

package/src/dream/manifest.ts

@@ -0,0 +1,21 @@
+export type Manifest = {
+	merge?: { into: string; from: string[]; summary?: string }[];
+	promote?: { path: string; to: string; reason: string }[];
+	trash?: { path: string; reason: string }[];
+	pending?: { path: string; reason: string }[];
+	skillCandidates?: { title: string; rationale: string }[];
+	report: string;
+};
+
+export function parseManifest(output: string): Manifest {
+	const starts = [...output.matchAll(/[\{[]/g)].map((m) => m.index ?? 0).reverse();
+	for (const start of starts) {
+		try {
+			const value = JSON.parse(output.slice(start)) as Manifest;
+			if (!value || typeof value !== "object" || typeof value.report !== "string") continue;
+			for (const key of ["merge", "promote", "trash", "pending", "skillCandidates"]) if (value[key as keyof Manifest] !== undefined && !Array.isArray(value[key as keyof Manifest])) throw new Error("invalid array");
+			return value;
+		} catch { /* try an earlier JSON start */ }
+	}
+	throw new Error("dreamer did not return a valid JSON manifest");
+}

package/src/dream/runner.ts

@@ -0,0 +1,53 @@
+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 type { Api, Model } from "@earendil-works/pi-ai";
+import { parseManifest, type Manifest } from "./manifest.js";
+
+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 defaultDreamerSessionFactory: DreamerSessionFactory = async ({ cwd, modelPattern, tools }) => {
+	let model: Model<Api> | undefined;
+	if (modelPattern) {
+		const runtime = await ModelRuntime.create({ allowModelNetwork: false, refreshOnCreate: false });
+		const result = await resolveModelScopeWithDiagnostics([modelPattern], runtime);
+		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 });
+	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 });
+	let answer = "";
+	let providerError: string | undefined;
+	const unsubscribe = session.subscribe((event: any) => {
+		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("") : "";
+	});
+	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;
+		}
+	} finally {
+		unsubscribe?.();
+		session.dispose();
+	}
+}
+export function loadPlaybook(path: string): string { return readFileSync(path, "utf8"); }

package/src/history-tools.ts

@@ -31,7 +31,7 @@ function truncateHistoryItem<T extends { truncated_content: string; truncated: b
 
 export function registerHistoryTools(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
-		name: "history_list_windows",
+		name: "history_windows",
 		label: "History list windows",
 		description: "List durable Pi session-history windows.",
 		parameters: Type.Object({ limit: positiveInteger(), recent_first: recentFirst() }, { additionalProperties: false }),
@@ -44,9 +44,9 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	}));
 
 	pi.registerTool(defineTool({
-		name: "history_list_items",
+		name: "history_list",
 		label: "History list items",
-		description: "List durable session items, including items before compaction, using opaque item and window IDs; the role parameter's description enumerates the six roles. Every item carries truncated and total_chars: when truncated is true, truncated_content is a plain prefix of the item's content with no marker, and total_chars is its full code-point length. max_chars_per_item: 1 therefore yields pure addresses you can resolve with history_read_item.",
+		description: "List durable session items, including items before compaction, using opaque item and window IDs; the role parameter's description enumerates the six roles. Every item carries truncated and total_chars: when truncated is true, truncated_content is a plain prefix of the item's content with no marker, and total_chars is its full code-point length. max_chars_per_item: 1 therefore yields pure addresses you can resolve with history_read.",
 		parameters: Type.Object({ limit: positiveInteger(), cursor: cursor(), recent_first: recentFirst(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const invalid = vacuousRoleToolCombo(params);
@@ -59,7 +59,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	}));
 
 	pi.registerTool(defineTool({
-		name: "history_read_item",
+		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 }),
@@ -81,9 +81,9 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	}));
 
 	pi.registerTool(defineTool({
-		name: "history_search_contents",
+		name: "history_search",
 		label: "History search",
-		description: "Case-sensitive literal substring search over durable Pi session history; query accepts one string or an array of strings, an item matches when it contains any of them (OR), and each item appears once. No semantic search. Invocations and outputs are separate items (roles \"tool_call\" and \"tool\"), so both are searchable; the role parameter's description enumerates all six. Each hit carries truncated and total_chars plus match_offset_chars: the code-point offset of the earliest query occurrence in the item's full content. With max_chars_per_item: 1 the page is an address list; resolve an address with history_read_item at match_offset_chars.",
+		description: "Case-sensitive literal substring search over durable Pi session history; query accepts one string or an array of strings, an item matches when it contains any of them (OR), and each item appears once. No semantic search. Invocations and outputs are separate items (roles \"tool_call\" and \"tool\"), so both are searchable; the role parameter's description enumerates all six. Each hit carries truncated and total_chars plus match_offset_chars: the code-point offset of the earliest query occurrence in the item's full content. With max_chars_per_item: 1 the page is an address list; resolve an address with history_read at match_offset_chars.",
 		parameters: Type.Object({ limit: positiveInteger(), cursor: cursor(), query: searchQuery(), recent_first: recentFirst(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const invalid = vacuousRoleToolCombo(params);

package/src/history.ts

@@ -72,7 +72,7 @@ function toolInfo(message: AgentMessage): Pick<HistoryItem, "toolName" | "output
  * An assistant turn's tool calls, projected as their own items: calls wear their own role so the
  * authoring turn's visible text (role "assistant") stays pure; what was invoked stays as
  * searchable as what came back (role "tool"). Ids derive from the turn's entry id and stay
- * opaque; history_read_item resolves them like any other item.
+ * opaque; history_read resolves them like any other item.
  */
 function toolCallItems(windowId: string, entry: { id: string; timestamp?: string }, message: AgentMessage): HistoryItem[] {
 	if (message.role !== "assistant" || !Array.isArray(message.content)) return [];

package/src/index.ts

@@ -1,5 +1,5 @@
 import { registerHistoryTools } from "./history-tools.js";
-import { registerNoteTools } from "./note-tools.js";
+import { registerMemoryTools } from "./memory/tools.js";
 import { registerBudget, deriveThresholds, mergePiContextSettings } from "./budget.js";
 import { output } from "./tool-output.js";
 export { deriveThresholds, mergePiContextSettings };
@@ -48,7 +48,7 @@ export default function piContext(pi: ExtensionAPI) {
 	});
 
 	registerHistoryTools(pi);
-	registerNoteTools(pi);
+	registerMemoryTools(pi);
 
 	pi.registerTool(defineTool({
 		name: "new_context",

package/src/memory/frontmatter.ts

@@ -0,0 +1,153 @@
+import { localIso } from "../notes.js";
+import type { Scope } from "./paths.js";
+
+export type NoteStatus = "active" | "superseded" | "pending" | "archived";
+export type Origin = "user" | "self" | "external";
+
+/**
+ * Harness-owned note metadata. The eight required keys are always written; the four optional
+ * sleep-shift keys survive this layer untouched when present. `[key: string]: unknown` carries
+ * any frontmatter key this layer does not know, preserved verbatim across rewrites.
+ */
+export type NoteMeta = {
+	scope: Scope;
+	origin: Origin;
+	status: NoteStatus;
+	stale: boolean;
+	created_at: number;
+	updated_at: number;
+	last_accessed: number;
+	access_count: number;
+	source_window?: string;
+	supersedes?: string;
+	recurrence_count?: number;
+	recurrence_windows?: string[];
+	[key: string]: unknown;
+};
+
+const SCOPES: readonly Scope[] = ["session", "project", "global"];
+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;
+
+export function isScope(value: unknown): value is Scope {
+	return typeof value === "string" && (SCOPES as readonly string[]).includes(value);
+}
+
+export function isOrigin(value: unknown): value is Origin {
+	return typeof value === "string" && (ORIGINS as readonly string[]).includes(value);
+}
+
+function isStatus(value: unknown): value is NoteStatus {
+	return typeof value === "string" && (STATUSES as readonly string[]).includes(value);
+}
+
+function toEpoch(value: unknown, fallback: number): number {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string") {
+		const parsed = Date.parse(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return fallback;
+}
+
+/** A frontmatter scalar encoded as JSON, falling back to a plain string for hand-written YAML. */
+function parseScalar(text: string): unknown {
+	const trimmed = text.trim();
+	if (trimmed === "") return "";
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) return trimmed.slice(1, -1);
+		return trimmed;
+	}
+}
+
+/**
+ * Split raw file text into its frontmatter fields and body. When the file does not open with
+ * a closed `---` block, the whole text is body and the field map is empty.
+ */
+function parseFrontmatter(raw: string): { fields: Record<string, unknown>; body: string } {
+	const stripped = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+	const lines = stripped.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+	if (lines[0]?.trim() !== "---") return { fields: {}, body: raw };
+	let close = -1;
+	for (let index = 1; index < lines.length; index++) {
+		if (lines[index]?.trim() === "---") {
+			close = index;
+			break;
+		}
+	}
+	if (close === -1) return { fields: {}, body: raw };
+	const fields: Record<string, unknown> = {};
+	for (let index = 1; index < close; index++) {
+		const line = lines[index]!;
+		const match = /^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/.exec(line);
+		if (!match) continue;
+		const key = match[1]!;
+		const rest = match[2]!;
+		if (rest.trim() === "") {
+			// A bare key opens a block sequence of `- item` lines, the only multi-line shape we parse.
+			const items: unknown[] = [];
+			while (index + 1 < close && /^\s*-\s+/.test(lines[index + 1]!)) {
+				index++;
+				items.push(parseScalar(lines[index]!.replace(/^\s*-\s+/, "")));
+			}
+			fields[key] = items;
+		} else {
+			fields[key] = parseScalar(rest);
+		}
+	}
+	const rest = lines.slice(close + 1);
+	if (rest[0] === "") rest.shift();
+	return { fields, body: rest.join("\n") };
+}
+
+/**
+ * Parse a note file. Missing known keys take the Design defaults (status active, stale false,
+ * access_count 0, timestamps now); unknown keys are carried through untouched.
+ */
+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.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;
+	return { meta: meta as NoteMeta, body };
+}
+
+/** Emit a YAML scalar: bare for safe strings and JSON literals, JSON-quoted otherwise. */
+function yamlScalar(value: unknown): string {
+	if (typeof value === "string") {
+		const reserved = new Set(["true", "false", "null", "yes", "no", "on", "off", "~"]);
+		if (/^[A-Za-z0-9_.+\-:/]+$/.test(value) && !reserved.has(value.toLowerCase())) return value;
+	}
+	return JSON.stringify(value);
+}
+
+/** Serialize frontmatter + blank line + body. Known keys emit in Design order, extras after. */
+export function serializeNote(meta: NoteMeta, body: string): string {
+	const lines: string[] = [];
+	for (const key of KNOWN_KEYS) {
+		const value = meta[key];
+		if (value === undefined) continue;
+		if ((TIMESTAMP_KEYS as readonly string[]).includes(key)) lines.push(`${key}: ${yamlScalar(localIso(value as number))}`);
+		else lines.push(`${key}: ${yamlScalar(value)}`);
+	}
+	for (const key of Object.keys(meta)) {
+		if ((KNOWN_KEYS as readonly string[]).includes(key)) continue;
+		if (meta[key] === undefined) continue;
+		lines.push(`${key}: ${yamlScalar(meta[key])}`);
+	}
+	return `---\n${lines.join("\n")}\n---\n\n${body}`;
+}
+
+/** Strip a leading frontmatter block from user content, so a note body is pure content. */
+export function stripLeadingFrontmatter(content: string): string {
+	return parseFrontmatter(content).body;
+}

package/src/memory/paths.ts

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type Scope = "session" | "project" | "global";
+
+/** Physical home of the on-disk note store: $PI_NOTES_HOME or ~/.agents/notes. */
+export function notesRoot(): string {
+	const override = process.env.PI_NOTES_HOME;
+	return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
+}
+
+/**
+ * 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.
+ */
+function gitRoot(cwd: string): string | undefined {
+	let dir = resolve(cwd);
+	for (;;) {
+		if (existsSync(join(dir, ".git"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return undefined;
+		dir = parent;
+	}
+}
+
+/** `<basename(absGitRoot)-sha1(absGitRoot)[:8]>`, or the same formula over cwd with no git root. */
+export function projectKey(cwd: string): string {
+	const absolute = resolve(cwd);
+	const root = gitRoot(absolute) ?? absolute;
+	const digest = createHash("sha1").update(root).digest("hex").slice(0, 8);
+	return `${basename(root)}-${digest}`;
+}
+
+/** Session identity comes from the pi session manager; ids are filesystem-safe by construction. */
+function sessionId(ctx: ExtensionContext): string {
+	return ctx.sessionManager.getSessionId();
+}
+
+/** Absolute directory holding every note of one scope. */
+export function scopeDir(scope: Scope, ctx: ExtensionContext): string {
+	if (scope === "global") return join(notesRoot(), "global");
+	if (scope === "project") return join(notesRoot(), "project", projectKey(ctx.cwd));
+	return join(notesRoot(), "pi", "session", sessionId(ctx));
+}
+
+/**
+ * Notes are markdown files: a virtual path without an `.md` suffix gains one, an explicit
+ * `.md` is kept as-is, so `a/b` and `a/b.md` name the same physical file.
+ */
+export function noteFileName(vpath: string): string {
+	return vpath.endsWith(".md") ? vpath : `${vpath}.md`;
+}
+
+/** Absolute file path for a virtual path in a scope. Callers validate the vpath first. */
+export function physicalPath(scope: Scope, vpath: string, ctx: ExtensionContext): string {
+	return join(scopeDir(scope, ctx), ...noteFileName(vpath).split("/"));
+}