@astrosheep/pi-context 0.21.0 → 0.22.1

package/dist/test/dream.test.js

@@ -1,48 +1,167 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { existsSync, linkSync, mkdirSync, readFileSync, statSync, symlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { execFile, execFileSync } from "node:child_process";
+import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { acquireLock, failLock } from "../src/dream/lock.js";
+import { acquireLock, failLock, lastRunPath, releaseLock } from "../src/dream/lock.js";
 import { materialGate, timeGate } from "../src/dream/gates.js";
 import { defaultDreamerSessionFactory, dreamerWriteToolDefinitions, runDreamer, DREAMER_TOOLS } from "../src/dream/runner.js";
 import { gitCommit } from "../src/dream/git.js";
-import { execFileSync } from "node:child_process";
+import { main } from "../src/dream/cli.js";
+import { deriveDreamer, mergePiContextSettings, readDreamerSettings } from "../src/thresholds.js";
+import { PI_CONTEXT_DREAMER_KEY, PI_CONTEXT_SETTINGS_KEY } from "../src/protocol.js";
 import { contentText } from "../src/history.js";
 function fixture() { return mkdtempSync(join(tmpdir(), "dream-")); }
 function old(path) { const d = new Date(Date.now() - 48 * 3600_000); utimesSync(path, d, d); }
+/** A session whose prompt runs a scripted interaction with the recorded event handler. */
+function scriptedSession(run) {
+    return async ({ cwd }) => {
+        let handler = () => { };
+        const session = {
+            subscribe(next) { handler = next; return () => { }; },
+            async prompt() { run(handler, cwd); },
+            dispose() { },
+        };
+        return session;
+    };
+}
+function successSession() {
+    return scriptedSession((handler) => handler({ type: "message_end", message: { role: "assistant", content: [{ type: "text", text: "done" }] } }));
+}
+/** Capture console.error lines without letting CLI chatter pollute the test output. */
+async function captureErrors(run) {
+    const errors = [];
+    const original = console.error;
+    console.error = (...parts) => { errors.push(parts.map(String).join(" ")); };
+    try {
+        return { code: await run(), errors };
+    }
+    finally {
+        console.error = original;
+    }
+}
 test("time and material gates preserve skip decisions and reasons", () => {
     const home = fixture();
     const lock = join(home, ".dream.lock");
-    writeFileSync(lock, "999999");
-    const fresh = timeGate(lock, 24);
+    const stamp = lastRunPath(lock);
+    assert.deepEqual(timeGate(stamp, 24).ok, true, "no prior dream passes");
+    writeFileSync(stamp, new Date().toISOString());
+    const fresh = timeGate(stamp, 24);
     assert.equal(fresh.ok, false);
-    assert.equal(fresh.reason, "time gate: lock is too fresh");
-    old(lock);
-    assert.deepEqual(timeGate(lock, 24).ok, true);
+    assert.equal(fresh.reason, "time gate: last dream is too recent");
+    old(stamp);
+    assert.equal(timeGate(stamp, 24).ok, true);
     mkdirSync(join(home, "pi/session/one"), { recursive: true });
     writeFileSync(join(home, "pi/session/one/a.md"), "a");
-    const material = materialGate(home, statSync(lock).mtimeMs, 1);
+    const material = materialGate(home, statSync(stamp).mtimeMs, 1);
     assert.equal(material.ok, true);
     assert.match(material.reason, /material gate: 1 changed sessions/);
     assert.equal(materialGate(home, Date.now(), 2).ok, false);
+    // The lock file's own mtime no longer carries the scheduler timestamp.
+    writeFileSync(lock, "1");
+    old(lock);
+    assert.equal(timeGate(stamp, 24).ok, true, "the sidecar survives an old lock file");
 });
-test("live lock is excluded, dead lock is reclaimed, and failures restore mtime", () => {
+test("failure restores the last-run timestamp and cleanup is idempotent", () => {
     const home = fixture();
     const lock = join(home, ".dream.lock");
-    writeFileSync(lock, String(process.pid));
-    const live = acquireLock(lock);
-    assert.equal(live.held, false);
-    assert.equal(live.reason, "lock gate: live process holds the lock");
-    writeFileSync(lock, "999999");
-    old(lock);
-    const prior = statSync(lock).mtimeMs;
-    const reclaimed = acquireLock(lock);
-    assert.equal(reclaimed.held, true);
-    utimesSync(lock, new Date(), new Date());
-    failLock(reclaimed);
-    assert.ok(Math.abs(statSync(lock).mtimeMs - prior) < 2000);
+    const stamp = lastRunPath(lock);
+    writeFileSync(stamp, new Date(Date.now() - 48 * 3600_000).toISOString());
+    old(stamp);
+    const prior = statSync(stamp).mtimeMs;
+    const held = acquireLock(lock);
+    assert.equal(held.held, true);
+    assert.equal(readFileSync(lock, "utf8").trim(), `${process.pid} ${held.token}`, "the lock records its owner and token");
+    assert.ok(statSync(stamp).mtimeMs > prior + 1000, "a held lock advances the last-run sidecar, not itself");
+    failLock(held);
+    assert.equal(held.held, false, "failure marks the state released");
+    assert.ok(Math.abs(statSync(stamp).mtimeMs - prior) < 2000, "a failed run restores the last-run timestamp");
+    assert.equal(existsSync(lock), false, "a failed run releases its lock");
+    // Repeated cleanup on an already-released state is harmless.
+    const settled = statSync(stamp).mtimeMs;
+    failLock(held);
+    releaseLock(held);
+    assert.ok(Math.abs(statSync(stamp).mtimeMs - settled) < 1000, "repeated failure cleanup changes nothing");
+    const released = acquireLock(lock);
+    assert.equal(released.held, true);
+    releaseLock(released);
+    releaseLock(released);
+    assert.equal(released.held, false, "release marks the state released");
+    assert.equal(existsSync(lock), false, "release removes the PID marker");
+    assert.equal(existsSync(stamp), true, "the timestamp sidecar survives release");
+});
+test("any existing lock refuses acquisition and is left byte-identical", () => {
+    const home = fixture();
+    const lock = join(home, ".dream.lock");
+    const stamp = lastRunPath(lock);
+    const markers = [
+        `${process.pid} live-owner`, // a live owner's marker
+        "999999", // a dead PID
+        "999999 dead-token", // a dead PID with a token
+        "", // empty
+        "not-a-pid", // malformed
+    ];
+    for (const marker of markers) {
+        writeFileSync(lock, marker);
+        old(lock);
+        const result = acquireLock(lock);
+        assert.equal(result.held, false, `refuses an existing marker ${JSON.stringify(marker)}`);
+        assert.equal(result.reason, "lock gate: lock already exists");
+        assert.equal(readFileSync(lock, "utf8"), marker, "the existing marker is byte-identical");
+    }
+    assert.equal(existsSync(stamp), false, "a refused acquisition writes no timestamp");
+});
+test("an acquired lock blocks every later contender until released", () => {
+    const home = fixture();
+    const lock = join(home, ".dream.lock");
+    const first = acquireLock(lock);
+    assert.equal(first.held, true);
+    const second = acquireLock(lock);
+    assert.equal(second.held, false);
+    assert.equal(second.reason, "lock gate: lock already exists");
+    assert.equal(readFileSync(lock, "utf8").trim(), `${process.pid} ${first.token}`, "the holder's marker is untouched");
+});
+test("cleanup never removes a successor's lock, even repeated", () => {
+    const home = fixture();
+    const lock = join(home, ".dream.lock");
+    const stamp = lastRunPath(lock);
+    const mine = acquireLock(lock);
+    assert.equal(mine.held, true);
+    // A successor acquires after ours is externally gone (human/supported protocol).
+    unlinkSync(lock);
+    const successor = acquireLock(lock);
+    assert.equal(successor.held, true);
+    const successorStamp = Date.now() - 5000;
+    utimesSync(stamp, new Date(), new Date(successorStamp));
+    failLock(mine);
+    releaseLock(mine);
+    assert.equal(mine.held, false, "the old state is marked released by the first cleanup");
+    assert.equal(readFileSync(lock, "utf8").trim(), `${process.pid} ${successor.token}`, "the successor's lock survives");
+    assert.ok(Math.abs(statSync(stamp).mtimeMs - successorStamp) < 1000, "the successor's timestamp survives");
+});
+/** Each child makes one actual acquisition attempt; a holder stays alive so later attempts see it. */
+async function acquireRaceOutcomes(lock, contenders) {
+    const moduleUrl = new URL("../src/dream/lock.js", import.meta.url).href;
+    const script = [
+        `import { acquireLock, releaseLock } from ${JSON.stringify(moduleUrl)};`,
+        `const result = acquireLock(${JSON.stringify(lock)});`,
+        `if (result.held) await new Promise((resolve) => setTimeout(resolve, 1200));`,
+        `process.stdout.write(result.held ? "held" : "lost");`,
+        `if (result.held) releaseLock(result);`,
+    ].join("\n");
+    const contender = () => new Promise((resolve, reject) => {
+        execFile(process.execPath, ["--input-type=module", "-e", script], (error, stdout) => error ? reject(error) : resolve(stdout.trim()));
+    });
+    return Promise.all(Array.from({ length: contenders }, contender));
+}
+test("concurrent acquisitions of an absent lock yield exactly one held:true", async () => {
+    const home = fixture();
+    const lock = join(home, ".dream.lock");
+    assert.equal(existsSync(lock), false, "the lock starts absent");
+    const outcomes = await acquireRaceOutcomes(lock, 8);
+    assert.equal(outcomes.filter((outcome) => outcome === "held").length, 1, "exactly one actual held:true return");
 });
 test("dreamer write jail accepts home files and refuses escapes", async () => {
     const home = fixture();
@@ -76,6 +195,9 @@ test("dreamer write jail accepts home files and refuses escapes", async () => {
     symlinkSync(insideFile, join(home, "global/inside-link.md"));
     await tools.get("write").execute("write", { path: "global/inside-link.md", content: "updated" }, undefined, undefined, ctx);
     assert.equal(readFileSync(insideFile, "utf8"), "updated", "the jail permits a symlinked file that resolves inside home");
+    // The jail has no `.git` special case: an in-home `.git` path is written like any other.
+    await tools.get("write").execute("write", { path: ".git/config", content: "not protected" }, undefined, undefined, ctx);
+    assert.equal(readFileSync(join(home, ".git/config"), "utf8"), "not protected", "the dream write jail does not protect .git");
 });
 test("dreamer allowlist contains only the file tools and reports their writes", async () => {
     let configured = [];
@@ -92,6 +214,7 @@ test("dreamer allowlist contains only the file tools and reports their writes",
     assert.deepEqual(result.writes, [{ tool: "write", path: "global/a.md" }, { tool: "edit", path: "project/p.md" }]);
     assert.equal(result.report, "done\nagain");
     assert.equal(result.report, contentText([{ type: "text", text: "done" }, { type: "text", text: "again" }]), "dream and history share the text projection");
+    assert.equal(result.error, undefined);
 });
 test("dreamer session has exactly the jailed file-tool allowlist", async () => {
     const session = await defaultDreamerSessionFactory({ cwd: fixture(), tools: DREAMER_TOOLS });
@@ -110,14 +233,14 @@ test("playbook describes plain files and the retained frontmatter", () => {
     assert.equal(/^scope:/m.test(playbook), false, "scope is derived from the address rather than persisted");
     assert.match(playbook, /Nothing is physically deleted/);
 });
-test("provider errors propagate without parsing a response", async () => {
-    const session = {
-        subscribe(handler) { this.handler = handler; return () => { }; },
-        handler: (_event) => { },
-        async prompt(_text) { this.handler({ type: "message_end", message: { role: "assistant", stopReason: "error", errorMessage: "Insufficient Balance" } }); },
-        dispose() { },
-    };
-    await assert.rejects(() => runDreamer("playbook", "/tmp/notes", { sessionFactory: async () => session }), /Insufficient Balance/);
+test("provider errors are reported with partial writes instead of parsing a response", async () => {
+    const factory = scriptedSession((handler) => {
+        handler({ type: "tool_execution_start", toolName: "write", args: { path: "global/partial.md", content: "half" } });
+        handler({ type: "message_end", message: { role: "assistant", stopReason: "error", errorMessage: "Insufficient Balance" } });
+    });
+    const result = await runDreamer("playbook", "/tmp/notes", { sessionFactory: factory });
+    assert.match(result.error ?? "", /Insufficient Balance/);
+    assert.deepEqual(result.writes, [{ tool: "write", path: "global/partial.md" }]);
 });
 test("default dreamer rejects an unresolvable model pattern", async () => {
     await assert.rejects(() => defaultDreamerSessionFactory({ cwd: "/tmp/notes", modelPattern: "definitely-not-a-real-model", tools: DREAMER_TOOLS }), /definitely-not-a-real-model/);
@@ -125,18 +248,180 @@ test("default dreamer rejects an unresolvable model pattern", async () => {
 test("git audit layer commits baseline and dream, stays silent when clean, keeps file content", () => {
     const home = fixture();
     writeFileSync(join(home, "a.md"), "one");
-    gitCommit(home, "baseline t");
-    gitCommit(home, "dream t"); // clean tree — no empty commit
+    const baseline = gitCommit(home, "baseline t");
+    assert.equal(baseline.ok, true);
+    const clean = gitCommit(home, "dream t"); // clean tree — no empty commit
+    assert.equal(clean.ok, true);
+    assert.equal(clean.empty, true);
     const log1 = execFileSync("git", ["log", "--format=%s"], { cwd: home, encoding: "utf8" }).trim();
     assert.equal(log1, "baseline t");
     writeFileSync(join(home, "a.md"), "two");
-    gitCommit(home, "dream t2");
+    const second = gitCommit(home, "dream t2");
+    assert.equal(second.ok, true);
+    assert.equal(second.empty, false);
     const log2 = execFileSync("git", ["log", "--format=%s"], { cwd: home, encoding: "utf8" }).trim();
     assert.equal(log2, "dream t2\nbaseline t");
     assert.equal(readFileSync(join(home, "a.md"), "utf8"), "two"); // notes themselves untouched by the layer
     const before = execFileSync("git", ["show", "HEAD~1:a.md"], { cwd: home, encoding: "utf8" }).trim();
     assert.equal(before, "one"); // rollback information actually recorded
 });
-test("git audit layer never breaks the run when git itself fails", () => {
-    gitCommit(join(fixture(), "missing", "home"), "x"); // init on a missing cwd throws inside — swallowed
+test("git audit layer gives a newly initialized empty repository a real baseline snapshot", () => {
+    const home = fixture();
+    const baseline = gitCommit(home, "baseline empty");
+    assert.equal(baseline.ok, true);
+    if (baseline.ok) {
+        assert.notEqual(baseline.commit, "", "the baseline carries a real commit, not an empty marker");
+        assert.equal(baseline.empty, true, "no files changed");
+    }
+    assert.equal(execFileSync("git", ["log", "--format=%s"], { cwd: home, encoding: "utf8" }).trim(), "baseline empty");
+});
+test("git audit layer reports its failure instead of swallowing it", () => {
+    const missing = gitCommit(join(fixture(), "missing", "home"), "x");
+    assert.equal(missing.ok, false);
+    const broken = fixture();
+    writeFileSync(join(broken, ".git"), "not a git directory");
+    const result = gitCommit(broken, "x");
+    assert.equal(result.ok, false);
+    if (!result.ok)
+        assert.ok(result.error.length > 0, "the audit failure names its cause");
+});
+test("CLI: a failed final audit is recorded in the report and in the exit status", async () => {
+    const home = fixture();
+    const sessionFactory = scriptedSession((_handler, cwd) => {
+        mkdirSync(join(cwd, "global"), { recursive: true });
+        writeFileSync(join(cwd, "global/ok.md"), "ok");
+        // Break the repository after the baseline so only the final audit fails.
+        rmSync(join(cwd, ".git"), { recursive: true, force: true });
+        writeFileSync(join(cwd, ".git"), "broken");
+    });
+    const { code, errors } = await captureErrors(() => main(["--notes-home", home, "--force"], { sessionFactory, dreamerSettings: () => ({ warnings: [] }) }));
+    assert.notEqual(code, 0, "a dream with no final snapshot is not a success");
+    assert.ok(errors.some((line) => /final audit failed/.test(line)), "the audit failure is named");
+    const reports = readdirSync(join(home, "dreams"));
+    assert.equal(reports.length, 1);
+    assert.match(readFileSync(join(home, "dreams", reports[0]), "utf8"), /Final audit failed/, "the success report records the audit failure");
+});
+test("CLI: a report-write failure does not prevent the final failure audit", async () => {
+    const home = fixture();
+    writeFileSync(join(home, "dreams"), "not a directory");
+    const sessionFactory = scriptedSession((handler, cwd) => {
+        mkdirSync(join(cwd, "global"), { recursive: true });
+        writeFileSync(join(cwd, "global/partial.md"), "half");
+        handler({ type: "tool_execution_start", toolName: "write", args: { path: "global/partial.md", content: "half" } });
+        handler({ type: "message_end", message: { role: "assistant", stopReason: "error", errorMessage: "Insufficient Balance" } });
+    });
+    const { code, errors } = await captureErrors(() => main(["--notes-home", home, "--force"], { sessionFactory, dreamerSettings: () => ({ warnings: [] }) }));
+    assert.notEqual(code, 0);
+    assert.ok(errors.some((line) => /could not write report/.test(line)), "the report failure is surfaced");
+    assert.match(execFileSync("git", ["log", "--format=%s"], { cwd: home, encoding: "utf8" }).trim(), /\(failed\)/, "the final failure audit still ran");
+    assert.equal(execFileSync("git", ["show", "HEAD:global/partial.md"], { cwd: home, encoding: "utf8" }), "half", "the partial write is still committed");
+});
+test("CLI: an unwritable report is a failure even when the dreamer succeeds", async () => {
+    const home = fixture();
+    writeFileSync(join(home, "dreams"), "not a directory");
+    const { code, errors } = await captureErrors(() => main(["--notes-home", home, "--force"], { sessionFactory: successSession(), dreamerSettings: () => ({ warnings: [] }) }));
+    assert.notEqual(code, 0, "a missing report is not a success");
+    assert.ok(errors.some((line) => /could not write report/.test(line)), "the report failure is surfaced");
+    assert.notEqual(execFileSync("git", ["log", "--format=%s"], { cwd: home, encoding: "utf8" }).trim(), "", "the final audit still ran");
+});
+test("CLI: a failed baseline audit aborts before the dreamer and preserves the notes bytes", async () => {
+    const home = fixture();
+    writeFileSync(join(home, "keep.md"), "keep me");
+    writeFileSync(join(home, ".git"), "not a git directory"); // every git command fails
+    let started = false;
+    const { code } = await captureErrors(() => main(["--notes-home", home, "--force"], {
+        sessionFactory: async () => { started = true; return {}; },
+        dreamerSettings: () => ({ warnings: [] }),
+    }));
+    assert.notEqual(code, 0, "a missing baseline is a failed run");
+    assert.equal(started, false, "the dreamer never starts without a baseline");
+    assert.equal(readFileSync(join(home, "keep.md"), "utf8"), "keep me", "the notes bytes survive");
+    assert.equal(existsSync(join(home, "dreams")), false, "no dream report is written");
+});
+test("CLI: a dreamer failure records the failure and the partial write in a final commit", async () => {
+    const home = fixture();
+    const sessionFactory = scriptedSession((handler, cwd) => {
+        mkdirSync(join(cwd, "global"), { recursive: true });
+        writeFileSync(join(cwd, "global/partial.md"), "half");
+        handler({ type: "tool_execution_start", toolName: "write", args: { path: "global/partial.md", content: "half" } });
+        handler({ type: "message_end", message: { role: "assistant", stopReason: "error", errorMessage: "Insufficient Balance" } });
+    });
+    const { code } = await captureErrors(() => main(["--notes-home", home, "--force"], { sessionFactory, dreamerSettings: () => ({ warnings: [] }) }));
+    assert.notEqual(code, 0);
+    const reports = readdirSync(join(home, "dreams"));
+    assert.equal(reports.length, 1, "one failure report");
+    const report = readFileSync(join(home, "dreams", reports[0]), "utf8");
+    assert.match(report, /Insufficient Balance/, "the report contains the failure");
+    assert.match(report, /global\/partial\.md/, "the report names the partial write");
+    const log = execFileSync("git", ["log", "--format=%s"], { cwd: home, encoding: "utf8" }).trim();
+    assert.match(log, /\(failed\)/, "the partial state is committed as a failure");
+    assert.equal(execFileSync("git", ["show", "HEAD:global/partial.md"], { cwd: home, encoding: "utf8" }), "half");
+});
+test("CLI: a successful run commits its report and leaves the audited tree clean", async () => {
+    const home = fixture();
+    writeFileSync(join(home, "seed.md"), "seed");
+    const { code } = await captureErrors(() => main(["--notes-home", home, "--force"], { sessionFactory: successSession(), dreamerSettings: () => ({ warnings: [] }) }));
+    assert.equal(code, 0);
+    assert.equal(execFileSync("git", ["status", "--porcelain"], { cwd: home, encoding: "utf8" }).trim(), "", "the audited tree is clean after the lock is released");
+    const tracked = execFileSync("git", ["ls-files"], { cwd: home, encoding: "utf8" }).trim().split("\n");
+    assert.equal(tracked.some((file) => file.startsWith(".dream.lock")), false, "lock artifacts stay out of the snapshot");
+    assert.equal(tracked.includes("seed.md"), true);
+});
+test("CLI: --force does not bypass an existing lock", async () => {
+    const home = fixture();
+    writeFileSync(join(home, ".dream.lock"), "999999 dead-owner");
+    let started = false;
+    const { code } = await captureErrors(() => main(["--notes-home", home, "--force"], {
+        sessionFactory: async () => { started = true; return {}; },
+        dreamerSettings: () => ({ warnings: [] }),
+    }));
+    assert.equal(code, 0, "an existing lock skips the run rather than failing");
+    assert.equal(started, false, "--force never reaches the dreamer while the lock exists");
+    assert.equal(readFileSync(join(home, ".dream.lock"), "utf8"), "999999 dead-owner", "the existing lock is byte-identical");
+    assert.equal(existsSync(join(home, "dreams")), false, "no dream report is written");
+});
+test("dreamer setting is a non-empty string; project overrides global; invalid values warn and fall back", () => {
+    assert.deepEqual(deriveDreamer({}), { warnings: [] }, "absent setting falls back silently");
+    assert.deepEqual(deriveDreamer({ dreamer: "openai/gpt-x" }), { pattern: "openai/gpt-x", warnings: [] });
+    const merged = mergePiContextSettings({ [PI_CONTEXT_SETTINGS_KEY]: { [PI_CONTEXT_DREAMER_KEY]: "global/model" } }, { [PI_CONTEXT_SETTINGS_KEY]: { [PI_CONTEXT_DREAMER_KEY]: "project/model" } });
+    assert.equal(deriveDreamer(merged).pattern, "project/model", "project wins per key");
+    for (const invalid of ["", "   ", 42, null]) {
+        const result = deriveDreamer({ dreamer: invalid });
+        assert.equal(result.pattern, undefined, `invalid ${JSON.stringify(invalid)} is ignored`);
+        assert.equal(result.warnings.length, 1, "one warning per invalid value");
+        assert.match(result.warnings[0], /dreamer/);
+    }
+});
+test("readDreamerSettings reads the project setting over the global one through SettingsManager", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "dream-cwd-"));
+    const agentDir = mkdtempSync(join(tmpdir(), "dream-agent-"));
+    const prior = process.env.PI_CODING_AGENT_DIR;
+    process.env.PI_CODING_AGENT_DIR = agentDir;
+    try {
+        writeFileSync(join(agentDir, "settings.json"), JSON.stringify({ [PI_CONTEXT_SETTINGS_KEY]: { [PI_CONTEXT_DREAMER_KEY]: "global/model" } }));
+        mkdirSync(join(cwd, ".pi"), { recursive: true });
+        writeFileSync(join(cwd, ".pi", "settings.json"), JSON.stringify({ [PI_CONTEXT_SETTINGS_KEY]: { [PI_CONTEXT_DREAMER_KEY]: "project/model" } }));
+        assert.equal(readDreamerSettings(cwd).pattern, "project/model");
+        writeFileSync(join(cwd, ".pi", "settings.json"), JSON.stringify({}));
+        assert.equal(readDreamerSettings(cwd).pattern, "global/model", "global applies when the project does not set the key");
+    }
+    finally {
+        if (prior === undefined)
+            delete process.env.PI_CODING_AGENT_DIR;
+        else
+            process.env.PI_CODING_AGENT_DIR = prior;
+    }
+});
+test("CLI: --dreamer wins over settings, settings win over the automatic fallback", async () => {
+    const home = fixture();
+    const seen = [];
+    const success = successSession();
+    const run = (argv, settings) => main(["--notes-home", home, "--force", ...argv], {
+        sessionFactory: async (options) => { seen.push(options.modelPattern); return success({ cwd: home, tools: DREAMER_TOOLS }); },
+        dreamerSettings: () => settings,
+    });
+    await captureErrors(() => run([], { pattern: "settings/model", warnings: [] }));
+    await captureErrors(() => run(["--dreamer", "cli/model"], { pattern: "settings/model", warnings: [] }));
+    await captureErrors(() => run([], { warnings: [] }));
+    assert.deepEqual(seen, ["settings/model", "cli/model", undefined]);
 });

package/dist/test/integration.test.js

@@ -117,12 +117,12 @@ export async function call(captured, name, params, ctx) {
     if (noteCall && "path" in params && !("address" in params)) {
         const { path, scope, ...rest } = params;
         assert.equal(typeof path, "string", "legacy note fixture path is a string");
-        const address = scope === "project" ? `@project/${path}` : scope === "global" ? `@global/${path}` : path;
+        const address = scope === "project" ? `@project/${path}` : scope === "personal" ? `@personal/${path}` : path;
         return tool.execute("call-1", { ...rest, address }, new AbortController().signal, () => { }, ctx);
     }
-    if ((name === "notes_list" || name === "notes_search") && params.scope === "global") {
+    if ((name === "notes_list" || name === "notes_search") && params.scope === "personal") {
         const { scope: _scope, pattern, ...rest } = params;
-        return tool.execute("call-1", { ...rest, pattern: `@global/${typeof pattern === "string" ? pattern : "**"}` }, new AbortController().signal, () => { }, ctx);
+        return tool.execute("call-1", { ...rest, pattern: `@personal/${typeof pattern === "string" ? pattern : "**"}` }, new AbortController().signal, () => { }, ctx);
     }
     if ((name === "notes_list" || name === "notes_search") && params.scope === "session") {
         const { scope: _scope, pattern, ...rest } = params;
@@ -134,7 +134,7 @@ export function resultJson(result) {
     const text = result.content[0];
     assert.ok(text && text.type === "text", "tool result carries text");
     const value = JSON.parse(text.text);
-    const suffix = (address) => address.startsWith("@project/") ? address.slice("@project/".length) : address.startsWith("@global/") ? address.slice("@global/".length) : address;
+    const suffix = (address) => address.startsWith("@project/") ? address.slice("@project/".length) : address.startsWith("@personal/") ? address.slice("@personal/".length) : address;
     const legacyPath = (row) => {
         if (typeof row.address === "string" && row.path === undefined)
             Object.defineProperty(row, "path", { value: suffix(row.address), enumerable: false });
@@ -323,36 +323,36 @@ test("notes_list is most-recently-updated first across merged scopes", async ()
     put("session", "b.md", base + 10);
     put("session", "a.md", base + 10);
     put("project", "c.md", base + 5);
-    put("global", "e.md", base + 20);
+    put("personal", "e.md", base + 20);
     const files = async (params) => resultJson(await call(captured, "notes_list", params, ctx)).files;
-    assert.deepEqual((await files({})).map((file) => file.address), ["@global/e.md", "a.md", "b.md", "@project/c.md"], "updated_at descending with address ascending as the tiebreak");
+    assert.deepEqual((await files({})).map((file) => file.address), ["@personal/e.md", "a.md", "b.md", "@project/c.md"], "updated_at descending with address ascending as the tiebreak");
     // A same-path pair in two scopes keeps both rows; equal timestamps tie-break by scope name.
-    put("global", "a.md", base + 10);
-    assert.deepEqual((await files({})).filter((file) => file.address.endsWith("a.md")).map((file) => file.scope), ["global", "session"], "equal timestamps tie-break by full address");
+    put("personal", "a.md", base + 10);
+    assert.deepEqual((await files({})).filter((file) => file.address.endsWith("a.md")).map((file) => file.scope), ["personal", "session"], "equal timestamps tie-break by full address");
     assert.deepEqual((await files({ pattern: "*.md" })).map((file) => file.address), ["a.md", "b.md"], "a bare pattern narrows to the session home");
 });
 test("notes are real files that persist across sessions and round-trip Unicode", async () => {
     const original = manager();
     const captured = makeExtension(original);
     const ctx = context(original);
-    await call(captured, "notes_write", { path: "checkpoint/进度.md", content: "第一行\nneedle Café", scope: "global" }, ctx);
-    // A brand-new session over the same physical root sees the global note: nothing is replayed
+    await call(captured, "notes_write", { path: "checkpoint/进度.md", content: "第一行\nneedle Café", scope: "personal" }, ctx);
+    // A brand-new session over the same physical root sees the personal note: nothing is replayed
     // from session entries, the file itself is the durable artifact.
     const restored = manager();
     const restoredCaptured = makeExtension(restored);
     const restoredCtx = context(restored);
-    const rawRead = await call(restoredCaptured, "notes_read", { path: "checkpoint/进度.md", scope: "global", offset_chars: -4 }, restoredCtx);
+    const rawRead = await call(restoredCaptured, "notes_read", { path: "checkpoint/进度.md", scope: "personal", offset_chars: -4 }, restoredCtx);
     const read = resultRead(rawRead);
-    assert.equal(read.details.address, "@global/checkpoint/进度.md");
+    assert.equal(read.details.address, "@personal/checkpoint/进度.md");
     assert.equal(read.content, "Café", "a negative offset reads the body tail in one call");
-    assert.equal(read.details.scope, "global");
-    const searched = resultJson(await call(restoredCaptured, "notes_search", { query: "Café", scope: "global" }, restoredCtx));
+    assert.equal(read.details.scope, "personal");
+    const searched = resultJson(await call(restoredCaptured, "notes_search", { query: "Café", scope: "personal" }, restoredCtx));
     assert.equal(searched.files[0]?.matches[0]?.line, 2);
-    const listedFiles = resultJson(await call(restoredCaptured, "notes_list", { pattern: "checkpoint/**", scope: "global" }, restoredCtx));
+    const listedFiles = resultJson(await call(restoredCaptured, "notes_list", { pattern: "checkpoint/**", scope: "personal" }, restoredCtx));
     assert.equal(listedFiles.files.length, 1, "glob ** crosses into the checkpoint directory");
     assert.equal(listedFiles.files[0]?.path, "checkpoint/进度.md");
     // A single-segment * never crosses `/`, so a nested-only store matches nothing at the root.
-    const rootOnly = resultJson(await call(restoredCaptured, "notes_list", { pattern: "*", scope: "global" }, restoredCtx));
+    const rootOnly = resultJson(await call(restoredCaptured, "notes_list", { pattern: "*", scope: "personal" }, restoredCtx));
     assert.equal(rootOnly.files.length, 0, "glob * stays within one segment");
     assert.equal(searched.files[0]?.created_at, listedFiles.files[0]?.created_at, "note tools agree on the timestamp format");
     assert.equal(searched.files[0]?.updated_at, listedFiles.files[0]?.updated_at);
@@ -380,6 +380,17 @@ test("stale lifecycle: writes and metadata-only edits close and revive a note",
     const missing = resultJson(await call(captured, "notes_edit", { path: "missing.md", stale: true }, ctx));
     assert.equal(missing.error, "note not found");
 });
+test("notes tools stay usable while a dream holds the lock", async () => {
+    // A live dream lock is not a general lock: the awake notes tools never consult it.
+    writeFileSync(join(process.env.PI_NOTES_HOME, ".dream.lock"), String(process.pid));
+    const sm = manager();
+    const captured = makeExtension(sm);
+    const ctx = context(sm);
+    const written = resultJson(await call(captured, "notes_write", { path: "during-dream.md", content: "awake" }, ctx));
+    assert.equal(written.address, "during-dream.md");
+    const edited = resultJson(await call(captured, "notes_edit", { path: "during-dream.md", edits: [{ oldText: "awake", newText: "still awake" }] }, ctx));
+    assert.equal(edited.applied, 1, "notes_edit still applies while a dream lock is held");
+});
 test("the boot notes index excludes stale notes while list, read, and search still see them", async () => {
     const sm = manager();
     const captured = makeExtension(sm);
@@ -416,22 +427,22 @@ test("the boot block gives awake agents the notes-home file layout", () => {
     const session = manager();
     const rendered = bootBlock(context(session), "pcw:test:root", undefined, false);
     assert.equal(rendered.includes(process.env.PI_NOTES_HOME ?? ""), false, "the absolute notes home is never exposed");
-    assert.match(rendered, /bare <vpath>.*@project\/<vpath>.*@global\/<vpath>/);
+    assert.match(rendered, /bare <vpath>.*@project\/<vpath>.*@personal\/<vpath>/);
     assert.match(rendered, /there is no cross-home fallback/);
     assert.match(rendered, /Any other note is a plain file — use the file tools/);
 });
-test("the boot block keeps fresh global and project maps resident, never a session map", async () => {
+test("the boot block keeps fresh personal and project maps resident, never a session map", async () => {
     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" }, ctx);
+    await call(captured, "notes_write", { address: "@personal/MAP.md", content: "MAP: personal" }, ctx);
     const rendered = bootBlock(ctx, "pcw:test:root", undefined, false);
-    assert.ok(rendered.includes("MAP: global"));
+    assert.ok(rendered.includes("MAP: personal"));
     assert.ok(rendered.includes("MAP: project"));
     assert.equal(rendered.includes("MAP: session"), false);
-    assert.ok(rendered.indexOf("MAP: global") < rendered.indexOf("MAP: project"), "global map precedes project map");
+    assert.ok(rendered.indexOf("MAP: personal") < rendered.indexOf("MAP: project"), "personal map precedes project map");
 });
 test("paged tool outputs stay bounded and cursors reconstruct history and notes", async () => {
     const session = manager();
@@ -1035,8 +1046,7 @@ test("the boot block is persisted at the root and baked into every reset summary
     assert.ok(rootText.includes("decisions.md"));
     const decisionsMeta = listNotes(ctx, { scope: "session" }).find((row) => row.path === "decisions.md")?.meta;
     assert.ok(decisionsMeta);
-    const bootUpdated = assertIsoTimestamp(rootText, "note metadata carries an updated timestamp");
-    assert.equal(Date.parse(bootUpdated), decisionsMeta.updated_at, "boot note timestamp restores the persisted updatedAt");
+    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));
     // Reset: the boot block IS the compaction summary; no separate boot/hint is persisted.
     await call(captured, "new_context", {}, ctx);
@@ -1050,8 +1060,8 @@ test("the boot block is persisted at the root and baked into every reset summary
     assert.equal(before.compaction.summary.startsWith(internal.CONTEXT_WINDOW_OPEN_TAG), false, "a reset line precedes the identity block");
     assert.match(before.compaction.summary, new RegExp(`Current context window id: ${details.windowId}`));
     assert.ok(before.compaction.summary.includes("decisions.md"));
-    const resetUpdated = assertIsoTimestamp(before.compaction.summary, "reset summary keeps the note updated timestamp");
-    assert.equal(Date.parse(resetUpdated), decisionsMeta.updated_at, "reset summary keeps the persisted updatedAt");
+    assert.match(before.compaction.summary, /updated \d+s ago\)/, "reset summary carries a relative update time");
+    assert.equal(listNotes(ctx, { scope: "session" }).find((row) => row.path === "decisions.md")?.meta.updated_at, decisionsMeta.updated_at, "rendering relative time preserves the stored timestamp");
     assert.ok(before.compaction.summary.includes(internal.CONTEXT_WINDOW_PROTOCOL_OPEN_TAG));
     const windows = historyFromSession(ctx);
     assert.ok(before.compaction.summary.includes(`Previous context window id: ${windows[windows.length - 1]?.windowId}`));