@vanillagreen/pi-qol 1.4.3 → 1.5.0

package/README.md

@@ -58,6 +58,8 @@ Arguments support autocomplete.
 
 Open `/extensions:settings`; settings appear under the **QOL** tab. Names below match the labels shown there.
 
+Glyph style: each package exposes `glyphStyle` (`unicode` default, `ascii` for terminal-safe chrome). `@vanillagreen/pi-tool-renderer.globalGlyphStyleOverride=ascii` forces ASCII chrome across vstack Pi extensions while leaving tool/model/user content unchanged.
+
 ### Statusline
 
 | Setting | What it does |
@@ -107,6 +109,8 @@ Advanced: input cap, title length, output tokens, timeout, custom prompt templat
 | --- | --- |
 | Enable /context command | Register `/context`. |
 
+`/context` also estimates the serialized payload size of the messages that would be sent on the next request. When that payload crosses **Transcript-risk warn budget (chars)** a `Transcript risk` block appears below the compact buffer section even if token count is still under the context window — useful for catching large blob-shaped tool outputs that inflate the request long before token count alone would page anyone. If transcript-risk estimation itself errors, `/context` shows a sanitized error in the same block rather than silently hiding the warning.
+
 ### Session search
 
 | Setting | What it does |
@@ -154,7 +158,7 @@ Off by default. When enabled, non-interactive matches are blocked.
 | Setting | What it does |
 | --- | --- |
 | Custom compaction summaries | Use QOL summaries instead of Pi's default. |
-| Compaction model | Summarizer model. |
+| Compaction model | Summarizer model. Defaults to `current`, meaning Pi's active model; set a provider/model when you want a dedicated larger-context summarizer. |
 | Compaction detail profile | `concise`, `balanced`, or `exhaustive`. |
 | Include previous summary | Pass the previous summary for iterative continuity. |
 | Fallback to Pi default compaction | Run Pi's default compaction if QOL's fails. |
@@ -165,6 +169,27 @@ Off by default. When enabled, non-interactive matches are blocked.
 
 Idle thresholds (token threshold, idle delay, fixed token limit, percent limit) tune when idle compaction fires.
 
+### Long-session budget guard
+
+For autonomous/Flightdeck-style runs the agent never goes idle, so idle compaction may never fire and the transcript can grow until provider/buffer limits hit. The budget guard runs on `agent_end` (not idle) and starts a compaction immediately when context usage crosses a percent of the model window or an absolute token limit. It fires once per threshold crossing — repeated `agent_end` events above the same threshold do not retrigger it, and the crossing key resets on a successful compaction or on a transient compaction failure (so the next `agent_end` retries).
+
+| Setting | What it does | Default |
+| --- | --- | --- |
+| Long-session budget guard | Master toggle for the agent_end budget guard. | on |
+| Budget guard percent | Context-window percentage that fires the guard. `-1` disables percent-based firing. | `85` |
+| Budget guard token limit | Absolute tokens that fire the guard. `-1` uses percent only. | `-1` |
+| Chunked compaction input cap | Max serialized characters per summarization request. Long transcripts are chunked, summarized chunk-by-chunk, then tree-reduced — every model/remote request (chunk + every reduce pass) is bounded so the compaction call itself cannot exceed provider buffer limits. `0` disables chunking. | `240000` |
+| Write pre-compaction handoff artifact | Before compaction, write `~/.pi/agent/vstack/sessions/<session>/pi-qol/handoff/<timestamp>.json` plus a `latest.json` pointer containing previous summary, last task state, and referenced files/artifacts. Write failures surface as a QOL warning notification and a `handoffArtifactError` field in the compaction details. | on |
+| Transcript-risk warn budget (chars) | `/context` shows a warning when the serialized payload of messages-to-send exceeds this many characters, even if tokens are still below the context window. `0` disables. | `600000` |
+
+When the budget guard fires it injects a sentinel into the compaction request so the QOL bounded handler always runs — chunked summarizer + handoff artifact — even if **Custom compaction summaries** is off. Manual compactions (`/tree`, idle compaction, user-triggered) still only use the QOL handler when **Custom compaction summaries** is on; otherwise they fall through to Pi's default compaction with no handoff artifact and no chunking. If you want every compaction to use the QOL bounded path, turn **Custom compaction summaries** on.
+
+Recommended values for autonomous/Flightdeck runs:
+
+- Keep **Long-session budget guard** on. Lower **Budget guard percent** to `75` if your provider buffers are tight.
+- Optionally turn **Custom compaction summaries** on so user-initiated and idle compactions also use the QOL chunked summarizer + handoff artifact. (Budget-guard-triggered compactions always use them regardless of this setting.)
+- Lower **Chunked compaction input cap** to ~`120000` when the summarizer model has a small context window.
+
 ### Thinking
 
 | Setting | What it does |

package/extensions/qol/budget-guard-runtime.ts

@@ -0,0 +1,100 @@
+// Runtime dispatch for the agent_end budget guard. Owns the last-crossing
+// key and in-flight flag so the guard fires exactly once per threshold
+// crossing, validates ctx.compact before marking in-flight, and clears the
+// crossing key on failure so the next agent_end can retry.
+
+import { QOL_BUDGET_GUARD_SENTINEL, type BudgetTrigger } from "./budget-guard.js";
+
+export type GuardLevel = "info" | "warning" | "error";
+
+export interface GuardCompactOptions {
+	customInstructions?: string;
+	onComplete?: (...args: unknown[]) => void;
+	onError?: (error: Error) => void;
+}
+
+export interface GuardDispatchInput {
+	trigger: BudgetTrigger | undefined;
+	compact: ((options: GuardCompactOptions) => void) | undefined;
+	notify: (message: string, level: GuardLevel) => void;
+	staleCtx?: () => boolean;
+}
+
+export type DispatchOutcome =
+	| { kind: "ignored" }
+	| { kind: "no-trigger" }
+	| { kind: "dedup" }
+	| { kind: "in-flight" }
+	| { kind: "no-compact-fn" }
+	| { kind: "dispatched"; reason: string }
+	| { kind: "dispatch-threw"; reason: string; error: string }
+	| { kind: "complete" }
+	| { kind: "failed"; error: string };
+
+export class BudgetGuardDriver {
+	private lastKey: string | undefined;
+	private inFlight = false;
+
+	reset(): void {
+		this.lastKey = undefined;
+		this.inFlight = false;
+	}
+
+	/** Returns true if the next call to dispatch is allowed to fire. Visible for tests. */
+	get canFire(): boolean {
+		return !this.inFlight;
+	}
+
+	get currentKey(): string | undefined {
+		return this.lastKey;
+	}
+
+	noteSessionCompacted(): void {
+		// Successful compaction drops usage below the budget; let the next
+		// crossing re-fire.
+		this.lastKey = undefined;
+		this.inFlight = false;
+	}
+
+	dispatch(input: GuardDispatchInput): DispatchOutcome {
+		if (input.staleCtx?.()) return { kind: "ignored" };
+		if (this.inFlight) return { kind: "in-flight" };
+		const trigger = input.trigger;
+		if (!trigger) {
+			this.lastKey = undefined;
+			return { kind: "no-trigger" };
+		}
+		if (trigger.key === this.lastKey) return { kind: "dedup" };
+		if (typeof input.compact !== "function") {
+			input.notify(`QOL budget guard cannot fire: ctx.compact is unavailable (${trigger.reason}).`, "warning");
+			return { kind: "no-compact-fn" };
+		}
+		input.notify(`QOL budget guard starting compaction: ${trigger.reason}`, "info");
+		this.inFlight = true;
+		this.lastKey = trigger.key;
+		const instructions = `${QOL_BUDGET_GUARD_SENTINEL} QOL budget guard triggered at agent_end because ${trigger.reason}. Bound the summary input, preserve current task state, decisions, files, blockers, and next steps.`;
+		try {
+			input.compact({
+				customInstructions: instructions,
+				onComplete: () => {
+					this.inFlight = false;
+					input.notify("QOL budget guard compaction completed.", "info");
+				},
+				onError: (error: Error) => {
+					this.inFlight = false;
+					// Allow the next agent_end to retry rather than poisoning the
+					// crossing key after a transient failure.
+					this.lastKey = undefined;
+					input.notify(`QOL budget guard compaction failed: ${error.message}`, "error");
+				},
+			});
+			return { kind: "dispatched", reason: trigger.reason };
+		} catch (error) {
+			this.inFlight = false;
+			this.lastKey = undefined;
+			const message = error instanceof Error ? error.message : String(error);
+			input.notify(`QOL budget guard compaction failed to start: ${message}`, "error");
+			return { kind: "dispatch-threw", error: message, reason: trigger.reason };
+		}
+	}
+}

package/extensions/qol/budget-guard.ts

@@ -0,0 +1,317 @@
+// Pure helpers for the long-session compaction budget guard. Kept dependency-free
+// so the chunking + risk math can be unit-tested without pulling the pi-ai or
+// pi-coding-agent peer deps. The wiring into the qol extension (settings reads,
+// session manager, ctx.compact) lives in compaction.ts and qol.ts.
+
+export interface BudgetTriggerInput {
+	enabled: boolean;
+	tokens: number;
+	contextWindow?: number;
+	tokenLimit: number;
+	percentLimit: number;
+}
+
+export interface BudgetTrigger {
+	reason: string;
+	key: string;
+	tokens: number;
+	contextWindow?: number;
+	percent?: number;
+}
+
+export function computeBudgetTrigger(input: BudgetTriggerInput): BudgetTrigger | undefined {
+	if (!input.enabled) return undefined;
+	if (!Number.isFinite(input.tokens) || input.tokens <= 0) return undefined;
+	const tokenLimit = Math.floor(input.tokenLimit);
+	if (tokenLimit > 0 && input.tokens >= tokenLimit) {
+		const bucket = Math.floor(input.tokens / Math.max(1, tokenLimit));
+		return {
+			contextWindow: input.contextWindow,
+			key: `tokens:${tokenLimit}:${bucket}`,
+			percent: input.contextWindow ? (input.tokens / input.contextWindow) * 100 : undefined,
+			reason: `${input.tokens.toLocaleString()} tokens >= ${tokenLimit.toLocaleString()} budget token limit`,
+			tokens: input.tokens,
+		};
+	}
+	const percentLimit = input.percentLimit;
+	if (percentLimit > 0 && input.contextWindow) {
+		const percent = (input.tokens / input.contextWindow) * 100;
+		if (percent >= percentLimit) {
+			const bucket = Math.floor(percent / Math.max(1, percentLimit));
+			return {
+				contextWindow: input.contextWindow,
+				key: `percent:${percentLimit}:${bucket}`,
+				percent,
+				reason: `${percent.toFixed(1)}% context >= ${percentLimit}% budget guard`,
+				tokens: input.tokens,
+			};
+		}
+	}
+	return undefined;
+}
+
+export function chunkConversationText(text: string, maxChars: number): string[] {
+	if (maxChars <= 0 || text.length <= maxChars) return [text];
+	const chunks: string[] = [];
+	const breaks = /\n{2,}/g;
+	let cursor = 0;
+	while (cursor < text.length) {
+		const remaining = text.length - cursor;
+		if (remaining <= maxChars) {
+			chunks.push(text.slice(cursor));
+			break;
+		}
+		const slice = text.slice(cursor, cursor + maxChars);
+		breaks.lastIndex = 0;
+		let breakAt = -1;
+		let match: RegExpExecArray | null;
+		// Pick the latest paragraph break inside the slice so chunks land on
+		// message boundaries. The half-slice floor avoids degenerate tiny chunks
+		// when the only paragraph break is right at the start of the window.
+		while ((match = breaks.exec(slice)) !== null) {
+			if (match.index >= Math.floor(maxChars / 2)) breakAt = match.index + match[0].length;
+		}
+		const end = breakAt > 0 ? cursor + breakAt : cursor + maxChars;
+		chunks.push(text.slice(cursor, end));
+		cursor = end;
+	}
+	return chunks;
+}
+
+export interface TranscriptRiskInput {
+	chars: number;
+	threshold: number;
+	messageCount: number;
+	error?: string;
+}
+
+export interface TranscriptRiskResult extends TranscriptRiskInput {
+	exceeded: boolean;
+}
+
+export function evaluateTranscriptRisk(input: TranscriptRiskInput): TranscriptRiskResult {
+	if (input.error) {
+		return { chars: 0, error: input.error, exceeded: false, messageCount: input.messageCount, threshold: input.threshold };
+	}
+	if (input.threshold <= 0 || input.messageCount <= 0 || input.chars <= 0) {
+		return { chars: input.chars, exceeded: false, messageCount: input.messageCount, threshold: input.threshold };
+	}
+	return {
+		chars: input.chars,
+		exceeded: input.chars >= input.threshold,
+		messageCount: input.messageCount,
+		threshold: input.threshold,
+	};
+}
+
+/**
+ * Sentinel marker injected into customInstructions when budget guard triggers
+ * a compaction. Detected by handleQolCompaction to force the bounded QOL path
+ * + handoff artifact write regardless of the global compaction.customEnabled
+ * setting.
+ */
+export const QOL_BUDGET_GUARD_SENTINEL = "[QOL_BUDGET_GUARD]";
+
+export function isBudgetGuardCompaction(customInstructions: unknown): boolean {
+	return typeof customInstructions === "string" && customInstructions.includes(QOL_BUDGET_GUARD_SENTINEL);
+}
+
+export interface SummarizeRequest {
+	text: string;
+	customInstructions?: string;
+	previousSummary?: string;
+	skipChunking: true;
+}
+
+export interface SummarizeOutcome {
+	model: string;
+	summary: string;
+	via: "model" | "remote";
+}
+
+export type SummarizeFn = (request: SummarizeRequest) => Promise<SummarizeOutcome>;
+
+export interface OrchestrateChunkedOptions {
+	text: string;
+	summarize: SummarizeFn;
+	maxInputChars: number;
+	signal?: AbortSignal;
+	customInstructions?: string;
+	previousSummary?: string;
+	notify?: (message: string, level?: "info" | "warning" | "error") => void;
+}
+
+export interface OrchestrateChunkedResult extends SummarizeOutcome {
+	chunkCount: number;
+	reduceLevels: number;
+	requestCount: number;
+}
+
+function instructionsForChunk(custom: string | undefined, index: number, total: number): string {
+	const base = `This is chunk ${index + 1} of ${total} from a long conversation. Preserve all concrete files, commands, decisions, blockers, and current tasks visible in this chunk so a follow-up summary-of-summaries pass can stitch the timeline together.`;
+	return custom?.trim() ? `${custom.trim()}\n\n${base}` : base;
+}
+
+function instructionsForReduce(custom: string | undefined, level: number, count: number): string {
+	const base = `Tree-reduce level ${level}: merge the following ${count} chunk summaries (oldest first) into a single continuation summary. De-duplicate facts, keep exact files/commands/paths, preserve decisions, blockers, current tasks, and any artifact paths. If chunks contradict, prefer the most recent.`;
+	return custom?.trim() ? `${custom.trim()}\n\n${base}` : base;
+}
+
+function partition(items: string[], maxChars: number, separator: string, minBatch: number = 1): string[][] {
+	const groups: string[][] = [];
+	let current: string[] = [];
+	let currentLen = 0;
+	const sepLen = separator.length;
+	for (const item of items) {
+		const projected = current.length === 0 ? item.length : currentLen + sepLen + item.length;
+		if (current.length >= minBatch && projected > maxChars) {
+			groups.push(current);
+			current = [item];
+			currentLen = item.length;
+		} else {
+			current.push(item);
+			currentLen = projected;
+		}
+	}
+	if (current.length > 0) groups.push(current);
+	return groups;
+}
+
+/**
+ * Bounded chunk + tree-reduce orchestrator. Every summarize() request gets
+ * a text body that is guaranteed to be <= maxInputChars (the chunker enforces
+ * the cap for source chunks; partition enforces it for reduce batches). When
+ * a reduce batch contains a single partial that's already over cap the
+ * orchestrator hard-truncates rather than retrying forever.
+ */
+export async function orchestrateChunkedSummary(options: OrchestrateChunkedOptions): Promise<OrchestrateChunkedResult> {
+	const { customInstructions, maxInputChars, notify, previousSummary, signal, summarize, text } = options;
+	if (maxInputChars <= 0 || text.length <= maxInputChars) {
+		if (signal?.aborted) throw new Error("Compaction aborted");
+		const single = await summarize({
+			customInstructions,
+			previousSummary,
+			skipChunking: true,
+			text,
+		});
+		return { ...single, chunkCount: 1, reduceLevels: 0, requestCount: 1 };
+	}
+	const chunks = chunkConversationText(text, maxInputChars);
+	notify?.(`QOL chunked compaction: summarizing ${chunks.length} chunk(s) (input ${text.length.toLocaleString()} chars > ${maxInputChars.toLocaleString()} cap).`, "info");
+	let requestCount = 0;
+	const partials: string[] = [];
+	let lastVia: "model" | "remote" = "model";
+	let lastModel = "";
+	let previous = previousSummary;
+	for (let i = 0; i < chunks.length; i += 1) {
+		if (signal?.aborted) throw new Error("Compaction aborted");
+		const chunk = chunks[i] ?? "";
+		const partial = await summarize({
+			customInstructions: instructionsForChunk(customInstructions, i, chunks.length),
+			previousSummary: previous,
+			skipChunking: true,
+			text: chunk,
+		});
+		requestCount += 1;
+		if (!partial.summary.trim()) throw new Error(`Chunk ${i + 1}/${chunks.length} summary was empty`);
+		partials.push(`### Chunk ${i + 1}/${chunks.length}\n${partial.summary.trim()}`);
+		previous = partial.summary;
+		lastVia = partial.via;
+		lastModel = partial.model;
+	}
+
+	let level = partials;
+	let reduceLevels = 0;
+	const separator = "\n\n";
+	const MAX_REDUCE_LEVELS = 12;
+	while (true) {
+		const combined = level.join(separator);
+		if (combined.length <= maxInputChars) {
+			if (signal?.aborted) throw new Error("Compaction aborted");
+			const final = await summarize({
+				customInstructions: instructionsForReduce(customInstructions, reduceLevels + 1, level.length),
+				previousSummary,
+				skipChunking: true,
+				text: combined,
+			});
+			requestCount += 1;
+			if (!final.summary.trim()) throw new Error("Final reduce summary was empty");
+			return {
+				chunkCount: chunks.length,
+				model: final.model || lastModel,
+				reduceLevels: reduceLevels + 1,
+				requestCount,
+				summary: final.summary,
+				via: final.via || lastVia,
+			};
+		}
+		reduceLevels += 1;
+		if (reduceLevels > MAX_REDUCE_LEVELS) {
+			// Defensive: refuse to spin forever if a model keeps emitting
+			// summaries larger than the cap. Final summarize over the
+			// hard-truncated joined level returns a bounded answer.
+			const truncated = combined.slice(0, maxInputChars);
+			const final = await summarize({
+				customInstructions: instructionsForReduce(customInstructions, reduceLevels, level.length),
+				previousSummary,
+				skipChunking: true,
+				text: truncated,
+			});
+			requestCount += 1;
+			return {
+				chunkCount: chunks.length,
+				model: final.model || lastModel,
+				reduceLevels,
+				requestCount,
+				summary: final.summary,
+				via: final.via || lastVia,
+			};
+		}
+		// Force-pair: at level >1 every batch must contain >=2 items so we
+		// always make progress. The summarize() call gets a text that may
+		// exceed the cap when each partial is itself near-cap; truncate to
+		// cap so the request remains bounded.
+		const minBatch = 2;
+		const batches = partition(level, maxInputChars, separator, minBatch);
+		const nextLevel: string[] = [];
+		for (const batch of batches) {
+			if (signal?.aborted) throw new Error("Compaction aborted");
+			if (batch.length === 1) {
+				const only = batch[0] ?? "";
+				nextLevel.push(only.length > maxInputChars ? only.slice(0, maxInputChars) : only);
+				continue;
+			}
+			let batchText = batch.join(separator);
+			if (batchText.length > maxInputChars) batchText = batchText.slice(0, maxInputChars);
+			const summary = await summarize({
+				customInstructions: instructionsForReduce(customInstructions, reduceLevels, batch.length),
+				previousSummary,
+				skipChunking: true,
+				text: batchText,
+			});
+			requestCount += 1;
+			if (!summary.summary.trim()) throw new Error(`Tree-reduce level ${reduceLevels} batch summary was empty`);
+			nextLevel.push(summary.summary);
+			lastVia = summary.via;
+			lastModel = summary.model;
+		}
+		if (nextLevel.length === 0) throw new Error("Tree-reduce collapsed to empty level");
+		if (nextLevel.length >= level.length) {
+			// No progress this round — fall back to hard truncation on the next
+			// pass via the level-cap guard. This typically means the model is
+			// emitting near-cap summaries; the MAX_REDUCE_LEVELS guard above
+			// will eventually terminate the loop with a truncated final.
+		}
+		level = nextLevel;
+		if (level.length === 1 && level[0]!.length <= maxInputChars) {
+			return {
+				chunkCount: chunks.length,
+				model: lastModel,
+				reduceLevels,
+				requestCount,
+				summary: level[0]!,
+				via: lastVia,
+			};
+		}
+	}
+}

package/extensions/qol/compaction-handoff.ts

@@ -0,0 +1,190 @@
+// Pre-compaction handoff artifact: writes a JSON snapshot of the previous
+// summary, the most recent task panel state, and recently referenced file
+// paths so an operator can recover continuity if the compaction summary
+// drops something critical. The pure data-building + write logic lives here
+// so it can be unit-tested without the pi-coding-agent / pi-ai peer deps.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+
+import { QOL_BUDGET_HANDOFF_FOLDER, QOL_BUDGET_HANDOFF_LATEST } from "./constants.js";
+
+export interface QolBudgetHandoff {
+	reason: string;
+	timestamp: number;
+	sessionId: string;
+	tokensBefore?: number;
+	messageCount: number;
+	previousSummary?: string;
+	taskState?: unknown;
+	artifactRefs: string[];
+	model?: string;
+}
+
+function expandHome(input: string): string {
+	if (input === "~") return homedir();
+	if (input.startsWith("~/")) return join(homedir(), input.slice(2));
+	return input;
+}
+
+export function piUserDir(): string {
+	return resolve(expandHome(process.env.PI_CODING_AGENT_DIR?.trim() || "~/.pi/agent"));
+}
+
+export function safeFileName(value: string): string {
+	return value.replace(/[^\w.-]+/g, "_");
+}
+
+export interface HandoffSessionAccessor {
+	getSessionId?: () => string | undefined;
+	getSessionFile?: () => string | undefined;
+	getBranch?: () => unknown[];
+}
+
+export function sessionIdFromManager(sm: HandoffSessionAccessor, fallbackPid: number = process.pid): string {
+	try {
+		const id = typeof sm.getSessionId === "function" ? sm.getSessionId() : undefined;
+		if (typeof id === "string" && id.trim()) return id;
+	} catch {
+		// Stale ctx may throw; fall through to file/pid.
+	}
+	try {
+		const file = typeof sm.getSessionFile === "function" ? sm.getSessionFile() : undefined;
+		if (typeof file === "string" && file.trim()) return basename(file, ".jsonl");
+	} catch {
+		// Same: fall through.
+	}
+	return `ephemeral-${fallbackPid}`;
+}
+
+/**
+ * Walks the branch newest-first and returns the most recent task panel state
+ * embedded in a tool result. Returns undefined when no task state is found.
+ */
+export function findLatestTaskState(branch: unknown[]): unknown {
+	for (let i = branch.length - 1; i >= 0; i -= 1) {
+		const entry = branch[i] as any;
+		if (entry?.type !== "message" || entry.message?.role !== "toolResult") continue;
+		const content = entry.message.content;
+		const parts = Array.isArray(content) ? content : [];
+		for (const part of parts) {
+			if (part?.type !== "toolResult") continue;
+			const details = part?.details;
+			if (details && typeof details === "object" && "state" in (details as Record<string, unknown>)) {
+				return (details as Record<string, unknown>).state;
+			}
+		}
+	}
+	return undefined;
+}
+
+const ARTIFACT_REF_PATTERN = /(?:^|\s|["'`(\[<])((?:\.{1,2}\/|\/|~\/)?[\w.\-+@/]+\.(?:md|json|jsonl|txt|log|ts|tsx|js|jsx|rs|toml|yml|yaml|html|sh|fish|bash|py|go|java|cs|cpp|h|hpp|sql|csv|env|lock|patch|diff))/g;
+
+/**
+ * Collects up to `maxRefs` file path-shaped strings from message contents,
+ * walking newest-first. Used to give the handoff artifact a quick "if you
+ * are recovering, here are recent files" pointer list.
+ */
+export function collectArtifactRefs(branch: unknown[], maxRefs = 20): string[] {
+	const refs = new Set<string>();
+	for (let i = branch.length - 1; i >= 0 && refs.size < maxRefs; i -= 1) {
+		const entry = branch[i] as any;
+		if (entry?.type !== "message") continue;
+		const content = entry.message?.content;
+		const parts = Array.isArray(content) ? content : [];
+		for (const part of parts) {
+			const text = typeof part?.text === "string" ? part.text : typeof part?.thinking === "string" ? part.thinking : "";
+			if (!text) continue;
+			ARTIFACT_REF_PATTERN.lastIndex = 0;
+			let match: RegExpExecArray | null;
+			while ((match = ARTIFACT_REF_PATTERN.exec(text)) !== null && refs.size < maxRefs) {
+				if (match[1]) refs.add(match[1]);
+			}
+		}
+	}
+	return Array.from(refs);
+}
+
+export interface BuildHandoffInput {
+	reason: string;
+	sessionManager: HandoffSessionAccessor;
+	preparation?: {
+		messagesToSummarize?: unknown[];
+		turnPrefixMessages?: unknown[];
+		previousSummary?: string;
+		tokensBefore?: number;
+	};
+	timestamp?: number;
+}
+
+export function buildBudgetHandoff(input: BuildHandoffInput): QolBudgetHandoff {
+	const preparation = input.preparation ?? {};
+	const messageCount = (preparation.messagesToSummarize?.length ?? 0) + (preparation.turnPrefixMessages?.length ?? 0);
+	let branch: unknown[] = [];
+	try {
+		const raw = typeof input.sessionManager.getBranch === "function" ? input.sessionManager.getBranch() : [];
+		branch = Array.isArray(raw) ? raw : [];
+	} catch {
+		branch = [];
+	}
+	return {
+		artifactRefs: collectArtifactRefs(branch),
+		messageCount,
+		previousSummary: preparation.previousSummary,
+		reason: input.reason,
+		sessionId: sessionIdFromManager(input.sessionManager),
+		taskState: findLatestTaskState(branch),
+		timestamp: input.timestamp ?? Date.now(),
+		tokensBefore: typeof preparation.tokensBefore === "number" ? preparation.tokensBefore : undefined,
+	};
+}
+
+export interface HandoffWriteResult {
+	path?: string;
+	latestPath?: string;
+	error?: string;
+}
+
+export function handoffStampedPath(baseDir: string, timestamp: number): string {
+	return join(baseDir, `${new Date(timestamp).toISOString().replace(/[:.]/g, "-")}.json`);
+}
+
+export function handoffBaseDir(sessionId: string, root: string = piUserDir()): string {
+	return join(root, "vstack", "sessions", safeFileName(sessionId), QOL_BUDGET_HANDOFF_FOLDER);
+}
+
+export interface WriteHandoffOptions {
+	enabled: boolean;
+	root?: string;
+	/** Injection point so tests can stub fs without mocking node:fs. */
+	writer?: (path: string, payload: string) => void;
+	mkdir?: (path: string) => void;
+}
+
+function defaultMkdir(path: string): void {
+	mkdirSync(path, { recursive: true, mode: 0o700 });
+}
+
+function defaultWriter(path: string, payload: string): void {
+	writeFileSync(path, payload, { mode: 0o600 });
+}
+
+export function writeBudgetHandoffArtifact(handoff: QolBudgetHandoff, options: WriteHandoffOptions): HandoffWriteResult {
+	if (!options.enabled) return {};
+	const baseDir = handoffBaseDir(handoff.sessionId, options.root);
+	const stampedPath = handoffStampedPath(baseDir, handoff.timestamp);
+	const latestPath = join(dirname(baseDir), basename(baseDir), QOL_BUDGET_HANDOFF_LATEST);
+	const mkdir = options.mkdir ?? defaultMkdir;
+	const writer = options.writer ?? defaultWriter;
+	try {
+		mkdir(baseDir);
+		const payload = JSON.stringify(handoff, null, 2);
+		writer(stampedPath, payload);
+		writer(latestPath, payload);
+		return { latestPath, path: stampedPath };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { error: message };
+	}
+}