@astrosheep/pi-context 0.21.0 → 0.22.1

package/dist/test/notes.test.js

@@ -62,7 +62,7 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     }
     assert.equal(typeof result.meta.created_at, "string", "wire meta renders timestamps as ISO strings");
     // A leading YAML block in user content is stripped from the body.
-    await call(captured, "notes_write", { path: "stripped.md", content: "---\nscope: global\nnonsense: true\n---\nreal body" }, ctx);
+    await call(captured, "notes_write", { path: "stripped.md", content: "---\nscope: personal\nnonsense: true\n---\nreal body" }, ctx);
     const stripped = readFileSync(physicalPath("session", "stripped.md", ctx), "utf8");
     assert.match(stripped, /\n---\n\nreal body$/, "the injected block is not part of the body");
     assert.equal(stripped.includes("nonsense"), false, "the injected block never reaches the file");
@@ -210,17 +210,17 @@ test.skip("scope resolution and movement are superseded by explicit address test
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
-    await call(captured, "notes_write", { path: "shared.md", content: "global body", scope: "global" }, ctx);
+    await call(captured, "notes_write", { path: "shared.md", content: "personal body", scope: "personal" }, ctx);
     await call(captured, "notes_write", { path: "shared.md", content: "session body", scope: "session" }, ctx);
     const first = resultRead(await call(captured, "notes_read", { path: "shared.md" }, ctx));
-    assert.equal(first.details.scope, "session", "session wins the precedence over global");
+    assert.equal(first.details.scope, "session", "session wins the precedence over personal");
     const readAgain = resultRead(await call(captured, "notes_read", { path: "shared.md", scope: "session" }, ctx));
     assert.ok(readAgain.content.includes("session body"));
     const sessionMeta = listNotes(ctx, { scope: "session" })[0].meta;
     assert.equal(sessionMeta.access_count, 2, "each read bumps access_count");
-    const globalMeta = listNotes(ctx, { scope: "global" })[0].meta;
-    assert.equal(globalMeta.access_count, 0, "the global copy is untouched");
-    // Move the session copy to project; the global copy is untouched.
+    const personalMeta = listNotes(ctx, { scope: "personal" })[0].meta;
+    assert.equal(personalMeta.access_count, 0, "the personal copy is untouched");
+    // Move the session copy to project; the personal copy is untouched.
     const moved = resultJson(await call(captured, "notes_edit", { path: "shared.md", edits: [{ oldText: "session", newText: "moved" }], scope: "project" }, ctx));
     assert.equal(moved.meta.scope, "project");
     assert.equal(moved.resolved_scope, "session", "resolved_scope names the layer the file moved from");
@@ -228,11 +228,11 @@ test.skip("scope resolution and movement are superseded by explicit address test
     assert.equal(existsSync(physicalPath("project", "shared.md", ctx)), true, "the file now lives in the project scope");
     // A move onto an existing target is refused and both files survive unchanged.
     await call(captured, "notes_write", { path: "clash.md", content: "session stay", scope: "session" }, ctx);
-    await call(captured, "notes_write", { path: "clash.md", content: "global stay", scope: "global" }, ctx);
-    const beforeGlobal = readFileSync(physicalPath("global", "clash.md", ctx), "utf8");
-    const refusal = resultJson(await call(captured, "notes_edit", { path: "clash.md", edits: [{ oldText: "stay", newText: "moved" }], scope: "global" }, ctx));
+    await call(captured, "notes_write", { path: "clash.md", content: "personal stay", scope: "personal" }, ctx);
+    const beforePersonal = readFileSync(physicalPath("personal", "clash.md", ctx), "utf8");
+    const refusal = resultJson(await call(captured, "notes_edit", { path: "clash.md", edits: [{ oldText: "stay", newText: "moved" }], scope: "personal" }, ctx));
     assert.match(refusal.error, /already exists/);
-    assert.equal(readFileSync(physicalPath("global", "clash.md", ctx), "utf8"), beforeGlobal, "the target survives a refused move");
+    assert.equal(readFileSync(physicalPath("personal", "clash.md", ctx), "utf8"), beforePersonal, "the target survives a refused move");
 });
 test("list and search merge scopes and carry scope; the path jail rejects escapes", async () => {
     freshRoot();
@@ -241,20 +241,20 @@ test("list and search merge scopes and carry scope; the path jail rejects escape
     const ctx = context(session);
     await call(captured, "notes_write", { path: "one.md", content: "needle one", scope: "session" }, ctx);
     await call(captured, "notes_write", { path: "two.md", content: "needle two", scope: "project" }, ctx);
-    await call(captured, "notes_write", { path: "three.md", content: "needle three", scope: "global" }, ctx);
+    await call(captured, "notes_write", { path: "three.md", content: "needle three", scope: "personal" }, ctx);
     const listed = resultJson(await call(captured, "notes_list", {}, ctx));
-    assert.deepEqual([...listed.files].map((file) => file.scope).sort(), ["global", "project", "session"], "every merged row carries its scope");
+    assert.deepEqual([...listed.files].map((file) => file.scope).sort(), ["personal", "project", "session"], "every merged row carries its scope");
     for (const row of listed.files) {
         assert.equal(typeof row.size_bytes, "number");
         assert.equal(row.origin, "self");
         assert.equal(row.status, "active");
         assert.equal(row.stale, false);
     }
-    const scoped = resultJson(await call(captured, "notes_list", { scope: "global" }, ctx));
+    const scoped = resultJson(await call(captured, "notes_list", { scope: "personal" }, ctx));
     assert.deepEqual(scoped.files.map((file) => file.path), ["three.md"], "a scope filter narrows the set");
     const searched = resultJson(await call(captured, "notes_search", { query: "needle" }, ctx));
     assert.equal(searched.files.length, 3, "literal search finds matches in every scope");
-    assert.deepEqual([...searched.files].map((file) => file.scope).sort(), ["global", "project", "session"]);
+    assert.deepEqual([...searched.files].map((file) => file.scope).sort(), ["personal", "project", "session"]);
     assert.equal(searched.files.every((file) => file.matches_total === 1), true);
     const hit = searched.files[0].matches[0];
     assert.equal(hit.line, 1);
@@ -276,12 +276,12 @@ test("the boot index reads the physical store across scopes and excludes stale n
     const captured = makeExtension(session);
     const ctx = context(session);
     await call(captured, "notes_write", { path: "fresh.md", content: "fresh content" }, ctx);
-    await call(captured, "notes_write", { path: "global.md", content: "global content", scope: "global" }, ctx);
+    await call(captured, "notes_write", { path: "personal.md", content: "personal content", scope: "personal" }, ctx);
     await call(captured, "notes_write", { path: "old.md", content: "stale content", stale: true }, ctx);
     runHandlers(captured, "session_start", {}, ctx);
     const text = typeof captured.sent[0]?.message.content === "string" ? captured.sent[0].message.content : "";
     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.ok(text.includes("personal.md"), "a fresh personal note is indexed");
     assert.equal(text.includes("old.md"), false, "a stale note leaves the index");
     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"]) {
@@ -356,31 +356,31 @@ 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("fresh global and project MAP.md bodies are both resident before the pocket", async () => {
+test("fresh personal 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", { 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", { address: "@personal/MAP.md", content: "MAP: personal\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"), "the global map is injected");
+    assert.ok(boot.includes("MAP: personal"), "the personal 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: personal") < boot.indexOf("MAP: project"), "the personal 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("the boot pocket applies per-home quotas in session, project, global order", async () => {
+test("the boot pocket applies per-home quotas in session, project, personal order", async () => {
     freshRoot();
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
     const base = Date.parse("2026-01-01T00:00:00.000Z");
-    for (const [scope, count] of [["session", 6], ["project", 3], ["global", 3]]) {
+    for (const [scope, count] of [["session", 6], ["project", 3], ["personal", 3]]) {
         for (let index = 0; index < count; index++) {
             const path = `${scope}-${index}.md`;
             await call(captured, "notes_write", { path, content: `${scope} body`, scope }, ctx);
@@ -389,21 +389,21 @@ test("the boot pocket applies per-home quotas in session, project, global order"
     }
     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);
+    await call(captured, "notes_write", { address: "@personal/MAP.md", content: "MAP: personal" }, 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("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("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 personal). 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", "@personal/personal-2.md", "@personal/personal-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"]) {
+    for (const name of ["session-0.md", "@project/project-0.md", "@personal/personal-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("@personal/personal-2.md") < boot.indexOf("@personal/personal-1.md"), "personal 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");
+    assert.ok(boot.indexOf("@project/project-1.md") < boot.indexOf("@personal/personal-2.md"), "project notes precede personal notes");
 });
 test("project scope keys off the git root basename and sha1 prefix", () => {
     const root = mkdtempSync(join(tmpdir(), "pi-context-proj-"));
@@ -421,54 +421,54 @@ test("@ addresses select one home, reject illegal sigils, and never fall back",
     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);
+    await call(captured, "notes_write", { address: "@personal/same.md", content: "personal" }, 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.ok(existsSync(physicalPath("personal", "same.md", ctx)), "@personal writes to the personal 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");
+    await assert.rejects(() => call(captured, "notes_read", { address: "@glboal/same.md" }, ctx), /@project\/.*@personal\/.*bare names are the session home/);
+    await assert.rejects(() => call(captured, "notes_write", { address: "bad@name.md", content: "no" }, ctx), /@project\/.*@personal\/.*bare names are the session home/);
+    assert.equal(existsSync(join(root, "personal", "bad@name.md")), false, "a bad sigil creates nothing anywhere");
 });
-test("full addresses drive outputs and patterns; legacy scope is read then dropped", async () => {
+test("full addresses drive outputs and patterns; on-disk 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);
+    await call(captured, "notes_write", { address: "@personal/personal.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(list.files.map((file) => file.address).sort(), ["@personal/personal.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 read = resultRead(await call(captured, "notes_read", { address: "@personal/personal.md" }, ctx));
+    assert.match(read.header, /^\[@personal\/personal\.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");
+    writeFileSync(legacy, "---\nscope: personal\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 () => {
+test("stale project and personal 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);
+    await call(captured, "notes_write", { address: "@personal/MAP.md", content: "personal 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");
+    assert.ok(boot.includes("project fresh"), "a fresh project map survives a stale personal map");
+    assert.equal(boot.includes("personal stale"), false, "the stale personal 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);
+    await call(secondCaptured, "notes_edit", { address: "@personal/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");
+    assert.ok(boot.includes("personal stale"), "a fresh personal map survives a stale project map");
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",

package/playbook.md

@@ -2,7 +2,7 @@ I am dreaming over my notes. They are plain markdown files in three homes, addre
 
 - bare `<vpath>` for this session
 - `@project/<vpath>` for this project
-- `@global/<vpath>` for global notes
+- `@personal/<vpath>` for personal notes
 
 Every note has this frontmatter block:
 
@@ -23,10 +23,10 @@ access_count: 0
 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.
+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 `@personal/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, personal. 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.
+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 `@personal/<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/dream/cli.ts

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { acquireLock, failLock, releaseLock } from "./lock.js";
+import { fileURLToPath } from "node:url";
+import { acquireLock, failLock, lastRunPath, releaseLock } from "./lock.js";
 import { materialGate, timeGate } from "./gates.js";
-import { loadPlaybook, runDreamer } from "./runner.js";
+import { loadPlaybook, runDreamer, type DreamerSessionFactory, type DreamResult, type DreamWrite } from "./runner.js";
 import { gitCommit } from "./git.js";
+import { readDreamerSettings, type DreamerSetting } from "../thresholds.js";
+import { doctor } from "./doctor.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; }
@@ -13,21 +16,105 @@ function packageRoot(): string {
 	while (true) { if (existsSync(join(dir, "package.json"))) return dir; const parent = dirname(dir); if (parent === dir) throw new Error("could not locate installed package root"); dir = parent; }
 }
 
-export async function main(argv = process.argv.slice(2)): Promise<number> {
-	const a = args(argv); if (a.help) { console.log("dream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <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; }
+/** Injection seams used by tests; production uses the defaults. */
+export type DreamDependencies = {
+	sessionFactory?: DreamerSessionFactory;
+	dreamerSettings?: (cwd?: string) => DreamerSetting;
+	runDreamer?: typeof runDreamer;
+};
+
+function writeList(writes: DreamWrite[]): string {
+	return writes.length ? writes.map((w) => `- ${w.tool}: ${w.path}`).join("\n") : "- no changes";
+}
+
+/** Best-effort text write; returns the failure message instead of throwing. */
+function writeText(path: string, content: string): string | undefined {
+	try { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, content); return undefined; }
+	catch (error) { return error instanceof Error ? error.message : String(error); }
+}
+
+function appendText(path: string, content: string): string | undefined {
+	try { appendFileSync(path, content); return undefined; }
+	catch (error) { return error instanceof Error ? error.message : String(error); }
+}
+
+/**
+ * Close one dream: record the report, then run the final audit commit. The audit always
+ * runs even when the report cannot be written, and a failed audit is appended to the
+ * report (when it exists) as well as named on stderr, so neither failure hides the other.
+ */
+function finishDream(home: string, stamp: string, reportPath: string, failed: boolean, body: string, writes: DreamWrite[]): number {
+	const header = failed ? `# Dream ${stamp} (failed)` : `# Dream ${stamp}`;
+	let reportError = writeText(reportPath, `${header}\n\n${body}\n\n${writeList(writes)}\n`);
+	const audit = gitCommit(home, `dream ${stamp}${failed ? " (failed)" : ""}`);
+	if (!audit.ok) {
+		console.error(`dream: final audit failed: ${audit.error}`);
+		reportError ??= appendText(reportPath, `\n## Final audit failed\n\n${audit.error}\n`);
+	}
+	if (reportError) console.error(`dream: could not write report at ${reportPath}: ${reportError}`);
+	return failed || !audit.ok || reportError !== undefined ? 1 : 0;
+}
+
+export async function main(argv = process.argv.slice(2), deps: DreamDependencies = {}): Promise<number> {
+	if (argv[0] === "doctor") {
+		const options = args(argv.slice(1));
+		if (options.help) { console.log("dream doctor [--notes-home <dir>] — read-only diagnostics; no model or repairs"); return 0; }
+		const home = resolve(String(options["notes-home"] ?? notesRoot()));
+		const issues = doctor(home);
+		console.log(issues.length ? issues.join("\n") : `dream doctor: OK (${home})`);
+		return issues.length ? 1 : 0;
+	}
+	const a = args(argv); if (a.help) { console.log("dream doctor [--notes-home <dir>] — read-only diagnostics\ndream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <model pattern>] [--playbook <path>]\nDreamer model: --dreamer wins, else pi-context.dreamer from settings, else the automatic model. 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;
+	const lockPath = join(home, ".dream.lock"); const stampPath = lastRunPath(lockPath);
+	const minHours = Number(a["min-hours"] ?? 24); const minSessions = Number(a["min-sessions"] ?? 3);
+	const time = timeGate(stampPath, minHours); console.log(time.reason); if (!a.force && !time.ok) return 0;
+	const since = existsSync(stampPath) ? statSync(stampPath).mtimeMs : 0;
+	const material = materialGate(home, since, 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}`);
+	let succeeded = false;
 	try {
+		// CLI --dreamer wins over settings; settings win over the automatic model fallback.
+		let modelPattern: string | undefined;
+		if (a.dreamer) modelPattern = String(a.dreamer);
+		else {
+			const settings = (deps.dreamerSettings ?? readDreamerSettings)();
+			for (const warning of settings.warnings) console.error(warning);
+			modelPattern = settings.pattern;
+		}
+
+		// The baseline snapshot is required: without it the human gate has nothing to inspect.
+		const baseline = gitCommit(home, `baseline ${stamp}`);
+		if (!baseline.ok) { console.error(`dream: baseline audit failed: ${baseline.error}`); return 1; }
+
 		const defaultBook = join(packageRoot(), "playbook.md");
 		const playbookPath = String(a.playbook ?? defaultBook);
-		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); }
+		let result: DreamResult;
+		try {
+			const playbook = loadPlaybook(playbookPath);
+			result = await (deps.runDreamer ?? runDreamer)(playbook, home, { modelPattern, sessionFactory: deps.sessionFactory });
+		} catch (e) {
+			const message = e instanceof Error ? e.message : String(e);
+			console.error(message);
+			return finishDream(home, stamp, reportPath, true, message, []);
+		}
+		if (result.error) {
+			console.error(result.error);
+			return finishDream(home, stamp, reportPath, true, result.error, result.writes);
+		}
+		const code = finishDream(home, stamp, reportPath, false, result.report, result.writes);
+		if (code === 0) { succeeded = true; console.log(reportPath); }
+		return code;
+	} finally {
+		// Only the holder's own lock is released; a successor's lock is never touched.
+		if (succeeded) releaseLock(lock); else failLock(lock);
+	}
+}
+
+function isEntryPoint(): boolean {
+	const entry = process.argv[1];
+	if (!entry) return false;
+	try { return realpathSync(resolve(entry)) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
 }
-main().then((code) => { process.exitCode = code; });
+if (isEntryPoint()) main().then((code) => { process.exitCode = code; });

package/src/dream/doctor.ts

@@ -0,0 +1,97 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { assertAddress } from "../notes/address.js";
+
+/** Read-only diagnostics. Never follows symlinks or acquires/removes a dream lock. */
+export function doctor(home: string): string[] {
+	const issues: string[] = [];
+	const report = (path: string, message: string) => issues.push(`${relative(home, path) || "."}: ${message}`);
+	const inspect = (path: string, action: () => void) => {
+		try { action(); } catch (error) { report(path, `cannot inspect: ${error instanceof Error ? error.message : String(error)}`); }
+	};
+	const directory = (path: string): boolean => {
+		const stat = lstatSync(path);
+		if (stat.isDirectory()) return true;
+		report(path, "expected a directory (symlinks are not followed); check its location/type");
+		return false;
+	};
+	const checkNote = (path: string, root: string, project?: string) => {
+		const raw = readFileSync(path, "utf8");
+		const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+		if (!match) { report(path, "missing or unclosed frontmatter; add a valid metadata block"); return; }
+		const fields = new Map<string, string>();
+		for (const line of match[1]!.split(/\r?\n/)) {
+			const field = /^([\w]+):\s*(.*?)\s*$/.exec(line);
+			if (!field) continue;
+			if (fields.has(field[1]!)) report(path, `duplicate metadata key ${field[1]}; keep one value`);
+			fields.set(field[1]!, field[2]!.replace(/^(["'])(.*)\1$/, "$2"));
+		}
+		for (const [key, valid] of Object.entries({ origin: /^(user|self|external)$/, status: /^(active|superseded|pending|archived)$/, stale: /^(true|false)$/, access_count: /^\d+$/ })) {
+			if (!valid.test(fields.get(key) ?? "")) report(path, `missing/invalid ${key}; repair frontmatter`);
+		}
+		for (const key of ["created_at", "updated_at", "last_accessed"]) {
+			const value = fields.get(key);
+			if (!value || !Number.isFinite(Date.parse(value))) report(path, `missing/invalid ${key}; use an ISO timestamp`);
+		}
+		if (fields.has("scope")) report(path, "obsolete scope field; remove it (home determines scope)");
+		// Check concrete, code-formatted addresses; examples/globs and prose are not links.
+		for (const link of raw.slice(match[0].length).matchAll(/`([^`\n]+)`/g)) {
+			const address = link[1]!;
+			if (!address.endsWith(".md") || /[<>*?\s]/.test(address)) continue;
+			if (!address.startsWith("@") && basename(path) !== "MAP.md") continue;
+			try {
+				const parsed = assertAddress(address);
+				const targetHome = parsed.scope === "personal" ? join(home, "personal") : parsed.scope === "project" ? project : root;
+				if (!targetHome) { report(path, `${address}: project context unavailable; use a resolvable reference`); continue; }
+				if (!existsSync(join(targetHome, parsed.path))) report(path, `${address}: target missing; update or remove the reference`);
+			} catch { report(path, `${address}: invalid address; use bare, @project/ or @personal/ addresses`); }
+		}
+	};
+	const walk = (dir: string, root: string, project?: string) => {
+		for (const name of readdirSync(dir)) {
+			const path = join(dir, name);
+			inspect(path, () => {
+				const stat = lstatSync(path);
+				if (stat.isSymbolicLink()) report(path, "symlink not inspected; replace with a regular note/directory");
+				else if (stat.isDirectory()) walk(path, root, project);
+				else if (stat.isFile() && name.endsWith(".md")) checkNote(path, root, project);
+				else report(path, "unexpected file in note home; inspect and relocate it");
+			});
+		}
+	};
+	inspect(home, () => {
+		if (!directory(home)) return;
+		for (const name of readdirSync(home)) {
+			const path = join(home, name);
+			inspect(path, () => {
+				if (name === "global") { report(path, "legacy home; manually migrate to personal/ without overwriting existing files"); return; }
+				if (name === ".dream.lock") {
+					const valid = lstatSync(path).isFile() && /^[1-9]\d* [\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}\s*$/i.test(readFileSync(path, "utf8"));
+					report(path, `${valid ? "lock present" : "malformed lock"}; verify no dream is running before manual removal; liveness not inferred`);
+					return;
+				}
+				if ([".git", "dreams", "snapshots", "trash", ".dream.lock.last-run"].includes(name)) return;
+				if (name === "personal") { if (directory(path)) walk(path, path); return; }
+				if (name === "project" || name === "pi") {
+					if (!directory(path)) return;
+					const homes = name === "pi" ? join(path, "session") : path;
+					if (name === "pi") {
+						for (const entry of readdirSync(path)) if (entry !== "session") report(join(path, entry), "unexpected directory; expected pi/session/<id>/");
+						if (!existsSync(homes) || !directory(homes)) return;
+					}
+					for (const id of readdirSync(homes)) {
+						const root = join(homes, id);
+						inspect(root, () => {
+							if (!directory(root)) return;
+							if (name === "project" && !/^.+-[\da-f]{8}$/.test(id)) report(root, "invalid project key; expected <name>-<8 hex>");
+							walk(root, root, name === "project" ? root : undefined);
+						});
+					}
+					return;
+				}
+				report(path, "unexpected root entry; expected personal/, project/, pi/session/ or dream artifacts");
+			});
+		}
+	});
+	return issues;
+}

package/src/dream/gates.ts

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