@oh-my-pi/pi-coding-agent 15.11.4 → 15.11.7

package/src/cli-commands.ts

@@ -16,6 +16,7 @@ export const commands: CommandEntry[] = [
 	{ name: "auth-broker", load: () => import("./commands/auth-broker").then(m => m.default) },
 	{ name: "auth-gateway", load: () => import("./commands/auth-gateway").then(m => m.default) },
 	{ name: "agents", load: () => import("./commands/agents").then(m => m.default) },
+	{ name: "bench", load: () => import("./commands/bench").then(m => m.default) },
 	{ name: "commit", load: () => import("./commands/commit").then(m => m.default) },
 	{ name: "completions", load: () => import("./commands/completions").then(m => m.default) },
 	{ name: "__complete", load: () => import("./commands/complete").then(m => m.default) },

package/src/commands/bench.ts

@@ -0,0 +1,42 @@
+import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { runBenchCommand } from "../cli/bench-cli";
+
+export default class Bench extends Command {
+	static description =
+		"Benchmark models with the same prompt: time-to-first-token and generation throughput (tokens/s)";
+
+	static args = {
+		models: Args.string({
+			description: "Model selectors (provider/model or fuzzy id, e.g. opus)",
+			required: true,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		runs: Flags.integer({ description: "Requests per model (results are averaged)", default: 1 }),
+		"max-tokens": Flags.integer({ description: "Max output tokens per request", default: 512 }),
+		prompt: Flags.string({ description: "Custom prompt text (default: bundled bench prompt)" }),
+		json: Flags.boolean({ description: "Output JSON" }),
+	};
+
+	static examples = [
+		"# Compare two models\n  omp bench anthropic/claude-opus-4-5 openai/gpt-5.2",
+		"# Fuzzy selectors work\n  omp bench opus sonnet",
+		"# Average over 3 runs each\n  omp bench opus gpt-5.2 --runs 3",
+		"# Machine-readable output\n  omp bench opus --json",
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Bench);
+		await runBenchCommand({
+			models: args.models ?? [],
+			flags: {
+				runs: flags.runs,
+				maxTokens: flags["max-tokens"],
+				prompt: flags.prompt,
+				json: flags.json,
+			},
+		});
+	}
+}

package/src/commands/usage.ts

@@ -15,6 +15,11 @@ export default class Usage extends Command {
 			description: "Redact account emails/ids (shortest unique prefix) for sharing screenshots",
 			default: false,
 		}),
+		history: Flags.boolean({
+			description: "Show recorded usage-limit history (hourly snapshots) instead of a live snapshot",
+			default: false,
+		}),
+		days: Flags.integer({ char: "d", description: "History window in days (with --history)", default: 7 }),
 	};
 
 	static examples = [
@@ -22,6 +27,7 @@ export default class Usage extends Command {
 		"# Only Anthropic accounts\n  omp usage --provider anthropic",
 		"# Redact account identifiers for screenshots\n  omp usage --redact",
 		"# Machine-readable output\n  omp usage --json",
+		"# Usage-limit trend over the last 30 days\n  omp usage --history --days 30",
 	];
 
 	async run(): Promise<void> {
@@ -30,6 +36,8 @@ export default class Usage extends Command {
 			json: flags.json,
 			provider: flags.provider,
 			redact: flags.redact,
+			history: flags.history,
+			days: flags.days,
 		});
 	}
 }

package/src/config/model-registry.ts

@@ -20,6 +20,11 @@ import {
 	UNK_CONTEXT_WINDOW,
 	UNK_MAX_TOKENS,
 } from "@oh-my-pi/pi-catalog/provider-models";
+import {
+	collapseBuiltModelVariants,
+	getVariantAliasSources,
+	resolveVariantAlias,
+} from "@oh-my-pi/pi-catalog/variant-collapse";
 
 // Sentinel for local-only OAuth token (LM Studio, vLLM) — declared inline to avoid loading
 // any provider module at startup. Must match `DEFAULT_LOCAL_TOKEN` in oauth/lm-studio.ts.
@@ -542,7 +547,37 @@ function normalizeSuppressedSelector(selector: string): string {
 	if (!trimmed) return trimmed;
 	const parsed = parseModelString(trimmed);
 	if (!parsed) return trimmed;
-	return `${parsed.provider}/${parsed.id}`;
+	// Retired effort-tier variant ids normalize to their collapsed logical id
+	// so persisted suppressions keyed by raw member ids still bind.
+	const aliasId = resolveVariantAlias(parsed.provider, parsed.id);
+	return `${parsed.provider}/${aliasId ?? parsed.id}`;
+}
+
+/**
+ * Look up a model's override, falling back to entries keyed by retired
+ * effort-tier variant ids (models.yml authored before collapsing). A raw key
+ * only re-binds when no live model holds that id.
+ */
+function resolveModelOverrideWithAliases(
+	overrides: Map<string, ModelOverride>,
+	model: Model<Api>,
+	hasLiveModel: (provider: string, id: string) => boolean,
+): ModelOverride | undefined {
+	const direct = overrides.get(model.id);
+	if (direct) return direct;
+	for (const rawId of getVariantAliasSources(model.provider, model.id)) {
+		if (hasLiveModel(model.provider, rawId)) continue;
+		const remapped = overrides.get(rawId);
+		if (remapped) {
+			logger.debug("model override re-keyed through variant alias", {
+				provider: model.provider,
+				from: rawId,
+				to: model.id,
+			});
+			return remapped;
+		}
+	}
+	return undefined;
 }
 
 function getDisabledProviderIdsFromSettings(): Set<string> {
@@ -799,7 +834,9 @@ export class ModelRegistry {
 		const withConfigModels = this.#mergeCustomModels(resolvedDefaults, this.#customModelOverlays);
 		// Merge runtime extension models so they survive refresh() cycles
 		const combined = this.#mergeCustomModels(withConfigModels, this.#runtimeModelOverlays);
-		const withModelOverrides = this.#applyModelOverrides(combined, this.#modelOverrides);
+		// Custom/config providers bypass the model-manager merge point —
+		// collapse effort-tier variants here so X/X-thinking twins fold.
+		const withModelOverrides = this.#applyModelOverrides(collapseBuiltModelVariants(combined), this.#modelOverrides);
 		this.#models = this.#applyRuntimeProviderOverrides(withModelOverrides);
 		this.#rebuildCanonicalIndex();
 		this.#lastStaticLoadMtime = this.#modelsConfigFile.getMtimeMs();
@@ -1152,7 +1189,7 @@ export class ModelRegistry {
 		const withConfigModels = this.#mergeCustomModels(resolved, this.#customModelOverlays);
 		// Merge runtime extension models so they survive online discovery completion
 		const combined = this.#mergeCustomModels(withConfigModels, this.#runtimeModelOverlays);
-		const withModelOverrides = this.#applyModelOverrides(combined, this.#modelOverrides);
+		const withModelOverrides = this.#applyModelOverrides(collapseBuiltModelVariants(combined), this.#modelOverrides);
 		this.#models = this.#applyRuntimeProviderOverrides(withModelOverrides);
 		this.#rebuildCanonicalIndex();
 	}
@@ -1398,8 +1435,13 @@ export class ModelRegistry {
 	#applyProviderModelOverrides(provider: string, models: Model<Api>[]): Model<Api>[] {
 		const overrides = this.#modelOverrides.get(provider);
 		if (!overrides || overrides.size === 0) return models;
+		let liveIds: Set<string> | null = null;
+		const hasLiveModel = (_provider: string, id: string) => {
+			liveIds ??= new Set(models.map(m => m.id));
+			return liveIds.has(id);
+		};
 		return models.map(model => {
-			const override = overrides.get(model.id);
+			const override = resolveModelOverrideWithAliases(overrides, model, hasLiveModel);
 			if (!override) return model;
 			return applyModelOverride(model, override);
 		});
@@ -1443,10 +1485,15 @@ export class ModelRegistry {
 	}
 	#applyModelOverrides(models: Model<Api>[], overrides: Map<string, Map<string, ModelOverride>>): Model<Api>[] {
 		if (overrides.size === 0) return models;
+		let liveKeys: Set<string> | null = null;
+		const hasLiveModel = (provider: string, id: string) => {
+			liveKeys ??= new Set(models.map(m => `${m.provider}\u0000${m.id}`));
+			return liveKeys.has(`${provider}\u0000${id}`);
+		};
 		return models.map(model => {
 			const providerOverrides = overrides.get(model.provider);
 			if (!providerOverrides) return model;
-			const override = providerOverrides.get(model.id);
+			const override = resolveModelOverrideWithAliases(providerOverrides, model, hasLiveModel);
 			if (!override) return model;
 			return applyModelOverride(model, override);
 		});

package/src/config/model-resolver.ts

@@ -3,8 +3,9 @@
  *
  * Layering:
  * - `matchModel` is the single matching engine. Order: exact `provider/id`
- *   reference (with OpenRouter routed/date fallbacks) → exact canonical id →
- *   exact bare id → provider-scoped fuzzy → substring with alias-vs-dated pick.
+ *   reference (with variant-alias and OpenRouter routed/date fallbacks) →
+ *   exact canonical id → exact bare id → retired variant alias →
+ *   provider-scoped fuzzy → substring with alias-vs-dated pick.
  * - `parseModelPatternWithContext`/`parseModelPattern` layer the selector
  *   grammar on top: trailing `:level` thinking suffixes (`splitThinkingSuffix`)
  *   and `@upstream` provider routing (`splitUpstreamRouting`).
@@ -19,9 +20,11 @@ import type { Api, Effort, KnownProvider, Model, ModelSpec } from "@oh-my-pi/pi-
 import { buildModel } from "@oh-my-pi/pi-catalog/build";
 import { modelMatchesHost } from "@oh-my-pi/pi-catalog/hosts";
 import { buildModelProviderPriorityRank } from "@oh-my-pi/pi-catalog/identity";
+import { stripThinkingVariantToken } from "@oh-my-pi/pi-catalog/identity/family";
 import { clampThinkingLevelForModel } from "@oh-my-pi/pi-catalog/model-thinking";
 import { modelsAreEqual } from "@oh-my-pi/pi-catalog/models";
 import { DEFAULT_MODEL_PER_PROVIDER } from "@oh-my-pi/pi-catalog/provider-models";
+import { resolveBareVariantAlias, resolveVariantAlias } from "@oh-my-pi/pi-catalog/variant-collapse";
 import { fuzzyMatch } from "@oh-my-pi/pi-tui";
 import { logger } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
@@ -228,6 +231,18 @@ export function resolveProviderModelReference(
 		return exact;
 	}
 
+	// Retired effort-tier variant ids resolve to their collapsed logical
+	// model: hand-table aliases first, then the `X-thinking` → `X` grammar
+	// for auto-derived pairs. Exact lookup above always wins while raw is live.
+	const variantAliasId =
+		resolveVariantAlias(normalizedProvider, normalizedModelId) ?? stripThinkingVariantToken(normalizedModelId);
+	if (variantAliasId) {
+		const aliased = index.get(`${normalizedProvider}\u0000${variantAliasId.toLowerCase()}`);
+		if (aliased) {
+			return aliased;
+		}
+	}
+
 	if (normalizedProvider !== "openrouter") {
 		return undefined;
 	}
@@ -407,11 +422,13 @@ function findExactCanonicalModelMatch(
 
 /**
  * The single model-matching engine. Tries, in order:
- * 1. exact `provider/id` reference (OpenRouter routed/date fallbacks included),
+ * 1. exact `provider/id` reference (variant-alias and OpenRouter routed/date
+ *    fallbacks included),
  * 2. exact canonical id (coalesces provider variants),
  * 3. exact bare id (preference-ranked),
- * 4. provider-scoped fuzzy match,
- * 5. substring match with the alias-vs-dated pick.
+ * 4. retired effort-tier variant alias (collapsed catalog entries),
+ * 5. provider-scoped fuzzy match,
+ * 6. substring match with the alias-vs-dated pick.
  * Returns the matched model or undefined if no match found.
  */
 function matchModel(
@@ -440,6 +457,20 @@ function matchModel(
 	if (exactMatches.length > 0) {
 		return pickPreferredModel(exactMatches, context);
 	}
+
+	// Retired effort-tier variant ids (bare, no provider prefix) resolve to
+	// their collapsed logical model; models from the providers whose table
+	// declared the alias win ties. Auto-derived `X-thinking` pairs resolve
+	// through the grammar fallback.
+	const bareAlias = resolveBareVariantAlias(modelPattern);
+	const bareAliasTargetId = bareAlias?.id ?? stripThinkingVariantToken(modelPattern);
+	if (bareAliasTargetId) {
+		const aliasMatches = availableModels.filter(m => m.id.toLowerCase() === bareAliasTargetId.toLowerCase());
+		if (aliasMatches.length > 0) {
+			const preferred = bareAlias ? aliasMatches.filter(m => bareAlias.providers.includes(m.provider)) : [];
+			return pickPreferredModel(preferred.length > 0 ? preferred : aliasMatches, context);
+		}
+	}
 	// Check for provider/modelId format — fuzzy match within provider only.
 	const slashIndex = modelPattern.indexOf("/");
 	if (slashIndex !== -1) {

package/src/config/settings-schema.ts

@@ -1,4 +1,5 @@
 import { THINKING_EFFORTS } from "@oh-my-pi/pi-ai";
+import { SHAPE_VARIANT_NAMES } from "@oh-my-pi/snapcompact";
 import { AUTO_THINKING, getConfiguredThinkingLevelMetadata, getThinkingLevelMetadata } from "../thinking";
 import {
 	TINY_MODEL_DEVICE_DEFAULT,
@@ -1572,14 +1573,28 @@ export const SETTINGS_SCHEMA = {
 
 	// Experimental: snapcompact inline imaging (transient, per-request; never persisted)
 	"snapcompact.systemPrompt": {
-		type: "boolean",
-		default: false,
+		type: "enum",
+		values: ["none", "agents-md", "all"] as const,
+		default: "none",
 		ui: {
 			tab: "context",
 			group: "Experimental",
 			label: "Snapcompact System Prompt",
 			description:
-				"Experimental: render the system prompt as dense PNG image(s) and attach to the first user message (vision models only). Saves tokens; loses system-prompt prompt caching.",
+				"Experimental: render selected system prompt text as dense PNG image(s) and attach to the first user message (vision models only). Saves tokens; loses prompt caching for imaged text.",
+			options: [
+				{ value: "none", label: "None", description: "Keep the system prompt as text." },
+				{
+					value: "agents-md",
+					label: "AGENTS.md",
+					description: "Only move loaded context-file instructions to images, when that saves tokens.",
+				},
+				{
+					value: "all",
+					label: "All",
+					description: "Move the full system prompt to images, when that saves tokens.",
+				},
+			],
 		},
 	},
 
@@ -1595,6 +1610,97 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"snapcompact.shape": {
+		type: "enum",
+		values: ["auto", ...SHAPE_VARIANT_NAMES] as const,
+		default: "auto",
+		ui: {
+			tab: "context",
+			group: "Experimental",
+			label: "Snapcompact Shape",
+			description:
+				"Frame shape snapcompact prints text with (compaction archive and inline imaging). Auto picks a shape tuned for the current model.",
+			options: [
+				{
+					value: "auto",
+					label: "Auto",
+					description: "Picks a shape tuned for the current model, falling back to its provider family.",
+				},
+				{
+					value: "8x8r-bw",
+					label: "8x8 repeated, black",
+					description:
+						"unscii square cell, black ink, every line printed twice with the copy on a pale highlight band.",
+				},
+				{
+					value: "8x8r-sent",
+					label: "8x8 repeated, sentence hues",
+					description: "Repeated grid with ink cycling six hues at sentence boundaries.",
+				},
+				{
+					value: "8x8u-bw",
+					label: "8x8, black",
+					description: "Plain unscii square cell, single-printed lines, black ink.",
+				},
+				{
+					value: "8x8u-sent",
+					label: "8x8, sentence hues",
+					description: "Plain unscii square cell with sentence-hue ink.",
+				},
+				{
+					value: "6x6u-bw",
+					label: "6x6 dense, black",
+					description: "unscii squeezed to 6x6 — densest readable cell, fewest frames — in black ink.",
+				},
+				{
+					value: "6x6u-sent",
+					label: "6x6 dense, sentence hues",
+					description: "Densest cell with sentence-hue ink.",
+				},
+				{
+					value: "5x8-bw",
+					label: "5x8 legacy, black",
+					description: "Original X.org 5x8 glyphs on the 2576px frame, black ink.",
+				},
+				{
+					value: "5x8-sent",
+					label: "5x8 legacy, sentence hues",
+					description: "The original snapcompact shape (pre-shape-table sessions rendered this).",
+				},
+				{
+					value: "6x12-dim",
+					label: "6x12, dimmed stopwords",
+					description: "X.org 6x12 glyphs, black ink, function words dimmed gray.",
+				},
+				{
+					value: "8x13-bw",
+					label: "8x13, black",
+					description: "X.org 8x13 glyphs, black ink.",
+				},
+				{
+					value: "8on16-bw",
+					label: "8x13 on 16px pitch, black",
+					description: "8x13 glyphs on an 8x16 cell (extra leading), black ink.",
+				},
+				{
+					value: "doc-8on16-bw",
+					label: "Doc 8on16, black",
+					description: "Two word-wrapped newspaper columns of 8x13 glyphs on a 16px pitch, black ink.",
+				},
+				{
+					value: "doc-8on16-sent",
+					label: "Doc 8on16, sentence hues",
+					description: "Two-column doc layout with sentence-hue ink.",
+				},
+				{
+					value: "doc-8on16-sent-dim",
+					label: "Doc 8on16, sentence hues + dimmed stopwords",
+					description: "Two-column doc layout, sentence-hue ink, function words dimmed gray.",
+				},
+			],
+		},
+	},
+
 	// Branch summaries
 	"branchSummary.enabled": {
 		type: "boolean",
@@ -3617,6 +3723,39 @@ export const SETTINGS_SCHEMA = {
 			],
 		},
 	},
+	// Codex saved rate-limit resets (auto-redeem)
+	"codexResets.autoRedeem": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "providers",
+			group: "Services",
+			label: "Codex Auto-Redeem Saved Resets",
+			description:
+				"When a turn is blocked by the Codex weekly limit on the active account and no other account is available, automatically spend one saved rate-limit reset (ChatGPT 'save rate limit resets'). Conservative: never fires for 5-hour-only or Spark limits, near a natural reset, or twice for the same block. Requires retries enabled.",
+		},
+	},
+	"codexResets.minBlockedMinutes": {
+		type: "number",
+		default: 60,
+		ui: {
+			tab: "providers",
+			group: "Services",
+			label: "Codex Auto-Redeem Min Block",
+			description:
+				"Only auto-redeem when the natural weekly reset is at least this many minutes away (don't spend a ~30-day credit to save a short wait).",
+		},
+	},
+	"codexResets.keepCredits": {
+		type: "number",
+		default: 0,
+		ui: {
+			tab: "providers",
+			group: "Services",
+			label: "Codex Auto-Redeem Reserve",
+			description: "Never auto-spend below this many saved resets (0 = the last credit may be spent automatically).",
+		},
+	},
 	"provider.appendOnlyContext": {
 		type: "enum",
 		values: ["auto", "on", "off"] as const,
@@ -4005,6 +4144,11 @@ export interface ShellMinimizerSettings {
 	sourceOutlineLevel: "default" | "aggressive";
 	legacyFilters: boolean | undefined;
 }
+export interface CodexResetsSettings {
+	autoRedeem: boolean;
+	minBlockedMinutes: number;
+	keepCredits: number;
+}
 
 /** Map group prefix -> typed settings interface */
 export interface GroupTypeMap {
@@ -4024,6 +4168,7 @@ export interface GroupTypeMap {
 	modelTags: ModelTagsSettings;
 	cycleOrder: string[];
 	shellMinimizer: ShellMinimizerSettings;
+	codexResets: CodexResetsSettings;
 }
 
 export type GroupPrefix = keyof GroupTypeMap;

package/src/config/settings.ts

@@ -798,6 +798,15 @@ export class Settings {
 			raw["compaction.strategy"] = "shake";
 		}
 
+		// snapcompact.systemPrompt: boolean -> scoped enum.
+		const snapcompactObj = raw.snapcompact as Record<string, unknown> | undefined;
+		if (snapcompactObj && typeof snapcompactObj.systemPrompt === "boolean") {
+			snapcompactObj.systemPrompt = snapcompactObj.systemPrompt ? "all" : "none";
+		}
+		if (typeof raw["snapcompact.systemPrompt"] === "boolean") {
+			raw["snapcompact.systemPrompt"] = raw["snapcompact.systemPrompt"] ? "all" : "none";
+		}
+
 		// statusLine: rename "plan_mode" segment to "mode"
 		const statusLineObj = raw.statusLine as Record<string, unknown> | undefined;
 		if (statusLineObj) {

package/src/edit/renderer.ts

@@ -579,6 +579,11 @@ function wrapEditRendererLine(line: string, width: number): string[] {
 
 export const editToolRenderer = {
 	mergeCallAndResult: true,
+	// Pending preview is a TAIL window of the streamed diff ("… N more lines
+	// above" + last rows); the result render re-anchors the block top-first, so
+	// committing the preview's settled head would strand a stale call-box
+	// fragment in native scrollback.
+	provisionalPendingPreview: true,
 
 	renderCall(
 		args: EditRenderArgs,

package/src/hindsight/client.ts

@@ -546,7 +546,7 @@ interface BuiltMemoryItem {
 function buildMemoryItem(item: MemoryItemInput): BuiltMemoryItem {
 	const out: BuiltMemoryItem = { content: item.content };
 	if (item.timestamp !== undefined) {
-		out.timestamp = item.timestamp instanceof Date ? item.timestamp.toISOString() : item.timestamp;
+		out.timestamp = item.timestamp instanceof Date ? formatDateWithLocalOffset(item.timestamp) : item.timestamp;
 	}
 	if (item.context !== undefined) out.context = item.context;
 	if (item.metadata !== undefined) out.metadata = item.metadata;
@@ -558,6 +558,31 @@ function buildMemoryItem(item: MemoryItemInput): BuiltMemoryItem {
 	return out;
 }
 
+function formatDateWithLocalOffset(date: Date): string {
+	const offsetMinutes = date.getTimezoneOffset();
+	const offsetSign = offsetMinutes <= 0 ? "+" : "-";
+	const absoluteOffset = Math.abs(offsetMinutes);
+	const offsetHours = Math.floor(absoluteOffset / 60);
+	const offsetRemainderMinutes = absoluteOffset % 60;
+	const milliseconds = date.getMilliseconds();
+	const millisecondsPart = milliseconds === 0 ? "" : `.${pad3(milliseconds)}`;
+	return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}T${pad2(
+		date.getHours(),
+	)}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}${millisecondsPart}${offsetSign}${pad2(
+		offsetHours,
+	)}:${pad2(offsetRemainderMinutes)}`;
+}
+
+function pad2(value: number): string {
+	return value < 10 ? `0${value}` : String(value);
+}
+
+function pad3(value: number): string {
+	if (value < 10) return `00${value}`;
+	if (value < 100) return `0${value}`;
+	return String(value);
+}
+
 function buildQueryString(query: Record<string, unknown>): string {
 	const params = new URLSearchParams();
 	for (const [key, value] of Object.entries(query)) {

package/src/hindsight/state.ts

@@ -26,6 +26,7 @@ const RETAIN_FLUSH_INTERVAL_MS = 5_000;
 interface PendingRetainItem {
 	content: string;
 	context?: string;
+	timestamp: Date;
 }
 
 interface RecallOutcome {
@@ -84,7 +85,7 @@ export class HindsightRetainQueue {
 		if (this.#closed) {
 			throw new Error("Hindsight retain queue is closed.");
 		}
-		this.#items.push({ content, context });
+		this.#items.push({ content, context, timestamp: new Date() });
 
 		if (this.#items.length >= RETAIN_FLUSH_BATCH_SIZE) {
 			void this.flush();
@@ -154,6 +155,7 @@ export class HindsightRetainQueue {
 				context: item.context ?? state.config.retainContext,
 				metadata: { session_id: sessionId },
 				tags: state.retainTags,
+				timestamp: item.timestamp,
 			}));
 			await state.client.retainBatch(state.bankId, batch, { async: true });
 			if (state.config.debug) {
@@ -281,6 +283,7 @@ export class HindsightSessionState {
 	}
 
 	async retainSession(messages: HindsightMessage[]): Promise<void> {
+		const retainedAt = new Date();
 		const retainFullWindow = this.config.retainMode === "full-session";
 		let target: HindsightMessage[];
 		let documentId: string;
@@ -291,7 +294,7 @@ export class HindsightSessionState {
 		} else {
 			const windowTurns = this.config.retainEveryNTurns + this.config.retainOverlapTurns;
 			target = sliceLastTurnsByUserBoundary(messages, windowTurns);
-			documentId = `${this.sessionId}-${Date.now()}`;
+			documentId = `${this.sessionId}-${retainedAt.getTime()}`;
 		}
 
 		const { transcript } = prepareRetentionTranscript(target, true);
@@ -303,6 +306,7 @@ export class HindsightSessionState {
 			context: this.config.retainContext,
 			metadata: { session_id: this.sessionId },
 			tags: this.retainTags,
+			timestamp: retainedAt,
 			async: true,
 		});
 	}