@roodriigoooo/pi-docket 0.4.0

package/extensions/checkpoint-lifecycle.ts

@@ -0,0 +1,195 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { createArtifactCatalog, buildReferenceList, type ArtifactCatalog } from "./artifact-catalog.js";
+import { showCheckpointSelector } from "./checkpoint-selector.js";
+import { createCheckpointStore, type CheckpointStore } from "./checkpoint-store.js";
+import { createCheckpointSummarizer, type CheckpointSummarizer } from "./checkpoint-summarizer.js";
+import { gitSnapshotLabel, readGitSnapshot } from "./git-context.js";
+import { loadConfig, type DocketConfig } from "./docket-config.js";
+import type { CheckpointCreateOptions } from "./docket-command-grammar.js";
+import type { Artifact, CheckpointIndexEntry, GitSnapshot } from "./types.js";
+
+export type CheckpointLifecycle = {
+	create(options: CheckpointCreateOptions): Promise<void>;
+};
+
+type NotifyLevel = "info" | "warning" | "error";
+
+type CheckpointLifecycleDeps = {
+	loadConfig?: (cwd: string) => Promise<DocketConfig>;
+	createCatalog?: (ctx: ExtensionCommandContext, config: DocketConfig) => ArtifactCatalog;
+	store?: CheckpointStore;
+	summarizer?: CheckpointSummarizer;
+	makeId?: () => string;
+	reviewMarkdown?: (markdown: string) => Promise<string | null>;
+	selectArtifactsForCheckpoint?: (artifacts: Artifact[], options: CheckpointCreateOptions) => Promise<Artifact[] | null> | Artifact[] | null;
+	notify?: (text: string, level: NotifyLevel) => void;
+};
+
+function makeCheckpointId(): string {
+	const d = new Date();
+	const stamp = d.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+	return stamp.replace("T", "-");
+}
+
+// Bundle-first checkpoint: a small deterministic orientation header. The artifact bundle
+// (.artifacts.json) is the spine; it is mounted at zero token cost on continue/load. This header
+// is all that enters a fresh session's context — never the artifact contents. Decisions and next
+// steps are human-authored (the note + the editor pass), not model-guessed. See ADR-0001.
+function buildOrientationHeader(
+	ctx: ExtensionCommandContext,
+	id: string,
+	note: string,
+	consumeOnUse: boolean,
+	artifacts: Artifact[],
+	references: string,
+	git?: GitSnapshot,
+): string {
+	const usage = ctx.getContextUsage();
+	const files = [...new Set(artifacts.filter((a) => a.kind === "file").map((a) => a.title.replace(/^(read|write|edit|grep|find|ls)\s+/, "")))];
+	const errors = artifacts.filter((a) => a.kind === "error");
+
+	const lines: string[] = [];
+	lines.push(`# Docket checkpoint ${id}`);
+	lines.push("");
+	lines.push("mode: handoff");
+	lines.push(`cwd: ${ctx.cwd}`);
+	lines.push(`created: ${new Date().toISOString()}`);
+	if (ctx.sessionManager.getSessionFile()) lines.push(`sourceSession: ${ctx.sessionManager.getSessionFile()}`);
+	const gitLabel = gitSnapshotLabel(git);
+	if (gitLabel) lines.push(`git: ${gitLabel}`);
+	if (usage && usage.tokens !== null) lines.push(`context: ~${usage.tokens.toLocaleString()} / ${usage.contextWindow.toLocaleString()} tokens`);
+	if (note) lines.push(`note: ${note}`);
+	if (consumeOnUse) lines.push("consumeOnUse: true");
+	lines.push("");
+	lines.push("## Resuming");
+	lines.push(note || "(state the goal you are resuming)");
+	lines.push("");
+	lines.push("## Decisions");
+	lines.push("<!-- decisions that constrain the continuation; state facts, not guesses -->");
+	lines.push("");
+	lines.push("## Next steps");
+	lines.push("<!-- concrete, ordered -->");
+	lines.push("");
+	lines.push("## Files touched or inspected");
+	lines.push(files.length ? files.map((f) => `- ${f}`).join("\n") : "- (none captured)");
+	lines.push("");
+	lines.push("## Errors to avoid repeating");
+	lines.push(errors.length ? errors.slice(0, 8).map((a) => `- ${a.title}: ${a.subtitle}`).join("\n") : "- (none captured)");
+	lines.push("");
+	lines.push("## Mounted artifacts");
+	lines.push("This checkpoint's artifacts are mounted at zero token cost. Read current file contents from disk; chip an artifact with `/docket ref <ref>` when you need its detail.");
+	lines.push("");
+	lines.push(references);
+	return lines.join("\n");
+}
+
+function defaultNotify(pi: ExtensionAPI, ctx: ExtensionCommandContext, text: string, level: NotifyLevel): void {
+	if (ctx.hasUI) ctx.ui.notify(text, level);
+	else pi.sendMessage({ customType: "docket", content: text, display: true, details: { kind: level === "error" ? "error" : "notice" } }, { triggerTurn: false });
+}
+
+export async function createCheckpointLifecycle(pi: ExtensionAPI, ctx: ExtensionCommandContext, deps: CheckpointLifecycleDeps = {}): Promise<CheckpointLifecycle> {
+	const config = await (deps.loadConfig ?? loadConfig)(ctx.cwd);
+	const catalog = deps.createCatalog ? deps.createCatalog(ctx, config) : createArtifactCatalog(ctx, config);
+	const store = deps.store ?? createCheckpointStore();
+	const summarizer = deps.summarizer ?? createCheckpointSummarizer();
+	const notify = deps.notify ?? ((text: string, level: NotifyLevel) => defaultNotify(pi, ctx, text, level));
+
+	const selectArtifacts = (): Artifact[] => {
+		return catalog.selectForCheckpoint(config.checkpointArtifacts);
+	};
+
+	const reviewArtifactSelection = async (artifacts: Artifact[], options: CheckpointCreateOptions): Promise<Artifact[] | null> => {
+		if (deps.selectArtifactsForCheckpoint) return deps.selectArtifactsForCheckpoint(artifacts, options);
+		if (!ctx.hasUI) return artifacts;
+		return showCheckpointSelector(ctx, artifacts, "handoff");
+	};
+
+	const draftMarkdown = async (id: string, options: CheckpointCreateOptions, artifacts: Artifact[], git?: GitSnapshot): Promise<string> => {
+		const header = buildOrientationHeader(ctx, id, options.note, options.consumeOnUse, artifacts, buildReferenceList(artifacts, ctx.cwd), git);
+		if (!options.summarize || !config.summarizer.enabled) return header;
+		if (ctx.hasUI) ctx.ui.notify("Docket summarizing checkpoint...", "info");
+		try {
+			return await summarizer.summarize({
+				id,
+				mode: "handoff",
+				note: options.note,
+				consumeOnUse: options.consumeOnUse,
+				cwd: ctx.cwd,
+				sourceSession: ctx.sessionManager.getSessionFile(),
+				git,
+				artifactsFile: store.artifactsFile(id),
+				payload: catalog.checkpointPayload(artifacts),
+				references: buildReferenceList(artifacts, ctx.cwd),
+				activeModel: ctx.model,
+				modelRegistry: ctx.modelRegistry,
+				config: config.summarizer,
+				overrides: { model: options.model, maxOutputTokens: options.maxOutputTokens },
+			});
+		} catch (err) {
+			notify(`Docket summarizer failed; using bundle header: ${String(err)}`, "warning");
+			return header;
+		}
+	};
+
+	const reviewMarkdown = async (markdown: string): Promise<string | null> => {
+		if (deps.reviewMarkdown) return deps.reviewMarkdown(markdown);
+		if (!ctx.hasUI) return markdown;
+		const edited = await ctx.ui.editor("Edit Docket checkpoint", markdown);
+		if (edited === undefined) return null;
+		return edited;
+	};
+
+	const persistCheckpoint = async (id: string, options: CheckpointCreateOptions, markdown: string, artifacts: Artifact[], git?: GitSnapshot): Promise<CheckpointIndexEntry> => {
+		return store.save({
+			id,
+			mode: "handoff",
+			markdown,
+			artifacts,
+			cwd: ctx.cwd,
+			sourceSession: ctx.sessionManager.getSessionFile(),
+			git,
+			note: options.note,
+			consumeOnUse: options.consumeOnUse,
+		});
+	};
+
+	const labelSession = (id: string, entry: CheckpointIndexEntry): void => {
+		pi.appendEntry("docket:checkpoint", entry);
+		const leaf = ctx.sessionManager.getLeafId();
+		if (leaf) pi.setLabel(leaf, `docket:${id}`);
+	};
+
+	return {
+		async create(options: CheckpointCreateOptions): Promise<void> {
+			const candidates = selectArtifacts();
+			if (candidates.length === 0) {
+				notify("Docket found no artifacts to checkpoint", "warning");
+				return;
+			}
+
+			const artifacts = await reviewArtifactSelection(candidates, options);
+			if (artifacts === null) {
+				notify("Docket checkpoint cancelled", "info");
+				return;
+			}
+			if (artifacts.length === 0) {
+				notify("Docket found no artifacts to checkpoint", "warning");
+				return;
+			}
+
+			const id = (deps.makeId ?? makeCheckpointId)();
+			const git = readGitSnapshot(ctx.cwd);
+			const draft = await draftMarkdown(id, options, artifacts, git);
+			const markdown = await reviewMarkdown(draft);
+			if (markdown === null) {
+				notify("Docket checkpoint cancelled", "info");
+				return;
+			}
+
+			const entry = await persistCheckpoint(id, options, markdown, artifacts, git);
+			labelSession(id, entry);
+			notify(`Docket checkpoint saved: ${id}${options.consumeOnUse ? " (once)" : ""}`, "info");
+		},
+	};
+}

package/extensions/checkpoint-selector.ts

@@ -0,0 +1,162 @@
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { Box, Key, Text, matchesKey, truncateToWidth, type Component, type TUI } from "@mariozechner/pi-tui";
+import type { Artifact, ArtifactKind, CheckpointMode } from "./types.js";
+
+export type CheckpointSelectionState = {
+	selected: number;
+	checked: boolean[];
+};
+
+export type CheckpointSelectionStats = {
+	total: number;
+	selected: number;
+	estimatedTokens: number;
+};
+
+function artifactChars(artifact: Artifact): number {
+	return artifact.title.length + artifact.subtitle.length + artifact.body.length;
+}
+
+export function initialCheckpointSelection(artifacts: Artifact[]): CheckpointSelectionState {
+	return { selected: 0, checked: artifacts.map(() => true) };
+}
+
+export function toggleCheckpointSelection(state: CheckpointSelectionState, index = state.selected): CheckpointSelectionState {
+	if (index < 0 || index >= state.checked.length) return state;
+	return { ...state, checked: state.checked.map((checked, i) => (i === index ? !checked : checked)) };
+}
+
+export function selectAllCheckpointArtifacts(state: CheckpointSelectionState): CheckpointSelectionState {
+	return { ...state, checked: state.checked.map(() => true) };
+}
+
+export function selectNoCheckpointArtifacts(state: CheckpointSelectionState): CheckpointSelectionState {
+	return { ...state, checked: state.checked.map(() => false) };
+}
+
+export function selectedCheckpointArtifacts(artifacts: Artifact[], state: CheckpointSelectionState): Artifact[] {
+	return artifacts.filter((_, index) => state.checked[index]);
+}
+
+export function checkpointSelectionStats(artifacts: Artifact[], state: CheckpointSelectionState): CheckpointSelectionStats {
+	const selected = selectedCheckpointArtifacts(artifacts, state);
+	return {
+		total: artifacts.length,
+		selected: selected.length,
+		estimatedTokens: Math.ceil(selected.reduce((sum, artifact) => sum + artifactChars(artifact), 0) / 4),
+	};
+}
+
+function clampSelected(selected: number, artifacts: Artifact[]): number {
+	return Math.min(Math.max(0, selected), Math.max(0, artifacts.length - 1));
+}
+
+function kindLabel(kind: ArtifactKind): string {
+	const labels: Record<ArtifactKind, string> = { command: "cmd", error: "err", file: "file", code: "code", prompt: "user", response: "ai", checkpoint: "ckpt" };
+	return labels[kind];
+}
+
+function colorKind(theme: any, kind: ArtifactKind, text: string): string {
+	if (kind === "error") return theme.fg("error", text);
+	if (kind === "command") return theme.fg("success", text);
+	if (kind === "file") return theme.fg("toolDiffAdded", text);
+	if (kind === "code") return theme.fg("warning", text);
+	if (kind === "checkpoint") return theme.fg("accent", text);
+	if (kind === "prompt") return theme.fg("customMessageLabel", text);
+	return theme.fg("muted", text);
+}
+
+class CheckpointSelectorView implements Component {
+	private state: CheckpointSelectionState;
+	private message = "";
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+
+	constructor(
+		private tui: TUI,
+		private theme: any,
+		private artifacts: Artifact[],
+		private mode: CheckpointMode,
+		private done: (result: Artifact[] | null) => void,
+	) {
+		this.state = initialCheckpointSelection(artifacts);
+	}
+
+	handleInput(data: string): void {
+		const selected = clampSelected(this.state.selected, this.artifacts);
+		this.state = selected === this.state.selected ? this.state : { ...this.state, selected };
+
+		if (matchesKey(data, Key.escape) || data === "q" || matchesKey(data, Key.ctrl("c"))) {
+			this.done(null);
+			return;
+		}
+		if (data === "j" || matchesKey(data, Key.down)) this.state = { ...this.state, selected: clampSelected(selected + 1, this.artifacts) };
+		else if (data === "k" || matchesKey(data, Key.up)) this.state = { ...this.state, selected: Math.max(0, selected - 1) };
+		else if (data === "g") this.state = { ...this.state, selected: 0 };
+		else if (data === "G") this.state = { ...this.state, selected: Math.max(0, this.artifacts.length - 1) };
+		else if (data === " ") this.state = toggleCheckpointSelection(this.state);
+		else if (data === "a") this.state = selectAllCheckpointArtifacts(this.state);
+		else if (data === "n") this.state = selectNoCheckpointArtifacts(this.state);
+		else if (matchesKey(data, Key.enter)) {
+			const selectedArtifacts = selectedCheckpointArtifacts(this.artifacts, this.state);
+			if (selectedArtifacts.length === 0) this.message = "select at least one artifact or q cancel";
+			else this.done(selectedArtifacts);
+			this.invalidate();
+			this.tui.requestRender();
+			return;
+		}
+		this.message = "";
+		this.invalidate();
+		this.tui.requestRender();
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+		const container = new Box(2, 1, (s) => this.theme.bg("customMessageBg", s));
+		const innerWidth = Math.max(20, width - 4);
+		const accent = (s: string) => this.theme.fg("accent", s);
+		const dim = (s: string) => this.theme.fg("dim", s);
+		const muted = (s: string) => this.theme.fg("muted", s);
+		const warning = (s: string) => this.theme.fg("warning", s);
+		const stats = checkpointSelectionStats(this.artifacts, this.state);
+		const header = `${accent(this.theme.bold("docket · checkpoint"))} ${dim(this.mode)} ${dim("·")} ${stats.selected}/${stats.total} selected ${dim("·")} ~${stats.estimatedTokens} tok`;
+		container.addChild(new Text(truncateToWidth(header, innerWidth - 2), 1, 0));
+
+		const windowSize = 14;
+		const selected = clampSelected(this.state.selected, this.artifacts);
+		const start = Math.max(0, Math.min(selected - Math.floor(windowSize / 2), this.artifacts.length - windowSize));
+		const visible = this.artifacts.slice(start, start + windowSize);
+		for (let i = 0; i < visible.length; i++) {
+			const artifact = visible[i]!;
+			const absolute = start + i;
+			const isSelected = absolute === selected;
+			const marker = isSelected ? accent("▸") : dim(" ");
+			const checked = this.state.checked[absolute] ? accent("[x]") : muted("[ ]");
+			const id = isSelected ? accent(this.theme.bold(artifact.displayId.padEnd(5))) : muted(artifact.displayId.padEnd(5));
+			const kind = colorKind(this.theme, artifact.kind, kindLabel(artifact.kind).padEnd(5));
+			const title = isSelected ? this.theme.bold(this.theme.fg("text", artifact.title)) : muted(artifact.title);
+			const line = `${marker} ${checked} ${id} ${kind} ${title} ${dim(artifact.subtitle)}`;
+			container.addChild(new Text(truncateToWidth(line, innerWidth - 2), 1, 0));
+		}
+		for (let i = visible.length; i < windowSize; i++) container.addChild(new Text("", 1, 0));
+
+		if (this.message) container.addChild(new Text(warning(this.message), 1, 0));
+		else container.addChild(new Text(dim("space toggle · a all · n none · enter create · q cancel"), 1, 0));
+
+		this.cachedLines = container.render(width);
+		this.cachedWidth = width;
+		return this.cachedLines;
+	}
+}
+
+export async function showCheckpointSelector(ctx: ExtensionCommandContext, artifacts: Artifact[], mode: CheckpointMode): Promise<Artifact[] | null> {
+	return ctx.ui.custom((tui, theme, _kb, done) => new CheckpointSelectorView(tui, theme, artifacts, mode, done), {
+		overlay: true,
+		overlayOptions: { anchor: "center", width: "88%", minWidth: 84, maxHeight: "90%", margin: 1 },
+	});
+}

package/extensions/checkpoint-store.ts

@@ -0,0 +1,230 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { createEventLog, type EventLog, replayEvents } from "./event-log.js";
+import type { Artifact, CheckpointIndexEntry, CheckpointMode, GitSnapshot } from "./types.js";
+
+type CheckpointSaveInput = {
+	id: string;
+	mode: CheckpointMode;
+	markdown: string;
+	artifacts: Artifact[];
+	cwd: string;
+	sourceSession?: string;
+	git?: GitSnapshot;
+	note?: string;
+	consumeOnUse?: boolean;
+};
+
+export type CheckpointSummary = {
+	entry: CheckpointIndexEntry;
+	artifactCount: number;
+	files: number;
+	errors: number;
+	commands: number;
+	estimatedTokens: number;
+};
+
+type ListOptions = { includeConsumed?: boolean };
+
+export type CheckpointStore = {
+	save(input: CheckpointSaveInput): Promise<CheckpointIndexEntry>;
+	find(idOrLast: string, options?: ListOptions): Promise<CheckpointIndexEntry | undefined>;
+	list(options?: ListOptions): Promise<CheckpointIndexEntry[]>;
+	listSummaries(options?: ListOptions): Promise<CheckpointSummary[]>;
+	readMarkdown(checkpoint: CheckpointIndexEntry): Promise<string>;
+	readArtifacts(checkpoint: CheckpointIndexEntry): Promise<Artifact[]>;
+	markConsumed(checkpoint: CheckpointIndexEntry, timestamp?: string): Promise<void>;
+	purge(checkpoint: CheckpointIndexEntry): Promise<void>;
+	sweepConsumed(retentionDays: number): Promise<number>;
+	artifactsFile(id: string): string;
+};
+
+function checkpointDir(): string {
+	return path.join(getAgentDir(), "docket", "checkpoints");
+}
+
+function checkpointIndexFile(): string {
+	return path.join(getAgentDir(), "docket", "index.json");
+}
+
+function checkpointMarkdownFile(id: string): string {
+	return path.join(checkpointDir(), `${id}.md`);
+}
+
+function checkpointArtifactsFile(id: string): string {
+	return path.join(checkpointDir(), `${id}.artifacts.json`);
+}
+
+async function readJsonFile<T>(file: string, fallback: T): Promise<T> {
+	try {
+		return JSON.parse(await fs.readFile(file, "utf8")) as T;
+	} catch {
+		return fallback;
+	}
+}
+
+async function fileExists(file: string): Promise<boolean> {
+	try {
+		await fs.access(file);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function writeFileAtomic(file: string, content: string): Promise<void> {
+	await fs.mkdir(path.dirname(file), { recursive: true });
+	const suffix = `${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+	const tempFile = path.join(path.dirname(file), `.${path.basename(file)}.${suffix}.tmp`);
+	try {
+		await fs.writeFile(tempFile, content, "utf8");
+		await fs.rename(tempFile, file);
+	} catch (err) {
+		await fs.rm(tempFile, { force: true });
+		throw err;
+	}
+}
+
+async function loadLegacyIndex(): Promise<CheckpointIndexEntry[]> {
+	return readJsonFile<CheckpointIndexEntry[]>(checkpointIndexFile(), []);
+}
+
+async function writeIndexSnapshot(entries: CheckpointIndexEntry[]): Promise<void> {
+	await writeFileAtomic(checkpointIndexFile(), `${JSON.stringify(entries, null, 2)}\n`);
+}
+
+async function existingMarkdownEntries(entries: CheckpointIndexEntry[]): Promise<CheckpointIndexEntry[]> {
+	const checks = await Promise.all(entries.map((entry) => fileExists(entry.file)));
+	return entries.filter((_, index) => checks[index]);
+}
+
+async function checkpointArtifacts(id: string): Promise<Artifact[]> {
+	return readJsonFile<Artifact[]>(checkpointArtifactsFile(id), []);
+}
+
+async function checkpointSummary(entry: CheckpointIndexEntry): Promise<CheckpointSummary> {
+	const [markdown, artifacts] = await Promise.all([
+		fs.readFile(entry.file, "utf8").catch(() => ""),
+		checkpointArtifacts(entry.id),
+	]);
+	const fileNames = new Set(artifacts.filter((artifact) => artifact.kind === "file").map((artifact) => artifact.title));
+	return {
+		entry,
+		artifactCount: artifacts.length,
+		files: fileNames.size,
+		errors: artifacts.filter((artifact) => artifact.kind === "error").length,
+		commands: artifacts.filter((artifact) => artifact.kind === "command").length,
+		estimatedTokens: Math.ceil(markdown.length / 4),
+	};
+}
+
+function applyConsumedFilter(entries: CheckpointIndexEntry[], options?: ListOptions): CheckpointIndexEntry[] {
+	if (options?.includeConsumed) return entries;
+	return entries.filter((entry) => !entry.consumedAt);
+}
+
+async function loadIndexFromEvents(log: EventLog): Promise<CheckpointIndexEntry[]> {
+	const events = await log.read();
+	if (events.length > 0) return replayEvents(events);
+	const legacy = await loadLegacyIndex();
+	if (legacy.length > 0) {
+		await log.backfillFromIndex(legacy);
+		return replayEvents(await log.read());
+	}
+	return [];
+}
+
+export function createCheckpointStore(): CheckpointStore {
+	const log = createEventLog();
+	return {
+		async save(input: CheckpointSaveInput): Promise<CheckpointIndexEntry> {
+			const file = checkpointMarkdownFile(input.id);
+			await writeFileAtomic(file, `${input.markdown.trim()}\n`);
+			await writeFileAtomic(checkpointArtifactsFile(input.id), `${JSON.stringify(input.artifacts, null, 2)}\n`);
+
+			const entry: CheckpointIndexEntry = {
+				id: input.id,
+				mode: input.mode,
+				file,
+				createdAt: new Date().toISOString(),
+				cwd: input.cwd,
+				sourceSession: input.sourceSession,
+				git: input.git,
+				note: input.note,
+				consumeOnUse: input.consumeOnUse,
+			};
+			await log.append({ type: "checkpoint_saved", timestamp: entry.createdAt, entry });
+			await writeIndexSnapshot(await loadIndexFromEvents(log));
+			return entry;
+		},
+
+		async find(idOrLast: string, options?: ListOptions): Promise<CheckpointIndexEntry | undefined> {
+			const index = await this.list(options);
+			if (index.length === 0) return undefined;
+			if (!idOrLast || idOrLast === "last") return index[index.length - 1];
+			return [...index].reverse().find((entry) => entry.id === idOrLast || entry.id.startsWith(idOrLast));
+		},
+
+		async list(options?: ListOptions): Promise<CheckpointIndexEntry[]> {
+			const present = await existingMarkdownEntries(await loadIndexFromEvents(log));
+			return applyConsumedFilter(present, options);
+		},
+
+		async listSummaries(options?: ListOptions): Promise<CheckpointSummary[]> {
+			return Promise.all((await this.list(options)).map((entry) => checkpointSummary(entry)));
+		},
+
+		async readMarkdown(checkpoint: CheckpointIndexEntry): Promise<string> {
+			return fs.readFile(checkpoint.file, "utf8");
+		},
+
+		async readArtifacts(checkpoint: CheckpointIndexEntry): Promise<Artifact[]> {
+			return checkpointArtifacts(checkpoint.id);
+		},
+
+		async markConsumed(checkpoint: CheckpointIndexEntry, timestamp?: string): Promise<void> {
+			const stamp = timestamp ?? new Date().toISOString();
+			const current = await loadIndexFromEvents(log);
+			const known = current.find((entry) => entry.id === checkpoint.id);
+			if (!known || known.consumedAt) return;
+			await log.append({ type: "checkpoint_consumed", timestamp: stamp, id: checkpoint.id, consumedAt: stamp });
+			await writeIndexSnapshot(await loadIndexFromEvents(log));
+		},
+
+		async purge(checkpoint: CheckpointIndexEntry): Promise<void> {
+			await log.append({ type: "checkpoint_purged", timestamp: new Date().toISOString(), id: checkpoint.id });
+			await writeIndexSnapshot(await loadIndexFromEvents(log));
+			await fs.rm(checkpoint.file, { force: true });
+			await fs.rm(checkpointArtifactsFile(checkpoint.id), { force: true });
+		},
+
+		async sweepConsumed(retentionDays: number): Promise<number> {
+			if (!Number.isFinite(retentionDays) || retentionDays < 0) return 0;
+			const current = await loadIndexFromEvents(log);
+			const cutoff = Date.now() - retentionDays * 86400000;
+			const expired: CheckpointIndexEntry[] = [];
+			for (const entry of current) {
+				const consumed = entry.consumedAt ? Date.parse(entry.consumedAt) : NaN;
+				if (Number.isFinite(consumed) && consumed <= cutoff) expired.push(entry);
+			}
+			if (expired.length === 0) return 0;
+			await log.append({
+				type: "checkpoint_swept",
+				timestamp: new Date().toISOString(),
+				ids: expired.map((entry) => entry.id),
+				retentionDays,
+			});
+			await writeIndexSnapshot(await loadIndexFromEvents(log));
+			await Promise.all(expired.flatMap((entry) => [
+				fs.rm(entry.file, { force: true }),
+				fs.rm(checkpointArtifactsFile(entry.id), { force: true }),
+			]));
+			return expired.length;
+		},
+
+		artifactsFile(id: string): string {
+			return checkpointArtifactsFile(id);
+		},
+	};
+}