@astrosheep/pi-context 0.20.0 → 0.22.0

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,27 @@ 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" }
+}
+```
+
+## 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/budget.js

@@ -5,7 +5,11 @@ import { thresholdsFor, resetThresholds } from "./thresholds.js";
 import { currentWindowId, hasWindowMessage } from "./history.js";
 import { tokenBudgetGuidance } from "./prompts.js";
 import { output } from "./tool-output.js";
-export { deriveThresholds, mergePiContextSettings } from "./thresholds.js";
+/** Remaining tokens in the current context window, or null when Pi has no usage estimate. */
+export function remainingTokens(ctx) {
+    const usage = ctx.getContextUsage();
+    return !usage || usage.tokens === null ? null : Math.max(0, usage.contextWindow - usage.tokens);
+}
 export function registerBudget(pi, isEnabled) {
     let guidancePersistedInWindow;
     pi.on("session_start", (_event, ctx) => { guidancePersistedInWindow = undefined; resetThresholds(); thresholdsFor(ctx); });
@@ -15,10 +19,9 @@ export function registerBudget(pi, isEnabled) {
             return undefined;
         // The early reminder persists once per window the first time remaining crosses
         // reserve+margin. It never edits the outgoing request.
-        const usage = ctx.getContextUsage();
-        if (!usage || usage.tokens === null)
+        const remaining = remainingTokens(ctx);
+        if (remaining === null)
             return undefined;
-        const remaining = Math.max(0, usage.contextWindow - usage.tokens);
         const windowId = currentWindowId(ctx);
         const { reminder, reserve, warning } = thresholdsFor(ctx);
         // The final warning owns the deep band: when it has fired (or is due now),
@@ -26,7 +29,7 @@ export function registerBudget(pi, isEnabled) {
         // the wipe, at a worse position. See warning.ts.
         if (remaining <= warning || hasWindowMessage(ctx, WARNING_TYPE))
             return undefined;
-        if (remaining <= reminder && guidancePersistedInWindow !== windowId && !hasWindowMessage(ctx, GUIDANCE_TYPE)) {
+        if (remaining <= reminder && guidancePersistedInWindow !== windowId) {
             guidancePersistedInWindow = windowId;
             // Persist once per window — no transient copy. A transient bridge would
             // cover the crossing request, but history would record the reminder after
@@ -53,11 +56,10 @@ export function registerBudget(pi, isEnabled) {
         description: "Return estimated context tokens left before your memory is wiped; null when Pi cannot estimate usage.",
         parameters: Type.Object({}, { additionalProperties: false }),
         async execute(_id, _params, _signal, _update, ctx) {
-            const usage = ctx.getContextUsage();
             // The countdown the model sees ends at the warning line (reserve + runway);
             // the runway below it is overdraft the model never sees. See protocol.ts.
-            const remaining = usage?.tokens === null || usage === undefined ? null : Math.max(0, usage.contextWindow - usage.tokens - thresholdsFor(ctx).warning);
-            return output({ remaining_tokens: remaining });
+            const remaining = remainingTokens(ctx);
+            return output({ remaining_tokens: remaining === null ? null : Math.max(0, remaining - thresholdsFor(ctx).warning) });
         },
     }));
 }

package/dist/src/dream/cli.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+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 { applyManifest } from "./apply.js";
+import { gitCommit } from "./git.js";
+import { readDreamerSettings } from "../thresholds.js";
+import { notesRoot } from "../notes/paths.js";
 function args(argv) { const out = {}; for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force" || a === "--help")
@@ -24,23 +26,65 @@ 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 = {}) {
     const a = args(argv);
     if (a.help) {
-        console.log("dream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <cmd>] [--dreamer-model <pattern>] [--playbook <path>]\nDefault dreamer: in-process pi SDK session with read-only tools; use a cheap model in production. Default playbook: <installed package root>/playbook.md; --playbook overrides it.");
+        console.log("dream --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"] ?? process.env.PI_NOTES_HOME ?? join(homedir(), ".agents", "notes")));
+    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,25 +102,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`);
+    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 manifest = await runDreamer(playbook, home, { command: a.dreamer ? String(a.dreamer) : undefined, modelPattern: a["dreamer-model"] ? String(a["dreamer-model"]) : undefined });
-        const ctx = { cwd: home, sessionManager: { getSessionId: () => "dream" } };
-        const actions = applyManifest(ctx, home, stamp, manifest);
-        mkdirSync(join(home, "dreams"), { recursive: true });
-        writeFileSync(reportPath, `# Dream ${stamp}\n\n${manifest.report}\n\n${actions.map((x) => `- ${x}`).join("\n")}\n`);
-        console.log(reportPath);
-        return 0;
-    }
-    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/gates.js

@@ -1,20 +1,25 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
-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" };
+import { sessionHomesRoot } from "../notes/paths.js";
+/**
+ * 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) {
-    const root = join(home, "pi", "session");
+export function materialGate(home, sinceMtime, minSessions) {
+    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))
+            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

@@ -0,0 +1,71 @@
+import { execFileSync } from "node:child_process";
+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`. 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" });
+            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}"`);
+        }
+        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) {
+        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

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