@wierdbytes/pi-dream 0.0.0-stage → 0.1.1

package/digest.ts

@@ -0,0 +1,329 @@
+/**
+ * Session digest: a compact, line-per-entry rendering of the active branch.
+ *
+ * User messages are kept almost whole, assistant text is clipped, tool calls
+ * are one line, tool results keep only a head (errors: head and tail).
+ * Images and thinking never appear. Every line carries its entry id, so the
+ * models can cite evidence the dream can later look up in the raw session.
+ * Credentials are scrubbed from every line.
+ */
+
+import { homedir } from "node:os";
+import { normalize, resolve } from "node:path";
+import { type ParsedSession, type RawEntry, textOf } from "./sessions.ts";
+import { scrubSecrets } from "./secrets.ts";
+
+export type LineKind = "USER" | "AI" | "CALL" | "RESULT" | "ERROR" | "SHELL" | "MEMORY" | "SUMMARY" | "CUSTOM";
+
+export interface DigestLine {
+	id: string;
+	kind: LineKind;
+	text: string;
+	ts?: string;
+}
+
+export interface DigestMeta {
+	sessionId: string;
+	file: string;
+	cwd: string;
+	started: string;
+	ended?: string;
+	name?: string;
+	models: string[];
+	userMessages: number;
+	toolCalls: number;
+	toolErrors: number;
+	/** Memory notes injected into this session by pi-dream. */
+	injected: string[];
+	/** Memory notes the agent opened with memory_read. */
+	read: string[];
+	lastEntryId?: string;
+	/** Absolute paths the session worked with (tool paths, `cd` targets), most used first. */
+	paths: Array<[string, number]>;
+}
+
+const MAX_PATHS = 40;
+
+/** `~/x`, `./x`, `x` (relative to cwd) → absolute path; undefined for globs, variables and flags. */
+export function expandPath(raw: string, cwd: string): string | undefined {
+	let t = raw.trim().replace(/^['"]|['"]$/g, "");
+	if (!t || t.startsWith("-") || /[$*?{}`]/.test(t) || t.includes("://")) return undefined;
+	if (t === "~") t = homedir();
+	else if (t.startsWith("~/")) t = homedir() + t.slice(1);
+	else if (!t.startsWith("/")) {
+		if (!cwd) return undefined;
+		t = resolve(cwd, t);
+	}
+	return normalize(t).replace(/\/+$/, "") || "/";
+}
+
+/** Paths a tool call works with: `path` arguments and, for bash, `cd` targets and home paths. */
+/** Absolute paths under a home folder in a shell command: `~/…`, `/Users/<u>/…` (macOS), `/home/<u>/…` (Linux) or this machine's home. */
+const HOME_PATH_RE = new RegExp(
+	`(?:^|[\\s'"=(:])((?:~|/Users/[^/\\s'"]+|/home/[^/\\s'"]+|${homedir().replace(/[.*+?^${}()|[\]\\]/g, "\\$&")})/[^\\s'"\`;|&)<>]+)`,
+	"g",
+);
+
+export function callPaths(name: string, args: unknown, cwd: string): string[] {
+	const a = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
+	const out: string[] = [];
+	const add = (p: string | undefined) => {
+		if (p) out.push(p);
+	};
+	if (typeof a.path === "string") add(expandPath(a.path, cwd));
+	if (name === "bash" && typeof a.command === "string") {
+		const cmd = a.command;
+		for (const m of cmd.matchAll(/(?:^|[;&|(]|\n)\s*cd\s+("[^"]+"|'[^']+'|[^\s;&|)]+)/g)) add(expandPath(m[1], cwd));
+		for (const m of cmd.matchAll(HOME_PATH_RE)) add(expandPath(m[1], cwd));
+	}
+	return out;
+}
+
+export interface Digest {
+	meta: DigestMeta;
+	lines: DigestLine[];
+}
+
+export const LIMITS = { USER: 6000, AI: 2000, CALL: 400, RESULT: 200, ERROR: 700, SHELL: 600, SUMMARY: 1500, CUSTOM: 400 };
+
+export function clipHead(text: string, max: number): string {
+	const t = text.trim();
+	return t.length <= max ? t : `${t.slice(0, max).trimEnd()} …[+${t.length - max} chars]`;
+}
+
+export function clipMiddle(text: string, max: number, headShare = 0.6): string {
+	const t = text.trim();
+	if (t.length <= max) return t;
+	const head = Math.floor(max * headShare);
+	const tail = max - head;
+	return `${t.slice(0, head).trimEnd()} …[${t.length - max} chars omitted]… ${t.slice(t.length - tail).trimStart()}`;
+}
+
+/** Collapse skill bodies and attached files pi inlines into user messages. */
+export function stripInjected(text: string): string {
+	return text
+		.replace(/<skill\b[^>]*\bname="([^"]+)"[^>]*>[\s\S]*?<\/skill>/g, "[skill: $1]")
+		.replace(/<file\b[^>]*\bname="([^"]+)"[^>]*>[\s\S]*?<\/file>/g, "[file: $1]")
+		.trim();
+}
+
+export function summarizeCall(name: string, args: unknown): string {
+	const a = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
+	const s = (v: unknown) => (typeof v === "string" ? v : v === undefined ? "" : JSON.stringify(v));
+	switch (name) {
+		case "bash":
+			return `bash $ ${s(a.command)}`;
+		case "read":
+			return `read ${s(a.path)}${a.offset ? ` @${s(a.offset)}` : ""}${a.limit ? `+${s(a.limit)}` : ""}`;
+		case "edit":
+			return `edit ${s(a.path)} (${Array.isArray(a.edits) ? a.edits.length : 1} edit(s))`;
+		case "write":
+			return `write ${s(a.path)} (${typeof a.content === "string" ? a.content.length : 0} chars)`;
+		case "grep":
+		case "find":
+		case "ls":
+			return `${name} ${s(a.pattern)} ${s(a.path)}`.trim();
+		default:
+			return `${name} ${s(args)}`;
+	}
+}
+
+function toolResultText(m: Record<string, unknown>): string {
+	return textOf(m.content);
+}
+
+function msgModel(m: Record<string, unknown>): string | undefined {
+	return typeof m.provider === "string" && typeof m.model === "string" ? `${m.provider}/${m.model}` : undefined;
+}
+
+/** Note ids an entry shows as injected (our own `pi-dream` custom entries). */
+function injectedIds(e: RawEntry): string[] {
+	if (e.type !== "custom" || e.customType !== "pi-dream") return [];
+	const d = e.data as { event?: string; ids?: unknown } | undefined;
+	return d?.event === "inject" && Array.isArray(d.ids) ? d.ids.filter((x): x is string => typeof x === "string") : [];
+}
+
+export function buildDigest(s: ParsedSession): Digest {
+	const lines: DigestLine[] = [];
+	const models = new Set<string>();
+	const injected = new Set<string>();
+	const read = new Set<string>();
+	let userMessages = 0;
+	let toolCalls = 0;
+	let toolErrors = 0;
+	let ended: string | undefined;
+	const paths = new Map<string, number>();
+	const touch = (list: string[]) => {
+		for (const p of list) paths.set(p, (paths.get(p) ?? 0) + 1);
+	};
+	const push = (e: RawEntry, kind: LineKind, text: string) => {
+		const t = scrubSecrets(text).trim();
+		if (t) lines.push({ id: e.id, kind, text: t, ts: e.timestamp });
+	};
+
+	for (const e of s.branch) {
+		if (e.timestamp) ended = e.timestamp;
+		const ids = injectedIds(e);
+		if (ids.length) {
+			for (const id of ids) injected.add(id);
+			push(e, "MEMORY", `injected notes: ${ids.join(", ")}`);
+			continue;
+		}
+		if (e.type === "branch_summary" && typeof e.summary === "string") {
+			push(e, "SUMMARY", clipHead(e.summary, LIMITS.SUMMARY));
+			continue;
+		}
+		if (e.type === "custom_message") {
+			const ct = typeof e.customType === "string" ? e.customType : "custom";
+			push(e, "CUSTOM", `${ct}: ${clipHead(textOf(e.content), LIMITS.CUSTOM)}`);
+			continue;
+		}
+		if (e.type !== "message" || !e.message) continue;
+		const m = e.message;
+		switch (m.role) {
+			case "user": {
+				userMessages++;
+				push(e, "USER", clipMiddle(stripInjected(textOf(m.content)), LIMITS.USER));
+				break;
+			}
+			case "assistant": {
+				const model = msgModel(m);
+				if (model) models.add(model);
+				const blocks = Array.isArray(m.content) ? m.content : [];
+				for (const b of blocks) {
+					if (!b || typeof b !== "object") continue;
+					const blk = b as { type?: string; text?: string; name?: string; arguments?: unknown };
+					if (blk.type === "text" && blk.text?.trim()) push(e, "AI", clipMiddle(blk.text, LIMITS.AI));
+					else if (blk.type === "toolCall" && blk.name) {
+						toolCalls++;
+						if (blk.name === "memory_read") {
+							const ref = (blk.arguments as { ref?: unknown } | undefined)?.ref;
+							if (typeof ref === "string" && ref.startsWith("m-")) read.add(ref);
+						}
+						touch(callPaths(blk.name, blk.arguments, s.header.cwd));
+						push(e, "CALL", clipHead(summarizeCall(blk.name, blk.arguments), LIMITS.CALL));
+					}
+				}
+				break;
+			}
+			case "toolResult": {
+				const name = typeof m.toolName === "string" ? m.toolName : "tool";
+				const text = toolResultText(m);
+				if (m.isError) {
+					toolErrors++;
+					push(e, "ERROR", `${name}: ${clipMiddle(text, LIMITS.ERROR, 0.65)}`);
+				} else {
+					push(e, "RESULT", `${name}: ${clipHead(text, LIMITS.RESULT) || "(empty)"}`);
+				}
+				break;
+			}
+			case "bashExecution": {
+				const cmd = typeof m.command === "string" ? m.command : "";
+				const out = typeof m.output === "string" ? m.output : "";
+				touch(callPaths("bash", { command: cmd }, s.header.cwd));
+				push(e, "SHELL", `$ ${cmd} (exit ${String(m.exitCode ?? "?")})\n${clipMiddle(out, LIMITS.SHELL, 0.5)}`);
+				break;
+			}
+			case "custom": {
+				const ct = typeof m.customType === "string" ? m.customType : "custom";
+				push(e, "CUSTOM", `${ct}: ${clipHead(textOf(m.content), LIMITS.CUSTOM)}`);
+				break;
+			}
+			default:
+				break;
+		}
+	}
+
+	return {
+		meta: {
+			sessionId: s.header.id,
+			file: s.file,
+			cwd: s.header.cwd,
+			started: s.header.timestamp,
+			ended,
+			name: s.name,
+			models: [...models],
+			userMessages,
+			toolCalls,
+			toolErrors,
+			injected: [...injected],
+			read: [...read],
+			lastEntryId: s.lastEntryId,
+			paths: [...paths.entries()].sort((a, b) => b[1] - a[1]).slice(0, MAX_PATHS),
+		},
+		lines,
+	};
+}
+
+function renderLine(l: DigestLine): string {
+	const body = l.text.replace(/\n/g, "\n    ");
+	return `[${l.id}] ${l.kind}: ${body}`;
+}
+
+/** Shrinking passes applied in order until the digest fits. User lines survive longest. */
+const PASSES: Array<(l: DigestLine) => DigestLine | null> = [
+	(l) => (l.kind === "RESULT" ? { ...l, text: clipHead(l.text, 80) } : l),
+	(l) => (l.kind === "AI" ? { ...l, text: clipMiddle(l.text, 700) } : l),
+	(l) => (l.kind === "CALL" ? { ...l, text: clipHead(l.text, 160) } : l),
+	(l) => (l.kind === "ERROR" || l.kind === "SHELL" || l.kind === "CUSTOM" ? { ...l, text: clipHead(l.text, 240) } : l),
+	(l) => (l.kind === "RESULT" ? null : l),
+	(l) => (l.kind === "AI" ? { ...l, text: clipMiddle(l.text, 300) } : l),
+	(l) => (l.kind === "USER" ? { ...l, text: clipMiddle(l.text, 2000) } : l),
+];
+
+export function renderDigest(d: Digest, maxChars = Number.POSITIVE_INFINITY): string {
+	let lines = d.lines;
+	let text = lines.map(renderLine).join("\n");
+	for (const pass of PASSES) {
+		if (text.length <= maxChars) return text;
+		lines = lines.map(pass).filter((l): l is DigestLine => l !== null);
+		text = lines.map(renderLine).join("\n");
+	}
+	if (text.length <= maxChars) return text;
+	const head = Math.floor(maxChars * 0.4);
+	const tail = maxChars - head;
+	return `${text.slice(0, head)}\n[… ${text.length - maxChars} chars omitted …]\n${text.slice(text.length - tail)}`;
+}
+
+export function digestHeader(meta: DigestMeta, projectKey: string): string {
+	const parts = [
+		`session ${meta.sessionId}`,
+		`project ${projectKey}`,
+		`cwd ${meta.cwd}`,
+		`started ${meta.started}`,
+		meta.name ? `name "${meta.name}"` : "",
+		meta.models.length ? `models ${meta.models.join(", ")}` : "",
+		`user messages ${meta.userMessages}, tool calls ${meta.toolCalls}, tool errors ${meta.toolErrors}`,
+	];
+	return parts.filter(Boolean).join(" | ");
+}
+
+/** A full rendering of one raw entry, for evidence excerpts shown to the fact checker. */
+export function renderEntryFull(e: RawEntry, max = 4000): string {
+	const line = (kind: string, text: string) => `[${e.id}] ${kind}: ${scrubSecrets(text).trim()}`;
+	if (e.type === "branch_summary" && typeof e.summary === "string") return line("SUMMARY", clipHead(e.summary, max));
+	if (e.type === "custom_message") return line("CUSTOM", clipHead(textOf(e.content), max));
+	if (e.type !== "message" || !e.message) return line(e.type.toUpperCase(), "");
+	const m = e.message;
+	switch (m.role) {
+		case "user":
+			return line("USER", clipMiddle(stripInjected(textOf(m.content)), max));
+		case "assistant": {
+			const parts: string[] = [];
+			for (const b of Array.isArray(m.content) ? m.content : []) {
+				const blk = b as { type?: string; text?: string; name?: string; arguments?: unknown };
+				if (blk?.type === "text" && blk.text) parts.push(blk.text);
+				if (blk?.type === "toolCall" && blk.name) parts.push(`CALL ${clipHead(summarizeCall(blk.name, blk.arguments), 1500)}`);
+			}
+			return line("AI", clipMiddle(parts.join("\n"), max));
+		}
+		case "toolResult": {
+			const name = typeof m.toolName === "string" ? m.toolName : "tool";
+			return line(m.isError ? "ERROR" : "RESULT", `${name}: ${clipMiddle(textOf(m.content), Math.min(max, 2000), 0.7)}`);
+		}
+		case "bashExecution":
+			return line("SHELL", `$ ${String(m.command ?? "")}\n${clipMiddle(String(m.output ?? ""), Math.min(max, 2000), 0.5)}`);
+		default:
+			return line(String(m.role ?? "ENTRY").toUpperCase(), clipHead(textOf(m.content), max));
+	}
+}

package/gitops.ts

@@ -0,0 +1,69 @@
+/**
+ * Thin, timeout-bounded wrappers around `git` and `gh`.
+ *
+ * Background dreams must never hang on a prompt: git runs with
+ * `GIT_TERMINAL_PROMPT=0` and ssh in batch mode, gh with `GH_PROMPT_DISABLED`.
+ */
+
+import { execFile } from "node:child_process";
+
+export interface ExecResult {
+	code: number;
+	stdout: string;
+	stderr: string;
+}
+
+const ENV = {
+	GIT_TERMINAL_PROMPT: "0",
+	GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND ?? "ssh -o BatchMode=yes -o ConnectTimeout=20",
+	GH_PROMPT_DISABLED: "1",
+	GH_NO_UPDATE_NOTIFIER: "1",
+};
+
+export function run(cmd: string, args: string[], opts: { cwd?: string; timeoutMs?: number } = {}): Promise<ExecResult> {
+	return new Promise((resolve) => {
+		execFile(
+			cmd,
+			args,
+			{ cwd: opts.cwd, timeout: opts.timeoutMs ?? 60_000, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, ...ENV } },
+			(err, stdout, stderr) => {
+				const e = err as (NodeJS.ErrnoException & { code?: number | string; killed?: boolean }) | null;
+				const code = !e ? 0 : typeof e.code === "number" ? e.code : 1;
+				const extra = e && !String(stderr ?? "").trim() ? (e.killed ? "timed out" : e.message) : "";
+				resolve({ code, stdout: String(stdout ?? ""), stderr: `${String(stderr ?? "")}${extra}` });
+			},
+		);
+	});
+}
+
+export function git(cwd: string, args: string[], timeoutMs?: number): Promise<ExecResult> {
+	return run("git", ["-C", cwd, ...args], { timeoutMs });
+}
+
+/** Run git and return trimmed stdout; throws with stderr on failure. */
+export async function gitOk(cwd: string, args: string[], timeoutMs?: number): Promise<string> {
+	const r = await git(cwd, args, timeoutMs);
+	if (r.code !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr.trim() || `exit ${r.code}`}`);
+	return r.stdout.trim();
+}
+
+export function gh(args: string[], opts: { cwd?: string; timeoutMs?: number } = {}): Promise<ExecResult> {
+	return run("gh", args, opts);
+}
+
+export async function ghOk(args: string[], opts: { cwd?: string; timeoutMs?: number } = {}): Promise<string> {
+	const r = await gh(args, opts);
+	if (r.code !== 0) throw new Error(`gh ${args.slice(0, 3).join(" ")}: ${r.stderr.trim() || `exit ${r.code}`}`);
+	return r.stdout.trim();
+}
+
+export async function ghJson<T>(args: string[], opts: { cwd?: string; timeoutMs?: number } = {}): Promise<T> {
+	return JSON.parse(await ghOk(args, opts)) as T;
+}
+
+/** `owner/repo` for a GitHub remote URL, or undefined. */
+export function githubRepoOf(remoteUrl: string | undefined): string | undefined {
+	if (!remoteUrl) return undefined;
+	const m = /github\.com[:/]+([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(remoteUrl.trim());
+	return m ? `${m[1]}/${m[2]}` : undefined;
+}

package/inbox.ts

@@ -0,0 +1,56 @@
+/**
+ * The inbox: things an agent (memory_inbox) or the user (/remember) wants the
+ * next dream to consider. Append-only JSONL per day under `.local/inbox/`;
+ * items are never active memory by themselves — the dream reviews them like
+ * any other evidence and proposes notes in the pull request.
+ */
+
+import { randomBytes } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { memoryPaths, today } from "./layout.ts";
+
+export const INBOX_KINDS = ["preference", "procedure", "pitfall", "fact", "decision", "reference", "other"] as const;
+export type InboxKind = (typeof INBOX_KINDS)[number];
+
+export interface InboxItem {
+	id: string;
+	ts: string;
+	source: "agent" | "user";
+	text: string;
+	kind?: InboxKind;
+	scope?: "global" | "project";
+	cwd: string;
+	projectKey: string;
+	sessionId?: string;
+	sessionFile?: string;
+	/** Leaf entry of the session when the item was written. */
+	entryId?: string;
+}
+
+export function appendInbox(root: string, item: Omit<InboxItem, "id" | "ts">): InboxItem {
+	const dir = memoryPaths(root).inbox;
+	mkdirSync(dir, { recursive: true });
+	const full: InboxItem = { id: `i-${randomBytes(4).toString("hex")}`, ts: new Date().toISOString(), ...item };
+	appendFileSync(join(dir, `${today()}.jsonl`), `${JSON.stringify(full)}\n`, "utf-8");
+	return full;
+}
+
+export function readInbox(root: string): InboxItem[] {
+	const dir = memoryPaths(root).inbox;
+	if (!existsSync(dir)) return [];
+	const out: InboxItem[] = [];
+	for (const name of readdirSync(dir).sort()) {
+		if (!name.endsWith(".jsonl")) continue;
+		for (const line of readFileSync(join(dir, name), "utf-8").split("\n")) {
+			if (!line.trim()) continue;
+			try {
+				const item = JSON.parse(line) as InboxItem;
+				if (item?.id && typeof item.text === "string") out.push(item);
+			} catch {
+				// torn line: skip
+			}
+		}
+	}
+	return out;
+}

package/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @wierdbytes/pi-dream — offline memory consolidation ("dreaming") for pi.
+ *
+ * Wiring only: the in-session behaviour lives in `runtime.ts`, the dream in
+ * `pipeline.ts` (run by `runner.ts` in a headless pi process).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerCommands } from "./commands.ts";
+import { Runtime } from "./runtime.ts";
+import { registerTools } from "./tools.ts";
+
+export default function piDream(pi: ExtensionAPI) {
+	if (process.env.PI_DREAM_CHILD === "1") return;
+
+	pi.registerFlag("no-memory", {
+		description: "pi-dream: no memory injection and no memory tools in this run",
+		type: "boolean",
+		default: false,
+	});
+
+	const rt = new Runtime(pi);
+
+	pi.on("session_start", async (event, ctx) => rt.onSessionStart(event.reason, ctx));
+	pi.on("resources_discover", async (event) => ({ skillPaths: rt.active() ? await rt.resourcesFor(event.cwd) : [] }));
+	pi.on("before_agent_start", async (event, ctx) => {
+		const section = await rt.memorySection(ctx);
+		if (section) (event.systemPromptOptions.sections ??= {}).memory = section;
+	});
+
+	registerTools(pi, rt);
+	registerCommands(pi, rt);
+}

package/layout.ts

@@ -0,0 +1,99 @@
+/**
+ * Layout of the memory repository.
+ *
+ * ```
+ * <memoryDir>/                 git repo, `main` = approved memory
+ *   scopes/global/             loaded in every session on this machine
+ *     charter.md               what this memory is for (steers the dream)
+ *     MEMORY.md                generated index — the part injected into sessions
+ *     notes/<slug>.md          one note per file, YAML front matter + body
+ *     skills/<name>/SKILL.md   approved skills (exposed to pi)
+ *   scopes/projects/<key>/     same, for one project (git remote or path)
+ *   reports/<run>.md           one report per dream
+ *   prompts/<stage>.md         optional overrides of the dream prompts
+ *   .local/                    gitignored: inbox, digests, cards, state, logs
+ * ```
+ */
+
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+
+export const GLOBAL_SCOPE = "global";
+export const INDEX_FILE = "MEMORY.md";
+export const CHARTER_FILE = "charter.md";
+export const SCOPE_META_FILE = "scope.json";
+
+/** Directory-safe name for a project key (`github.com/o/r` → `github.com__o__r`). */
+export function keyToDir(key: string): string {
+	const raw = key.startsWith("local:") ? `local/${key.slice(6)}` : key;
+	let s = raw
+		.split("/")
+		.filter(Boolean)
+		.join("__")
+		.replace(/[^A-Za-z0-9._-]/g, "_");
+	if (s.length > 120) s = `${s.slice(0, 100)}__${createHash("sha256").update(key).digest("hex").slice(0, 8)}`;
+	return s || "_";
+}
+
+/** Scope id for a project key: `projects/<dir>`. */
+export function projectScope(key: string): string {
+	return `projects/${keyToDir(key)}`;
+}
+
+export function scopeDir(root: string, scope: string): string {
+	return join(root, "scopes", scope);
+}
+
+export interface MemoryPaths {
+	root: string;
+	scopes: string;
+	reports: string;
+	prompts: string;
+	local: string;
+	state: string;
+	lock: string;
+	notify: string;
+	inbox: string;
+	digests: string;
+	digestIndex: string;
+	cards: string;
+	runs: string;
+	logs: string;
+	worktrees: string;
+	sync: string;
+}
+
+export function memoryPaths(root: string): MemoryPaths {
+	const local = join(root, ".local");
+	return {
+		root,
+		scopes: join(root, "scopes"),
+		reports: join(root, "reports"),
+		prompts: join(root, "prompts"),
+		local,
+		state: join(local, "state.json"),
+		lock: join(local, "dream.lock"),
+		notify: join(local, "notified.json"),
+		inbox: join(local, "inbox"),
+		digests: join(local, "digests"),
+		digestIndex: join(local, "digests", "index.json"),
+		cards: join(local, "cards"),
+		runs: join(local, "runs"),
+		logs: join(local, "logs"),
+		worktrees: join(local, "worktrees"),
+		sync: join(local, "last-sync"),
+	};
+}
+
+/** Local calendar date `YYYY-MM-DD`. */
+export function today(d: Date = new Date()): string {
+	const p = (n: number) => String(n).padStart(2, "0");
+	return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+/** Sortable run id: `20261108-0415-a1b2`. */
+export function newRunId(d: Date = new Date()): string {
+	const p = (n: number) => String(n).padStart(2, "0");
+	const rand = Math.random().toString(16).slice(2, 6);
+	return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}-${rand}`;
+}