@astrosheep/pi-context 0.25.1 → 0.26.0

package/dist/test/boot.integration.test.js

@@ -1,8 +1,9 @@
 import assert from "node:assert/strict";
+import { rmSync, writeFileSync } from "node:fs";
 import test from "node:test";
 import { historyFromSession, internal } from "../src/index.js";
-import { listNotes } from "../src/notes/store.js";
-import { CONTINUATION_TYPE } from "../src/protocol.js";
+import { listNotes } from "./helpers/notes.js";
+import { CONTINUATION_TYPE, WARNING_TYPE } from "../src/protocol.js";
 import { appendText, call, commitTurnEndBoundary, context, installExtensionTestEnvironment, makeExtension, manager, noticesOf, resultJson, resultRead, runContextHook, runContextWithSystemHook, runHandlers, runManualCompact, runCommand, sentOf, } from "./helpers/extension.js";
 const testEnvironment = installExtensionTestEnvironment("pi-context-integration");
 test.beforeEach(() => testEnvironment.beforeEach());
@@ -21,7 +22,12 @@ test("custom reset marker removes old provider context while history remains sea
     const branch = sessionManager.getBranch();
     const marker = branch.find((entry) => entry.type === "custom" && entry.customType === internal.RESET_MARKER_TYPE);
     assert.ok(marker && marker.type === "custom");
-    assert.equal(marker.parentId, toolResultId, "marker follows the completed tool result");
+    const checkpoint = branch.find((entry) => entry.type === "compaction");
+    assert.ok(checkpoint && checkpoint.type === "compaction", "reset persists a native retain-none checkpoint");
+    assert.equal(checkpoint.parentId, toolResultId, "checkpoint follows the completed tool result");
+    assert.equal(checkpoint.summary, "");
+    assert.equal(checkpoint.firstKeptEntryId, checkpoint.id);
+    assert.equal(marker.parentId, checkpoint.id, "marker follows the native checkpoint");
     assert.deepEqual(Object.keys(marker.data), ["windowId"]);
     const projected = await runContextWithSystemHook(captured, ctx, sessionManager.buildSessionContext().messages);
     const providerText = JSON.stringify(projected?.messages ?? []);
@@ -46,14 +52,14 @@ test("the root boot and reset boot carry durable window identity", async () => {
     appendText(sessionManager, "assistant", "working");
     await call(captured, "notes_write", { path: "decisions.md", content: "use terra" }, ctx);
     // Root window: session_start persists the boot block without triggering a turn.
-    runHandlers(captured, "session_start", { reason: "startup" }, ctx);
+    await runHandlers(captured, "session_start", { reason: "startup" }, ctx);
     assert.equal(captured.sent.length, 1);
     const rootBoot = captured.sent[0];
     assert.equal(rootBoot?.message.customType, internal.BOOT_TYPE);
     assert.equal(rootBoot?.message.display, false, "boot block stays out of the TUI");
     assert.equal(rootBoot?.options?.triggerTurn, false);
     assert.equal(noticesOf(ctx).length, 0, "initial boot is silent");
-    runHandlers(captured, "session_start", { reason: "reload" }, ctx);
+    await runHandlers(captured, "session_start", { reason: "reload" }, ctx);
     assert.equal(noticesOf(ctx).length, 0, "reload is silent");
     assert.deepEqual(rootBoot?.message.details, { windowId: `pcw:${sessionManager.getSessionId().slice(0, 8)}:root` });
     const rootText = typeof rootBoot?.message.content === "string" ? rootBoot.message.content : "";
@@ -63,7 +69,7 @@ test("the root boot and reset boot carry durable window identity", async () => {
     assert.match(rootText, new RegExp(`First context window id: pcw:${sessionManager.getSessionId().slice(0, 8)}:root`));
     assert.match(rootText, new RegExp(`Current context window id: pcw:${sessionManager.getSessionId().slice(0, 8)}:root`));
     assert.ok(rootText.includes("decisions.md"));
-    const decisionsMeta = listNotes(ctx, { scope: "session" }).find((row) => row.path === "decisions.md")?.meta;
+    const decisionsMeta = (await listNotes(ctx, { scope: "session" })).find((row) => row.path === "decisions.md")?.meta;
     assert.ok(decisionsMeta);
     assert.match(rootText, /updated \d+s ago\)/, "boot note metadata carries a relative update time");
     assert.ok(rootText.includes(internal.CONTEXT_WINDOW_PROTOCOL_OPEN_TAG));
@@ -72,8 +78,8 @@ test("the root boot and reset boot carry durable window identity", async () => {
     assert.equal(noticesOf(ctx).length, 0, "requesting a reset does not announce success");
     const boundary = await commitTurnEndBoundary(captured, sessionManager, ctx);
     assert.equal(boundary.continue, true);
-    runHandlers(captured, "turn_start", {}, ctx);
-    runHandlers(captured, "agent_settled", {}, ctx);
+    await runHandlers(captured, "turn_start", {}, ctx);
+    await runHandlers(captured, "agent_settled", {}, ctx);
     assert.equal(noticesOf(ctx).filter((notice) => notice.message.includes("memory cleared")).length, 1, "the committed reset is announced once");
     const entries = sessionManager.getBranch();
     const marker = entries.find((entry) => entry.type === "custom" && entry.customType === internal.RESET_MARKER_TYPE);
@@ -85,7 +91,28 @@ test("the root boot and reset boot carry durable window identity", async () => {
     const continuation = entries.find((entry) => entry.type === "custom_message" && entry.customType === CONTINUATION_TYPE);
     assert.ok(continuation && continuation.type === "custom_message" && continuation.display === false, "the resumed run is represented by one hidden continuation");
 });
-test("a marker tail with only metadata repairs its missing boot and continuation without moving the boundary", () => {
+test("an aborted async boot repair emits no boot, continuation, or incomplete-notes notice", async () => {
+    const notesHome = process.env.PI_NOTES_HOME;
+    assert.ok(notesHome);
+    rmSync(notesHome, { recursive: true, force: true });
+    writeFileSync(notesHome, "not a directory");
+    const sessionManager = manager();
+    const windowId = "pcw:aborted-boot-repair";
+    sessionManager.appendCustomEntry(internal.RESET_MARKER_TYPE, { windowId });
+    const captured = makeExtension(sessionManager);
+    const ctx = context(sessionManager);
+    const controller = new AbortController();
+    ctx.signal = controller.signal;
+    const sessionStart = captured.handlers.get("session_start")?.[0];
+    assert.ok(sessionStart);
+    const pending = sessionStart({ reason: "startup" }, ctx);
+    controller.abort();
+    await pending;
+    assert.equal(captured.sent.length, 0, "aborted snapshot work cannot append the reset boot or continuation");
+    assert.equal(noticesOf(ctx).some((notice) => notice.message.includes("notes index incomplete")), false, "aborted snapshot work cannot notify about missing homes");
+    assert.equal(sessionManager.getBranch().some((entry) => entry.type === "custom_message" && [internal.BOOT_TYPE, CONTINUATION_TYPE].includes(entry.customType)), false);
+});
+test("a marker tail with only metadata repairs its missing boot and continuation without moving the boundary", async () => {
     const sessionManager = manager(true);
     const windowId = "pcw:metadata-tail";
     const markerId = sessionManager.appendCustomEntry(internal.RESET_MARKER_TYPE, { windowId });
@@ -93,7 +120,7 @@ test("a marker tail with only metadata repairs its missing boot and continuation
     sessionManager.appendThinkingLevelChange("low");
     const captured = makeExtension(sessionManager);
     const ctx = context(sessionManager);
-    runHandlers(captured, "session_start", { reason: "startup" }, ctx);
+    await runHandlers(captured, "session_start", { reason: "startup" }, ctx);
     const branch = sessionManager.getBranch();
     const markerIndex = branch.findIndex((entry) => entry.id === markerId);
     const bootEntries = branch.filter((entry) => entry.type === "custom_message" && entry.customType === internal.BOOT_TYPE && entry.details && typeof entry.details === "object" && entry.details.windowId === windowId);
@@ -108,13 +135,13 @@ test("a marker tail with only metadata repairs its missing boot and continuation
     assert.equal(captured.sent[1]?.message.customType, CONTINUATION_TYPE);
     assert.equal(noticesOf(ctx).length, 0, "repairing a reset tail is not a new reset");
 });
-test("a bare marker tail repairs the full ordered reset shape", () => {
+test("a bare marker tail repairs the full ordered reset shape", async () => {
     const sessionManager = manager(true);
     const windowId = "pcw:bare-marker";
     const markerId = sessionManager.appendCustomEntry(internal.RESET_MARKER_TYPE, { windowId });
     const captured = makeExtension(sessionManager);
     const ctx = context(sessionManager);
-    runHandlers(captured, "session_start", { reason: "startup" }, ctx);
+    await runHandlers(captured, "session_start", { reason: "startup" }, ctx);
     assert.equal(captured.sent.length, 2, "a bare marker emits a boot and a continuation");
     const branch = sessionManager.getBranch();
     const markerIndex = branch.findIndex((entry) => entry.id === markerId);
@@ -123,7 +150,7 @@ test("a bare marker tail repairs the full ordered reset shape", () => {
     assert.ok(bootIndex > markerIndex, "the repaired boot follows its marker");
     assert.ok(continuationIndex > bootIndex, "the repaired continuation follows its boot");
 });
-test("a marker tail that already carries a boot repairs only its missing continuation, once", () => {
+test("a marker tail that already carries a boot repairs only its missing continuation, once", async () => {
     const sessionManager = manager(true);
     const windowId = "pcw:missing-continuation";
     const markerId = sessionManager.appendCustomEntry(internal.RESET_MARKER_TYPE, { windowId });
@@ -131,23 +158,23 @@ test("a marker tail that already carries a boot repairs only its missing continu
     sessionManager.appendCustomMessageEntry(internal.BOOT_TYPE, "already-persisted boot", false, { windowId });
     const captured = makeExtension(sessionManager);
     const ctx = context(sessionManager);
-    runHandlers(captured, "session_start", { reason: "startup" }, ctx);
+    await runHandlers(captured, "session_start", { reason: "startup" }, ctx);
     assert.equal(captured.sent.length, 1, "only the missing continuation is emitted");
     assert.equal(captured.sent[0]?.message.customType, CONTINUATION_TYPE);
     assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === internal.BOOT_TYPE).length, 1, "the existing boot is never duplicated");
     assert.ok(sessionManager.getBranch().findIndex((entry) => entry.id === markerId) >= 0);
-    runHandlers(captured, "session_start", { reason: "reload" }, ctx);
+    await runHandlers(captured, "session_start", { reason: "reload" }, ctx);
     assert.equal(captured.sent.length, 1, "a complete reset tail is idempotent");
     assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === CONTINUATION_TYPE).length, 1);
 });
-test("a marker tail followed by real conversation is never repaired", () => {
+test("a marker tail followed by real conversation is never repaired", async () => {
     const sessionManager = manager(true);
     const windowId = "pcw:unsafe-tail";
     sessionManager.appendCustomEntry(internal.RESET_MARKER_TYPE, { windowId });
     appendText(sessionManager, "user", "post-marker work that must not be pushed behind a late boot");
     const captured = makeExtension(sessionManager);
     const ctx = context(sessionManager);
-    runHandlers(captured, "session_start", { reason: "startup" }, ctx);
+    await runHandlers(captured, "session_start", { reason: "startup" }, ctx);
     assert.equal(captured.sent.length, 0, "an unsafe marker tail emits nothing");
     assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === internal.BOOT_TYPE).length, 0, "no boot is appended after real work");
     assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === CONTINUATION_TYPE).length, 0, "no continuation is appended after real work");
@@ -180,37 +207,36 @@ test("wipe_memory uses one turn boundary and never calls ctx.compact", async ()
     assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom" && entry.customType === internal.RESET_MARKER_TYPE).length, 1);
     assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === internal.BOOT_TYPE && entry.details && typeof entry.details === "object" && "windowId" in entry.details).length, 1);
 });
-test("pi-context command toggles future work, /wipe-memory is the manual path, and active markers cancel /compact", async () => {
+test("pi-context command toggles future work, /wipe-memory starts close-out, and /compact remains disabled", async () => {
     const sessionManager = manager();
     appendText(sessionManager, "user", "hello");
     const captured = makeExtension(sessionManager);
     const low = context(sessionManager, undefined, { tokens: 170_000, contextWindow: 200_000, percent: 85 });
     // On by default: session_start persists the root boot block.
-    runHandlers(captured, "session_start", { reason: "startup" }, low);
+    await runHandlers(captured, "session_start", { reason: "startup" }, low);
     assert.equal(captured.sent.length, 1);
     assert.equal(captured.sent[0]?.message.customType, internal.BOOT_TYPE);
     let notices = await runCommand(captured, "pi-context", "off", low);
     assert.match(notices[0]?.message ?? "", /off/);
     assert.equal(await runContextHook(captured, low), undefined, "no guidance while off");
     assert.equal(sentOf(captured, internal.GUIDANCE_TYPE).length, 0, "no guidance persisted while off");
-    runHandlers(captured, "session_start", { reason: "startup" }, low);
+    await runHandlers(captured, "session_start", { reason: "startup" }, low);
     assert.equal(captured.sent.length, 1, "no new boot block is persisted while off");
     const offResult = resultJson(await call(captured, "wipe_memory", {}, low));
     assert.match(offResult.error ?? "", /off/, "wipe_memory refuses while off");
     notices = await runCommand(captured, "pi-context", "on", low);
     assert.match(notices[0]?.message ?? "", /on/);
     notices = await runCommand(captured, "wipe-memory", "", low);
-    assert.equal(notices.length, 1, "manual clear emits exactly one notification");
-    assert.match(notices[0]?.message ?? "", /memory cleared/);
-    assert.equal(captured.sent.length, 3, "/wipe-memory writes one hidden boot and one continuation without triggering a model turn");
-    assert.equal(captured.sent[1]?.options?.triggerTurn, false);
-    assert.equal(captured.sent[1]?.message.customType, internal.BOOT_TYPE);
-    assert.equal(captured.sent[2]?.message.customType, CONTINUATION_TYPE);
-    assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom" && entry.customType === internal.RESET_MARKER_TYPE).length, 1);
+    assert.equal(notices.length, 0, "the command begins a model close-out rather than announcing a reset request");
+    assert.equal(captured.sent.length, 2, "the command persists one hidden warning after the startup boot");
+    assert.equal(captured.sent[1]?.options?.triggerTurn, true, "the shared warning starts an ordinary agent turn");
+    assert.equal(captured.sent[1]?.message.customType, WARNING_TYPE);
+    assert.equal(captured.sent[1]?.message.display, false);
+    assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom" && entry.customType === internal.RESET_MARKER_TYPE).length, 0, "no reset is claimed until close-out completes");
     const markerContext = await runManualCompact(captured, low);
-    assert.deepEqual(markerContext, { cancel: true }, "/compact is canceled while a marker is active");
+    assert.deepEqual(markerContext, { cancel: true }, "/compact is canceled while context windows are enabled");
     const projected = await runContextWithSystemHook(captured, low, sessionManager.buildSessionContext().messages);
-    assert.equal(JSON.stringify(projected?.messages ?? []).includes("hello"), false, "off keeps the existing wipe in force");
+    assert.equal(JSON.stringify(projected?.messages ?? []).includes("hello"), true, "the old window remains active until the close-out commits");
     notices = await runCommand(captured, "pi-context", "maybe", low);
     assert.equal(notices[0]?.type, "error", "unknown argument rejected");
     // Bare command reports current state without changing it.

package/dist/test/budget-settings.integration.test.d.ts

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

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 {};