@shanepadgett/tau-agent 0.33.0 → 0.34.0

package/extensions/aside/panel.ts

@@ -0,0 +1,83 @@
+import { bindingHint, bindingsHint, ScrollableMarkdown, ToolPanel } from "@shanepadgett/tau-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	type KeybindingsManager,
+	truncateToWidth,
+	type TUI,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+
+const PREVIEW_LINES = 5;
+const PREVIEW_CHARACTERS = 2_000;
+
+export interface AsideResult {
+	question: string;
+	answer: string;
+	context: string;
+}
+
+export class AsideWidget implements Component {
+	private readonly panel: ToolPanel;
+
+	constructor(theme: Theme, question: string) {
+		this.panel = new ToolPanel(theme, {
+			title: "Aside · Thinking…",
+			body: {
+				render: (width) =>
+					wrapTextWithAnsi(theme.fg("muted", question.slice(0, PREVIEW_CHARACTERS)), width)
+						.slice(0, PREVIEW_LINES)
+						.map((line) => truncateToWidth(line, width, "")),
+				invalidate() {},
+			},
+			footer: { kind: "hints", hints: [] },
+			border: "horizontal",
+		});
+	}
+
+	render(width: number): string[] {
+		return this.panel.render(width);
+	}
+
+	invalidate(): void {
+		this.panel.invalidate();
+	}
+}
+
+export class AsideResultPanel implements Component {
+	private readonly panel: ToolPanel;
+	private readonly body: ScrollableMarkdown;
+
+	constructor(tui: TUI, theme: Theme, keys: KeybindingsManager, result: AsideResult, done: () => void) {
+		this.body = new ScrollableMarkdown(tui, result.answer, 8);
+		this.panel = new ToolPanel(theme, {
+			title: "Aside",
+			secondary: `${result.context} · ${result.question.slice(0, 240)}`,
+			body: this.body,
+			footer: {
+				kind: "hints",
+				hints: [
+					bindingsHint(["tui.select.up", "tui.select.down"], "scroll"),
+					bindingHint("tui.select.confirm", "close"),
+					bindingHint("tui.select.cancel", "close"),
+				],
+			},
+			border: "box",
+		});
+		this.handleInput = (data) => {
+			if (keys.matches(data, "tui.select.up")) this.body.scroll(-1);
+			else if (keys.matches(data, "tui.select.down")) this.body.scroll(1);
+			else if (keys.matches(data, "tui.select.confirm") || keys.matches(data, "tui.select.cancel")) done();
+		};
+	}
+
+	handleInput: (data: string) => void;
+
+	render(width: number): string[] {
+		return this.panel.render(width);
+	}
+
+	invalidate(): void {
+		this.panel.invalidate();
+	}
+}

package/extensions/branch/index.ts

@@ -14,7 +14,7 @@ const LIST_BRANCH_REFS_ARGS = [
 	"refs/remotes",
 ];
 
-export function normalizeBranchName(name: string): string {
+function normalizeBranchName(name: string): string {
 	return name
 		.toLowerCase()
 		.replace(/[^a-z0-9]+/g, "-")
@@ -108,38 +108,55 @@ async function loadBranchChoices(git: GitRunner, root: string): Promise<BranchCh
 	return parseBranchChoices(await git.run(LIST_BRANCH_REFS_ARGS, { cwd: root }));
 }
 
-function parseBranchChoices(output: string): BranchChoice[] {
-	const refs = output
+interface ParsedRef {
+	ref: string;
+	updatedAt: number;
+	current: boolean;
+	symbolic: boolean;
+}
+
+function parseRefLines(output: string): ParsedRef[] {
+	return output
 		.split("\n")
 		.filter(Boolean)
 		.map((line) => {
 			const [ref = "", seconds = "0", head = "", symref = ""] = line.split("\0");
 			return { ref, updatedAt: Number(seconds) * 1000, current: head.trim() === "*", symbolic: Boolean(symref) };
 		});
-	const localPrefix = "refs/heads/";
-	const remotePrefix = "refs/remotes/";
+}
+
+function localChoice(ref: ParsedRef): BranchChoice | undefined {
+	const name = ref.ref.slice("refs/heads/".length);
+	if (!name || ref.current) return undefined;
+	return { id: `local:${name}`, kind: "local", label: name, name, updatedAt: ref.updatedAt };
+}
+
+function remoteChoice(ref: ParsedRef, localNames: ReadonlySet<string>): BranchChoice | undefined {
+	if (ref.symbolic) return undefined;
+	const upstream = ref.ref.slice("refs/remotes/".length);
+	const separator = upstream.indexOf("/");
+	if (separator < 1) return undefined;
+	const name = upstream.slice(separator + 1);
+	if (!name || name === "HEAD" || localNames.has(name)) return undefined;
+	const label = localNames.has(upstream) ? `${upstream} (remote)` : upstream;
+	return { id: `remote:${upstream}`, kind: "remote", label, name, upstream, updatedAt: ref.updatedAt };
+}
+
+function parseBranchChoices(output: string): BranchChoice[] {
+	const refs = parseRefLines(output);
 	const localNames = new Set(
-		refs.filter(({ ref }) => ref.startsWith(localPrefix)).map(({ ref }) => ref.slice(localPrefix.length)),
+		refs.filter(({ ref }) => ref.startsWith("refs/heads/")).map(({ ref }) => ref.slice("refs/heads/".length)),
 	);
 	const choices: BranchChoice[] = [];
-
 	for (const ref of refs) {
-		if (ref.ref.startsWith(localPrefix)) {
-			const name = ref.ref.slice(localPrefix.length);
-			if (name && !ref.current)
-				choices.push({ id: `local:${name}`, kind: "local", label: name, name, updatedAt: ref.updatedAt });
+		if (ref.ref.startsWith("refs/heads/")) {
+			const choice = localChoice(ref);
+			if (choice) choices.push(choice);
 			continue;
 		}
-		if (!ref.ref.startsWith(remotePrefix) || ref.symbolic) continue;
-
-		const upstream = ref.ref.slice(remotePrefix.length);
-		const separator = upstream.indexOf("/");
-		if (separator < 1) continue;
-		const name = upstream.slice(separator + 1);
-		if (!name || name === "HEAD" || localNames.has(name)) continue;
-		const label = localNames.has(upstream) ? `${upstream} (remote)` : upstream;
-		choices.push({ id: `remote:${upstream}`, kind: "remote", label, name, upstream, updatedAt: ref.updatedAt });
+		if (!ref.ref.startsWith("refs/remotes/")) continue;
+		const choice = remoteChoice(ref, localNames);
+		if (choice) choices.push(choice);
 	}
-
 	return choices.sort((left, right) => right.updatedAt - left.updatedAt || left.label.localeCompare(right.label));
 }

package/extensions/cache-diagnostics/index.ts

@@ -179,6 +179,72 @@ export default function cacheDiagnosticsExtension(pi: ExtensionAPI): void {
 		cacheActivitySeen = false;
 	};
 
+	const purgeExpiredFiles = async (): Promise<void> => {
+		const cutoff = Date.now() - RETENTION_MS;
+		for (const parent of [directory, reportsDirectory]) {
+			for (const entry of await readdir(parent, { withFileTypes: true })) {
+				if (
+					!entry.isFile() ||
+					(!entry.name.endsWith(".jsonl") && !entry.name.endsWith(".json") && !entry.name.endsWith(".tmp"))
+				)
+					continue;
+				const path = join(parent, entry.name);
+				if ((await stat(path)).mtimeMs < cutoff) await unlink(path);
+			}
+		}
+	};
+
+	const restoreRecordsFromLog = async (path: string): Promise<Array<Record<string, unknown>>> => {
+		const persisted = await readRecentLogRecords(path);
+		requests = keepRecent(
+			persisted
+				.filter((record) => record.kind === "request" && record.version === 2)
+				.map((record) => record as unknown as RequestRecord),
+		);
+		responses = keepRecent(
+			persisted
+				.filter((record) => record.kind === "response" && record.version === 2)
+				.map((record) => record as unknown as ResponseRecord),
+		);
+		results = keepRecent(
+			persisted
+				.filter((record) => record.kind === "result" && record.version === 2)
+				.map((record) => record as unknown as ResultRecord),
+		);
+		markers = keepRecent(
+			persisted
+				.filter((record) => record.kind === "marker" && record.version === 2)
+				.map((record) => record as unknown as MarkerRecord),
+		);
+		return persisted;
+	};
+
+	const restoreComparisonBaseline = (persisted: Array<Record<string, unknown>>): void => {
+		let latestModelSelectIndex = -1;
+		for (let index = persisted.length - 1; index >= 0; index -= 1) {
+			const record = persisted[index];
+			if (record?.kind !== "marker" || record.version !== 2 || record.name !== "model-select") continue;
+			latestModelSelectIndex = index;
+			break;
+		}
+		const comparisonResults = persisted
+			.slice(latestModelSelectIndex + 1)
+			.filter((record) => record.kind === "result" && record.version === 2)
+			.map((record) => record as unknown as ResultRecord);
+		const latestPromotedResult = [...comparisonResults].reverse().find((result) => result.baselinePromoted);
+		const latestRequest = latestPromotedResult
+			? requests.find((request) => request.id === latestPromotedResult.id)
+			: undefined;
+		if (!latestPromotedResult || !latestRequest) return;
+		previousFingerprint = payloadFingerprintFromRequest(latestRequest);
+		previousRequestId = latestRequest.id;
+		previousPromptState = latestRequest.promptState;
+		previousPromptTokens = latestPromotedResult.usage.promptTokens;
+		cacheActivitySeen = comparisonResults.some(
+			(result) => result.baselinePromoted && result.usage.cacheRead + result.usage.cacheWrite > 0,
+		);
+	};
+
 	pi.registerCommand("cache-debug", {
 		description: "Write a bounded prompt-cache diagnostic report for this session",
 		async handler(_args, ctx) {
@@ -246,63 +312,9 @@ export default function cacheDiagnosticsExtension(pi: ExtensionAPI): void {
 		resetComparison();
 		await mkdir(reportsDirectory, { recursive: true });
 		logFile = join(directory, `${sessionId.replaceAll(/[^a-zA-Z0-9_-]/g, "_")}.jsonl`);
-		const cutoff = Date.now() - RETENTION_MS;
-		for (const parent of [directory, reportsDirectory]) {
-			for (const entry of await readdir(parent, { withFileTypes: true })) {
-				if (
-					!entry.isFile() ||
-					(!entry.name.endsWith(".jsonl") && !entry.name.endsWith(".json") && !entry.name.endsWith(".tmp"))
-				)
-					continue;
-				const path = join(parent, entry.name);
-				if ((await stat(path)).mtimeMs < cutoff) await unlink(path);
-			}
-		}
-		const persisted = await readRecentLogRecords(logFile);
-		requests = keepRecent(
-			persisted
-				.filter((record) => record.kind === "request" && record.version === 2)
-				.map((record) => record as unknown as RequestRecord),
-		);
-		responses = keepRecent(
-			persisted
-				.filter((record) => record.kind === "response" && record.version === 2)
-				.map((record) => record as unknown as ResponseRecord),
-		);
-		results = keepRecent(
-			persisted
-				.filter((record) => record.kind === "result" && record.version === 2)
-				.map((record) => record as unknown as ResultRecord),
-		);
-		markers = keepRecent(
-			persisted
-				.filter((record) => record.kind === "marker" && record.version === 2)
-				.map((record) => record as unknown as MarkerRecord),
-		);
-		let latestModelSelectIndex = -1;
-		for (let index = persisted.length - 1; index >= 0; index -= 1) {
-			const record = persisted[index];
-			if (record?.kind !== "marker" || record.version !== 2 || record.name !== "model-select") continue;
-			latestModelSelectIndex = index;
-			break;
-		}
-		const comparisonRecords = persisted.slice(latestModelSelectIndex + 1);
-		const comparisonResults = comparisonRecords
-			.filter((record) => record.kind === "result" && record.version === 2)
-			.map((record) => record as unknown as ResultRecord);
-		const latestPromotedResult = [...comparisonResults].reverse().find((result) => result.baselinePromoted);
-		const latestRequest = latestPromotedResult
-			? requests.find((request) => request.id === latestPromotedResult.id)
-			: undefined;
-		if (latestPromotedResult && latestRequest) {
-			previousFingerprint = payloadFingerprintFromRequest(latestRequest);
-			previousRequestId = latestRequest.id;
-			previousPromptState = latestRequest.promptState;
-			previousPromptTokens = latestPromotedResult.usage.promptTokens;
-			cacheActivitySeen = comparisonResults.some(
-				(result) => result.baselinePromoted && result.usage.cacheRead + result.usage.cacheWrite > 0,
-			);
-		}
+		await purgeExpiredFiles();
+		const persisted = await restoreRecordsFromLog(logFile);
+		restoreComparisonBaseline(persisted);
 		await appendRecord({
 			kind: "runtime",
 			version: 2,
@@ -471,7 +483,7 @@ export default function cacheDiagnosticsExtension(pi: ExtensionAPI): void {
 	);
 	pi.on("session_tree", () => addMarker("session-tree"));
 	pi.on("tool_execution_end", (event) => {
-		if (event.toolName !== "working_memory" && event.toolName !== "load_tools") return;
+		if (event.toolName !== "checkpoint" && event.toolName !== "load_tools") return;
 		return addMarker("cache-affecting-tool", { tool: event.toolName, isError: event.isError });
 	});
 }

package/extensions/checkpoint/README.md

@@ -0,0 +1,9 @@
+# Checkpoint
+
+Keeps long-running agent work focused by letting the agent checkpoint durable working context while disposable conversation history is retired. The agent writes a short resume directive that is appended to the hidden continuation message after each checkpoint.
+
+Checkpoint rows are hidden by default. Set `extensions.checkpoint.showToolRows` to `true` before `/reload` to watch checkpoint and newly injected-file rows while working. Existing injected-file rows keep their saved display state.
+
+Checkpoint nudges the agent at 50% and 75% of `extensions.checkpoint.checkpointTokenLimit`, which defaults to 150,000 context tokens. At the limit, it blocks non-checkpoint tools until the agent checkpoints.
+
+After changing this extension, run `/reload` before testing it.

package/extensions/checkpoint/checkpoint-budget.ts

@@ -0,0 +1,79 @@
+export const DEFAULT_CHECKPOINT_TOKEN_LIMIT = 150_000;
+
+export type CheckpointBudgetLevel = 0 | 50 | 75 | 100;
+export type CheckpointBudgetNoticeLevel = Exclude<CheckpointBudgetLevel, 0>;
+
+export interface CheckpointBudget {
+	configure(limit: number): void;
+	beginTurn(tokens: number | null): CheckpointBudgetNoticeLevel | undefined;
+	finishTurn(tokens: number | null): CheckpointBudgetNoticeLevel | undefined;
+	shouldBlockTool(toolName: string, checkpointToolName: string): boolean;
+	reset(): void;
+}
+
+export function createCheckpointBudget(initialLimit = DEFAULT_CHECKPOINT_TOKEN_LIMIT): CheckpointBudget {
+	let limit = validateLimit(initialLimit);
+	let highestNoticed: CheckpointBudgetLevel = 0;
+	let forced = false;
+	let baselineTokens: number | null = 0;
+
+	return {
+		configure(nextLimit: number): void {
+			limit = validateLimit(nextLimit);
+			highestNoticed = 0;
+			forced = false;
+			baselineTokens = 0;
+		},
+
+		beginTurn(tokens: number | null): CheckpointBudgetNoticeLevel | undefined {
+			return observe(tokens);
+		},
+
+		finishTurn(tokens: number | null): CheckpointBudgetNoticeLevel | undefined {
+			return observe(tokens);
+		},
+
+		shouldBlockTool(toolName: string, checkpointToolName: string): boolean {
+			return forced && toolName !== checkpointToolName;
+		},
+
+		reset(): void {
+			highestNoticed = 0;
+			forced = false;
+			baselineTokens = null;
+		},
+	};
+
+	function observe(tokens: number | null): CheckpointBudgetNoticeLevel | undefined {
+		if (tokens === null) return undefined;
+		if (baselineTokens === null) {
+			baselineTokens = tokens;
+			return undefined;
+		}
+		if (tokens < baselineTokens) {
+			baselineTokens = tokens;
+			highestNoticed = 0;
+			forced = false;
+			return undefined;
+		}
+		const level = levelFor(tokens - baselineTokens, limit);
+		if (level === 100) forced = true;
+		if (level <= highestNoticed) return undefined;
+		highestNoticed = level;
+		return level === 0 ? undefined : level;
+	}
+}
+
+function levelFor(tokens: number, limit: number): CheckpointBudgetLevel {
+	if (tokens >= limit) return 100;
+	if (tokens >= limit * 0.75) return 75;
+	if (tokens >= limit * 0.5) return 50;
+	return 0;
+}
+
+function validateLimit(limit: number): number {
+	if (!Number.isSafeInteger(limit) || limit <= 0) {
+		throw new Error("Checkpoint token limit must be a positive safe integer");
+	}
+	return limit;
+}

package/extensions/checkpoint/checkpoint.ts

@@ -0,0 +1,277 @@
+import {
+	defineTool,
+	keyText,
+	type ExtensionAPI,
+	type SessionEntry,
+	type SessionMessageEntry,
+	type Theme,
+} from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, type Component, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { Type, type Static } from "typebox";
+import { prepareFileInjection } from "@shanepadgett/tau-agent";
+import { areCheckpointRowsVisible } from "../../shared/checkpoint-visibility.ts";
+import type { FileInjectionFile } from "../../src/file-injection/index.ts";
+import { extractConversationText } from "./messages.ts";
+import { formatCheckpointMessage } from "./prompt.ts";
+
+export const CHECKPOINT_TOOL = "checkpoint";
+const CONTINUATION_TYPE = "tau.checkpoint";
+const CONTINUATION_PREAMBLE =
+	"Continue directly from the checkpoint state and provided files. Trust the provided sources and continue the listed work.";
+const CHECKPOINT_PREVIEW_CHARACTERS = 240;
+const CHECKPOINT_RENDER_CHARACTERS = 24_000;
+const CHECKPOINT_RENDER_LINES = 200;
+const CONVERSATION_MESSAGE_ID_ATTRIBUTE = /^(<(?:user|assistant)-message)\s+id="(?:\\.|[^"\\])*">$/gm;
+
+const lineRange = Type.Object(
+	{
+		startLine: Type.Integer({ minimum: 1 }),
+		endLine: Type.Integer({ minimum: 1 }),
+	},
+	{ additionalProperties: false },
+);
+
+const checkpointFile = Type.Union([
+	Type.Object(
+		{
+			path: Type.String({ minLength: 1 }),
+			mode: Type.Literal("read"),
+			ranges: Type.Optional(Type.Array(lineRange)),
+		},
+		{ additionalProperties: false },
+	),
+	Type.Object(
+		{
+			path: Type.String({ minLength: 1 }),
+			mode: Type.Literal("outline"),
+		},
+		{ additionalProperties: false },
+	),
+	Type.Object(
+		{
+			path: Type.String({ minLength: 1 }),
+			mode: Type.Literal("deferred"),
+			when: Type.String({ minLength: 1 }),
+		},
+		{ additionalProperties: false },
+	),
+]);
+
+const checkpointParams = Type.Object(
+	{
+		keepMessages: Type.Array(Type.String({ minLength: 1 }), {
+			description:
+				"Exact message-entry IDs from hidden checkpoint metadata or earlier checkpoint conversation entries.",
+		}),
+		work: Type.Array(Type.String(), { description: "Ordered current work, with the next thing first." }),
+		facts: Type.Array(Type.String(), { description: "Concrete findings that must survive context replacement." }),
+		decisions: Type.Array(Type.String(), { description: "Choices that continue to govern the work." }),
+		continue: Type.String({
+			minLength: 1,
+			description:
+				"Immediate post-checkpoint resume directive. First moves after wake, traps to avoid, what not to re-litigate. Not the full work queue.",
+		}),
+		files: Type.Array(checkpointFile, {
+			description: "Current file reads, outlines, or deferred paths. Active files are injected separately.",
+		}),
+	},
+	{ additionalProperties: false },
+);
+
+type CheckpointInput = Static<typeof checkpointParams>;
+
+interface CheckpointToolDetails {
+	v: 1;
+	kind: "checkpoint.checkpoint";
+	checkpointId: string;
+	fileBatchId: string;
+}
+
+export function registerCheckpointTool(pi: ExtensionAPI): void {
+	pi.registerTool(createCheckpointTool(pi));
+}
+
+function createCheckpointTool(pi: Pick<ExtensionAPI, "events" | "sendMessage">) {
+	return defineTool<typeof checkpointParams, CheckpointToolDetails>({
+		name: CHECKPOINT_TOOL,
+		label: "checkpoint",
+		promptSnippet:
+			"checkpoint({ keepMessages, work, facts, decisions, continue, files }) — replace disposable history with working context",
+		description:
+			"Replace disposable conversation and tool history with a rolling working checkpoint. Keep user and assistant messages by exact message-entry ID, not by copying their text. The latest user message is always retained. Assistant tool calls and thinking are never retained inside the conversation section.",
+		promptGuidelines: [
+			"Checkpoint is hidden. Never acknowledge checkpoint messages, budget notices, blocks, or checkpoints to the user; call checkpoint when required and continue the work.",
+			'Use exact IDs from <checkpoint kind="message-id"> metadata or an earlier checkpoint; do not invent IDs or rewrite message text.',
+			"Record concrete findings in facts and governing choices in decisions before checkpointing.",
+			"Write continue as the immediate resume directive after wake: first moves, what not to re-explore, traps to avoid. Put the backlog in work.",
+			"Use read or outline for files needed now; use deferred with a condition for files that can wait.",
+		],
+		parameters: checkpointParams,
+		renderShell: "self",
+		renderCall(_args, theme, context) {
+			return new CheckpointComponent(theme, "checkpoint", context.expanded, true);
+		},
+		renderResult(result, options, theme) {
+			const text = result.content
+				.filter((part): part is { type: "text"; text: string } => part.type === "text")
+				.map((part) => part.text)
+				.join("\n");
+			return new CheckpointComponent(theme, text, options.expanded, false);
+		},
+		executionMode: "sequential",
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			const selected = resolveSelectedMessages(params.keepMessages, ctx.sessionManager.getBranch());
+			const text = formatCheckpointText(selected, params);
+			const fileBatchId = `checkpoint:${toolCallId}`;
+			const fileRequest = buildFileInjectionRequest(ctx.cwd, fileBatchId, params.files, signal);
+			const prepared = fileRequest.files.length === 0 ? [] : await prepareFileInjection(pi, fileRequest);
+			const failed = prepared.find((message) => message.details.status === "failed");
+			if (failed) {
+				throw new Error(
+					`Checkpoint file injection failed for ${failed.details.path}: ${failed.details.error ?? "unknown error"}`,
+				);
+			}
+			const display = areCheckpointRowsVisible();
+			for (const message of prepared) pi.sendMessage({ ...message, display });
+			pi.sendMessage({
+				customType: CONTINUATION_TYPE,
+				content: formatContinuationMessage(params.continue),
+				display: false,
+				details: {
+					v: 1,
+					kind: "checkpoint.continuation",
+					source: "checkpoint",
+					batchId: fileBatchId,
+				},
+			});
+			return {
+				content: [{ type: "text", text }],
+				details: { v: 1, kind: "checkpoint.checkpoint", checkpointId: toolCallId, fileBatchId },
+			};
+		},
+	});
+}
+
+class CheckpointComponent implements Component {
+	private readonly theme: Theme;
+	private readonly content: string;
+	private readonly expanded: boolean;
+	private readonly call: boolean;
+
+	constructor(theme: Theme, content: string, expanded: boolean, call: boolean) {
+		this.theme = theme;
+		this.content = content;
+		this.expanded = expanded;
+		this.call = call;
+	}
+
+	render(width: number): string[] {
+		if (!areCheckpointRowsVisible()) return [];
+		if (this.call) return [truncateToWidth(this.theme.fg("toolTitle", this.theme.bold(CHECKPOINT_TOOL)), width, "…")];
+		const displayContent = this.content.replace(CONVERSATION_MESSAGE_ID_ATTRIBUTE, "$1>");
+		if (!this.expanded) {
+			const preview = displayContent.replace(/\s+/g, " ").trim().slice(0, CHECKPOINT_PREVIEW_CHARACTERS);
+			const suffix = displayContent.length > CHECKPOINT_PREVIEW_CHARACTERS ? "…" : "";
+			return [
+				truncateToWidth(
+					`${this.theme.fg("dim", preview + suffix)} ${this.theme.fg("muted", `(${keyText("app.tools.expand")} to expand)`)}`,
+					width,
+					"…",
+				),
+			];
+		}
+
+		const bounded =
+			displayContent.length > CHECKPOINT_RENDER_CHARACTERS
+				? `${displayContent.slice(0, CHECKPOINT_RENDER_CHARACTERS)}\n…`
+				: displayContent;
+		return wrapTextWithAnsi(this.theme.fg("dim", bounded), Math.max(1, width))
+			.slice(0, CHECKPOINT_RENDER_LINES)
+			.map((line) => truncateToWidth(line, width, "…"));
+	}
+
+	invalidate(): void {}
+}
+
+function resolveSelectedMessages(ids: readonly string[], branch: readonly SessionEntry[]): SessionMessageEntry[] {
+	const entriesById = new Map(branch.map((entry) => [entry.id, entry]));
+	const selectedIds = new Set(ids);
+	const latestUser = [...branch].reverse().find(isUserMessageEntry);
+	if (!latestUser) throw new Error("Checkpoint requires a current user message");
+	selectedIds.add(latestUser.id);
+
+	for (const id of selectedIds) {
+		const entry = entriesById.get(id);
+		if (!entry || !isConversationEntry(entry)) throw new Error(`Unknown user or assistant message ID: ${id}`);
+		if (entry.message.role === "assistant" && extractConversationText(entry.message) === "") {
+			throw new Error(`Assistant message ID has no text content: ${id}`);
+		}
+	}
+
+	return branch.filter(
+		(entry): entry is SessionMessageEntry => selectedIds.has(entry.id) && isConversationEntry(entry),
+	);
+}
+
+function formatCheckpointText(selected: readonly SessionMessageEntry[], params: CheckpointInput): string {
+	const conversation = selected
+		.map((entry) => {
+			const text = extractConversationText(entry.message);
+			if (text === undefined) throw new Error(`Message ID is not a user or assistant message: ${entry.id}`);
+			const role = entry.message.role === "user" ? "user" : "assistant";
+			return `<${role}-message id=${JSON.stringify(entry.id)}>\n${text}\n</${role}-message>`;
+		})
+		.join("\n\n");
+	const deferred = params.files
+		.filter(
+			(file): file is Extract<CheckpointInput["files"][number], { mode: "deferred" }> => file.mode === "deferred",
+		)
+		.map((file) => `- ${file.path} — ${file.when}`);
+
+	return [
+		`Conversation:\n${conversation || "(none)"}`,
+		`Work:\n${formatList(params.work)}`,
+		`Facts:\n${formatList(params.facts)}`,
+		`Decisions:\n${formatList(params.decisions)}`,
+		`Continue:\n${params.continue}`,
+		`Deferred files:\n${deferred.length ? deferred.join("\n") : "(none)"}`,
+	].join("\n\n");
+}
+
+function formatContinuationMessage(continueNudge: string): string {
+	return formatCheckpointMessage("continuation", `${CONTINUATION_PREAMBLE}\n\n${continueNudge}`);
+}
+
+function buildFileInjectionRequest(
+	cwd: string,
+	batchId: string,
+	files: CheckpointInput["files"],
+	signal: AbortSignal | undefined,
+) {
+	const activeFiles: FileInjectionFile[] = [];
+	for (const file of files) {
+		if (file.mode === "deferred") continue;
+		if (file.mode === "outline") {
+			activeFiles.push({ path: file.path, mode: "outline" });
+			continue;
+		}
+		activeFiles.push({
+			path: file.path,
+			mode: "full",
+			...(file.ranges === undefined ? {} : { ranges: file.ranges }),
+		});
+	}
+	return { cwd, source: "checkpoint", batchId, files: activeFiles, signal };
+}
+
+function formatList(items: readonly string[]): string {
+	return items.length ? items.map((item) => `- ${item}`).join("\n") : "(none)";
+}
+
+function isConversationEntry(entry: SessionEntry): entry is SessionMessageEntry {
+	return entry.type === "message" && (entry.message.role === "user" || entry.message.role === "assistant");
+}
+
+function isUserMessageEntry(entry: SessionEntry): entry is SessionMessageEntry {
+	return entry.type === "message" && entry.message.role === "user";
+}