@astrosheep/pi-context 0.21.0 → 0.22.1

package/README.md

@@ -20,7 +20,7 @@ pi -e npm:@astrosheep/pi-context
 - **A boot block at every window head** — static once-per-window content (cache-stable) carrying the window identity, the recent-notes index, and a short protocol that teaches the model how to recover: notes for its own bookkeeping, history tools for everything before the reset.
 - **Low-budget guidance** — one persisted early warning per window when the estimated remaining budget crosses the reminder line, so the model checkpoints before the lights go out.
 - **`get_context_remaining`** — the live, reserve-adjusted estimate of the context budget left before Pi's compaction reserve.
-- **Nine history/notes tools** — Codex's History/Notes actions flattened into Pi's single tool namespace; notes are real markdown files under `~/.agents/notes` (`global/`, `project/`, `pi/session/`):
+- **Nine history/notes tools** — Codex's History/Notes actions flattened into Pi's single tool namespace; notes are real markdown files under `~/.agents/notes` (`personal/`, `project/`, `pi/session/`):
 
 | Codex action | Pi tool |
 | --- | --- |
@@ -51,6 +51,31 @@ The reminder threshold is Pi's compaction reserve plus a margin, configured unde
 
 `reminder = reserveTokens + reminderMarginTokens`; with the defaults the early warning fires 24,576 tokens above Pi's reset line.
 
+The dreamer model is configured under the same key. `--dreamer <model pattern>` on the `dream` CLI wins; otherwise a non-empty `pi-context.dreamer` string from settings applies; otherwise the automatic model is used. An invalid value (empty or not a string) is ignored with one warning.
+
+```json
+{
+  "pi-context": { "reminderMarginTokens": 24576, "dreamer": "anthropic/claude-sonnet-4-5" }
+}
+```
+
+## Check the notes store
+
+Run `dream doctor` (or `dream doctor --notes-home <dir>`) to check home layout, note frontmatter, concrete backtick-quoted note addresses, MAP entries, and lock presence/format. It is read-only: no model, git commits, directory creation, or repairs. Exit status is 0 when clean and 1 when issues are found. References needing an unavailable project context are reported as unresolved; prose and example/glob addresses are not validated. A present lock is reported without inferring process liveness.
+
+## The dream lock
+
+The `dream` CLI takes an exclusive `.dream.lock` in the notes home with a single O_CREAT|O_EXCL creation. The lock is Git-style existence locking: an existing lock refuses a new run regardless of its contents, PID, or age, and `--force` bypasses only the scheduling and material gates, never the lock. A lock is released only by the run that acquired it (and repeated cleanup is harmless), so a live dream is never displaced.
+
+If a dream process crashed, its lock remains and later runs refuse to start. There is no automatic recovery and no force-unlock command: after you have confirmed that no dream process is running, remove the stale lock by hand.
+
+```sh
+# only when no dream is running
+rm "${PI_NOTES_HOME:-$HOME/.agents/notes}/.dream.lock"
+```
+
+Removing a lock while a holder is running is outside the supported cooperative protocol and can let two dreams run at once.
+
 ## Documentation
 
 Implementation architecture and the reset lifecycle live in [docs/](docs/).

package/dist/src/dream/cli.js

@@ -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 { gitCommit } from "./git.js";
+import { readDreamerSettings } from "../thresholds.js";
+import { doctor } from "./doctor.js";
 import { notesRoot } from "../notes/paths.js";
 function args(argv) { const out = {}; for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -24,23 +27,76 @@ function packageRoot() {
         dir = parent;
     }
 }
-export async function main(argv = process.argv.slice(2)) {
+function writeList(writes) {
+    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, content) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, content);
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+function appendText(path, content) {
+    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, stamp, reportPath, failed, body, writes) {
+    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 = {}) {
+    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 --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.");
+        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 stampPath = lastRunPath(lockPath);
     const minHours = Number(a["min-hours"] ?? 24);
     const minSessions = Number(a["min-sessions"] ?? 3);
-    const time = timeGate(lockPath, minHours);
+    const time = timeGate(stampPath, minHours);
     console.log(time.reason);
     if (!a.force && !time.ok)
         return 0;
-    const material = materialGate(home, existsSync(lockPath) ? statSync(lockPath).mtimeMs : 0, minSessions);
+    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;
@@ -58,26 +114,65 @@ export async function main(argv = process.argv.slice(2)) {
     }
     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;
+        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;
+        let result;
+        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 {
-        releaseLock(lock);
+        // Only the holder's own lock is released; a successor's lock is never touched.
+        if (succeeded)
+            releaseLock(lock);
+        else
+            failLock(lock);
+    }
+}
+function isEntryPoint() {
+    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/dist/src/dream/doctor.js

@@ -0,0 +1,138 @@
+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) {
+    const issues = [];
+    const report = (path, message) => issues.push(`${relative(home, path) || "."}: ${message}`);
+    const inspect = (path, action) => {
+        try {
+            action();
+        }
+        catch (error) {
+            report(path, `cannot inspect: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const directory = (path) => {
+        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, root, project) => {
+        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();
+        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, root, project) => {
+        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/dist/src/dream/gates.js

@@ -1,13 +1,17 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { sessionHomesRoot } from "../notes/paths.js";
-export function timeGate(lockPath, minHours, now = Date.now()) {
-    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, minHours, now = Date.now()) {
+    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, lockMtime, minSessions) {
+export function materialGate(home, sinceMtime, minSessions) {
     const root = sessionHomesRoot(home);
     let changed = 0;
     if (existsSync(root))
@@ -15,7 +19,7 @@ export function materialGate(home, lockMtime, minSessions) {
             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))
+            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` };

package/dist/src/dream/git.js

@@ -1,28 +1,71 @@
 import { execFileSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Lock runtime artifacts are not notes and must not appear in snapshots or `git status`. */
+const RUNTIME_IGNORE = ".dream.lock*";
+/** Add the runtime-artifact pattern to the repository's local exclude, once. */
+function ensureRuntimeIgnored(home) {
+    try {
+        const exclude = join(home, ".git", "info", "exclude");
+        const current = existsSync(exclude) ? readFileSync(exclude, "utf8") : "";
+        if (current.split(/\r?\n/).includes(RUNTIME_IGNORE))
+            return;
+        mkdirSync(dirname(exclude), { recursive: true });
+        const prefix = current.length > 0 && !current.endsWith("\n") ? `${current}\n` : current;
+        writeFileSync(exclude, `${prefix}${RUNTIME_IGNORE}\n`);
+    }
+    catch { /* best effort: an unignored lock only adds noise to the audit */ }
+}
 /**
- * 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.
+ * 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`. The caller decides how loud a failure is; this function only reports it.
+ * A clean tree on an established repository commits nothing; a repository with no HEAD
+ * gets an empty baseline commit, because an audit run with no snapshot is not a success.
  */
 export function gitCommit(home, message) {
     try {
         if (!existsSync(join(home, ".git"))) {
             execFileSync("git", ["init", "-q"], { cwd: home, stdio: "ignore" });
         }
+        ensureRuntimeIgnored(home);
         execFileSync("git", ["add", "-A"], { cwd: home, stdio: "ignore" });
+        let clean = false;
         try {
             execFileSync("git", ["diff", "--cached", "--quiet"], { cwd: home, stdio: "ignore" });
-            return; // clean tree — no empty commit
+            clean = true; // clean tree — no empty commit on an established repository
+        }
+        catch {
+            clean = false;
+        }
+        const before = headCommit(home);
+        if (!clean) {
+            execFileSync("git", ["commit", "-q", "-m", message], { cwd: home, stdio: "ignore" });
+            console.log(`git: committed "${message}"`);
         }
-        catch { /* staged changes exist — fall through to commit */ }
-        execFileSync("git", ["commit", "-q", "-m", message], { cwd: home, stdio: "ignore" });
-        console.log(`git: committed "${message}"`);
+        else if (before === undefined) {
+            // A newly initialized repository has no snapshot at all; give the audit one.
+            execFileSync("git", ["commit", "-q", "--allow-empty", "-m", message], { cwd: home, stdio: "ignore" });
+            console.log(`git: committed "${message}"`);
+        }
+        const commit = headCommit(home);
+        if (commit === undefined)
+            return { ok: false, error: "audit commit produced no snapshot (no HEAD)" };
+        return { ok: true, commit, empty: clean };
     }
     catch (error) {
-        console.log(`git audit layer skipped: ${error instanceof Error ? error.message : error}`);
+        const reason = error instanceof Error ? error.message : String(error);
+        console.log(`git audit layer failed: ${reason}`);
+        return { ok: false, error: reason };
+    }
+}
+/** HEAD sha, or undefined when the repository has no commit yet. */
+function headCommit(home) {
+    try {
+        const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: home, encoding: "utf8" }).trim();
+        return head.length > 0 ? head : undefined;
+    }
+    catch {
+        return undefined;
     }
 }

package/dist/src/dream/lock.js

@@ -1,58 +1,99 @@
-import { existsSync, readFileSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
-const HOUR = 60 * 60 * 1000;
-function live(pid) {
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
+import { randomUUID } from "node:crypto";
+import { readFileSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+/**
+ * The scheduler's last-run timestamp lives in a sidecar beside the lock, never in the
+ * lock file itself: acquiring, releasing or cleaning up the lock touches only the PID
+ * marker, so lock lifecycle does not destroy the timestamp the time gate reads.
+ */
+export function lastRunPath(lockPath) {
+    return `${lockPath}.last-run`;
+}
+function readText(path) {
     try {
-        process.kill(pid, 0);
-        return true;
+        return readFileSync(path, "utf8");
     }
     catch {
-        return false;
+        return undefined;
     }
 }
-export function acquireLock(path) {
-    const now = Date.now();
-    let priorMtime;
-    if (existsSync(path)) {
-        const stat = statSync(path);
-        priorMtime = stat.mtimeMs;
-        let pid = 0;
-        try {
-            pid = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
-        }
-        catch { /* reclaim */ }
-        if (now - stat.mtimeMs <= HOUR && live(pid))
-            return { path, held: false, reason: "lock gate: live process holds the lock", startedAt: now };
-        try {
-            unlinkSync(path);
-        }
-        catch {
-            return { path, held: false, reason: "lock gate: lock could not be reclaimed", startedAt: now };
-        }
+function stampMtime(stampPath) {
+    try {
+        return statSync(stampPath).mtimeMs;
+    }
+    catch {
+        return undefined;
     }
-    writeFileSync(path, String(process.pid), { flag: "wx" });
-    return { path, held: true, startedAt: now, priorMtime };
 }
-export function releaseLock(lock) {
-    // The lock is also the durable last-dream timestamp. Leave the PID marker in place;
-    // the next acquisition reclaims it once the PID is dead or it is older than an hour.
+/**
+ * Cleanup ownership: only the exact marker this run wrote may be removed. The token is
+ * diagnostic and guards cleanup; it never grants permission to take an existing lock.
+ */
+function ownsLock(lock) {
+    if (!lock.held || !lock.token)
+        return false;
+    return readText(lock.path)?.trim() === `${process.pid} ${lock.token}`;
 }
-export function restoreMtime(path, mtimeMs) {
+/**
+ * Acquire the dream lock with Git-style exclusive existence locking: one O_CREAT|O_EXCL
+ * creation. An existing path refuses acquisition regardless of its contents, PID, or age,
+ * and is never read for permission, replaced, or removed. There is no automatic stale
+ * recovery; a crash-left lock is human cleanup after confirming no dream is running.
+ */
+export function acquireLock(path) {
+    const now = Date.now();
+    const priorStampMtime = stampMtime(lastRunPath(path));
+    const token = randomUUID();
+    try {
+        writeFileSync(path, `${process.pid} ${token}`, { flag: "wx" });
+    }
+    catch {
+        return { path, held: false, reason: "lock gate: lock already exists", startedAt: now };
+    }
+    // Only a held lock advances the scheduler timestamp.
     try {
-        utimesSync(path, new Date(), new Date(mtimeMs));
+        writeFileSync(lastRunPath(path), new Date(now).toISOString());
     }
     catch { /* advisory */ }
+    return { path, held: true, startedAt: now, priorStampMtime, token };
+}
+/** Release only the lock this run acquired. Idempotent: repeated cleanup does nothing. */
+export function releaseLock(lock) {
+    if (!lock.held)
+        return;
+    if (ownsLock(lock)) {
+        try {
+            unlinkSync(lock.path);
+        }
+        catch { /* best effort */ }
+    }
+    lock.held = false;
 }
+/**
+ * A failed run must not advance the scheduler: restore the previous timestamp, or remove
+ * the one this run wrote when there was none. Only this run's own marker is removed, and
+ * the state is marked released so a later cleanup attempt is harmless.
+ */
 export function failLock(lock) {
     if (!lock.held)
         return;
-    if (lock.priorMtime === undefined) {
+    if (ownsLock(lock)) {
+        const stampPath = lastRunPath(lock.path);
+        if (lock.priorStampMtime === undefined) {
+            try {
+                unlinkSync(stampPath);
+            }
+            catch { /* best effort */ }
+        }
+        else {
+            try {
+                utimesSync(stampPath, new Date(), new Date(lock.priorStampMtime));
+            }
+            catch { /* best effort */ }
+        }
         try {
             unlinkSync(lock.path);
         }
         catch { /* best effort */ }
     }
-    else
-        restoreMtime(lock.path, lock.priorMtime);
+    lock.held = false;
 }

package/dist/src/dream/runner.js

@@ -83,6 +83,11 @@ export const defaultDreamerSessionFactory = async ({ cwd, modelPattern, tools })
     const { session } = await createAgentSession({ cwd, sessionManager: SessionManager.inMemory(cwd), tools, customTools: dreamerWriteToolDefinitions(cwd), noTools: "all", model, thinkingLevel: "off" });
     return session;
 };
+/**
+ * Run one dream turn. A dreamer failure is returned as `error` together with the partial
+ * writes observed so far, so the caller can record partial state instead of losing it;
+ * only a failure to even start the session throws.
+ */
 export async function runDreamer(playbook, cwd, options = {}) {
     const session = await (options.sessionFactory ?? defaultDreamerSessionFactory)({ cwd, modelPattern: options.modelPattern, tools: DREAMER_TOOLS });
     let answer = "";
@@ -102,9 +107,14 @@ export async function runDreamer(playbook, cwd, options = {}) {
         answer = contentText(event.message.content);
     });
     try {
-        await session.prompt(playbook);
+        try {
+            await session.prompt(playbook);
+        }
+        catch (error) {
+            return { report: answer, writes, error: error instanceof Error ? error.message : String(error) };
+        }
         if (providerError)
-            throw new Error(`dreamer failed: ${providerError}`);
+            return { report: answer, writes, error: `dreamer failed: ${providerError}` };
         return { report: answer, writes };
     }
     finally {