@astrosheep/pi-context 0.20.0 → 0.21.0

package/dist/test/{memory.test.js → notes.test.js}

@@ -11,16 +11,21 @@ import { existsSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } fro
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
-import { physicalPath, projectKey, scopeDir } from "../src/memory/paths.js";
-import { listNotes } from "../src/memory/store.js";
+import { physicalPath, projectKey, scopeDir } from "../src/notes/paths.js";
+import { listNotes } from "../src/notes/store.js";
 import { MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES, PROTOCOL_BLOCK } from "../src/protocol.js";
 import { call, context, makeExtension, manager, resultJson, resultRead, runHandlers } from "./integration.test.js";
-process.env.PI_CODING_AGENT_DIR = mkdtempSync(join(tmpdir(), "pi-context-memory-agent-"));
+process.env.PI_CODING_AGENT_DIR = mkdtempSync(join(tmpdir(), "pi-context-notes-agent-"));
 function freshRoot() {
     const root = mkdtempSync(join(tmpdir(), "pi-context-notes-"));
     process.env.PI_NOTES_HOME = root;
     return root;
 }
+function setUpdatedAt(scope, path, ctx, timestamp) {
+    const file = physicalPath(scope, path, ctx);
+    const raw = readFileSync(file, "utf8");
+    writeFileSync(file, raw.replace(/^updated_at: .*$/m, `updated_at: ${new Date(timestamp).toISOString()}`));
+}
 test("exactly the five notes tools are registered; the legacy five are gone", () => {
     const captured = makeExtension(manager());
     for (const name of ["notes_write", "notes_edit", "notes_read", "notes_list", "notes_search"]) {
@@ -48,9 +53,10 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     const raw = readFileSync(file, "utf8");
     assert.match(raw, /^---\n/, "the file opens with frontmatter");
     assert.match(raw, /\n---\n\nhello$/, "frontmatter is followed by a blank line and the exact body");
-    for (const [key, value] of [["scope", "session"], ["origin", "self"], ["status", "active"], ["stale", "false"], ["access_count", "0"]]) {
+    for (const [key, value] of [["origin", "self"], ["status", "active"], ["stale", "false"], ["access_count", "0"]]) {
         assert.match(raw, new RegExp(`^${key}: ${value}$`, "m"), `frontmatter carries ${key}=${value}`);
     }
+    assert.equal(/^scope:/m.test(raw), false, "scope is derived from the file home, never persisted");
     for (const key of ["created_at", "updated_at", "last_accessed"]) {
         assert.match(raw, new RegExp(`^${key}: \\d{4}-\\d{2}-\\d{2}T`, "m"), `frontmatter renders ${key} via localIso`);
     }
@@ -84,6 +90,14 @@ test("overwrite preserves created_at and unknown keys, bumps updated_at, and cle
     assert.equal(listed.meta.stale, false, "a plain rewrite clears stale");
     assert.equal(listed.meta.status, "active");
 });
+test("listNotes retains each parsed body for MAP injection", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    await call(captured, "notes_write", { path: "retained.md", content: "parsed once" }, ctx);
+    assert.equal(listNotes(ctx, { scope: "session" })[0]?.body, "parsed once");
+});
 test("edit is body-scoped with named failures and a replace_all escape hatch", async () => {
     freshRoot();
     const session = manager();
@@ -103,6 +117,30 @@ test("edit is body-scoped with named failures and a replace_all escape hatch", a
     const frontmatterOnly = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "scope", newText: "x" }] }, ctx));
     assert.equal(frontmatterOnly.edit_index, 0, "a frontmatter-only anchor is not a body match");
 });
+test("a single edit inserts newText byte-for-byte: no $-pattern substitution", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    // Each pattern is a JS String.replace replacement token. With positional splicing the whole
+    // two-character (or two-dollar) sequence lands literally; with String.replace it would expand,
+    // and the prefix token ($`) would splice in the entire document prefix.
+    const cases = ["$&", "$`", "$'", "$1", "$$"];
+    for (const token of cases) {
+        const newText = `pre${token}post`;
+        await call(captured, "notes_write", { path: "literal.md", content: "alpha\nbeta\ngamma" }, ctx);
+        const edited = resultJson(await call(captured, "notes_edit", { path: "literal.md", edits: [{ oldText: "beta", newText }] }, ctx));
+        assert.equal(edited.applied, 1, `the single edit for ${JSON.stringify(token)} applied`);
+        const body = resultRead(await call(captured, "notes_read", { path: "literal.md" }, ctx)).content;
+        assert.equal(body.endsWith(`alpha\n${newText}\ngamma`), true, `${JSON.stringify(token)} is inserted literally`);
+        assert.equal(body.endsWith(`alpha\nalpha\npre${token}post\ngamma`), false, `${JSON.stringify(token)} does not splice in the document prefix`);
+    }
+    // The replace_all branch (split/join) is likewise literal, so both branches agree.
+    await call(captured, "notes_write", { path: "literal-all.md", content: "one X two X three" }, ctx);
+    await call(captured, "notes_edit", { path: "literal-all.md", edits: [{ oldText: "X", newText: "$`$&$1$$" }], replace_all: true }, ctx);
+    const allBody = resultRead(await call(captured, "notes_read", { path: "literal-all.md" }, ctx)).content;
+    assert.equal(allBody.endsWith("one $`$&$1$$ two $`$&$1$$ three"), true, "replace_all inserts $-patterns literally too");
+});
 test("metadata-only edit updates setters without touching the body", async () => {
     freshRoot();
     const session = manager();
@@ -134,12 +172,12 @@ test("notes_edit returns a pi-edit-style diff of what changed", async () => {
     assert.match(metaOnly.diff, /- *\d+ stale: false/);
     assert.match(metaOnly.diff, /\+ *\d+ stale: true/);
     assert.equal(metaOnly.diff.includes("alpha"), false, "a metadata-only diff does not drag the body in");
-    // Both → one combined diff naming body and frontmatter changes.
-    const combined = resultJson(await call(captured, "notes_edit", { path: "d.md", edits: [{ oldText: "alpha", newText: "ALPHA" }], scope: "project" }, ctx));
+    // Both → one combined diff naming body and frontmatter changes, without moving homes.
+    const combined = resultJson(await call(captured, "notes_edit", { path: "d.md", edits: [{ oldText: "alpha", newText: "ALPHA" }], stale: false }, ctx));
     assert.match(combined.diff, /- *\d+ alpha/);
     assert.match(combined.diff, /\+ *\d+ ALPHA/);
-    assert.match(combined.diff, /- *\d+ scope: session/);
-    assert.match(combined.diff, /\+ *\d+ scope: project/);
+    assert.match(combined.diff, /- *\d+ stale: true/);
+    assert.match(combined.diff, /\+ *\d+ stale: false/);
 });
 test("nothing-to-do, not-found, atomic batches, and replace_all zero-match are named", async () => {
     freshRoot();
@@ -167,7 +205,7 @@ test("nothing-to-do, not-found, atomic batches, and replace_all zero-match are n
     const zero = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "zzz", newText: "y" }], replace_all: true }, ctx));
     assert.equal(zero.edit_index, 0, "replace_all with zero matches is the same zero-match error, not a silent no-op");
 });
-test("scope resolution, access counting, and movement with a typed refusal", async () => {
+test.skip("scope resolution and movement are superseded by explicit address tests", async () => {
     freshRoot();
     const session = manager();
     const captured = makeExtension(session);
@@ -245,7 +283,7 @@ test("the boot index reads the physical store across scopes and excludes stale n
     assert.ok(text.includes("fresh.md"), "a fresh session note is indexed");
     assert.ok(text.includes("global.md"), "a fresh global note is indexed");
     assert.equal(text.includes("old.md"), false, "a stale note leaves the index");
-    assert.equal(text.includes("stale content"), false, "a stale preview is not rendered");
+    assert.equal(text.includes("stale content"), false, "the stale note's body is absent from boot");
     for (const name of ["notes_write", "notes_edit", "notes_read", "notes_search", "notes_list"]) {
         assert.ok(PROTOCOL_BLOCK.includes(name), `the protocol block names ${name}`);
     }
@@ -318,46 +356,54 @@ test("write-time caps refuse an oversized vpath or serialized file, and edit ref
     const refusedEdit = resultJson(await call(captured, "notes_edit", { path: "small.md", edits: [{ oldText: "small", newText: "y".repeat(MAX_NOTE_BYTES) }] }, ctx));
     assert.match(refusedEdit.error, new RegExp(String(MAX_NOTE_BYTES)), "an edit that would exceed the cap is refused");
 });
-test("a global TOC.md body is injected ahead of the recent-notes list", async () => {
+test("fresh global and project MAP.md bodies are both resident before the pocket", async () => {
     freshRoot();
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
-    await call(captured, "notes_write", { path: "TOC.md", content: "MAP: global\nMAP: second", scope: "global" }, ctx);
+    await call(captured, "notes_write", { address: "MAP.md", content: "MAP: session" }, ctx);
+    await call(captured, "notes_write", { address: "@project/MAP.md", content: "MAP: project" }, ctx);
+    await call(captured, "notes_write", { address: "@global/MAP.md", content: "MAP: global\nMAP: second" }, ctx);
     await call(captured, "notes_write", { path: "recent.md", content: "recent body" }, ctx);
     runHandlers(captured, "session_start", {}, ctx);
     const boot = typeof captured.sent.at(-1)?.message.content === "string" ? captured.sent.at(-1).message.content : "";
-    assert.ok(boot.includes("MAP: global"), "a global TOC is injected");
-    assert.ok(boot.indexOf("MAP: global") < boot.indexOf("crumpled note"), "the TOC body precedes the recent-notes list");
+    assert.ok(boot.includes("MAP: global"), "the global map is injected");
+    assert.ok(boot.includes("MAP: project"), "the project map is injected");
+    assert.equal(boot.includes("MAP: session"), false, "the session map is never injected");
+    assert.ok(boot.indexOf("MAP: global") < boot.indexOf("MAP: project"), "the global map precedes the project map");
+    assert.ok(boot.indexOf("MAP: project") < boot.indexOf("crumpled note"), "both map bodies precede the pocket");
     assert.ok(PROTOCOL_BLOCK.includes("notes_write"), "the protocol text still rides along");
 });
-test("a session TOC.md wins precedence over the global map", async () => {
-    freshRoot();
-    const session = manager();
-    const captured = makeExtension(session);
-    const ctx = context(session);
-    await call(captured, "notes_write", { path: "TOC.md", content: "MAP: global", scope: "global" }, ctx);
-    await call(captured, "notes_write", { path: "TOC.md", content: "MAP: session", scope: "session" }, ctx);
-    runHandlers(captured, "session_start", {}, ctx);
-    const boot = typeof captured.sent.at(-1)?.message.content === "string" ? captured.sent.at(-1).message.content : "";
-    const injected = boot.slice(0, boot.indexOf("crumpled note") === -1 ? boot.length : boot.indexOf("crumpled note"));
-    assert.ok(injected.includes("MAP: session"), "the session TOC wins the precedence");
-    assert.equal(injected.includes("MAP: global"), false, "only the first-hit TOC is injected");
-});
-test("the boot index admits up to five fresh notes and the protocol carries the exact stale line", async () => {
+test("the boot pocket applies per-home quotas in session, project, global order", async () => {
     freshRoot();
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
-    for (let index = 0; index < 6; index++) {
-        await call(captured, "notes_write", { path: `fresh-${index}.md`, content: `body ${index}` }, ctx);
+    const base = Date.parse("2026-01-01T00:00:00.000Z");
+    for (const [scope, count] of [["session", 6], ["project", 3], ["global", 3]]) {
+        for (let index = 0; index < count; index++) {
+            const path = `${scope}-${index}.md`;
+            await call(captured, "notes_write", { path, content: `${scope} body`, scope }, ctx);
+            setUpdatedAt(scope, path, ctx, base + index * 1_000);
+        }
     }
+    await call(captured, "notes_write", { address: "MAP.md", content: "MAP: session" }, ctx);
+    await call(captured, "notes_write", { address: "@project/MAP.md", content: "MAP: project" }, ctx);
+    await call(captured, "notes_write", { address: "@global/MAP.md", content: "MAP: global" }, ctx);
     runHandlers(captured, "session_start", {}, ctx);
     const boot = typeof captured.sent.at(-1)?.message.content === "string" ? captured.sent.at(-1).message.content : "";
-    assert.match(boot, /\(up to 5, most recent first\)/, "the pocket line says up to 5");
-    assert.equal((boot.match(/^- /gm) ?? []).length, 5, "exactly five fresh notes are indexed, not six");
-    assert.ok(PROTOCOL_BLOCK.includes("Mark outdated or unneeded notes stale — leave them, and they will keep misleading you."), "the protocol block carries the v2 stale line verbatim");
-    assert.equal(PROTOCOL_BLOCK.split("Mark outdated or unneeded notes stale — leave them, and they will keep misleading you.").length - 1, 1, "the stale line appears exactly once");
+    assert.ok(boot.includes("You find 9 crumpled notes in your pocket (by home, most recent first within each: up to 5 from this session, 2 from this project, 2 from global). A note's content never appears here, so its name has to say what the note is about:"), "the pocket line matches the dictated copy");
+    for (const name of ["session-5.md", "session-4.md", "session-3.md", "session-2.md", "session-1.md", "@project/project-2.md", "@project/project-1.md", "@global/global-2.md", "@global/global-1.md"]) {
+        assert.ok(boot.includes(name), `${name} stays in the pocket`);
+    }
+    for (const name of ["session-0.md", "@project/project-0.md", "@global/global-0.md", "MAP.md", "MAP: session"]) {
+        assert.equal(boot.includes(name), false, `${name} is not a pocket entry`);
+    }
+    assert.ok(boot.indexOf("session-5.md") < boot.indexOf("session-4.md"), "session notes are most-recent-first");
+    assert.ok(boot.indexOf("@project/project-2.md") < boot.indexOf("@project/project-1.md"), "project notes are most-recent-first");
+    assert.ok(boot.indexOf("@global/global-2.md") < boot.indexOf("@global/global-1.md"), "global notes are most-recent-first");
+    assert.ok(boot.indexOf("session-1.md") < boot.indexOf("@project/project-2.md"), "session notes precede project notes");
+    assert.ok(boot.indexOf("@project/project-1.md") < boot.indexOf("@global/global-2.md"), "project notes precede global notes");
 });
 test("project scope keys off the git root basename and sha1 prefix", () => {
     const root = mkdtempSync(join(tmpdir(), "pi-context-proj-"));
@@ -368,3 +414,61 @@ test("project scope keys off the git root basename and sha1 prefix", () => {
     assert.match(key, /^pi-context-proj-[^-]+-[0-9a-f]{8}$/, "the project key is basename plus an 8-hex sha1 prefix");
     assert.equal(scopeDir("project", ctx), join(process.env.PI_NOTES_HOME, "project", key));
 });
+test("@ addresses select one home, reject illegal sigils, and never fall back", async () => {
+    const root = freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    await call(captured, "notes_write", { address: "same.md", content: "session" }, ctx);
+    await call(captured, "notes_write", { address: "@project/same.md", content: "project" }, ctx);
+    await call(captured, "notes_write", { address: "@global/same.md", content: "global" }, ctx);
+    assert.ok(existsSync(physicalPath("project", "same.md", ctx)), "@project writes to the current project home");
+    assert.ok(existsSync(physicalPath("global", "same.md", ctx)), "@global writes to the global home");
+    assert.match(resultRead(await call(captured, "notes_read", { address: "same.md" }, ctx)).content, /session$/);
+    assert.equal(resultJson(await call(captured, "notes_read", { address: "@project/missing.md" }, ctx)).error, "note not found");
+    await assert.rejects(() => call(captured, "notes_read", { address: "@glboal/same.md" }, ctx), /@project\/.*@global\/.*bare names are the session home/);
+    await assert.rejects(() => call(captured, "notes_write", { address: "bad@name.md", content: "no" }, ctx), /@project\/.*@global\/.*bare names are the session home/);
+    assert.equal(existsSync(join(root, "global", "bad@name.md")), false, "a bad sigil creates nothing anywhere");
+});
+test("full addresses drive outputs and patterns; legacy scope is read then dropped", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    await call(captured, "notes_write", { address: "root.md", content: "needle" }, ctx);
+    await call(captured, "notes_write", { address: "@project/project.md", content: "needle" }, ctx);
+    await call(captured, "notes_write", { address: "@global/global.md", content: "needle" }, ctx);
+    const list = resultJson(await call(captured, "notes_list", { pattern: "**" }, ctx));
+    assert.deepEqual(list.files.map((file) => file.address).sort(), ["@global/global.md", "@project/project.md", "root.md"]);
+    assert.deepEqual(resultJson(await call(captured, "notes_list", { pattern: "*.md" }, ctx)).files.map((file) => file.address), ["root.md"]);
+    assert.deepEqual(resultJson(await call(captured, "notes_search", { query: "needle", pattern: "@project/**" }, ctx)).files.map((file) => file.address), ["@project/project.md"]);
+    const read = resultRead(await call(captured, "notes_read", { address: "@global/global.md" }, ctx));
+    assert.match(read.header, /^\[@global\/global\.md /, "the raw read header echoes the full address");
+    const legacy = physicalPath("project", "legacy.md", ctx);
+    writeFileSync(legacy, "---\nscope: global\norigin: self\nstatus: active\nstale: false\ncreated_at: 2026-01-01T00:00:00.000+00:00\nupdated_at: 2026-01-01T00:00:00.000+00:00\nlast_accessed: 2026-01-01T00:00:00.000+00:00\naccess_count: 0\n---\n\nlegacy");
+    const legacyRead = resultRead(await call(captured, "notes_read", { address: "@project/legacy.md" }, ctx));
+    assert.equal(legacyRead.details.scope, "project", "scope is derived from the file location");
+    await call(captured, "notes_edit", { address: "@project/legacy.md", stale: true }, ctx);
+    assert.equal(/^scope:/m.test(readFileSync(legacy, "utf8")), false, "the next write removes legacy scope frontmatter");
+});
+test("stale project and global maps are skipped independently", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    await call(captured, "notes_write", { address: "@project/MAP.md", content: "project fresh" }, ctx);
+    await call(captured, "notes_write", { address: "@global/MAP.md", content: "global stale", stale: true }, ctx);
+    runHandlers(captured, "session_start", {}, ctx);
+    let boot = String(captured.sent.at(-1)?.message.content ?? "");
+    assert.ok(boot.includes("project fresh"), "a fresh project map survives a stale global map");
+    assert.equal(boot.includes("global stale"), false, "the stale global map is skipped");
+    const second = manager();
+    const secondCaptured = makeExtension(second);
+    const secondCtx = context(second);
+    await call(secondCaptured, "notes_edit", { address: "@project/MAP.md", stale: true }, secondCtx);
+    await call(secondCaptured, "notes_edit", { address: "@global/MAP.md", stale: false }, secondCtx);
+    runHandlers(secondCaptured, "session_start", {}, secondCtx);
+    boot = String(secondCaptured.sent.at(-1)?.message.content ?? "");
+    assert.equal(boot.includes("project fresh"), false, "the stale project map is skipped");
+    assert.ok(boot.includes("global stale"), "a fresh global map survives a stale project map");
+});

package/dist/test/pagination.property.test.js

@@ -21,7 +21,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { historyFromSession } from "../src/index.js";
-import { listNotes, searchNotes } from "../src/memory/store.js";
+import { listNotes, searchNotes } from "../src/notes/store.js";
 import { TOOL_OUTPUT_MAX_BYTES } from "../src/tool-output.js";
 import { MAX_NOTE_PATH_BYTES } from "../src/protocol.js";
 import { appendText, call, context, makeExtension, manager, resultJson } from "./integration.test.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "dream": "dist/src/dream/cli.js"
   },
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/src/dream/cli.js', 0o755)\"",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test dist/test/*.test.js",
     "prepublishOnly": "npm run typecheck",
@@ -42,9 +42,9 @@
     "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.85.1",
-    "@earendil-works/pi-ai": "^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-agent-core": "^0.86.0",
+    "@earendil-works/pi-ai": "^0.86.0",
+    "@earendil-works/pi-coding-agent": "^0.86.0",
     "@types/node": "^22.19.19",
     "typescript": "^5.9.3"
   },

package/playbook.md

@@ -1,5 +1,32 @@
-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 am dreaming over my notes. They are plain markdown files in three homes, addressed as:
 
-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.
+- bare `<vpath>` for this session
+- `@project/<vpath>` for this project
+- `@global/<vpath>` for global notes
 
-My final output is the manifest schema documented by the command: merge, promote, trash, pending, skillCandidates, and a required report string.
+Every note has this frontmatter block:
+
+```yaml
+---
+origin: user | self | external
+status: active
+stale: false
+created_at: <timestamp>
+updated_at: <timestamp>
+last_accessed: <timestamp>
+access_count: 0
+---
+```
+
+## Dream rules
+
+1. **Probe before you trust.** Before keeping or promoting a note, verify its world referents with read-only file tools: paths in the body — do they still exist? branches — still present? Dead referents are why a note gets merged away or marked stale, never promoted.
+2. **Merge threshold.** Supersede another note only when all three hold: same topic (name it in the survivor's body), same kind of note (checkpoint/design/log…), and the survivor is strictly newer or strictly more specific. Otherwise keep both and record the open conflict in the survivor.
+3. **Size budget.** Keep every note under ~200 lines / ~8KB. Oversized notes get split by topic with a one-line cross-link in each (`see also: @home/<vpath>`). Checkpoints may exceed the budget — trim prose, never facts.
+4. **Keep the maps.** Each home's `MAP.md` maps that home's durable notes: one line per entry — its address and a short gist in your own words, never a mechanical body slice. Project notes go on `@project/MAP.md`, cross-project knowledge on `@global/MAP.md`; session notes are never mapped — the pocket covers them. When a note is promoted across homes, move its line to the destination map; when a note goes stale, drop its line. Maps obey the same size budget as any note.
+5. **Jurisdiction.** Your mandate is the whole store — every session home, every project home, global. Nothing is skipped: notes are never physically deleted and every run is bracketed by git commits, so the human gate can audit and revert whatever you touch. Group your report by home so the gate can see what moved. In every home: map entry lines are yours to maintain, but prose that carries rules or guidance is not — flag it in your report instead of rewriting it.
+6. **Leave stable notes alone.** Change notes to incorporate new evidence, resolve verified errors, merge genuine duplicates, or split oversized files—not merely to shorten or rephrase them. Preserve facts, conditions, exceptions, and uncertainty. No change is a valid outcome.
+
+Read the files and merge genuinely duplicate notes by editing the survivor, then set `stale: true` in the absorbed note's frontmatter. Nothing is physically deleted; stale notes remain readable. Promote durable cross-project knowledge by writing or editing at `@global/<vpath>`. Keep notes compact and preserve useful provenance in the body.
+
+Do not write skill ideas as files. Put skill ideas and unresolved questions in your final assistant message as proposals for the human. Your final message should be a concise report of what you inspected, changed, and left unresolved. If you made no file writes, say so.

package/src/budget.ts

@@ -1,12 +1,16 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { GUIDANCE_TYPE, WARNING_TYPE } from "./protocol.js";
-import { thresholdsFor, resetThresholds, deriveThresholds, mergePiContextSettings } from "./thresholds.js";
+import { thresholdsFor, resetThresholds } from "./thresholds.js";
 import { currentWindowId, hasWindowMessage } from "./history.js";
 import { tokenBudgetGuidance } from "./prompts.js";
 import { output } from "./tool-output.js";
 
-export { deriveThresholds, mergePiContextSettings } from "./thresholds.js";
+/** Remaining tokens in the current context window, or null when Pi has no usage estimate. */
+export function remainingTokens(ctx: Pick<ExtensionContext, "getContextUsage">): number | null {
+	const usage = ctx.getContextUsage();
+	return !usage || usage.tokens === null ? null : Math.max(0, usage.contextWindow - usage.tokens);
+}
 
 export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean) {
 	let guidancePersistedInWindow: string | undefined;
@@ -17,16 +21,15 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean) {
 		if (!isEnabled() || hasWindowMessage(ctx, GUIDANCE_TYPE)) return undefined;
 		// The early reminder persists once per window the first time remaining crosses
 		// reserve+margin. It never edits the outgoing request.
-		const usage = ctx.getContextUsage();
-		if (!usage || usage.tokens === null) return undefined;
-		const remaining = Math.max(0, usage.contextWindow - usage.tokens);
+		const remaining = remainingTokens(ctx);
+		if (remaining === null) return undefined;
 		const windowId = currentWindowId(ctx);
 		const { reminder, reserve, warning } = thresholdsFor(ctx);
 		// The final warning owns the deep band: when it has fired (or is due now),
 		// the shallow reminder would only repeat the same instruction closer to
 		// the wipe, at a worse position. See warning.ts.
 		if (remaining <= warning || hasWindowMessage(ctx, WARNING_TYPE)) return undefined;
-		if (remaining <= reminder && guidancePersistedInWindow !== windowId && !hasWindowMessage(ctx, GUIDANCE_TYPE)) {
+		if (remaining <= reminder && guidancePersistedInWindow !== windowId) {
 			guidancePersistedInWindow = windowId;
 			// Persist once per window — no transient copy. A transient bridge would
 			// cover the crossing request, but history would record the reminder after
@@ -54,11 +57,10 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean) {
 		description: "Return estimated context tokens left before your memory is wiped; null when Pi cannot estimate usage.",
 		parameters: Type.Object({}, { additionalProperties: false }),
 		async execute(_id, _params, _signal, _update, ctx) {
-			const usage = ctx.getContextUsage();
 			// The countdown the model sees ends at the warning line (reserve + runway);
 			// the runway below it is overdraft the model never sees. See protocol.ts.
-			const remaining = usage?.tokens === null || usage === undefined ? null : Math.max(0, usage.contextWindow - usage.tokens - thresholdsFor(ctx as ExtensionContext).warning);
-			return output({ remaining_tokens: remaining });
+			const remaining = remainingTokens(ctx);
+			return output({ remaining_tokens: remaining === null ? null : Math.max(0, remaining - thresholdsFor(ctx as ExtensionContext).warning) });
 		},
 	}));
 

package/src/dream/cli.ts

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { acquireLock, failLock, releaseLock } from "./lock.js";
 import { materialGate, timeGate } from "./gates.js";
 import { loadPlaybook, runDreamer } from "./runner.js";
-import { applyManifest } from "./apply.js";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { gitCommit } from "./git.js";
+import { notesRoot } from "../notes/paths.js";
 
 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 {
@@ -15,19 +14,20 @@ function packageRoot(): string {
 }
 
 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 a = args(argv); if (a.help) { console.log("dream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <model pattern>] [--playbook <path>]\nDefault dreamer: in-process pi SDK session with jailed file tools. Default playbook: <installed package root>/playbook.md; --playbook overrides it."); return 0; }
+	const home = resolve(String(a["notes-home"] ?? notesRoot())); 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`);
+	gitCommit(home, `baseline ${stamp}`);
 	try {
 		const defaultBook = join(packageRoot(), "playbook.md");
 		const playbookPath = String(a.playbook ?? defaultBook);
-		const playbook = loadPlaybook(playbookPath); const manifest = await runDreamer(playbook, home, { command: a.dreamer ? String(a.dreamer) : undefined, modelPattern: a["dreamer-model"] ? String(a["dreamer-model"]) : undefined });
-		const ctx = { cwd: home, sessionManager: { getSessionId: () => "dream" } } 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;
+		const playbook = loadPlaybook(playbookPath); const result = await runDreamer(playbook, home, { modelPattern: a.dreamer ? String(a.dreamer) : undefined });
+		const writes = result.writes.length ? result.writes.map((w) => `- ${w.tool}: ${w.path}`).join("\n") : "- no changes";
+		mkdirSync(join(home, "dreams"), { recursive: true }); writeFileSync(reportPath, `# Dream ${stamp}\n\n${result.report}\n\n${writes}\n`); gitCommit(home, `dream ${stamp}`); 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

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

package/src/dream/git.ts

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

package/src/dream/runner.ts

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