@wierdbytes/pi-dream 0.0.0-stage → 0.1.1

package/search.ts

@@ -0,0 +1,153 @@
+/**
+ * Small in-memory BM25 for notes and session digests (Russian + English).
+ *
+ * The corpus is tiny (hundreds of notes, a few thousand digest chunks), so a
+ * plain inverted index rebuilt on demand beats running a search service.
+ *
+ * Russian inflects heavily, so a Cyrillic word yields truncated forms at two
+ * lengths (4 and 6 letters) plus the same without a common verb prefix:
+ * "коммита"/"коммит" and "задеплой"/"деплой" meet, while the longer form
+ * keeps "контекст" apart from "контроль". English gets light suffix
+ * stripping ("deploys" → "deploy").
+ */
+
+const RU_PREFIXES = ["пере", "под", "при", "про", "раз", "рас", "за", "вы", "по", "на", "от", "до", "об", "вз", "из"];
+
+const STOP = new Set(
+	"и в во не что он на я с со как а то все она так его но да ты к у же вы за бы по только ее мне было вот от меня еще нет о из ему теперь когда даже ну вдруг ли если уже или ни быть был него до вас нибудь опять уж вам ведь там потом себя ничего ей может они тут где есть надо ней для мы тебя их чем была сам чтоб без будто чего раз тоже себе под будет ж тогда кто этот того потому этого какой совсем ним здесь этом один почти мой тем чтобы нее сейчас были куда зачем всех никогда можно при наконец два об другой хоть после над больше тот через эти нас про всего них какая много разве три эту моя впрочем хорошо свою этой перед иногда лучше чуть том нельзя такой им более всегда конечно всю между the a an and or of to in on for is it this that with be as at by from are was were has have had not but if then so do does did can will just".split(
+		" ",
+	),
+);
+
+function ruForms(word: string): string[] {
+	if (word.length <= 4) return [word];
+	const out = [word.slice(0, 4)];
+	if (word.length >= 6) out.push(word.slice(0, 6));
+	for (const p of RU_PREFIXES) {
+		if (word.startsWith(p) && word.length - p.length >= 5) {
+			const rest = word.slice(p.length);
+			out.push(rest.slice(0, 4));
+			if (rest.length >= 6) out.push(rest.slice(0, 6));
+			break;
+		}
+	}
+	return out;
+}
+
+function enStem(word: string): string {
+	if (word.length > 4) {
+		for (const suf of ["ing", "ed", "es", "s"]) if (word.endsWith(suf) && word.length - suf.length >= 3) return word.slice(0, -suf.length);
+	}
+	return word;
+}
+
+export function tokenize(text: string): string[] {
+	const out: string[] = [];
+	for (const raw of text.toLowerCase().replace(/ё/g, "е").split(/[^\p{L}\p{N}_]+/u)) {
+		if (raw.length < 2 || STOP.has(raw)) continue;
+		if (/^[а-я]+$/.test(raw)) out.push(...ruForms(raw));
+		else if (/^[a-z]+$/.test(raw)) out.push(enStem(raw));
+		else out.push(raw);
+	}
+	return out;
+}
+
+export interface Doc<M = unknown> {
+	id: string;
+	text: string;
+	meta: M;
+}
+
+export interface Hit<M = unknown> {
+	doc: Doc<M>;
+	score: number;
+}
+
+export class Bm25<M = unknown> {
+	private postings = new Map<string, Array<[number, number]>>();
+	private lengths: number[] = [];
+	private avg = 0;
+	constructor(
+		readonly docs: Doc<M>[],
+		private k1 = 1.2,
+		private b = 0.75,
+	) {
+		let total = 0;
+		docs.forEach((doc, i) => {
+			const tf = new Map<string, number>();
+			const toks = tokenize(doc.text);
+			for (const t of toks) tf.set(t, (tf.get(t) ?? 0) + 1);
+			for (const [t, n] of tf) {
+				let list = this.postings.get(t);
+				if (!list) this.postings.set(t, (list = []));
+				list.push([i, n]);
+			}
+			this.lengths.push(toks.length);
+			total += toks.length;
+		});
+		this.avg = docs.length ? total / docs.length : 0;
+	}
+
+	search(query: string, limit = 10, filter?: (doc: Doc<M>) => boolean): Hit<M>[] {
+		const terms = [...new Set(tokenize(query))];
+		if (!terms.length || !this.docs.length) return [];
+		const scores = new Map<number, number>();
+		const N = this.docs.length;
+		for (const t of terms) {
+			const list = this.postings.get(t);
+			if (!list) continue;
+			const idf = Math.log(1 + (N - list.length + 0.5) / (list.length + 0.5));
+			for (const [i, tf] of list) {
+				const len = this.lengths[i] || 1;
+				const s = (idf * tf * (this.k1 + 1)) / (tf + this.k1 * (1 - this.b + (this.b * len) / (this.avg || 1)));
+				scores.set(i, (scores.get(i) ?? 0) + s);
+			}
+		}
+		return [...scores.entries()]
+			.filter(([i]) => !filter || filter(this.docs[i]))
+			.sort((a, b) => b[1] - a[1])
+			.slice(0, limit)
+			.map(([i, score]) => ({ doc: this.docs[i], score }));
+	}
+}
+
+/** The lines of `text` that best match `query`, clipped to `max` chars. */
+export function snippet(text: string, query: string, max = 320): string {
+	const terms = new Set(tokenize(query));
+	const lines = text.split("\n");
+	let best = 0;
+	let bestScore = -1;
+	lines.forEach((line, i) => {
+		const score = tokenize(line).filter((t) => terms.has(t)).length;
+		if (score > bestScore) {
+			bestScore = score;
+			best = i;
+		}
+	});
+	let out = lines[best] ?? "";
+	for (let i = best + 1; i < lines.length && out.length < max; i++) out += `\n${lines[i]}`;
+	return out.length > max ? `${out.slice(0, max)}…` : out;
+}
+
+/** Split a digest into chunks of whole lines; each chunk starts at an entry line. */
+export function chunkDigest(text: string, maxChars = 2400): Array<{ entryId?: string; text: string }> {
+	const chunks: Array<{ entryId?: string; text: string }> = [];
+	let cur: string[] = [];
+	let size = 0;
+	let entryId: string | undefined;
+	const flush = () => {
+		if (cur.length) chunks.push({ entryId, text: cur.join("\n") });
+		cur = [];
+		size = 0;
+		entryId = undefined;
+	};
+	for (const line of text.split("\n")) {
+		const id = /^\[([0-9a-f-]{6,})\]/.exec(line)?.[1];
+		if (id && size + line.length > maxChars) flush();
+		if (id && !entryId) entryId = id;
+		cur.push(line);
+		size += line.length + 1;
+	}
+	flush();
+	return chunks;
+}

package/secrets.ts

@@ -0,0 +1,74 @@
+/**
+ * Redact credentials before transcript text reaches a model or a note, and
+ * detect them when linting what the dream is about to write.
+ */
+
+interface Rule {
+	kind: string;
+	re: RegExp;
+	/** Keep capture group 1 (e.g. the key name) and redact the rest. */
+	keepPrefix?: boolean;
+}
+
+const RULES: Rule[] = [
+	{ kind: "private-key", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g },
+	{ kind: "anthropic-key", re: /\bsk-ant-[A-Za-z0-9_-]{16,}/g },
+	{ kind: "openai-key", re: /\bsk-(?!ant-|lf-)(?:proj-|svcacct-)?[A-Za-z0-9_-]{20,}/g },
+	{ kind: "langfuse-key", re: /\b(?:pk|sk)-lf-[A-Za-z0-9-]{8,}/g },
+	{ kind: "github-token", re: /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})/g },
+	{ kind: "aws-key", re: /\bAKIA[0-9A-Z]{16}\b/g },
+	{ kind: "slack-token", re: /\bxox[abprs]-[A-Za-z0-9-]{10,}/g },
+	{ kind: "google-key", re: /\bAIza[0-9A-Za-z_-]{30,}/g },
+	{ kind: "jwt", re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g },
+	{ kind: "bearer", re: /\b(Bearer\s+)[A-Za-z0-9._~+/-]{20,}=*/g, keepPrefix: true },
+	{
+		kind: "assignment",
+		re: /\b((?:api[_-]?key|apikey|secret|client[_-]?secret|token|access[_-]?token|auth[_-]?token|refresh[_-]?token|password|passwd|pwd)["']?\s*[:=]\s*["']?)([^\s"'`,;]{8,})/gi,
+		keepPrefix: true,
+	},
+];
+
+export function scrubSecrets(text: string): string {
+	if (!text) return text;
+	let out = text;
+	for (const rule of RULES) {
+		rule.re.lastIndex = 0;
+		out = out.replace(rule.re, (match: string, prefix?: string) =>
+			rule.keepPrefix && typeof prefix === "string" ? `${prefix}[REDACTED]` : `[REDACTED:${rule.kind}]`,
+		);
+	}
+	return out;
+}
+
+/** Kinds of credentials found in `text` (empty when clean). */
+export function findSecrets(text: string): string[] {
+	const found = new Set<string>();
+	for (const rule of RULES) {
+		rule.re.lastIndex = 0;
+		for (const m of text.matchAll(rule.re)) {
+			// `[REDACTED]` placeholders left by scrubSecrets are not secrets.
+			const value = rule.keepPrefix ? (m[2] ?? m[0]) : m[0];
+			if (!value.includes("[REDACTED")) found.add(rule.kind);
+		}
+	}
+	return [...found];
+}
+
+const INJECTION: Array<[string, RegExp]> = [
+	["ignore-instructions", /ignore (?:all |any )?(?:the )?(?:previous|prior|above) instructions/i],
+	["disregard-instructions", /disregard (?:all |any )?(?:the )?(?:previous|prior|above)/i],
+	["fake-prompt-tag", /<\/?(?:system|instructions|memory|project_context)>/i],
+	["role-override", /you are now\b/i],
+];
+
+const RISKY: Array<[string, RegExp]> = [["pipe-to-shell", /\b(?:curl|wget)\b[^\n|]*\|\s*(?:sudo\s+)?(?:ba|z)?sh\b/i]];
+
+/** Prompt-injection phrases: never acceptable as memory text. */
+export function findInjection(text: string): string[] {
+	return INJECTION.filter(([, re]) => re.test(text)).map(([name]) => name);
+}
+
+/** Risky but possibly legitimate content (e.g. an installer piped to sh): flagged for the reviewer. */
+export function findRisky(text: string): string[] {
+	return RISKY.filter(([, re]) => re.test(text)).map(([name]) => name);
+}

package/sessions.ts

@@ -0,0 +1,176 @@
+/**
+ * Reading pi session files (`~/.pi/agent/sessions/<cwd>/<ts>_<id>.jsonl`).
+ *
+ * Sessions are trees; the newest appended entry is the current leaf, so the
+ * active branch is the parent chain from the last entry back to the root.
+ * Images and thinking are dropped while streaming, which keeps 100 MB
+ * sessions full of screenshots cheap to hold in memory.
+ */
+
+import { createReadStream, existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export interface SessionFile {
+	path: string;
+	mtimeMs: number;
+	size: number;
+}
+
+export interface RawEntry {
+	type: string;
+	id: string;
+	parentId?: string | null;
+	timestamp?: string;
+	message?: Record<string, unknown> & { role?: string; content?: unknown };
+	customType?: string;
+	data?: unknown;
+	content?: unknown;
+	summary?: string;
+	name?: string;
+	[key: string]: unknown;
+}
+
+export interface SessionHeader {
+	id: string;
+	cwd: string;
+	timestamp: string;
+	parentSession?: string;
+}
+
+export interface ParsedSession {
+	file: string;
+	header: SessionHeader;
+	/** Active branch, root first. */
+	branch: RawEntry[];
+	name?: string;
+	lastEntryId?: string;
+}
+
+export function sessionsRoot(): string {
+	return process.env.PI_CODING_AGENT_SESSION_DIR || join(getAgentDir(), "sessions");
+}
+
+export function listSessionFiles(root: string = sessionsRoot()): SessionFile[] {
+	const out: SessionFile[] = [];
+	if (!existsSync(root)) return out;
+	for (const dir of readdirSync(root, { withFileTypes: true })) {
+		if (!dir.isDirectory()) continue;
+		const full = join(root, dir.name);
+		let names: string[];
+		try {
+			names = readdirSync(full);
+		} catch {
+			continue;
+		}
+		for (const name of names) {
+			if (!name.endsWith(".jsonl")) continue;
+			const path = join(full, name);
+			try {
+				const st = statSync(path);
+				if (st.isFile()) out.push({ path, mtimeMs: st.mtimeMs, size: st.size });
+			} catch {
+				// vanished between readdir and stat
+			}
+		}
+	}
+	return out;
+}
+
+/** Session id from a file name `<timestamp>_<id>.jsonl`. */
+export function sessionIdFromPath(path: string): string {
+	const base = path.split("/").pop() ?? path;
+	const m = /_([^_]+)\.jsonl$/.exec(base);
+	return m ? m[1] : base.replace(/\.jsonl$/, "");
+}
+
+function slim(content: unknown): unknown {
+	if (!Array.isArray(content)) return content;
+	return content.map((b) => {
+		if (!b || typeof b !== "object") return b;
+		const t = (b as { type?: string }).type;
+		if (t === "image") return { type: "image" };
+		if (t === "thinking" || t === "redacted_thinking") return { type: "thinking" };
+		return b;
+	});
+}
+
+function slimEntry(e: RawEntry): RawEntry {
+	if (e.message && typeof e.message === "object") {
+		const m = e.message;
+		if (m.role === "system") e.message = { role: "system" };
+		else if ("content" in m) m.content = slim(m.content);
+	}
+	if (e.type === "custom_message" && "content" in e) e.content = slim(e.content);
+	if (e.type === "compaction") delete e.systemMessage;
+	return e;
+}
+
+export async function parseSession(file: string): Promise<ParsedSession | undefined> {
+	const entries = new Map<string, RawEntry>();
+	let header: SessionHeader | undefined;
+	let lastId: string | undefined;
+	let name: string | undefined;
+	const rl = createInterface({ input: createReadStream(file, { encoding: "utf8" }), crlfDelay: Infinity });
+	for await (const line of rl) {
+		if (!line) continue;
+		let e: RawEntry;
+		try {
+			e = JSON.parse(line) as RawEntry;
+		} catch {
+			continue;
+		}
+		if (e.type === "session") {
+			header = e as unknown as SessionHeader;
+			continue;
+		}
+		if (typeof e.id !== "string") continue;
+		entries.set(e.id, slimEntry(e));
+		lastId = e.id;
+		if (e.type === "session_info" && typeof e.name === "string") name = e.name;
+	}
+	if (!header) return undefined;
+	const branch: RawEntry[] = [];
+	const seen = new Set<string>();
+	let cur = lastId ? entries.get(lastId) : undefined;
+	while (cur && !seen.has(cur.id)) {
+		seen.add(cur.id);
+		branch.push(cur);
+		cur = cur.parentId ? entries.get(cur.parentId) : undefined;
+	}
+	branch.reverse();
+	return { file, header, branch, name, lastEntryId: lastId };
+}
+
+/** Plain text of a message content (string or blocks); images become `[image]`. */
+export function textOf(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const b of content) {
+		if (!b || typeof b !== "object") continue;
+		const blk = b as { type?: string; text?: unknown };
+		if (blk.type === "text" && typeof blk.text === "string") parts.push(blk.text);
+		else if (blk.type === "image") parts.push("[image]");
+	}
+	return parts.join("\n");
+}
+
+/** Small LRU of parsed sessions, for evidence lookups during one dream. */
+export class SessionCache {
+	private map = new Map<string, Promise<ParsedSession | undefined>>();
+	constructor(private max = 8) {}
+	get(file: string): Promise<ParsedSession | undefined> {
+		let p = this.map.get(file);
+		if (p) {
+			this.map.delete(file);
+			this.map.set(file, p);
+			return p;
+		}
+		p = parseSession(file);
+		this.map.set(file, p);
+		while (this.map.size > this.max) this.map.delete(this.map.keys().next().value as string);
+		return p;
+	}
+}

package/setup.ts

@@ -0,0 +1,148 @@
+/**
+ * `/dream init`: create the memory repository, its GitHub remote and the
+ * settings file. Idempotent — every step checks before it acts, so running it
+ * again only fills in what is missing.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configPath, type DreamConfig, saveConfig } from "./config.ts";
+import { gh, ghOk, git, githubRepoOf, gitOk } from "./gitops.ts";
+import { CHARTER_FILE, GLOBAL_SCOPE, INDEX_FILE, memoryPaths, scopeDir } from "./layout.ts";
+import { buildIndex } from "./memindex.ts";
+import { DEFAULT_GLOBAL_CHARTER, DEFAULT_PROJECT_CHARTER } from "./prompts.ts";
+
+const GITIGNORE = ".local/\n.DS_Store\n";
+
+const README = `# pi memory
+
+Память агентов [pi](https://pi.dev) на этой машине. Её ведёт [@wierdbytes/pi-dream](https://github.com/wierdbytes/pi-wierd-stuff/tree/master/packages/dream): фоновый «сон» перечитывает новые сессии pi, предлагает изменения памяти и присылает их сюда pull request'ом. В сессии попадает только то, что смёрджено в \`main\`.
+
+## Устройство
+
+\`\`\`
+scopes/global/                 всё, что верно для тебя и машины во всех проектах
+  charter.md                   зачем эта память — направляет сон (в сессии не попадает)
+  MEMORY.md                    индекс, генерируется из notes/ — именно он подгружается в сессии
+  notes/<slug>.md              одна заметка = один файл (front matter + текст)
+  skills/<name>/SKILL.md       одобренные скиллы, pi подхватывает их автоматически
+scopes/projects/<проект>/      то же для одного проекта (ключ — git remote или путь)
+reports/<run>.md               отчёт каждого сна
+prompts/<stage>.md             (необязательно) свои промпты сна: cards, curator, review, verify
+.local/                        не в git: inbox, дайджесты и карточки сессий, логи, состояние
+\`\`\`
+
+## Заметка
+
+\`\`\`markdown
+---
+id: m-7f3a2c
+title: "Утверждение одной строкой — это и есть строка в индексе"
+type: procedure            # preference | procedure | pitfall | fact | decision | reference
+status: active             # active | superseded | deprecated
+index: always              # always — строка в каждой сессии scope; pointer — «когда → id»; none — только поиск
+when: "когда это нужно"
+created: "2026-11-08"
+updated: "2026-11-08"
+evidence:
+  - {"s": "<session id>", "e": ["<entry id>"], "date": "2026-11-06", "at": "2026-11-06T14:05Z", "kind": "user"}
+---
+
+Подробности: точные команды, пути, условия, причины.
+\`\`\`
+
+## Ревью
+
+- **Merge** — изменения становятся памятью.
+- **Правки прямо в PR** — сон продолжит с твоей версии; можно и руками добавлять заметки (id и даты сон допишет сам).
+- **Комментарий в PR** — указание сну, выполнится при следующем \`/dream run\`.
+- **Закрыть без merge** — отклонить предложенные заметки.
+- \`pinned: true\` в заметке — сон никогда не закроет её сам.
+
+Сессию-доказательство можно открыть: \`pi --session <id>\`.
+`;
+
+const PROMPTS_README = `# Свои промпты сна
+
+Положи сюда \`cards.md\`, \`curator.md\`, \`review.md\` или \`verify.md\`, чтобы заменить соответствующий системный промпт pi-dream.
+Плейсхолдеры: \`{{language}}\`, \`{{charter}}\`, \`{{global_budget}}\`, \`{{project_budget}}\`.
+Изменения промптов проходят ревью как всё остальное.
+`;
+
+function writeIfMissing(path: string, content: string, created: string[]): void {
+	if (existsSync(path)) return;
+	mkdirSync(join(path, ".."), { recursive: true });
+	writeFileSync(path, content, "utf-8");
+	created.push(path);
+}
+
+export async function initMemory(cfg: DreamConfig, log: (msg: string) => void): Promise<{ repo?: string }> {
+	const root = cfg.memoryDir;
+	const P = memoryPaths(root);
+	mkdirSync(P.local, { recursive: true });
+
+	if (!existsSync(join(root, ".git"))) {
+		await gitOk(root, ["init", "-b", cfg.github.base]);
+		log(`git init ${root}`);
+	}
+
+	const created: string[] = [];
+	writeIfMissing(join(root, ".gitignore"), GITIGNORE, created);
+	writeIfMissing(join(root, "README.md"), README, created);
+	writeIfMissing(join(scopeDir(root, GLOBAL_SCOPE), CHARTER_FILE), `${DEFAULT_GLOBAL_CHARTER}\n`, created);
+	writeIfMissing(join(scopeDir(root, GLOBAL_SCOPE), INDEX_FILE), buildIndex([], "global", cfg.budgets.globalTokens).text, created);
+	writeIfMissing(join(scopeDir(root, GLOBAL_SCOPE), "notes", ".gitkeep"), "", created);
+	writeIfMissing(join(P.scopes, "projects", "_charter.md"), `${DEFAULT_PROJECT_CHARTER}\n`, created);
+	writeIfMissing(join(P.reports, ".gitkeep"), "", created);
+	writeIfMissing(join(P.prompts, "README.md"), PROMPTS_README, created);
+	if (created.length) log(`created ${created.length} files`);
+
+	const status = await git(root, ["status", "--porcelain"]);
+	if (status.stdout.trim()) {
+		await gitOk(root, ["add", "-A"]);
+		await gitOk(root, ["commit", "-m", "pi-dream: initialize memory repository"]);
+		log("committed the skeleton");
+	}
+
+	let remote = await git(root, ["remote", "get-url", "origin"]);
+	if (remote.code !== 0) {
+		const owner = await ghOk(["api", "user", "--jq", ".login"]);
+		const full = `${owner}/${cfg.github.repo}`;
+		const exists = await gh(["repo", "view", full, "--json", "name"]);
+		if (exists.code === 0) {
+			const ssh = `git@github.com:${full}.git`;
+			await gitOk(root, ["remote", "add", "origin", ssh]);
+			log(`origin → existing ${full}`);
+		} else {
+			await ghOk(
+				["repo", "create", full, "--private", "--description", "pi agent memory, maintained by pi-dream", "--source", root, "--remote", "origin"],
+				{ timeoutMs: 120_000 },
+			);
+			log(`created private GitHub repo ${full}`);
+		}
+		remote = await git(root, ["remote", "get-url", "origin"]);
+	}
+	const repo = githubRepoOf(remote.stdout.trim());
+
+	const push = await git(root, ["push", "-u", "origin", cfg.github.base], 120_000);
+	if (push.code !== 0) log(`push failed: ${push.stderr.trim()}`);
+	else log(`pushed ${cfg.github.base}`);
+
+	if (repo) {
+		const label = await gh(["label", "create", cfg.github.label, "--repo", repo, "--color", "7AA2F7", "--description", "pi-dream memory review", "--force"]);
+		if (label.code === 0) log(`label "${cfg.github.label}" ready`);
+	}
+
+	if (!existsSync(configPath())) {
+		saveConfig(cfg);
+		log(`settings → ${configPath()}`);
+	}
+	return { repo };
+}
+
+/** Whether the memory repo exists and has a remote. */
+export async function memoryReady(root: string): Promise<{ git: boolean; remote: boolean }> {
+	if (!existsSync(join(root, ".git"))) return { git: false, remote: false };
+	const r = await git(root, ["remote", "get-url", "origin"]);
+	return { git: true, remote: r.code === 0 };
+}

package/state.ts

@@ -0,0 +1,84 @@
+/**
+ * Local dream state (`.local/state.json`, never committed): which sessions and
+ * inbox items were processed, the open review pull request, what was rejected.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface SessionMark {
+	size: number;
+	mtimeMs: number;
+	at: string;
+	/** The session (at this size) was summarized, or had nothing to summarize. */
+	ok: boolean;
+	/** Failed card attempts at this size; the session is skipped after 3. */
+	failures: number;
+}
+
+export interface RunRecord {
+	id: string;
+	pr?: number;
+	/** Notes added by this run (id + title), to learn from rejections. */
+	added: Array<{ id: string; title: string }>;
+}
+
+export interface DreamState {
+	version: 1;
+	createdAt: string;
+	/** Sessions last written before this and never processed are ignored. */
+	cutoffMs: number;
+	sessions: Record<string, SessionMark>;
+	inboxDone: string[];
+	lastRun?: {
+		id: string;
+		startedAt: string;
+		finishedAt?: string;
+		status: "running" | "ok" | "noop" | "error";
+		error?: string;
+		pr?: string;
+		sessions?: number;
+		cost?: number;
+	};
+	openPr?: { number: number; url: string; branch: string };
+	/** PR number → ISO time of the newest review comment already applied. */
+	reviewSeen: Record<string, string>;
+	rejected: Array<{ title: string; at: string; pr?: number }>;
+	runs: RunRecord[];
+}
+
+export function freshState(lookbackDays: number, now = Date.now()): DreamState {
+	return {
+		version: 1,
+		createdAt: new Date(now).toISOString(),
+		cutoffMs: now - lookbackDays * 86_400_000,
+		sessions: {},
+		inboxDone: [],
+		reviewSeen: {},
+		rejected: [],
+		runs: [],
+	};
+}
+
+export function loadState(path: string): DreamState | undefined {
+	if (!existsSync(path)) return undefined;
+	try {
+		const s = JSON.parse(readFileSync(path, "utf-8")) as DreamState;
+		if (s?.version !== 1) return undefined;
+		s.sessions ??= {};
+		s.inboxDone ??= [];
+		s.reviewSeen ??= {};
+		s.rejected ??= [];
+		s.runs ??= [];
+		return s;
+	} catch {
+		return undefined;
+	}
+}
+
+export function saveState(path: string, state: DreamState): void {
+	mkdirSync(dirname(path), { recursive: true });
+	const tmp = `${path}.tmp-${process.pid}`;
+	writeFileSync(tmp, `${JSON.stringify(state, null, 1)}\n`, "utf-8");
+	renameSync(tmp, path);
+}