@quantmind-br/pi-goal-x 0.0.0-stage → 0.35.0

package/extensions/goal-policy.ts

@@ -0,0 +1,370 @@
+import { statusLabel, type GoalDisplayRecordLike } from "./goal-core.ts";
+import type { GoalTask, GoalTaskList, TaskStatus } from "./goal-record.ts";
+import { countTaskSubtree } from "./goal-task-count.ts";
+
+export type GoalStatusLike = "active" | "paused" | "blocked" | "budget_limited" | "complete";
+export type StopReasonLike = "user" | "agent";
+
+export interface GoalPolicyRecordLike extends GoalDisplayRecordLike {
+	id: string;
+	status: GoalStatusLike;
+	updatedAt?: string;
+	pauseReason?: string;
+	pauseSuggestedAction?: string;
+	taskList?: GoalTaskList;
+}
+
+export type PolicyValidation =
+	| { ok: true }
+	| { ok: false; message: string };
+
+export function isRunnableStatus(status: GoalStatusLike): boolean {
+	return status === "active";
+}
+
+export function isCompletableStatus(status: GoalStatusLike): boolean {
+	// A budget-limited goal is NOT completed by the transition itself, but the
+	// user (or the model on explicit evidence) may still complete it. A blocked
+	// goal is the model's terminal surrender — resume or clear it instead.
+	return status === "active" || status === "paused" || status === "budget_limited";
+}
+
+export function validateGoalCompletion(args: {
+	goal: GoalPolicyRecordLike | null;
+	runningGoalId?: string | null;
+}): PolicyValidation {
+	const { goal, runningGoalId } = args;
+	if (!goal) return { ok: false, message: "No goal is set." };
+	if (runningGoalId && goal.id !== runningGoalId) return { ok: false, message: "The active goal changed during this run; not marking it complete." };
+	if (!isCompletableStatus(goal.status)) return { ok: false, message: `Goal is ${statusLabel(goal)}; update_goal(complete) does not apply.` };
+	return { ok: true };
+}
+
+/** update_goal(blocked) applies only to an ACTIVE goal — paused/complete/blocked/budget-limited reject it. */
+export function validateGoalBlock(args: {
+	goal: GoalPolicyRecordLike | null;
+	runningGoalId?: string | null;
+}): PolicyValidation {
+	const { goal } = args;
+	if (!goal) return { ok: false, message: "No goal is set." };
+	if (goal.status !== "active") {
+		return { ok: false, message: `Goal is ${statusLabel(goal)}; update_goal(blocked) applies only to an active goal.` };
+	}
+	return { ok: true };
+}
+
+/**
+ * update_goal(paused) is the agent-initiated immediate pause (Stage 5.1-C).
+ * It applies only to an ACTIVE goal and is distinct from the three-turn
+ * blocked gate and from the user-owned pause/resume commands.
+ */
+export function validateGoalAgentPause(args: {
+	goal: GoalPolicyRecordLike | null;
+	runningGoalId?: string | null;
+}): PolicyValidation {
+	const { goal } = args;
+	if (!goal) return { ok: false, message: "No goal is set." };
+	if (goal.status !== "active") {
+		return { ok: false, message: `Goal is ${statusLabel(goal)}; update_goal(paused) applies only to an active goal.` };
+	}
+	return { ok: true };
+}
+
+export function validateResumeGoal(goal: GoalPolicyRecordLike | null): PolicyValidation {
+	if (!goal) return { ok: false, message: "No goal is set. Use /goal to draft one, or /goal-direct <objective> to start immediately." };
+	if (goal.status === "complete") return { ok: false, message: "Goal is complete. Use /goal to draft a new one, or /goal-direct <objective> to start immediately." };
+	if (goal.status === "active" && goal.autoContinue) return { ok: false, message: "Goal is already running." };
+	return { ok: true };
+}
+
+export function clearGoalCommandMessage(args: { archived: boolean }): string {
+	return args.archived ? "Goal cleared and archived." : "No goal is set.";
+}
+
+/** Count tasks in subtree recursively */
+export function buildTaskSummary(taskList: GoalTaskList): string {
+	const { total, complete, skipped } = countTaskSubtree(taskList.tasks);
+	if (total === 0) return "No tasks";
+	const parts: string[] = [`${complete}/${total} tasks complete`];
+	if (skipped > 0) parts.push(`(${skipped} skipped)`);
+	return parts.join(" ");
+}
+
+export function taskCompletionBlockWarning(taskList: GoalTaskList): string | null {
+	if (!taskList.blockCompletion) return null;
+	const { pending } = countTaskSubtree(taskList.tasks);
+	if (pending === 0) return null;
+	return `${pending} task${pending > 1 ? "s" : ""} still pending with blockCompletion enabled. Complete or skip all pending tasks before finishing the goal.`;
+}
+
+/**
+ * Validate a task completion transition (evidence requirement is enforced by
+ * the update_goal_task handler against the task's verification contract).
+ */
+export function validateTaskCompletion(args: {
+	goal: GoalPolicyRecordLike | null;
+	taskId: string;
+}): PolicyValidation {
+	if (!args.goal) return { ok: false, message: "No goal is set." };
+	if (!args.goal.taskList) return { ok: false, message: "Goal has no task list." };
+	const task = findTaskInTree(args.goal.taskList.tasks, args.taskId);
+	if (!task) return { ok: false, message: `Task "${args.taskId}" not found.` };
+	if (task.status === "complete") return { ok: false, message: `Task "${args.taskId}" is already complete.` };
+	if (task.status === "skipped") return { ok: false, message: `Task "${args.taskId}" was already skipped.` };
+	return { ok: true };
+}
+
+export function validateTaskSkip(args: {
+	goal: GoalPolicyRecordLike | null;
+	taskId: string;
+	reason: string;
+}): PolicyValidation {
+	if (!args.goal) return { ok: false, message: "No goal is set." };
+	if (!args.goal.taskList) return { ok: false, message: "Goal has no task list." };
+	const task = findTaskInTree(args.goal.taskList.tasks, args.taskId);
+	if (!task) return { ok: false, message: `Task "${args.taskId}" not found.` };
+	if (task.status === "complete") return { ok: false, message: `Task "${args.taskId}" is already complete.` };
+	// Skipped tasks toggle via the executor; reason is only required for first-time skips.
+	if (task.status === "skipped") return { ok: true };
+	if (!args.reason.trim()) return { ok: false, message: "Skipping requires a non-empty reason." };
+	return { ok: true };
+}
+
+/**
+ * Count the maximum nesting depth of a task's subtask tree.
+ * Root level = 0. Returns the deepest nesting depth found.
+ */
+export function measureSubtaskDepth(task: GoalTask): number {
+	if (!task.subtasks || task.subtasks.length === 0) return 0;
+	let maxChild = 0;
+	for (const child of task.subtasks) {
+		const childDepth = measureSubtaskDepth(child);
+		if (childDepth > maxChild) maxChild = childDepth;
+	}
+	return maxChild + 1;
+}
+
+/**
+ * Validate that a task's subtask tree does not exceed the configured max depth.
+ * maxDepth is the subtaskDepth setting (default 1) — how many levels of nesting are allowed.
+ * Returns the first violation found, or undefined if valid.
+ */
+export function findSubtaskDepthViolation(tasks: GoalTask[], maxDepth: number): string | undefined {
+	for (const task of tasks) {
+		const depth = measureSubtaskDepth(task);
+		if (depth > maxDepth) {
+			return `Task "${task.id}" has subtask nesting depth ${depth}, exceeding the configured maximum of ${maxDepth}`;
+		}
+		if (task.subtasks) {
+			const childViolation = findSubtaskDepthViolation(task.subtasks, maxDepth);
+			if (childViolation) return childViolation;
+		}
+	}
+	return undefined;
+}
+
+function checkDuplicateTaskIds(tasks: GoalTask[], ids: Set<string>): string | undefined {
+	for (const t of tasks) {
+		const id = t.id.trim();
+		if (!id) return "All tasks must have a non-empty id.";
+		if (ids.has(id)) return `Duplicate task id: "${id}".`;
+		ids.add(id);
+		if (t.subtasks) {
+			const childErr = checkDuplicateTaskIds(t.subtasks, ids);
+			if (childErr) return childErr;
+		}
+	}
+	return undefined;
+}
+
+export function validateTaskListProposal(args: {
+	goal: GoalPolicyRecordLike | null;
+	tasks: GoalTask[];
+	maxSubtaskDepth?: number;
+}): PolicyValidation {
+	if (!args.goal) return { ok: false, message: "No goal is set." };
+	if (args.tasks.length > 50) return { ok: false, message: "Task list cannot exceed 50 tasks." };
+	const ids = new Set<string>();
+	for (const t of args.tasks) {
+		if (!t.id.trim()) return { ok: false, message: "All tasks must have a non-empty id." };
+		if (!t.title.trim()) return { ok: false, message: `Task "${t.id}" must have a non-empty title.` };
+		if (ids.has(t.id)) return { ok: false, message: `Duplicate task id: "${t.id}".` };
+		ids.add(t.id);
+		// Recursively check subtask ids against the same global set
+		if (t.subtasks && t.subtasks.length > 0) {
+			const childErr = checkDuplicateTaskIds(t.subtasks, ids);
+			if (childErr) return { ok: false, message: childErr };
+		}
+	}
+	// Check subtask depth limit
+	const maxDepth = args.maxSubtaskDepth ?? 1;
+	const depthViolation = findSubtaskDepthViolation(args.tasks, maxDepth);
+	if (depthViolation) return { ok: false, message: depthViolation };
+	return { ok: true };
+}
+
+/**
+ * Recursively find a task by ID in a task tree.
+ */
+export function findTaskInTree(tasks: GoalTask[], taskId: string): GoalTask | undefined {
+	for (const t of tasks) {
+		if (t.id === taskId) return t;
+		if (t.subtasks) {
+			const found = findTaskInTree(t.subtasks, taskId);
+			if (found) return found;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Recursively update a task by ID in a task tree using an updater function.
+ */
+export function updateTaskInTree(tasks: GoalTask[], taskId: string, updater: (task: GoalTask) => GoalTask): GoalTask[] {
+	let next: GoalTask[] | undefined;
+	for (let i = 0; i < tasks.length; i++) {
+		const task = tasks[i]!;
+		let updated = task;
+		if (task.id === taskId) updated = updater(task);
+		else if (task.subtasks) {
+			const subtasks = updateTaskInTree(task.subtasks, taskId, updater);
+			if (subtasks !== task.subtasks) updated = {...task, subtasks};
+		}
+		if (updated !== task) { next ??= tasks.slice(); next[i] = updated; }
+	}
+	return next ?? tasks;
+}
+
+/**
+ * Check if all subtasks of a task are complete (for full subtasks only).
+ * Returns undefined when all are complete/skipped, or an error message.
+ */
+export function checkSubtasksComplete(task: GoalTask): string | undefined {
+	if (!task.subtasks || task.subtasks.length === 0 || task.lightweightSubtasks) return undefined;
+	for (const child of task.subtasks) {
+		if (child.status === "pending") {
+			return `Task "${task.id}" has pending subtask "${child.id}". Complete or skip all subtasks first.`;
+		}
+		// Check recursively
+		const childCheck = checkSubtasksComplete(child);
+		if (childCheck) return childCheck;
+	}
+	return undefined;
+}
+
+/**
+ * Recursively skip all subtasks of a task.
+ * Returns a set of all skipped task IDs.
+ */
+export function skipAllSubtasks(task: GoalTask, now: string, reason: string): GoalTask {
+	if (!task.subtasks || task.subtasks.length === 0) return task;
+	return {
+		...task,
+		subtasks: task.subtasks.map((child) => {
+			if (child.status === "complete") return child;
+			const skipped = {
+				...child,
+				status: "skipped" as const,
+				skippedAt: now,
+				skipReason: reason,
+			};
+			return skipAllSubtasks(skipped, now, reason);
+		}),
+	};
+}
+
+export function buildCompletionReport(args: { detailedSummary: string; auditorReport?: string | null; auditSkippedReason?: string | null; taskSummary?: string | null }): string {
+	const auditSkipped = args.auditSkippedReason?.trim();
+	const auditorReport = args.auditorReport?.trim();
+	const lines = auditSkipped
+		? ["Goal audit skipped.", "", "Reason: " + auditSkipped, "", "Goal complete."]
+		: auditorReport
+			? ["Goal audit approved.", "", "Auditor approval:", auditorReport, "", "Goal complete."]
+			: ["Goal complete."];
+	const taskSummary = args.taskSummary?.trim();
+	if (taskSummary) {
+		lines.push("", `Task summary: ${taskSummary}`);
+	}
+	lines.push("", args.detailedSummary);
+	return lines.join("\n");
+}
+
+export interface GoalCreatedReportArgs {
+	objective: string;
+	detailedSummary?: string | null;
+	/**
+	 * Guided-confirmation report (§14): the richer opening line plus expanded
+	 * detail (goal id, active file, task count, verification contract, auditor
+	 * configuration, token budget). Direct creation keeps the default text.
+	 */
+	confirmed?: boolean;
+	goalId?: string;
+	filePath?: string;
+	taskCount?: number;
+	verificationContract?: string;
+	auditorEnabled?: boolean;
+	tokenBudget?: number;
+}
+
+export function formatGoalBudget(budget: number | undefined): string {
+	return `Budget: ${budget === undefined ? "none" : `${budget} tokens`}`;
+}
+
+export function buildGoalCreatedReport(args: GoalCreatedReportArgs): string {
+	const opening = args.confirmed
+		? ["✓ Goal created and focused.", "Continuing automatically with the confirmed plan."]
+		: ["Goal confirmed and created."];
+	const lines = [...opening, "", "Finalized goal:", "", args.objective.trim()];
+	const details: string[] = [];
+	if (args.goalId) details.push(`Goal id: ${args.goalId}`);
+	if (args.filePath) details.push(`File: ${args.filePath}`);
+	if (args.taskCount !== undefined) details.push(`Tasks: ${args.taskCount}`);
+	if (args.verificationContract?.trim()) details.push(`Verification: ${args.verificationContract.trim()}`);
+	if (args.auditorEnabled !== undefined) details.push(`Auditor: ${args.auditorEnabled ? "enabled" : "disabled"}`);
+	details.push(formatGoalBudget(args.tokenBudget));
+	const summary = args.detailedSummary?.trim();
+	if (summary) details.push(summary);
+	if (details.length > 0) {
+		lines.push("", "Goal details:", ...details);
+	}
+	return lines.join("\n");
+}
+
+/** Count the ordered steps in a sisyphus objective (numbered items or "Step N"). */
+export function countOrderedSteps(objective: string): number {
+	const numbered = objective.match(/^\s*\d{1,2}\s*[.):]/gm)?.length ?? 0;
+	const stepMarkers = objective.match(/^\s*step\s+\d+/gim)?.length ?? 0;
+	return Math.max(numbered, stepMarkers);
+}
+
+/**
+ * E6/F4: where the goal is in its ordered sisyphus sequence. M = ordered steps
+ * in the objective; N = completed top-level tasks + 1 (clamped), falling back
+ * to 1 when no task tracking exists. Returns null for non-sisyphus goals or
+ * objectives without ordered markers.
+ */
+export function sisyphusStepProgress(goal: { sisyphus: boolean; objective: string; taskList?: { tasks?: Array<{ status: string }> } | null }): { current: number; total: number } | null {
+	if (!goal.sisyphus) return null;
+	const total = countOrderedSteps(goal.objective);
+	if (total === 0) return null;
+	let current = 1;
+	const tasks = goal.taskList?.tasks;
+	if (tasks && tasks.length > 0) {
+		const completedTop = tasks.filter((t) => t.status === "complete").length;
+		current = Math.min(total, completedTop + 1);
+	}
+	return { current, total };
+}
+
+export function shouldQueueContinuation(goal: Pick<GoalPolicyRecordLike, "status" | "autoContinue"> | null): boolean {
+	return !!goal && goal.status === "active" && goal.autoContinue;
+}
+
+
+export function shouldArmPostCompactReminder(goal: Pick<GoalPolicyRecordLike, "sisyphus" | "status"> | null): boolean {
+	return !!goal && isRunnableStatus(goal.status);
+}
+
+export function shouldInjectPostCompactReminder(args: { pending: boolean; goal: Pick<GoalPolicyRecordLike, "sisyphus"> | null }): boolean {
+	return args.pending && !!args.goal;
+}

package/extensions/goal-pool.ts

@@ -0,0 +1,103 @@
+import {
+	displayObjectiveTitle,
+	formatDuration,
+	formatTokenValue,
+	statusLabel,
+	truncateText,
+} from "./goal-core.ts";
+import { cloneGoal, type GoalFocusEntry, type GoalRecord } from "./goal-record.ts";
+
+export function goalPoolFromGoals(goals: Iterable<GoalRecord>): Map<string, GoalRecord> {
+	const pool = new Map<string, GoalRecord>();
+	for (const goal of goals) {
+		if (goal.status !== "complete") pool.set(goal.id, cloneGoal(goal));
+	}
+	return pool;
+}
+
+export function openGoalsFromPool(pool: Map<string, GoalRecord>): GoalRecord[] {
+	return Array.from(pool.values())
+		.filter((goal) => goal.status !== "complete")
+		.sort((a, b) => {
+			const byCreated = a.createdAt.localeCompare(b.createdAt);
+			return byCreated !== 0 ? byCreated : a.id.localeCompare(b.id);
+		});
+}
+
+export function focusedGoalFromPool(pool: Map<string, GoalRecord>, focusedGoalId: string | null): GoalRecord | null {
+	if (!focusedGoalId) return null;
+	const goal = pool.get(focusedGoalId) ?? null;
+	return goal;
+}
+
+export function otherOpenGoalCount(pool: Map<string, GoalRecord>, focusedGoalId: string | null): number {
+	let count = 0;
+	for (const goal of pool.values()) if (goal.status !== "complete" && goal.id !== focusedGoalId) count++;
+	return count;
+}
+
+export function resolveSessionFocus(args: {
+	pool: Map<string, GoalRecord>;
+	focusEntry?: GoalFocusEntry | null;
+	legacyGoal?: GoalRecord | null;
+	autoSelectSingleGoal?: boolean;
+}): string | null {
+	const focusedGoalId = args.focusEntry?.focusedGoalId ?? null;
+	const focused = focusedGoalId ? focusedGoalFromPool(args.pool, focusedGoalId) : null;
+	if (focused && focused.status !== "complete") {
+		return focusedGoalId;
+	}
+	if (args.focusEntry) {
+		return null;
+	}
+	if (args.legacyGoal && args.legacyGoal.status !== "complete") {
+		if (args.pool.has(args.legacyGoal.id)) return args.legacyGoal.id;
+		args.pool.set(args.legacyGoal.id, cloneGoal(args.legacyGoal));
+		return args.legacyGoal.id;
+	}
+	// Auto-select single open goal only when explicitly enabled.
+	// Default (false): sessions start unfocused to prevent goals from
+	// bleeding across sessions that share the same .pi/goals/ directory.
+	if (args.autoSelectSingleGoal) {
+		const open = openGoalsFromPool(args.pool);
+		return open.length === 1 ? open[0]?.id ?? null : null;
+	}
+	return null;
+}
+
+export function goalSelectorLabel(goal: GoalRecord, focusedGoalId: string | null): string {
+	const marker = goal.id === focusedGoalId ? "*" : " ";
+	const mode = goal.sisyphus ? "sisyphus" : "goal";
+	const path = goal.activePath ? ` ${goal.activePath}` : "";
+	return `${marker} ${goal.id} | ${statusLabel(goal)} | ${mode} | ${truncateText(displayObjectiveTitle(goal.objective), 72)}${path}`;
+}
+
+export function buildGoalListText(pool: Map<string, GoalRecord>, focusedGoalId: string | null): string {
+	const open = openGoalsFromPool(pool);
+	if (open.length === 0) return "No open goals. Use /goal <objective> or /sisyphus <objective> to start immediately.";
+	const lines = [`Open goals: ${open.length}`, ""];
+	for (const goal of open) {
+		const focused = goal.id === focusedGoalId ? "*" : " ";
+		const mode = goal.sisyphus ? "sisyphus" : "goal";
+		const usage = goal.usage.tokensUsed > 0 || goal.usage.activeSeconds > 0
+			? ` · ${formatDuration(goal.usage.activeSeconds)} · ${formatTokenValue(goal.usage.tokensUsed).split(" ")[0]}`
+			: "";
+		lines.push(`${focused} ${goal.id} — ${statusLabel(goal)} · ${mode}${usage}`);
+		lines.push(`  ${displayObjectiveTitle(goal.objective)}`);
+		if (goal.activePath) lines.push(`  ${goal.activePath}`);
+	}
+	return lines.join("\n");
+}
+
+export function buildUnfocusedOpenGoalsSummary(openGoalCount: number): string {
+	return `No goal is focused in this session. ${openGoalCount} open goal${openGoalCount === 1 ? "" : "s"} exist in the goal pool. Use /goal-focus to choose the session focus before doing goal work.`;
+}
+
+export function mergeFocusedGoalWithDisk(args: { memoryGoal: GoalRecord; diskGoal: GoalRecord }): GoalRecord {
+	const tokensUsed = Math.max(args.memoryGoal.usage.tokensUsed, args.diskGoal.usage.tokensUsed);
+	const activeSeconds = Math.max(args.memoryGoal.usage.activeSeconds, args.diskGoal.usage.activeSeconds);
+	return {
+		...args.diskGoal,
+		usage: { tokensUsed, activeSeconds },
+	};
+}

package/extensions/goal-prompt-cache.ts

@@ -0,0 +1,80 @@
+import { asRecord } from "./goal-record.ts";
+
+/**
+ * Pi marks the final user block for explicit caching. Our request-only state
+ * never enters history, so that block cannot be reused on the next request.
+ * Move that existing breakpoint to the preceding cacheable history block.
+ * Implicit caches and cacheRetention=none have no marker and are untouched.
+ * Reuse the provider's TTL and marker count rather than enabling caching here.
+ *
+ * The live tail may span several request-only blocks (stable goal state plus
+ * volatile counters) and previously sent tails may be retained verbatim
+ * mid-history for implicit-prefix stability. Every such block is transient:
+ * the breakpoint must skip all of them and land on real history.
+ */
+export function cacheGoalHistory(payload: unknown, liveContent: string | readonly string[] | undefined): unknown {
+	const live = liveContent === undefined
+		? undefined
+		: new Set((typeof liveContent === "string" ? [liveContent] : liveContent).filter(text => text.length > 0));
+	const root = asRecord(payload);
+	if (!live || live.size === 0 || !Array.isArray(root?.messages)) return undefined;
+	const messages = root.messages;
+	let lastIndex = messages.length - 1;
+	for (; lastIndex >= 0; lastIndex--) {
+		const content = asRecord(messages[lastIndex])?.content;
+		if (typeof content === "string" || Array.isArray(content) ? content.length > 0 : content != null) break;
+	}
+	const last = asRecord(messages[lastIndex]);
+	if (last?.role !== "user" || !Array.isArray(last.content)) return undefined;
+	// Match on text membership, not the type tag: Bedrock payloads use
+	// typeless { text } blocks, and neither cachePoint markers nor thinking
+	// blocks carry a text field, so they can never match by accident. A real
+	// history block quoting a live tail verbatim would misclassify as transient;
+	// accepted: it requires an exact full-string quote of a volatile block.
+	const isLiveText = (block: unknown): boolean => {
+		const record = asRecord(block);
+		return typeof record?.text === "string" && live.has(record.text);
+	};
+	// Bedrock represents its breakpoint as a separate content block. The tail
+	// may be several live blocks; skip back over all of them.
+	const bedrockPoint = asRecord(last.content.at(-1));
+	if (asRecord(bedrockPoint?.cachePoint)) {
+		// Require our live text immediately before the marker. A bare marker
+		// or another extension's suffix is not ours to relocate.
+		if (!isLiveText(last.content.at(-2))) return undefined;
+		for (let i = lastIndex; i >= 0; i--) {
+			const previous = asRecord(messages[i]);
+			if (!Array.isArray(previous?.content)) continue;
+			for (let j = previous.content.length - 1; j >= 0; j--) {
+				const block = asRecord(previous.content[j]);
+				if (!block || isLiveText(block) || !["text", "image", "document", "toolUse", "toolResult"].some(key => key in block)) continue;
+				last.content.pop();
+				if (!asRecord(previous.content[j + 1])?.cachePoint) previous.content.splice(j + 1, 0, { ...bedrockPoint });
+				return payload;
+			}
+		}
+		return undefined;
+	}
+	const tail = asRecord(last.content.at(-1));
+	if (tail?.type !== "text" || typeof tail.text !== "string" || !live.has(tail.text) || !asRecord(tail.cache_control)) return undefined;
+	for (let i = lastIndex; i >= 0; i--) {
+		const message = asRecord(messages[i]);
+		if (!message || !["user", "assistant", "tool"].includes(String(message.role))) continue;
+		if (typeof message.content === "string" && message.content.length > 0 && !live.has(message.content)) {
+			message.content = [{ type: "text", text: message.content, cache_control: tail.cache_control }];
+			delete tail.cache_control;
+			return payload;
+		}
+		if (!Array.isArray(message.content)) continue;
+		for (let j = message.content.length - 1; j >= 0; j--) {
+			const block = asRecord(message.content[j]);
+			// Thinking blocks cannot carry cache_control. Never split/reorder tool pairs.
+			// Live tails are transient by construction: never anchor the breakpoint on one.
+			if (!block || isLiveText(block) || !["text", "image", "tool_use", "tool_result"].includes(String(block.type))) continue;
+			block.cache_control ??= tail.cache_control;
+			delete tail.cache_control;
+			return payload;
+		}
+	}
+	return undefined;
+}