pi-goal-x 0.27.4 → 0.28.0

package/README.md

@@ -343,6 +343,38 @@ Completed and cleared goals are stored in:
 
 Each session can focus on one goal while the project keeps other goals open.
 
+## Session checkpoint recovery
+
+Auto-continue checkpoints are tiny structured markers (≤160 chars) that
+trigger the next turn; the full goal state is injected once per turn by the
+extension and is never persisted into checkpoints. Sessions created by older
+versions may still contain large "legacy" full-prompt checkpoints.
+
+Check `/goal-recovery` or `/goal-status health` for a read-only report:
+
+```text
+Session checkpoints:
+  total: 851
+  legacy full checkpoints: 851
+  checkpoint content: 5.4 MB
+  projected content after recovery: 92 KB
+```
+
+To repair an affected session file, close Pi first (the tool refuses to run
+while a live session could be open), then:
+
+```bash
+# Report only — writes nothing:
+pi-goal-x-recover --session <session.jsonl>
+
+# Repair (creates a timestamped backup, rewrites only checkpoint entries):
+pi-goal-x-recover --session <session.jsonl> --apply --confirm-pi-closed
+```
+
+Recovery preserves every entry id and parent link, keeps all non-goal lines
+byte-identical (including malformed lines), and is idempotent. Rollback is
+the timestamped `.backup-*` file created next to the session.
+
 ## Commands
 
 ```text
@@ -368,12 +400,21 @@ Each session can focus on one goal while the project keeps other goals open.
 
 ## Configuration
 
-Settings are stored in:
+Settings resolve per setting in this order (highest wins):
+
+```text
+environment > project layer > global layer > defaults
+```
+
+Files:
 
 ```text
-.pi/pi-goal-x-settings.json
+global:  ~/.pi/pi-goal-x-settings.json   (or $PI_CODING_AGENT_DIR, or $PI_GOAL_GLOBAL_SETTINGS_FILE)
+project: <cwd>/.pi/pi-goal-x-settings.json   (or $PI_GOAL_SETTINGS_FILE)
 ```
 
+Define shared configuration once in the global file and override per project. Explicit `false`/`0` values in a lower layer override inherited values; nested `keybindings` inherit per key. `/goal-settings` shows each row's effective value and source, can switch the edited scope, and can remove a local override to return to inheritance.
+
 Use `/goal-settings` to configure task lists, verification contracts, subtask depth, automatic goal selection, and completion auditing. Goal objectives have no hard length limit by default; set `objectiveMaxChars` (or `PI_GOAL_OBJECTIVE_MAX_CHARS`, `0` = no limit) to cap objective length across `create_goal`, `propose_goal_draft`, and `/goal-tweak`.
 
 Configure the task shortcuts in the same file when the terminal captures the defaults:

package/extensions/goal-commands.ts

@@ -5,10 +5,15 @@ import { extractVerificationContract, sisyphusObjectiveSufficient } from "./goal
 import { detailedSummary, oneLineSummary } from "./goal-format.ts";
 import {
 	goalSettingsPath,
+	goalGlobalSettingsPath,
 	loadGoalSettings,
-	loadGoalSettingsFileConfig,
-	saveGoalSettingsFileConfig,
+	loadSettingsSnapshot,
+	mutateSettingsLayer,
+	readSettingsLayer,
+	envOverrideFor,
 	type GoalSettings,
+	type SettingsMutation,
+	type SettingsScope,
 } from "./goal-settings.ts";
 import {
 	buildGoalListText,
@@ -19,11 +24,12 @@ import {
 import { clearGoalCommandMessage, validateResumeGoal } from "./goal-policy.ts";
 import { invalidateGoalLedgerCache, readGoalLedger } from "./goal-ledger.ts";
 import { buildGoalStatusText } from "./goal-status.ts";
-import { effectiveSettingsReport, envOverrideFor, invalidateGoalSettingsCache } from "./goal-settings.ts";
+import { effectiveSettingsReport, invalidateGoalSettingsCache, loadGoalSettingsFileConfig } from "./goal-settings.ts";
 import { invalidateGoalPoolCache, mergeGoalPromptFromDisk, readActiveGoalPool } from "./storage/goal-files.ts";
 import { nowIso, type GoalMode, type GoalRecord } from "./goal-record.ts";
 import { clearGoalDrafting, hasActiveDraft, startGoalDrafting } from "./goal-drafting.ts";
 import { formatRecoveryReport, runRecoveryReport, runRecoveryRepair } from "./goal-recovery.ts";
+import { formatCheckpointHealthReport, readSessionCheckpointHealth } from "./goal-session-health.ts";
 
 export interface GoalRefreshState {
 	poolIds: Iterable<string>;
@@ -206,7 +212,18 @@ export function registerGoalCommands(core: GoalCore): void {
 			}
 			return;
 		}
-		ctx.ui.notify(formatRecoveryReport(report), report.healthy ? "info" : "warning");
+		// Issue #30: surface persisted-checkpoint health for this session file
+		// (read-only). Legacy full checkpoints are repairable offline with the
+		// shipped pi-goal-x-recover CLI; this command never writes.
+		const sessionFile = (ctx.sessionManager as { getSessionFile?: () => string | undefined } | undefined)?.getSessionFile?.();
+		const checkpointHealth = sessionFile ? readSessionCheckpointHealth(sessionFile) : null;
+		const checkpointSection = checkpointHealth && checkpointHealth.total > 0
+			? `\n\n${formatCheckpointHealthReport(checkpointHealth, sessionFile)}`
+			: "";
+		ctx.ui.notify(
+			formatRecoveryReport(report) + checkpointSection,
+			report.healthy && (checkpointHealth?.legacyFull ?? 0) === 0 ? "info" : "warning",
+		);
 	}
 
 	async function runGoalRefresh(ctx: ExtensionContext): Promise<void> {
@@ -271,6 +288,13 @@ export function registerGoalCommands(core: GoalCore): void {
 			activeFilePresent: health && view?.activePath
 				? existsSync(path.resolve(ctx.cwd, view.activePath))
 				: undefined,
+			// Issue #30: checkpoint growth report (health view only, read-only).
+			checkpointHealth: health
+				? readSessionCheckpointHealth(
+					(ctx.sessionManager as { getSessionFile?: () => string | undefined } | undefined)?.getSessionFile?.() ?? "",
+				)
+				: null,
+			checkpointSessionFile: (ctx.sessionManager as { getSessionFile?: () => string | undefined } | undefined)?.getSessionFile?.(),
 			// §13.2: effective settings with provenance appear only in verbose mode;
 			// the standard mode stays free of settings noise (§13.1).
 			settingsReport: verbose ? effectiveSettingsReport(ctx.cwd) : [],
@@ -364,6 +388,7 @@ export function registerGoalCommands(core: GoalCore): void {
 
 	const SETTING_ROWS: readonly SettingRow[] = [
 		{ key: "autoSelectSingleGoal", label: "autoSelectSingleGoal", section: "Goal behavior", kind: "boolean" },
+		{ key: "hideUnfocusedBanner", label: "hideUnfocusedBanner", section: "Goal behavior", kind: "boolean" },
 		{ key: "disableContracts", label: "disableContracts", section: "Goal behavior", kind: "boolean" },
 		{ key: "stallTimeoutMinutes", label: "stall timeout (minutes)", section: "Goal behavior", kind: "positiveInteger" },
 		{ key: "objectiveMaxChars", label: "max objective length (0 = none)", section: "Goal behavior", kind: "positiveInteger" },
@@ -376,7 +401,7 @@ export function registerGoalCommands(core: GoalCore): void {
 	];
 
 	function settingsValue(config: GoalSettings, key: keyof GoalSettings): string {
-		if (key === "disabled" || key === "disableTasks" || key === "disableContracts" || key === "autoSelectSingleGoal" || key === "auditorProjectResources") {
+		if (key === "disabled" || key === "disableTasks" || key === "disableContracts" || key === "autoSelectSingleGoal" || key === "auditorProjectResources" || key === "hideUnfocusedBanner") {
 			return config[key] === true ? "true" : "false";
 		}
 		if (key === "subtaskDepth") return config.subtaskDepth !== undefined ? String(config.subtaskDepth) : "1";
@@ -393,29 +418,52 @@ export function registerGoalCommands(core: GoalCore): void {
 
 	async function handleSettingsMenu(ctx: ExtensionContext): Promise<void> {
 		if (!ctx.hasUI) {
-			ctx.ui.notify(`Settings file: ${goalSettingsPath(ctx.cwd)}`, "info");
+			// Headless: read-only report of both layer paths.
+			ctx.ui.notify(
+				`Settings — project file: ${goalSettingsPath(ctx.cwd)}\nGlobal file: ${goalGlobalSettingsPath()}`,
+				"info",
+			);
 			return;
 		}
+
 		/**
-		 * Persist a settings edit, then reinstall the fixed three/five profile
-		 * when the effective disableTasks value changed since the last install.
-		 * core.tasksEnabled tracks the last profile actually installed (updated
-		 * by installGoalToolProfile), so toggling task availability off, on, and
-		 * off within one menu session reinstalls on every real change instead of
-		 * comparing against the value captured when the menu opened.
+		 * After any mutation: reinstall the fixed three/five tool profile when
+		 * the effective disableTasks value changed since the last install, and
+		 * refresh the UI. This is the central settings side-effect hook — no
+		 * ad hoc per-row refresh code.
 		 */
-		const saveSettings = (next: GoalSettings): void => {
-			saveGoalSettingsFileConfig(ctx.cwd, next);
+		const applyEffectiveSettings = (): void => {
 			const tasksEnabledNow = !loadGoalSettings(ctx.cwd).disableTasks;
 			if (tasksEnabledNow !== core.tasksEnabled) {
 				core.installGoalToolProfile(tasksEnabledNow);
 			}
+			// PR #29: settings changes must be visible immediately — the banner
+			// hide/restore happens through this coalesced UI refresh.
+			core.updateUI(ctx);
 		};
+
+		const applyMutation = (scope: SettingsScope, mutation: SettingsMutation): boolean => {
+			try {
+				mutateSettingsLayer({ scope, cwd: ctx.cwd, mutation });
+				applyEffectiveSettings();
+				return true;
+			} catch (err) {
+				ctx.ui.notify(`Settings change failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
+				return false;
+			}
+		};
+
+		const scopePath = (scope: SettingsScope): string =>
+			scope === "global" ? goalGlobalSettingsPath() : goalSettingsPath(ctx.cwd);
+
 		core.enterGoalModal();
 		try {
+			let scope: SettingsScope = "project";
 			while (true) {
-				const config = loadGoalSettingsFileConfig(ctx.cwd);
+				const snapshot = loadSettingsSnapshot(ctx.cwd);
+				const localLayer = snapshot[scope].layer as Record<string, unknown>;
 				const options: string[] = [];
+				options.push(`─── Editing: ${scope} (${scopePath(scope)}) ───`);
 				let lastSection: string | null = null;
 				for (const row of SETTING_ROWS) {
 					if (row.section !== lastSection) {
@@ -423,109 +471,147 @@ export function registerGoalCommands(core: GoalCore): void {
 						lastSection = row.section;
 					}
 					const envVar = envOverrideFor(row.key);
-					options.push(envVar ? `  ${row.label}: ${settingsValue(config, row.key)} (env: ${envVar} — read-only)` : `  ${row.label}: ${settingsValue(config, row.key)}`);
+					if (envVar) {
+						options.push(`  ${row.label}: ${settingsValue(snapshot.value, row.key)} (environment; read-only)`);
+						continue;
+					}
+					const provenance = snapshot.provenance.get(String(row.key));
+					let source: string;
+					if (provenance?.source === "global") source = scope === "project" ? "(inherited from global)" : "(global override)";
+					else if (provenance?.source === "project") source = scope === "project" ? "(project override)" : "(project; edit via project scope)";
+					else source = "(default)";
+					const hasLocalOverride = localLayer[row.key] !== undefined;
+					if (hasLocalOverride && provenance?.source === scope) source = `(${scope} override)`;
+					options.push(`  ${row.label}: ${settingsValue(snapshot.value, row.key)} ${source}`);
 				}
 				options.push("Done");
 				const selected = await ctx.ui.select("Goal settings", options);
 				if (!selected || selected === "Done") break;
-				if (selected.startsWith("───")) continue; // section headers are not rows
-				// Strip leading spaces and resolve the row from the display label.
-				const selectedTrimmed = selected.trim();
-				const colon = selectedTrimmed.indexOf(":");
+				if (selected.startsWith("───")) continue; // headers are not rows
+				const trimmed = selected.trim();
+				if (trimmed.startsWith("Scope:")) {
+					scope = scope === "project" ? "global" : "project";
+					continue;
+				}
+				const colon = trimmed.indexOf(":");
 				if (colon === -1) continue;
-			const label = selectedTrimmed.slice(0, colon).trim();
-			const row = SETTING_ROWS.find((r) => r.label === label);
-			if (!row) continue;
-			const key = row.key;
-			if (envOverrideFor(key)) {
-				ctx.ui.notify(`${row.label} is read-only: overridden by the ${envOverrideFor(key)} env var.`, "warning");
-				continue;
-			}
-			if (row.kind === "boolean") {
-				const next = { ...config, [key]: config[key] !== true };
-				saveSettings(next);
-				ctx.ui.notify(`Settings saved:\n${settingsLines(loadGoalSettingsFileConfig(ctx.cwd)).join("\n")}`, "info");
-				continue;
-			}
-			if (row.kind === "positiveInteger") {
-				const input = await ctx.ui.input(`Set ${row.label}`, settingsValue(config, key));
-				if (input === undefined) continue;
-				// Row-driven lower bound: subtaskDepth is a nesting depth (min 1);
-				// stallTimeoutMinutes and objectiveMaxChars default to 0 meaning
-				// "off / no limit".
-				const min = (row.key === "stallTimeoutMinutes" || row.key === "objectiveMaxChars") ? 0 : 1;
-				// Full-string decimal validation: no partial parseInt. Rejects
-				// 1.5, 1x, negatives, infinity, and unsafe integers alike.
-				const trimmed = input.trim();
-				if (!/^[0-9]+$/.test(trimmed) || !Number.isSafeInteger(Number(trimmed)) || Number(trimmed) < min) {
-					ctx.ui.notify(`${row.label} must be an integer >= ${min} (e.g. ${min}, ${min + 1}, ${min + 2})`, "warning");
+				const label = trimmed.slice(0, colon).trim();
+				const row = SETTING_ROWS.find((r) => r.label === label);
+				if (!row) continue;
+				if (envOverrideFor(row.key)) {
+					ctx.ui.notify(`${row.label} is read-only: overridden by the ${envOverrideFor(row.key)} env var.`, "warning");
 					continue;
 				}
-				const next = { ...config, [key]: Number(trimmed) };
-				saveSettings(next);
-				ctx.ui.notify(`Settings saved:\n${settingsLines(loadGoalSettingsFileConfig(ctx.cwd)).join("\n")}`, "info");
-				continue;
-			}
-			if (row.kind === "thinking") {
-				const currentValue = settingsValue(config, key);
-				const levels = thinkingLevelChoices(currentValue === "(default)" ? undefined : currentValue);
-				const picked = await ctx.ui.select(`Set ${row.label}`, levels);
-				if (!picked) continue;
-				const trimmed = picked.trim().replace(/^\u2713\s+/, "");
-				const next: GoalSettings = { ...config };
-				if (trimmed === "(default)") {
-					delete next.thinkingLevel;
-				} else if ((AUDITOR_THINKING_LEVELS as readonly string[]).includes(trimmed)) {
-					next.thinkingLevel = trimmed as GoalSettings["thinkingLevel"];
-				} else {
-					ctx.ui.notify(`thinking_level must be one of: ${AUDITOR_THINKING_LEVELS.join(", ")} (or "(default)")`, "warning");
+
+				const inheritLabel = scope === "project" ? "Use inherited value" : "Use default (delete global override)";
+				const hasLocalOverride = localLayer[row.key] !== undefined;
+
+				if (row.kind === "boolean") {
+					const effective = snapshot.provenance.get(String(row.key))?.value === true;
+					const actions = [
+						`Set ${scope} override to true`,
+						`Set ${scope} override to false`,
+					];
+					if (hasLocalOverride) actions.push(inheritLabel);
+					actions.push("Cancel");
+					const action = await ctx.ui.select(`${row.label} (${scope})`, actions);
+					if (!action || action === "Cancel") continue;
+					if (action === inheritLabel) {
+						applyMutation(scope, { op: "unset", path: [row.key] });
+						continue;
+					}
+					const value = action.endsWith("true");
+					if (value !== effective || !hasLocalOverride) {
+						applyMutation(scope, { op: "set", path: [row.key], value });
+					}
 					continue;
 				}
-				saveSettings(next);
-				ctx.ui.notify(`Settings saved:\n${settingsLines(loadGoalSettingsFileConfig(ctx.cwd)).join("\n")}`, "info");
-				continue;
-			}
-			// modelSelector rows (provider, model): searchable auditor model
-			// picker with current-session/default, authenticated models (\u2713
-			// marker on the exact current selection), and a manual
-			// provider/model entry (ll01 pattern). Either row applies the same
-			// provider+model pair.
-			const configured = configuredAuditorModelKey(config);
-			const session = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
-			const choices = buildAuditorModelChoices(ctx.modelRegistry.getAvailable(), configured, session);
-			const filter = await ctx.ui.input("Filter auditor models (provider/id/name; blank = all)", "");
-			if (filter === undefined) continue;
-			const filtered = filterAuditorModelChoices(choices, filter);
-			const picked = await ctx.ui.select("Select auditor model", filtered.map((choice) => choice.label));
-			if (!picked) continue;
-			const choice = filtered.find((candidate: AuditorChoice) => candidate.label === picked);
-			if (!choice) continue;
-			const next: GoalSettings = { ...config };
-			if (choice.kind === "default") {
-				delete next.provider;
-				delete next.model;
-			} else if (choice.kind === "manual") {
-				const input = await ctx.ui.input("Set auditor provider/model", configured ?? "provider/model");
-				if (input === undefined) continue;
-				const parsed = parseManualAuditorModel(input);
-				if ("error" in parsed) {
-					ctx.ui.notify(parsed.error, "warning");
+
+				if (row.kind === "positiveInteger") {
+					const min = (row.key === "stallTimeoutMinutes" || row.key === "objectiveMaxChars") ? 0 : 1;
+					const actions = [`Set ${scope} override...`];
+					if (hasLocalOverride) actions.push(inheritLabel);
+					actions.push("Cancel");
+					const action = await ctx.ui.select(`${row.label} (${scope})`, actions);
+					if (!action || action === "Cancel") continue;
+					if (action === inheritLabel) {
+						applyMutation(scope, { op: "unset", path: [row.key] });
+						continue;
+					}
+					const input = await ctx.ui.input(`Set ${row.label}`, String(snapshot.provenance.get(String(row.key))?.value ?? min));
+					if (input === undefined) continue;
+					// Full-string decimal validation: rejects 1.5, 1x, negatives,
+					// infinity, and unsafe integers alike.
+					const value = input.trim();
+					if (!/^[0-9]+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < min) {
+						ctx.ui.notify(`${row.label} must be an integer >= ${min} (e.g. ${min}, ${min + 1}, ${min + 2})`, "warning");
+						continue;
+					}
+					applyMutation(scope, { op: "set", path: [row.key], value: Number(value) });
 					continue;
 				}
-				next.provider = parsed.provider;
-				next.model = parsed.model;
-			} else {
-				next.provider = choice.provider;
-				next.model = choice.model;
-			}
-			saveSettings(next);
-			ctx.ui.notify(`Settings saved:\n${settingsLines(loadGoalSettingsFileConfig(ctx.cwd)).join("\n")}`, "info");
+
+				if (row.kind === "thinking") {
+					const currentValue = settingsValue(snapshot.value, row.key);
+					const levels = thinkingLevelChoices(currentValue === "(default)" ? undefined : currentValue);
+					const picked = await ctx.ui.select(`Set ${row.label} (${scope})`, levels);
+					if (!picked) continue;
+					const choice = picked.trim().replace(/^\u2713\s+/, "");
+					if (choice === "(default)") {
+						if (hasLocalOverride) applyMutation(scope, { op: "unset", path: ["thinkingLevel"] });
+						continue;
+					}
+					if (!(AUDITOR_THINKING_LEVELS as readonly string[]).includes(choice)) {
+						ctx.ui.notify(`thinking_level must be one of: ${AUDITOR_THINKING_LEVELS.join(", ")} (or "(default)")`, "warning");
+						continue;
+					}
+					applyMutation(scope, { op: "set", path: ["thinkingLevel"], value: choice });
+					continue;
+				}
+
+				// modelSelector rows (provider, model): searchable auditor model
+				// picker with explicit inherit/default handling. Either row applies
+				// the same provider+model pair.
+				const configured = configuredAuditorModelKey(snapshot.value as GoalSettings);
+				const session = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+				const choices = buildAuditorModelChoices(ctx.modelRegistry.getAvailable(), configured, session);
+				const filter = await ctx.ui.input("Filter auditor models (provider/id/name; blank = all)", "");
+				if (filter === undefined) continue;
+				const filtered = filterAuditorModelChoices(choices, filter);
+				const picked = await ctx.ui.select("Select auditor model", filtered.map((choice: AuditorChoice) => choice.label));
+				if (!picked) continue;
+				const choice = filtered.find((candidate: AuditorChoice) => candidate.label === picked);
+				if (!choice) continue;
+				if (choice.kind === "default") {
+					for (const key of ["provider", "model"] as const) {
+						if (localLayer[key] !== undefined) applyMutation(scope, { op: "unset", path: [key] });
+					}
+					continue;
+				}
+				let providerValue: string;
+				let modelValue: string;
+				if (choice.kind === "manual") {
+					const input = await ctx.ui.input("Set auditor provider/model", configured ?? "provider/model");
+					if (input === undefined) continue;
+					const parsed = parseManualAuditorModel(input);
+					if ("error" in parsed) {
+						ctx.ui.notify(parsed.error, "warning");
+						continue;
+					}
+					providerValue = parsed.provider;
+					modelValue = parsed.model;
+				} else {
+					providerValue = choice.provider;
+					modelValue = choice.model;
+				}
+				if (applyMutation(scope, { op: "set", path: ["provider"], value: providerValue })) {
+					applyMutation(scope, { op: "set", path: ["model"], value: modelValue });
+				}
 			}
 		} finally {
 			core.exitGoalModal();
 		}
 	}
-
 	async function handleGoalClear(ctx: ExtensionContext): Promise<void> {
 		core.reconcileFocusedGoalFromDisk(ctx);
 		if (!core.state.goal && core.openGoals().length > 0) {

package/extensions/goal-events.ts

@@ -17,9 +17,10 @@ import { shouldArmPostCompactReminder, shouldInjectPostCompactReminder } from ".
 import { formatTokenValue } from "./goal-core.ts";
 import { loadGoalSettings, invalidateGoalSettingsCache } from "./goal-settings.ts";
 import { budgetLine, budgetRemaining } from "./goal-accounting.ts";
-import { asRecord, nowIso, type AssistantMessageLike } from "./goal-record.ts";
+import { asRecord, nowIso, type AssistantMessageLike, type GoalRecord } from "./goal-record.ts";
 import { goalSelectorLabel } from "./goal-pool.ts";
-import { invalidateGoalPoolCache } from "./storage/goal-files.ts";import {
+import { invalidateGoalPoolCache } from "./storage/goal-files.ts";
+import { checkpointTriggerPrompt } from "./prompts/goal-prompts.ts";import {
 	goalPrompt,
 	staleContinuationPrompt,
 	unfocusedOpenGoalsPrompt,
@@ -30,6 +31,56 @@ import { syncTerminalInputPause } from "./goal-widget.ts";
 import type { GoalCore } from "./goal-state.ts";
 import type { GoalMutationOutcome } from "./goal-service.ts";
 
+/**
+ * Issue #30: provider-context checkpoint compaction (pure helper).
+ *
+ * Every historical checkpoint message is redundant: its authoritative state is
+ * reconstructed from goal storage and injected once per turn by
+ * before_agent_start. Normal provider requests therefore retain at most ONE
+ * checkpoint marker — the latest — rewritten to the tiny bounded v2 trigger
+ * content. Keeping one user-role turn-start marker avoids provider edge cases
+ * where removing it would leave the request ending on an assistant or tool
+ * result. Audit events, user messages, assistant messages, and tool results
+ * pass through untouched.
+ */
+export function compactGoalCheckpointContext(
+	messages: readonly unknown[],
+	currentGoal: GoalRecord | null,
+): unknown[] | null {
+	let lastCheckpointIndex = -1;
+	for (let i = 0; i < messages.length; i += 1) {
+		if (goalEventMessageId(messages[i] as { customType?: string; details?: unknown; content?: unknown }) !== null) {
+			lastCheckpointIndex = i;
+		}
+	}
+	if (lastCheckpointIndex < 0) return null;
+
+	const output: unknown[] = [];
+	for (let i = 0; i < messages.length; i += 1) {
+		const message = messages[i] as { customType?: string; details?: unknown; content?: unknown };
+		const checkpointGoalId = goalEventMessageId(message);
+		if (checkpointGoalId === null) {
+			output.push(messages[i]);
+			continue;
+		}
+		// Every historical checkpoint is dropped entirely.
+		if (i !== lastCheckpointIndex) continue;
+		output.push({
+			...(message as Record<string, unknown>),
+			content: checkpointTriggerPrompt(checkpointGoalId),
+			display: false,
+			details: {
+				version: 2,
+				kind: currentGoal?.id === checkpointGoalId && currentGoal?.status === "active" ? "checkpoint" : "stale",
+				goalId: checkpointGoalId,
+				currentGoalId: currentGoal?.id ?? null,
+				currentStatus: currentGoal?.status ?? null,
+			},
+		});
+	}
+	return output;
+}
+
 /**
  * The goal extension's lifecycle event handlers (context, turn_start,
  * tool_call, tool_execution_end, turn_end, message_end, session_start,
@@ -41,40 +92,10 @@ export function registerGoalEvents(core: GoalCore): void {
 	const { pi } = core;
 	let continuationAfterSettleFor: string | null = null;
 
-	pi.on("context", async (event): Promise<{ messages: typeof event.messages } | undefined> => {
-		let changed = false;
-		const latestGoalEventIndex = new Map<string, number>();
-		event.messages.forEach((message, index) => {
-			const queuedGoalId = goalEventMessageId(message as { customType?: string; details?: unknown; content?: unknown });
-			if (queuedGoalId) latestGoalEventIndex.set(queuedGoalId, index);
-		});
-
-		const messages = event.messages.map((message, index) => {
-			const candidate = message as { customType?: string; details?: unknown; content?: unknown };
-			const queuedGoalId = goalEventMessageId(candidate);
-			if (!queuedGoalId) return message;
-			if (
-				core.state.goal?.id === queuedGoalId
-				&& (core.state.goal.status === "active")
-				&& core.state.goal.autoContinue
-				&& latestGoalEventIndex.get(queuedGoalId) === index
-			) return message;
-			changed = true;
-			const details = asRecord(candidate.details) ?? {};
-			return {
-				...message,
-				content: staleContinuationPrompt(queuedGoalId, core.state.goal),
-				display: false,
-				details: {
-					...details,
-					kind: "stale",
-					goalId: queuedGoalId,
-					currentGoalId: core.state.goal?.id ?? null,
-					currentStatus: core.state.goal?.status ?? null,
-				},
-			} as typeof message;
-		});
-		return changed ? { messages } : undefined;
+	pi.on("context", async (event) => {
+		const messages = compactGoalCheckpointContext(event.messages, core.state.goal);
+		// Reference equality means no goal-event messages existed at all.
+		return messages === null ? undefined : { messages: messages as typeof event.messages };
 	});
 
 	pi.on("turn_start", async (_event, ctx) => {

package/extensions/goal-format.ts

@@ -176,17 +176,38 @@ export function renderGoalAuditEvent(message: { content?: unknown; details?: Goa
 	);
 }
 
-export function extractGoalIdFromInjectedMessage(text: string): string | null {
+/**
+ * Issue #30 v2 markers are self-closing and carry an explicit version:
+ * `<pi_goal_continuation goal_id="..." kind="checkpoint" v="2"/>`.
+ */
+function matchV2SelfClosingContinuation(text: string): string | null {
+	const match = text.match(/^<pi_goal_continuation\s+goal_id="([^"]+)"[^>]*v="2"\s*\/?>/);
+	return match?.[1] ?? null;
+}
+
+function matchLegacyContinuation(text: string): string | null {
 	// Phase 5 C1: structured outer marker `<pi_goal_continuation goal_id="..." kind="...">`.
 	// Borrowed from pi-codex-goal. More robust than bare bracket text because
 	// the angle brackets + attributes are nearly impossible for users to type
 	// by accident, and the structure is grep-able / parse-able by external tooling.
 	const xmlMatch = text.match(/^<pi_goal_continuation\s+goal_id="([^"]+)"/);
 	if (xmlMatch) return xmlMatch[1] ?? null;
+	return null;
+}
+
+function matchLegacyBracketCheckpoint(text: string): string | null {
 	const match = text.match(/^\[(?:GOAL CHECKPOINT|GOAL CONTINUATION|GOAL STALE) goalId=([^\]\s]+)\]/);
 	return match?.[1] ?? null;
 }
 
+export function extractGoalIdFromInjectedMessage(text: string): string | null {
+	return (
+		matchV2SelfClosingContinuation(text)
+		?? matchLegacyContinuation(text)
+		?? matchLegacyBracketCheckpoint(text)
+	);
+}
+
 export function goalEventMessageId(message: { customType?: string; details?: unknown; content?: unknown }): string | null {
 	if (message.customType !== GOAL_EVENT_ENTRY) return null;
 	const details = asRecord(message.details);

package/extensions/goal-record.ts

@@ -81,7 +81,24 @@ export interface GoalFocusEntry {
 	reason: GoalFocusReason;
 }
 
-export interface GoalEventDetails {
+/**
+ * Issue #30 v2 checkpoint details: a tiny structured trigger record. Never
+ * contains objective text, task text, verification contracts, budget strings,
+ * or policy text — the authoritative state is injected once per turn by
+ * before_agent_start from goal storage.
+ */
+export interface GoalCheckpointDetailsV2 {
+	version: 2;
+	kind: "checkpoint";
+	goalId: string;
+	status: "active";
+	revision: number;
+	checkpointSeq: number;
+	timestamp: number;
+}
+
+/** Pre-v2 event details (full objective persisted). Read-only legacy shape. */
+export interface LegacyGoalEventDetails {
 	kind: GoalEventKind;
 	goalId: string;
 	status?: GoalStatus;
@@ -93,6 +110,23 @@ export interface GoalEventDetails {
 	focus?: GoalMode;
 }
 
+/** Historical "stale" rewrite of a checkpoint that no longer matches the goal. */
+export interface GoalStaleDetails {
+	kind: "stale";
+	goalId: string;
+	currentGoalId?: string | null;
+	currentStatus?: GoalStatus | null;
+}
+
+/** Everything that can appear in a persisted pi-goal-event entry's details. */
+export type GoalEventEntryDetails = GoalCheckpointDetailsV2 | LegacyGoalEventDetails | GoalStaleDetails;
+
+/**
+ * Legacy normalized renderer shape. Kept as the stable contract for
+ * renderGoalEvent / registerMessageRenderer; v2 entries normalize into it.
+ */
+export type GoalEventDetails = LegacyGoalEventDetails;
+
 export interface GoalCreationConfig {
 	objective: string;
 	autoContinue: boolean;