@astrosheep/pi-context 0.25.2 → 0.26.0

package/dist/test/budget-settings.integration.test.js

@@ -31,7 +31,7 @@ test("the visible countdown ends at the warning line, clamps at zero, and preser
     });
     const sm = manager();
     const captured = makeExtension(sm);
-    runHandlers(captured, "session_tree", {}, context(sm, undefined, undefined, true, fixture.cwd, true));
+    await runHandlers(captured, "session_tree", {}, context(sm, undefined, undefined, true, fixture.cwd, true));
     const readBudget = async (tokens, trusted = true) => {
         const ctx = context(sm, undefined, { tokens, contextWindow: 200_000, percent: tokens === null ? null : tokens / 2000 }, true, fixture.cwd, trusted);
         return resultJson(await call(captured, "get_context_remaining", {}, ctx)).remaining_tokens;
@@ -44,7 +44,7 @@ test("the visible countdown ends at the warning line, clamps at zero, and preser
     const absent = context(sm, undefined, undefined, true, fixture.cwd);
     assert.equal(resultJson(await call(captured, "get_context_remaining", {}, absent)).remaining_tokens, null);
     const untrusted = context(sm, undefined, { tokens: 72_563, contextWindow: 200_000, percent: 36.2815 }, true, fixture.cwd, false);
-    runHandlers(captured, "session_start", {}, untrusted);
+    await runHandlers(captured, "session_start", {}, untrusted);
     assert.equal(await readBudget(72_563, false), 98_765, "session start reloads the global reserve when the project is untrusted");
 });
 test("absent pi-context key or margins reproduce the default reminder threshold at Pi's default reserve", async () => {
@@ -59,7 +59,7 @@ test("absent pi-context key or margins reproduce the default reminder threshold
         const captured = makeExtension(sm);
         // Thresholds are resolved once per session and cached; branch navigation clears the
         // cache without emitting a boot block, so the next read uses this fixture.
-        runHandlers(captured, "session_tree", {}, context(sm, undefined, undefined, true, fixture.cwd));
+        await runHandlers(captured, "session_tree", {}, context(sm, undefined, undefined, true, fixture.cwd));
         const window = 200_000;
         const at = (remaining) => context(sm, undefined, { tokens: window - remaining, percent: 0, contextWindow: window }, true, fixture.cwd);
         const first = at(40_961);
@@ -81,7 +81,7 @@ test("project pi-context reminder margin and reserve override global per key", a
     // Project reserve wins: reminder = 50000 + 40000 (project margin).
     const sm = manager();
     const captured = makeExtension(sm);
-    runHandlers(captured, "session_tree", {}, context(sm, undefined, undefined, true, fixture.cwd));
+    await runHandlers(captured, "session_tree", {}, context(sm, undefined, undefined, true, fixture.cwd));
     const window = 300_000;
     const at = (remaining) => context(sm, undefined, { tokens: window - remaining, percent: 0, contextWindow: window }, true, fixture.cwd);
     assert.equal(await runContextHook(captured, at(90_001)), undefined, "nothing injected above the project-derived reminder");
@@ -96,12 +96,13 @@ test("an invalid reminder margin degrades to its default with one warning and ne
     const sm = manager();
     const captured = makeExtension(sm);
     const ctx = context(sm, undefined, undefined, true, fixture.cwd);
-    assert.doesNotThrow(() => runHandlers(captured, "session_start", { reason: "startup" }, ctx));
+    await assert.doesNotReject(() => runHandlers(captured, "session_start", { reason: "startup" }, ctx));
     const notices = noticesOf(ctx).filter((notice) => notice.type === "warning");
     assert.equal(notices.length, 1, "one warning for the offending key");
     assert.equal(notices[0]?.type, "warning");
     assert.match(notices[0]?.message ?? "", /reminderMarginTokens/);
-    assert.match(notices[0]?.message ?? "", /24576/);
+    assert.match(notices[0]?.message ?? "", /default reminder margin/);
+    assert.equal(/\d+\s*k?\s*(remaining|tokens)/i.test(notices[0]?.message ?? ""), false, "UI notices do not expose token counts");
     const window = 200_000;
     const at = (remaining) => context(sm, undefined, { tokens: window - remaining, percent: 0, contextWindow: window }, true, fixture.cwd);
     // The degraded reminder is Pi's default reserve + default margin = 40960.
@@ -121,6 +122,6 @@ test("the warning supersedes the early reminder when usage jumps across both thr
     assert.deepEqual(warningResult?.messages.map((message) => message.customType), [internal.WARNING_TYPE]);
     await commitTurnEndBoundary(captured, sm, ctx);
     const reloaded = makeExtension(sm);
-    runHandlers(reloaded, "context", {}, ctx);
+    await runHandlers(reloaded, "context", {}, ctx);
     assert.equal(reloaded.sent.length, 0, "persisted warning also suppresses a late reminder after reload");
 });

package/dist/test/doctor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/doctor.test.js

@@ -1,11 +1,19 @@
 import assert from "node:assert/strict";
 import { main } from "../src/dream/cli.js";
 import { doctor } from "../src/dream/doctor.js";
-import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import test from "node:test";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-const note = "---\norigin: self\nstatus: active\nstale: false\ncreated_at: 2026-01-01T00:00:00Z\nupdated_at: 2026-01-01T00:00:00Z\nlast_accessed: 2026-01-01T00:00:00Z\naccess_count: 0\n---\n\n";
+const note = "---\norigin: self\nstatus: active\nstale: false\ncreatedAt: 2026-01-01T00:00:00Z\nupdatedAt: 2026-01-01T00:00:00Z\nlastAccessed: 2026-01-01T00:00:00Z\naccessCount: 0\n---\n\n";
+test("doctor identifies legacy metadata as requiring manual migration", (t) => {
+    const root = mkdtempSync(join(tmpdir(), "dream-doctor-legacy-"));
+    t.after(() => rmSync(root, { recursive: true, force: true }));
+    mkdirSync(join(root, "human"));
+    writeFileSync(join(root, "human/legacy.md"), note.replace("createdAt", "created_at"));
+    const issues = doctor(root);
+    assert.ok(issues.some((issue) => issue.includes("legacy metadata key created_at; manually migrate to createdAt")));
+});
 test("doctor validates without repairing files or running the dreamer", async () => {
     const root = mkdtempSync(join(tmpdir(), "dream-doctor-test-"));
     mkdirSync(join(root, "human"));

package/dist/test/dream-skill.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/dream-skill.test.js

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import test from "node:test";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadSkillsFromDir } from "@earendil-works/pi-coding-agent";
+import { loadPlaybook } from "../src/dream/runner.js";
+function packageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    while (!existsSync(join(dir, "package.json"))) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            throw new Error("could not locate package root");
+        dir = parent;
+    }
+    return dir;
+}
+function discoverDreamSkill(skillsDir) {
+    const result = loadSkillsFromDir({ dir: skillsDir, source: "path" });
+    assert.deepEqual(result.diagnostics, []);
+    const skill = result.skills.find((candidate) => candidate.name === "dream");
+    assert.ok(skill, "Pi's public skill loader discovers dream");
+    assert.ok(skill.description.length > 0);
+    return skill;
+}
+test("dream skill is publicly discoverable and resolves the CLI's shared playbook", () => {
+    const root = packageRoot();
+    const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    assert.deepEqual(manifest.pi.skills, ["./skills"]);
+    assert.deepEqual(manifest.pi.extensions, ["./dist/extension.js"]);
+    assert.equal(manifest.bin.dream, "dist/src/dream/cli.js");
+    assert.ok(manifest.files.includes("skills"));
+    const skill = discoverDreamSkill(join(root, "skills"));
+    const skillPlaybook = resolve(skill.baseDir, "../../playbook.md");
+    const packagePlaybook = resolve(root, "playbook.md");
+    assert.equal(skillPlaybook, packagePlaybook);
+    const playbook = readFileSync(packagePlaybook, "utf8");
+    assert.equal(loadPlaybook(skillPlaybook), playbook);
+});
+test("npm tarball keeps the skill's relative playbook path portable after extraction", () => {
+    const root = packageRoot();
+    const fixture = mkdtempSync(join(tmpdir(), "dream-skill-pack-"));
+    try {
+        const packed = JSON.parse(execFileSync("npm", ["pack", "--offline", "--ignore-scripts", "--json", "--pack-destination", fixture], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        }))[0];
+        const packedPaths = packed.files.map((file) => file.path);
+        assert.ok(packedPaths.includes("skills/dream/SKILL.md"));
+        assert.ok(packedPaths.includes("playbook.md"));
+        assert.ok(packedPaths.includes("dist/extension.js"));
+        assert.ok(packedPaths.includes("dist/src/dream/cli.js"));
+        const extracted = join(fixture, "extracted");
+        execFileSync("mkdir", ["-p", extracted]);
+        execFileSync("tar", ["-xzf", join(fixture, packed.filename), "-C", extracted]);
+        const installedRoot = join(extracted, "package");
+        const installedSkill = discoverDreamSkill(join(installedRoot, "skills"));
+        const referencedPlaybook = resolve(installedSkill.baseDir, "../../playbook.md");
+        assert.equal(referencedPlaybook, resolve(installedRoot, "playbook.md"));
+        assert.equal(loadPlaybook(referencedPlaybook), readFileSync(referencedPlaybook, "utf8"));
+        assert.equal(loadPlaybook(referencedPlaybook), readFileSync(join(root, "playbook.md"), "utf8"));
+    }
+    finally {
+        rmSync(fixture, { recursive: true, force: true });
+    }
+});

package/dist/test/dream.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/helpers/extension.d.ts

@@ -0,0 +1,115 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { type ContextUsage, type ExtensionAPI, type ExtensionContext, type RegisteredCommand, SessionManager, SettingsManager, type SessionBoundaryDraft, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+export type ExtensionTestEnvironment = {
+    readonly cwd: string;
+    readonly agentDir: string;
+    beforeEach(): void;
+    afterEach(): void;
+    newNotesRoot(): string;
+    dispose(): void;
+};
+/**
+ * Install the process-level settings and notes roots needed by one test file.
+ * The caller owns the lifecycle hooks; this helper never registers tests or hooks.
+ */
+export declare function installExtensionTestEnvironment(prefix?: string): ExtensionTestEnvironment;
+export type Notice = {
+    message: string;
+    type?: "info" | "warning" | "error";
+};
+export declare function writeJson(path: string, value: unknown): void;
+export type SettingsFixture = {
+    cwd: string;
+    agentDir: string;
+};
+/**
+ * Materialize global (agentDir/settings.json) and project (cwd/.pi/settings.json)
+ * settings in temp directories, then read them back through the same public
+ * SettingsManager.create the extension uses. Never touches the real ~/.pi.
+ */
+export declare function settingsFixture(options?: {
+    global?: Record<string, unknown>;
+    project?: Record<string, unknown>;
+    reserveTokens?: number;
+}): SettingsFixture;
+export type EventHandler = (event: never, ctx: ExtensionContext) => unknown;
+type SendMessageArg = Parameters<ExtensionAPI["sendMessage"]>[0];
+export type SentMessage = {
+    message: SendMessageArg;
+    options: {
+        triggerTurn?: boolean;
+    } | undefined;
+};
+export type Captured = {
+    tools: Map<string, ToolDefinition>;
+    handlers: Map<string, EventHandler[]>;
+    commands: Map<string, CommandOptions>;
+    sent: SentMessage[];
+    contextMessages: unknown[];
+    flags: string[];
+};
+export type CommandOptions = Omit<RegisteredCommand, "name" | "sourceInfo">;
+export type CompactionHookResult = {
+    cancel: true;
+} | {
+    compaction: {
+        summary: string;
+        firstKeptEntryId: string | null;
+        tokensBefore: number;
+        details?: unknown;
+    };
+} | undefined;
+/** TypeBox's TSchema does not expose `type`/`required` statically; read them structurally. */
+export declare function objectSchema(tool: ToolDefinition | undefined): {
+    type?: string;
+    required?: string[];
+} | undefined;
+export declare function manager(persisted?: boolean): SessionManager;
+export declare function makeExtension(sessionManager: SessionManager, settingsManager?: SettingsManager): Captured;
+export declare function explicitBoot(ctx: ExtensionContext, currentWindowId: string, previousWindowId: string | undefined): Promise<string>;
+export declare function context(sessionManager: SessionManager, compact?: ExtensionContext["compact"], usage?: ContextUsage, idle?: boolean, cwd?: string, projectTrusted?: boolean, model?: string | {
+    provider: string;
+    id: string;
+}): ExtensionContext;
+export declare function noticesOf(ctx: ExtensionContext): Notice[];
+export declare function sentOf(captured: Captured, customType: string): SentMessage[];
+export declare function call(captured: Captured, name: string, params: Record<string, unknown>, ctx: ExtensionContext): Promise<AgentToolResult<unknown>>;
+export declare function resultJson<T>(result: AgentToolResult<unknown>): T;
+/** Assert the delivered wire text fits the tool-output budget, header included for raw reads. */
+export declare function assertWithinBudget(result: AgentToolResult<unknown>, message: string): void;
+/** Decoded raw read response using the shared READ WINDOW grammar. */
+export type ReadWindow = {
+    header: string;
+    content: string;
+    offset_chars: number;
+    total_chars: number;
+    next_offset_chars: number | null;
+    details: Record<string, unknown>;
+};
+/** Decode either raw read without including its shared metadata block in the payload. */
+export declare function resultRead(result: AgentToolResult<unknown>): ReadWindow;
+/**
+ * Assert a value is a local-time ISO 8601 string with an explicit numeric offset (never "Z")
+ * and that Date.parse restores the stored epoch milliseconds. No time zone is assumed.
+ */
+export declare function assertLocalIso(value: unknown, epochMs: number, message: string): void;
+/** Assert the text contains a well-formed local ISO timestamp and return it, without pinning surrounding wording. */
+export declare function assertIsoTimestamp(text: string, message: string): string;
+/** Assert `actual` is a middle-truncation of `original`: same head, same tail, strictly fewer characters. */
+export declare function assertTruncationOf(original: string, actual: string): void;
+export declare function runManualCompact(captured: Captured, ctx: ExtensionContext): Promise<CompactionHookResult>;
+export declare function runHandlers(captured: Captured, name: string, event: unknown, ctx: ExtensionContext): Promise<void>;
+export declare function runHandlersAsync(captured: Captured, name: string, event: unknown, ctx: ExtensionContext): Promise<unknown[]>;
+export declare function completeRequestedCompaction(ctx: ExtensionContext): void;
+export declare function runCommand(captured: Captured, name: string, args: string, ctx: ExtensionContext): Promise<Notice[]>;
+export type ContextHookResult = {
+    messages: unknown[];
+} | undefined;
+export declare function runContextHook(captured: Captured, ctx: ExtensionContext, eventOverride?: Record<string, unknown>): Promise<ContextHookResult>;
+export declare function runContextWithSystemHook(captured: Captured, ctx: ExtensionContext, messages: unknown[]): Promise<ContextHookResult>;
+export declare function commitTurnEndBoundary(captured: Captured, sessionManager: SessionManager, ctx: ExtensionContext): Promise<{
+    entries: SessionBoundaryDraft[];
+    continue: boolean;
+}>;
+export declare function appendText(sessionManager: SessionManager, role: "user" | "assistant" | "toolResult", text: string, toolName?: string): string;
+export {};

package/dist/test/helpers/extension.js

@@ -4,9 +4,9 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import piContext, { createPiContext } from "../../src/index.js";
-import { loadNotesSnapshot } from "../../src/notes/notes-snapshot.js";
+import { loadNotesSnapshot } from "../../src/pi/notes/snapshot.js";
 import { renderBootBlock } from "../../src/context/prompts.js";
-import { agentSlug, modelSlug } from "../../src/notes/paths.js";
+import { agentSlug, modelSlug } from "../../src/pi/notes/adapter.js";
 import { rootWindowId } from "../../src/context/context-window.js";
 import { TOOL_OUTPUT_MAX_BYTES } from "../../src/tool-output.js";
 let defaultCwd = "/private/tmp/pi-context-test-cwd";
@@ -130,14 +130,14 @@ export function makeExtension(sessionManager, settingsManager) {
     (settingsManager ? createPiContext({ settingsManager }) : piContext)(api);
     return captured;
 }
-export function explicitBoot(ctx, currentWindowId, previousWindowId) {
+export async function explicitBoot(ctx, currentWindowId, previousWindowId) {
     return renderBootBlock({
         agentName: agentSlug(ctx),
         modelName: modelSlug(ctx),
         firstWindowId: rootWindowId(ctx.sessionManager.getSessionId()),
         currentWindowId,
         previousWindowId,
-        notes: loadNotesSnapshot(ctx),
+        notes: await loadNotesSnapshot(ctx),
     });
 }
 export function context(sessionManager, compact, usage, idle = true, cwd = defaultCwd, projectTrusted = true, model) {
@@ -270,13 +270,13 @@ export async function runManualCompact(captured, ctx) {
     };
     return (await handler(event, ctx));
 }
-export function runHandlers(captured, name, event, ctx) {
+export async function runHandlers(captured, name, event, ctx) {
     const isIdle = ctx.isIdle;
     if (name === "agent_settled")
         ctx.isIdle = () => true;
     try {
         for (const handler of captured.handlers.get(name) ?? [])
-            handler(event, ctx);
+            await handler(event, ctx);
     }
     finally {
         ctx.isIdle = isIdle;

package/dist/test/helpers/notes.d.ts

@@ -0,0 +1,6 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type NoteRow, type NotesQuery, type Scope } from "../../src/notes/index.js";
+/** Test-only conveniences for fixtures that still model notes through a live Pi context. */
+export declare function physicalPath(scope: Scope, path: string, ctx: ExtensionContext, who?: string): string;
+export declare function scopeDir(scope: Scope, ctx: ExtensionContext, who?: string): string;
+export declare function listNotes(ctx: ExtensionContext, query?: NotesQuery): Promise<NoteRow[]>;

package/dist/test/helpers/notes.js

@@ -0,0 +1,13 @@
+import { createNotesStore } from "../../src/notes/index.js";
+import { notesContextFromPi } from "../../src/pi/notes/adapter.js";
+import { physicalPath as corePhysicalPath, scopeDir as coreScopeDir } from "../../src/notes/paths.js";
+/** Test-only conveniences for fixtures that still model notes through a live Pi context. */
+export function physicalPath(scope, path, ctx, who) {
+    return corePhysicalPath(scope, path, notesContextFromPi(ctx), who);
+}
+export function scopeDir(scope, ctx, who) {
+    return coreScopeDir(scope, notesContextFromPi(ctx), who);
+}
+export function listNotes(ctx, query = {}) {
+    return createNotesStore(notesContextFromPi(ctx)).list(query);
+}

package/dist/test/history.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/notes-library.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/notes-library.test.js

@@ -0,0 +1,111 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { createNotesStore, NoteError } from "../src/notes/index.js";
+function fixture(t) {
+    const home = mkdtempSync(join(tmpdir(), "notes-library-"));
+    t.after(() => rmSync(home, { recursive: true, force: true }));
+    const context = { home, sessionId: "session-a", projectKey: "project-12345678", agent: "root", model: "test-model" };
+    return { home, context, notes: createNotesStore(context) };
+}
+test("standalone notes API persists camelCase metadata, edits, lists and searches full results", async (t) => {
+    const { home, notes } = fixture(t);
+    const first = await notes.write("checkpoint", "alpha\nneedle 😀", { origin: "user" });
+    assert.equal(first.meta.project, "project-12345678");
+    const read = (await notes.read("checkpoint.md"));
+    assert.equal(read.body, "alpha\nneedle 😀");
+    assert.equal(read.meta.origin, "user");
+    assert.equal(read.meta.accessCount, 1);
+    assert.equal(await notes.read("missing.md"), undefined);
+    const edited = await notes.edit("checkpoint", [{ oldText: "alpha", newText: "beta" }]);
+    assert.deepEqual(edited.change, { kind: "body", before: "alpha\nneedle 😀", after: "beta\nneedle 😀" });
+    assert.equal(edited.resolvedScope, read.resolvedScope);
+    assert.equal(edited.applied, 1);
+    const metadataEdit = await notes.edit("checkpoint", undefined, { stale: true });
+    assert.equal(metadataEdit.change.kind, "metadata");
+    assert.match(metadataEdit.change.before, /\nstale: false\n/);
+    assert.match(metadataEdit.change.after, /\nstale: true\n/);
+    assert.equal(metadataEdit.change.after.includes("needle"), false, "metadata-only diff excludes body");
+    assert.equal((await notes.list())[0]?.meta.stale, true);
+    const matches = await notes.search(["needle"]);
+    assert.equal(matches[0]?.matches[0]?.line, 2);
+    const text = (await notes.read("checkpoint")).text;
+    assert.equal(Array.from(text).slice(matches[0].matches[0].offsetChars).join(""), "needle 😀");
+    // An existing hand-written extra field and original ownership survive a new caller.
+    const path = join(home, "pi/session/session-a/checkpoint.md");
+    writeFileSync(path, readFileSync(path, "utf8").replace("\n---\n\n", "\nsourceWindow: pcw:test\nrecurrenceCount: 2\nrecurrenceWindows:\n  - pcw:one\n  - pcw:two\n__proto__: {\"sentinel\":true}\ncustom: preserved\n---\n\n"));
+    const moved = createNotesStore({ home, sessionId: "session-a", projectKey: "other-12345678", agent: "root", model: "test-model" });
+    const rewritten = await moved.write("checkpoint", "new body");
+    assert.equal(rewritten.meta.createdAt, first.meta.createdAt);
+    assert.equal(rewritten.meta.project, "project-12345678");
+    assert.equal(rewritten.meta.custom, "preserved");
+    assert.deepEqual(rewritten.meta["__proto__"], { sentinel: true });
+    assert.deepEqual((await moved.read("checkpoint"))?.meta["__proto__"], { sentinel: true }, "unknown __proto__ metadata survives persistence and reread");
+    assert.equal(rewritten.meta.sourceWindow, "pcw:test");
+    assert.equal(rewritten.meta.recurrenceCount, 2);
+    assert.deepEqual(rewritten.meta.recurrenceWindows, ["pcw:one", "pcw:two"]);
+    assert.equal(rewritten.meta.stale, false);
+    const combined = await moved.edit("checkpoint", [{ oldText: "new", newText: "final" }], { stale: true });
+    assert.equal(combined.change.kind, "file");
+    assert.match(combined.change.after, /\nstale: true\n/);
+    assert.match(combined.change.after, /final body$/);
+    assert.deepEqual((await moved.edit("checkpoint", undefined, { stale: true })).change, { kind: "none", before: "", after: "" });
+});
+test("same-file read/modify/write operations serialize across stores and markdown aliases", async (t) => {
+    const { home, context, notes } = fixture(t);
+    const other = createNotesStore(context);
+    await notes.write("shared", "alpha\nbeta");
+    const firstEdit = notes.edit("shared", [{ oldText: "alpha", newText: "A" }]);
+    const secondEdit = other.edit("shared.md", [{ oldText: "beta", newText: "B" }]);
+    await Promise.all([firstEdit, secondEdit]);
+    assert.equal((await notes.read("shared"))?.body, "A\nB", "edits through address aliases retain both changes");
+    const before = (await notes.read("shared")).meta.accessCount;
+    const [readA, readB] = await Promise.all([notes.read("shared.md"), other.read("shared")]);
+    assert.ok(readA && readB);
+    assert.equal((await notes.list({ scope: "session" }))[0]?.meta.accessCount, before + 2, "parallel reads do not lose access-counter updates");
+    const file = join(home, "pi/session/session-a/shared.md");
+    const stableEdits = [{ oldText: "A", newText: "first" }];
+    const operation = notes.edit("shared", stableEdits);
+    stableEdits[0].newText = "mutated after call";
+    await operation;
+    assert.equal((await notes.read("shared"))?.body, "first\nB", "edit arguments are snapshotted at method entry");
+    assert.equal(readFileSync(file, "utf8").includes("mutated after call"), false);
+});
+test("stores snapshot explicit identity and do not leak homes across instances", async (t) => {
+    const { home, context } = fixture(t);
+    const mutable = { ...context };
+    const notes = createNotesStore(mutable);
+    const other = createNotesStore({ ...context, home: join(home, "other"), agent: "other-agent", model: "other-model" });
+    assert.equal(existsSync(join(home, "other")), false, "construction does not create the supplied home");
+    mutable.agent = "changed-after-construction";
+    await notes.write("@self/private", "first");
+    await other.write("@self/private", "second");
+    assert.equal((await notes.read("@self/private"))?.body, "first");
+    assert.equal((await other.read("@self/private"))?.body, "second");
+    assert.equal((await notes.list())[0]?.address, "@agents/root/private.md");
+    assert.equal((await other.list())[0]?.address, "@agents/other-agent/private.md");
+    mkdirSync(join(home, "agents/visitor"), { recursive: true });
+    writeFileSync(join(home, "agents/visitor/hello.md"), "visiting");
+    assert.equal((await notes.read("@agents/visitor/hello"))?.body, "visiting");
+    await assert.rejects(() => notes.write("@agents/visitor/hello", "overwrite"), (error) => error instanceof NoteError && error.code === "invalid_scope");
+});
+test("invalid addressing and failed edits leave stored bytes untouched without poisoning the queue", async (t) => {
+    const { home, context, notes } = fixture(t);
+    assert.throws(() => createNotesStore({ ...context, sessionId: "../escape" }));
+    await assert.rejects(() => notes.write("@project/../escape", "bad"));
+    await assert.rejects(() => notes.list({ scope: "agent", who: "../escape" }));
+    // The typed API disallows this; JavaScript callers must still receive a refusal.
+    // @ts-expect-error who cannot accompany project scope
+    await assert.rejects(() => notes.list({ scope: "project", who: "root" }), (error) => error instanceof NoteError && error.code === "invalid_scope");
+    await notes.write("edit", "alpha\nbeta\nbeta");
+    const path = join(home, "pi/session/session-a/edit.md");
+    const before = readFileSync(path, "utf8");
+    await assert.rejects(() => notes.edit("edit", [{ oldText: "beta", newText: "B" }]), (error) => error instanceof NoteError && error.code === "ambiguous_edit" && error.lineNumbers?.join(",") === "2,3");
+    await assert.rejects(() => notes.edit("edit", [{ oldText: "alpha", newText: "A" }, { oldText: "absent", newText: "X" }]), (error) => error instanceof NoteError && error.code === "no_match" && error.editIndex === 1);
+    assert.equal(readFileSync(path, "utf8"), before);
+    await assert.rejects(() => notes.edit("absent", undefined, { stale: true }), (error) => error instanceof NoteError && error.code === "not_found");
+    await notes.edit("edit", [{ oldText: "alpha", newText: "A" }]);
+    assert.equal((await notes.read("edit"))?.body, "A\nbeta\nbeta", "failed operations do not poison later queue work");
+});

package/dist/test/notes.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/notes.integration.test.js

@@ -2,11 +2,10 @@ import assert from "node:assert/strict";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import test from "node:test";
-import { loadNotesSnapshot as loadNotesSnapshot } from "../src/notes/notes-snapshot.js";
+import { loadNotesSnapshot } from "../src/pi/notes/snapshot.js";
 import { renderBootBlock } from "../src/context/prompts.js";
 import { localIso } from "../src/notes/frontmatter.js";
-import { physicalPath, scopeDir } from "../src/notes/paths.js";
-import { listNotes } from "../src/notes/store.js";
+import { listNotes, physicalPath, scopeDir } from "./helpers/notes.js";
 import { TOOL_OUTPUT_MAX_BYTES } from "../src/tool-output.js";
 import { assertWithinBudget, call, context, explicitBoot, installExtensionTestEnvironment, makeExtension, manager, resultJson, resultRead, } from "./helpers/extension.js";
 const testEnvironment = installExtensionTestEnvironment("pi-context-integration");
@@ -20,7 +19,7 @@ test("notes_list is most-recently-updated first across merged scopes", async ()
     const put = (scope, path, updated) => {
         const file = physicalPath(scope, path, ctx);
         mkdirSync(dirname(file), { recursive: true });
-        writeFileSync(file, `---\nscope: ${scope}\norigin: self\nstatus: active\nstale: false\ncreated_at: ${localIso(updated - 1000)}\nupdated_at: ${localIso(updated)}\nlast_accessed: ${localIso(updated)}\naccess_count: 0\n---\n\nbody`);
+        writeFileSync(file, `---\nscope: ${scope}\norigin: self\nstatus: active\nstale: false\ncreatedAt: ${localIso(updated - 1000)}\nupdatedAt: ${localIso(updated)}\nlastAccessed: ${localIso(updated)}\naccessCount: 0\n---\n\nbody`);
     };
     const base = 1_700_000_000_000;
     put("session", "b.md", base + 10);
@@ -56,7 +55,6 @@ test("notes are real files that persist across sessions and round-trip Unicode",
     // A single-segment * never crosses `/`, so a nested-only store matches nothing at the root.
     const rootOnly = resultJson(await call(restoredCaptured, "notes_list", { pattern: "*", scope: "human" }, restoredCtx));
     assert.equal(rootOnly.files.length, 0, "glob * stays within one segment");
-    assert.equal(searched.files[0]?.created_at, listedFiles.files[0]?.created_at, "note tools agree on the timestamp format");
     assert.equal(searched.files[0]?.updated_at, listedFiles.files[0]?.updated_at);
     await assert.rejects(() => call(captured, "notes_write", { path: "../escape", content: "x" }, ctx), /unsupported component/);
 });
@@ -68,29 +66,29 @@ test("stale lifecycle: writes and metadata-only edits close and revive a note",
     // metadata-only: content unchanged, flag set, applied 0
     const markOnly = resultJson(await call(captured, "notes_edit", { path: "journal.md", stale: true }, ctx));
     assert.equal(markOnly.applied, 0);
-    assert.equal(listNotes(ctx, { scope: "session" })[0]?.meta.stale, true);
+    assert.equal((await listNotes(ctx, { scope: "session" }))[0]?.meta.stale, true);
     assert.equal(resultRead(await call(captured, "notes_read", { path: "journal.md" }, ctx)).content.endsWith("log line"), true, "mark-only leaves content unchanged");
     // explicit revive
     const revived = resultJson(await call(captured, "notes_edit", { path: "journal.md", stale: false }, ctx));
-    assert.equal(listNotes(ctx, { scope: "session" })[0]?.meta.stale, false, "stale:false revives");
+    assert.equal((await listNotes(ctx, { scope: "session" }))[0]?.meta.stale, false, "stale:false revives");
     // write+stale closure then plain write revival
     await call(captured, "notes_write", { path: "journal.md", content: "final", stale: true }, ctx);
-    assert.equal(listNotes(ctx, { scope: "session" })[0]?.meta.stale, true);
+    assert.equal((await listNotes(ctx, { scope: "session" }))[0]?.meta.stale, true);
     await call(captured, "notes_write", { path: "journal.md", content: "reopened" }, ctx);
-    assert.equal(listNotes(ctx, { scope: "session" })[0]?.meta.stale, false, "writing without stale revives");
+    assert.equal((await listNotes(ctx, { scope: "session" }))[0]?.meta.stale, false, "writing without stale revives");
     // metadata-only on a missing path is the typed not-found arm
     const missing = resultJson(await call(captured, "notes_edit", { path: "missing.md", stale: true }, ctx));
     assert.equal(missing.error, "note not found");
 });
-test("the filesystem notes loader treats an absent home as empty but surfaces a real directory read failure", () => {
+test("the filesystem notes loader treats an absent home as empty but surfaces a real directory read failure", async () => {
     const sm = manager();
     const ctx = context(sm);
-    assert.deepEqual(listNotes(ctx, { scope: "human" }), [], "a home that has not been created is empty");
+    assert.deepEqual(await listNotes(ctx, { scope: "human" }), [], "a home that has not been created is empty");
     const blockedHome = scopeDir("human", ctx);
     writeFileSync(blockedHome, "not a directory");
-    assert.throws(() => listNotes(ctx, { scope: "human" }), (error) => error.code === "ENOTDIR", "a non-ENOENT directory failure is not swallowed as an empty home");
+    await assert.rejects(() => listNotes(ctx, { scope: "human" }), (error) => error.code === "ENOTDIR", "a non-ENOENT directory failure is not swallowed as an empty home");
 });
-test("boot note acquisition is one closed snapshot and isolates one or all failed homes", () => {
+test("boot note acquisition is one closed snapshot and isolates one or all failed homes", async () => {
     const sm = manager();
     const ctx = context(sm);
     const updated = Date.now();
@@ -105,10 +103,10 @@ test("boot note acquisition is one closed snapshot and isolates one or all faile
             origin: "self",
             status: "active",
             stale: false,
-            created_at: updated,
-            updated_at: updated,
-            last_accessed: updated,
-            access_count: 0,
+            createdAt: updated,
+            updatedAt: updated,
+            lastAccessed: updated,
+            accessCount: 0,
         },
     });
     const rows = new Map([
@@ -119,7 +117,7 @@ test("boot note acquisition is one closed snapshot and isolates one or all faile
         ["model", [note("model", "model.md", "@models/default/model.md", "MODEL_POCKET_BODY")]],
     ]);
     const calls = new Map();
-    const snapshot = loadNotesSnapshot(ctx, (_ctx, scope) => {
+    const snapshot = await loadNotesSnapshot(ctx, (_ctx, scope) => {
         calls.set(scope, (calls.get(scope) ?? 0) + 1);
         return rows.get(scope) ?? [];
     });
@@ -138,7 +136,7 @@ test("boot note acquisition is one closed snapshot and isolates one or all faile
     assert.ok(rendered.includes("session.md") && rendered.includes("@human/human.md"), "pocket rows come from the same snapshot");
     assert.equal(rendered.includes("SESSION_POCKET_BODY"), false, "pocket bodies stay excluded");
     const readFailure = (code) => Object.assign(new Error("scripted read failure"), { code });
-    const oneFailed = loadNotesSnapshot(ctx, (_ctx, scope) => {
+    const oneFailed = await loadNotesSnapshot(ctx, (_ctx, scope) => {
         if (scope === "human")
             throw readFailure("EIO");
         return rows.get(scope) ?? [];
@@ -153,7 +151,7 @@ test("boot note acquisition is one closed snapshot and isolates one or all faile
     });
     assert.ok(oneFailedText.includes("PROJECT_MAP_BODY") && oneFailedText.includes("notes_list can retry after recovery"), "healthy homes and the recovery notice survive one failure");
     assert.equal(oneFailedText.includes("HUMAN_POCKET_BODY"), false, "the failed home's index is omitted");
-    const allFailed = loadNotesSnapshot(ctx, (_ctx, scope) => {
+    const allFailed = await loadNotesSnapshot(ctx, (_ctx, scope) => {
         throw readFailure(scope === "session" ? "EACCES" : "EIO");
     });
     assert.equal(allFailed.unavailable.length, 5);
@@ -168,12 +166,12 @@ test("boot note acquisition is one closed snapshot and isolates one or all faile
     assert.ok(allFailedText.includes("pcw:test:root") && allFailedText.includes("pcw:test:next"), "identity survives an all-home failure");
     assert.ok(allFailedText.includes("Your memory resets whenever the context window fills"), "protocol survives an all-home failure");
     assert.equal(allFailedText.includes("scripted read failure"), false, "the model-facing notice does not expose OS/error details");
-    assert.throws(() => loadNotesSnapshot(ctx, () => { throw new TypeError("programmer failure"); }), (error) => error instanceof TypeError, "unrelated TypeError construction failures remain visible");
-    assert.throws(() => loadNotesSnapshot(ctx, () => { throw Object.assign(new Error("invalid argument"), { code: "ERR_INVALID_ARG_TYPE" }); }), (error) => error.code === "ERR_INVALID_ARG_TYPE", "Node ERR_* failures are not treated as filesystem errno failures");
+    await assert.rejects(() => loadNotesSnapshot(ctx, () => { throw new TypeError("programmer failure"); }), (error) => error instanceof TypeError, "unrelated TypeError construction failures remain visible");
+    await assert.rejects(() => loadNotesSnapshot(ctx, () => { throw Object.assign(new Error("invalid argument"), { code: "ERR_INVALID_ARG_TYPE" }); }), (error) => error.code === "ERR_INVALID_ARG_TYPE", "Node ERR_* failures are not treated as filesystem errno failures");
 });
-test("the boot block gives awake agents the notes-home file layout", () => {
+test("the boot block gives awake agents the notes-home file layout", async () => {
     const session = manager();
-    const rendered = explicitBoot(context(session), "pcw:test:root", undefined);
+    const rendered = await explicitBoot(context(session), "pcw:test:root", undefined);
     assert.equal(rendered.includes(process.env.PI_NOTES_HOME ?? ""), false, "the absolute notes home is never exposed");
     assert.match(rendered, /bare <vpath>.*@project\/<vpath>.*@human\/<vpath>/);
 });

package/dist/test/notes.test.d.ts

@@ -0,0 +1 @@
+export {};