@oh-my-pi/pi-coding-agent 17.1.8 → 17.2.0

package/src/advisor/runtime.ts

@@ -2,6 +2,7 @@ import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import { estimateTokens } from "@oh-my-pi/pi-agent-core/compaction";
 import type { AssistantMessage, ImageContent, TextContent } from "@oh-my-pi/pi-ai";
 import * as AIError from "@oh-my-pi/pi-ai/error";
+import { raceWithSignal } from "@oh-my-pi/pi-ai/utils/abort";
 import { type CursorExecResolvedCarrier, kCursorExecResolved } from "@oh-my-pi/pi-ai/utils/block-symbols";
 import { logger } from "@oh-my-pi/pi-utils";
 import { obfuscateToolArguments, type SecretObfuscator } from "../secrets/obfuscator";
@@ -47,7 +48,7 @@ export interface AdvisorRuntimeHost {
 	 * recovery path must never replay the full primary transcript.
 	 * Optional: hosts that omit it get no proactive maintenance.
 	 */
-	maintainContext?(incomingTokens: number): Promise<boolean>;
+	maintainContext?(incomingTokens: number, signal: AbortSignal): Promise<boolean>;
 	/**
 	 * Called immediately before each `agent.prompt(batch)` cycle. Lets the host
 	 * clear per-update advisor state — currently the one-advise-per-update gate
@@ -67,6 +68,7 @@ export interface AdvisorRuntimeHost {
 	onTurnError?(
 		error: unknown,
 		failedMessages: readonly AgentMessage[],
+		signal: AbortSignal,
 	): Promise<boolean | undefined> | boolean | undefined;
 	/** Called after a successful advisor turn so the host can finish fallback lifecycle reporting. */
 	onTurnSuccess?(): Promise<void> | void;
@@ -76,6 +78,8 @@ export interface AdvisorRuntimeHost {
 	 *  recovery (credential switch, fallback chain) declined. Cleared only by
 	 *  an explicit reset (`/new`, config rebuild, session restart). */
 	notifyQuotaExhausted?(): void;
+	/** Stable identity for the live advisor model. Used to restore full transcript rendering after a model switch. */
+	getModelIdentity?(): string;
 }
 
 /**
@@ -228,7 +232,6 @@ const MAX_COALESCE_ROUNDS = 3;
 const MAX_QUARANTINE_RETRIES = 2;
 
 const ADVISOR_RENDER_OPTIONS = {
-	includeThinking: true,
 	includeToolIntent: true,
 	watchedRoles: true,
 	expandPrimaryContext: true,
@@ -285,11 +288,17 @@ export class AdvisorRuntime {
 	#advisorRegexSecretValues = new Set<string>();
 	#pending: PendingDelta[] = [];
 	#busy = false;
+	#sessionTransitionPaused = false;
+	#promptInFlight: Promise<void> | undefined;
+	#iterationAbort: AbortController | undefined;
 	#backlog = 0;
 	#consecutiveFailures = 0;
 	#failureNotified = false;
 	/** Consecutive quarantined turns since the last success/reset (issue #6661). */
 	#consecutiveQuarantines = 0;
+	/** Whether primary reasoning is included in advisor deltas for the current model. */
+	#includeThinking = true;
+	#modelIdentity: string | undefined;
 	/** Completed 3-failure backlog-drop cycles since the last success/reset. */
 	#droppedBacklogs = 0;
 	/**
@@ -428,6 +437,7 @@ export class AdvisorRuntime {
 	}
 
 	dispose(): void {
+		this.#iterationAbort?.abort("advisor disposed");
 		this.disposed = true;
 		this.#epoch++;
 		this.#pending = [];
@@ -490,6 +500,31 @@ export class AdvisorRuntime {
 		});
 	}
 
+	/** Stop new advisor work and wait only for the active prompt's recorder-visible events. */
+	pauseForSessionTransition(): Promise<void> {
+		if (!this.#sessionTransitionPaused) {
+			this.#sessionTransitionPaused = true;
+			this.#wakeAllWaiters();
+			this.#iterationAbort?.abort("advisor session transition");
+			try {
+				this.agent.abort("advisor session transition");
+			} catch {}
+		}
+		return (
+			this.#promptInFlight?.then(
+				() => {},
+				() => {},
+			) ?? Promise.resolve()
+		);
+	}
+
+	/** Continue queued work after a session transition rolls back or preserves the conversation. */
+	resumeAfterSessionTransition(): void {
+		if (!this.#sessionTransitionPaused) return;
+		this.#sessionTransitionPaused = false;
+		if (!this.#quotaExhausted && !this.#halted) void this.#drain();
+	}
+
 	/**
 	 * Re-prime the advisor after a history rewrite (compaction, session
 	 * switch/resume, branch). Clears the advisor's own (non-persisted) context
@@ -498,7 +533,9 @@ export class AdvisorRuntime {
 	 * leaving it blind to everything before the rewrite.
 	 */
 	reset(): void {
+		this.#iterationAbort?.abort("advisor reset");
 		this.#epoch++;
+		this.#sessionTransitionPaused = false;
 		this.#quotaExhausted = false;
 		this.#halted = false;
 		this.#failing = false;
@@ -530,13 +567,23 @@ export class AdvisorRuntime {
 		this.#wakeAllWaiters();
 	}
 
+	#syncModelIdentity(): void {
+		const identity = this.host.getModelIdentity?.();
+		if (identity === undefined || identity === this.#modelIdentity) return;
+		this.#modelIdentity = identity;
+		this.#includeThinking = true;
+	}
+
 	#formatRawDelta(rawMessages: AgentMessage[], wip = false): string | null {
 		const delta = rawMessages
 			.filter(message => !(message.role === "custom" && message.customType === "advisor"))
 			.map(message => this.#dedupContextMessage(message));
 		if (delta.length === 0) return null;
 		const obfuscator = this.host.obfuscator;
-		let md = formatSessionHistoryMarkdown(delta, ADVISOR_RENDER_OPTIONS);
+		let md = formatSessionHistoryMarkdown(delta, {
+			...ADVISOR_RENDER_OPTIONS,
+			includeThinking: this.#includeThinking,
+		});
 		if (!md.trim()) return null;
 		if (obfuscator?.hasSecrets()) {
 			let discoveredNewRegexSecretValue = false;
@@ -570,7 +617,7 @@ export class AdvisorRuntime {
 						? obfuscateAdvisorMessage(obfuscator, message, this.#advisorRegexSecretValues)
 						: message,
 				),
-				ADVISOR_RENDER_OPTIONS,
+				{ ...ADVISOR_RENDER_OPTIONS, includeThinking: this.#includeThinking },
 			);
 			md = obfuscator.obfuscate(md, this.#advisorRegexSecretValues);
 		}
@@ -696,6 +743,7 @@ export class AdvisorRuntime {
 		epoch: number,
 		initial: PendingDelta[],
 		recoveringOverflow: boolean,
+		signal: AbortSignal,
 	): Promise<{
 		batch: string | null;
 		rawMessages: AgentMessage[];
@@ -712,11 +760,12 @@ export class AdvisorRuntime {
 		let wip = initial.at(-1)?.wip ?? false;
 
 		for (let round = 0; round < MAX_COALESCE_ROUNDS; round++) {
+			if (this.#sessionTransitionPaused) break;
 			if (this.host.maintainContext) {
 				const incomingTokens = estimateTokens({ role: "user", content: batchText, timestamp: Date.now() });
 				let shouldResetContext = false;
 				try {
-					shouldResetContext = await this.host.maintainContext(incomingTokens);
+					shouldResetContext = await this.host.maintainContext(incomingTokens, signal);
 				} catch (err) {
 					logger.debug("advisor context maintenance failed", { err: String(err) });
 				}
@@ -733,6 +782,7 @@ export class AdvisorRuntime {
 					// remain queued and ship as their own subsequent batch.
 					if (round > 0) {
 						const lateItems = this.#pending.splice(0);
+						initial.push(...lateItems);
 						turns += lateItems.reduce((sum, b) => sum + b.turns, 0);
 						if (lateItems.length > 0) {
 							wip = lateItems.at(-1)!.wip;
@@ -769,6 +819,7 @@ export class AdvisorRuntime {
 			// update WIP state, and re-check the maintenance budget.
 			const late = this.#pending.splice(0);
 			if (late.length === 0) break;
+			initial.push(...late);
 			batchText = [batchText, ...late.map(b => b.text)].join("\n\n");
 			rawMessages = rawMessages.concat(late.flatMap(b => b.rawMessages));
 			turns += late.reduce((sum, b) => sum + b.turns, 0);
@@ -802,10 +853,12 @@ export class AdvisorRuntime {
 	}
 
 	async #drain(): Promise<void> {
-		if (this.#busy) return;
+		if (this.#busy || this.#sessionTransitionPaused) return;
 		this.#busy = true;
 		try {
-			while (!this.disposed && this.#pending.length) {
+			this.#syncModelIdentity();
+			while (!this.disposed && !this.#sessionTransitionPaused && this.#pending.length) {
+				this.#syncModelIdentity();
 				let popped: PendingDelta[];
 				if (this.#pending[0]?.overflowRecovery) {
 					const recovery = this.#pending.shift();
@@ -814,6 +867,8 @@ export class AdvisorRuntime {
 				} else {
 					popped = this.#pending.splice(0);
 				}
+				const iterationAbort = new AbortController();
+				this.#iterationAbort = iterationAbort;
 				const epoch = this.#epoch;
 				for (const delta of popped) {
 					if (delta.renderRevision === this.#renderRevision) continue;
@@ -822,10 +877,19 @@ export class AdvisorRuntime {
 					delta.renderRevision = this.#renderRevision;
 				}
 				const recoveringOverflow = popped.some(delta => delta.overflowRecovery === true);
-				const result = await this.#collectAndMaintainBatch(epoch, popped, recoveringOverflow);
+				const result = await this.#collectAndMaintainBatch(
+					epoch,
+					popped,
+					recoveringOverflow,
+					iterationAbort.signal,
+				);
 
 				// Epoch was invalidated during batch collection; restart the loop.
 				if (result === null) continue;
+				if (this.#sessionTransitionPaused) {
+					this.#pending.unshift(...popped);
+					continue;
+				}
 
 				const { batch, rawMessages, finalTurns, wip, resetContext } = result;
 
@@ -847,7 +911,13 @@ export class AdvisorRuntime {
 					// Reset the host's per-update advisor state (one-advise-per-update
 					// gate) before each model cycle so the new batch starts fresh.
 					this.host.beginAdvisorUpdate?.();
-					await this.agent.prompt(batch);
+					const prompt = this.agent.prompt(batch);
+					this.#promptInFlight = prompt;
+					try {
+						await prompt;
+					} finally {
+						if (this.#promptInFlight === prompt) this.#promptInFlight = undefined;
+					}
 					// Agent.#runLoop catches provider/stream failures internally and
 					// resolves prompt() cleanly with stopReason: "error". Treat that
 					// as a failed turn so endpoint rejections trip the retry path.
@@ -868,12 +938,17 @@ export class AdvisorRuntime {
 					this.#consecutiveQuarantines = 0;
 					if (this.host.onTurnSuccess) {
 						try {
-							await this.host.onTurnSuccess();
+							await raceWithSignal(Promise.resolve(this.host.onTurnSuccess()), iterationAbort.signal);
 						} catch (hookErr) {
 							logger.debug("advisor onTurnSuccess hook failed", { err: String(hookErr) });
 						}
 					}
 				} catch (err) {
+					if (this.#sessionTransitionPaused) {
+						this.#rollbackFailedTurn(messageSnapshot);
+						this.#pending.unshift(...popped);
+						continue;
+					}
 					// reset()/dispose() aborts the in-flight prompt; treat it as a
 					// reset, not a transient failure — drop the stale batch.
 					if (this.#epoch !== epoch) continue;
@@ -885,6 +960,9 @@ export class AdvisorRuntime {
 					this.#wakeAllWaiters();
 					const failedMessages = this.agent.state.messages.slice(messageSnapshot);
 					const terminalFailure = this.#terminalAssistantFailure(messageSnapshot);
+					const classifierRefusal =
+						(terminalFailure !== undefined && isClassifierRefusal(terminalFailure)) ||
+						AIError.is(AIError.classify(err), AIError.Flag.ContentBlocked);
 					const terminalFailureId =
 						terminalFailure === undefined ? undefined : AIError.classifyMessage(terminalFailure);
 					const contextOverflow =
@@ -900,12 +978,43 @@ export class AdvisorRuntime {
 						AIError.is(terminalFailureId, AIError.Flag.ContextOverflow);
 					this.#rollbackFailedTurn(messageSnapshot);
 					logger.debug("advisor turn failed", { err: String(err) });
+					if (classifierRefusal) {
+						if (this.#includeThinking) {
+							this.#includeThinking = false;
+							const strippedBatch = this.#formatRawDelta(rawMessages, wip);
+							if (strippedBatch) {
+								this.#pending.unshift({
+									text: strippedBatch,
+									rawMessages,
+									renderRevision: this.#renderRevision,
+									turns: finalTurns,
+									wip,
+									overflowRecovery: recoveringOverflow || undefined,
+								});
+								logger.debug("advisor refusal recovered by stripping primary reasoning");
+								continue;
+							}
+						}
+						this.#notifyFailureOnce(err);
+						this.#clearSeenContext();
+						this.#backlog = Math.max(0, this.#backlog - finalTurns);
+						this.#notifyWaiters();
+						continue;
+					}
 					let recovered = false;
 					try {
-						recovered = (await this.host.onTurnError?.(err, failedMessages)) === true;
+						recovered =
+							(await raceWithSignal(
+								Promise.resolve(this.host.onTurnError?.(err, failedMessages, iterationAbort.signal)),
+								iterationAbort.signal,
+							)) === true;
 					} catch (hookErr) {
 						logger.debug("advisor onTurnError hook failed", { err: String(hookErr) });
 					}
+					if (this.#sessionTransitionPaused) {
+						this.#pending.unshift(...popped);
+						continue;
+					}
 					if (err instanceof AdvisorOutputQuarantinedError) {
 						// A quarantine discards the advisor's whole turn before dispatch, so
 						// its advice never reaches the primary. One re-prime is allowed to
@@ -1020,7 +1129,15 @@ export class AdvisorRuntime {
 								wip,
 								overflowRecovery: recoveringOverflow || undefined,
 							});
-							await Bun.sleep(this.retryDelayMs);
+							if (this.retryDelayMs <= 0) {
+								await Bun.sleep(0);
+							} else {
+								try {
+									await raceWithSignal(Bun.sleep(this.retryDelayMs), iterationAbort.signal);
+								} catch (sleepError) {
+									if (!iterationAbort.signal.aborted) throw sleepError;
+								}
+							}
 						}
 					}
 				}
@@ -1031,11 +1148,20 @@ export class AdvisorRuntime {
 				}
 			}
 		} finally {
+			this.#iterationAbort = undefined;
 			this.#busy = false;
 		}
 	}
 }
 
+/** Mirrors turn recovery's refusal classification and retains AIError's provider-neutral content-block fallback. */
+function isClassifierRefusal(message: AssistantMessage): boolean {
+	if (message.stopReason !== "error") return false;
+	const stopType = message.stopDetails?.type;
+	if (stopType === "refusal" || stopType === "sensitive") return true;
+	return AIError.is(AIError.classifyMessage(message), AIError.Flag.ContentBlocked);
+}
+
 /**
  * The only malformed advisor turn shape: the prompt resolved but produced no
  * assistant response at all. Everything an assistant message carries — advice,

package/src/advisor/transcript-recorder.ts

@@ -1,7 +1,9 @@
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { Message, UserMessage } from "@oh-my-pi/pi-ai";
 import { logger } from "@oh-my-pi/pi-utils";
+import { visitEntriesFromFileStream } from "../session/session-loader";
 import { SessionManager } from "../session/session-manager";
 
 /**
@@ -31,6 +33,60 @@ export function isAdvisorTranscriptName(name: string): boolean {
 	);
 }
 
+/**
+ * Sum the advisor spend already persisted next to a primary session transcript,
+ * keyed by advisor slug.
+ *
+ * The ledger a session keeps in memory only covers the current process, so a
+ * resumed session would report zero until the next advisor turn. The recorded
+ * transcripts are the durable copy of exactly the same finalized messages, so
+ * they are read back through the shared loader - no lock, no writer, and no
+ * second parser to keep in step with the session format.
+ *
+ * Only the session's own advisors count: subagent advisors write to
+ * `<session>/<SubId>/__advisor.jsonl`, and their spend belongs to the subagent,
+ * not to this roster. Hence the scan stays at the top level of the directory.
+ */
+export async function loadAdvisorTranscriptCosts(sessionFile: string | undefined): Promise<Map<string, number>> {
+	const costs = new Map<string, number>();
+	if (!sessionFile?.endsWith(JSONL_SUFFIX)) return costs;
+	const directory = sessionFile.slice(0, -JSONL_SUFFIX.length);
+	const dirents = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+	for (const dirent of dirents) {
+		if (!dirent.isFile() || !isAdvisorTranscriptName(dirent.name)) continue;
+		const slug =
+			dirent.name === ADVISOR_TRANSCRIPT_FILENAME
+				? ""
+				: dirent.name.slice(`${ADVISOR_TRANSCRIPT_STEM}.`.length, -JSONL_SUFFIX.length);
+		let total = 0;
+		let validHeader: boolean | undefined;
+		try {
+			await visitEntriesFromFileStream(path.join(directory, dirent.name), entry => {
+				const isObject = typeof entry === "object" && entry !== null;
+				if (validHeader === undefined) {
+					validHeader = isObject && entry.type === "session" && typeof entry.id === "string";
+					return;
+				}
+				// A syntactically valid but non-object entry (e.g. a bare `null`
+				// line) must cost only itself, not crash entry.type access and
+				// discard everything accumulated for this transcript.
+				if (!validHeader || !isObject || entry.type !== "message") return;
+				const message = entry.message;
+				if (!message || typeof message !== "object" || message.role !== "assistant") return;
+				// One malformed usage block must cost that entry only, not the
+				// whole transcript's total.
+				const total_ = message.usage?.cost?.total;
+				if (typeof total_ === "number" && Number.isFinite(total_)) total += total_;
+			});
+		} catch (err) {
+			logger.debug("advisor transcript cost read failed", { file: dirent.name, err: String(err) });
+			continue;
+		}
+		if (total > 0) costs.set(slug, total);
+	}
+	return costs;
+}
+
 /**
  * Append-only persister for an advisor agent's transcript.
  *

package/src/auto-thinking/classifier.ts

@@ -5,7 +5,8 @@
  * {@link Effort}, clamped into the active model's supported range (never below
  * {@link Effort.Low}). Two backends, selected by `providers.autoThinkingModel`:
  *
- * - `online` (default): a smol model classifies into `low|medium|high|xhigh`.
+ * - `online` (default): a smol model classifies into `low|medium|high|xhigh`,
+ *   plus `max` when the target model exposes that tier.
  * - a local key: an on-device memory model classifies into the coarser
  *   `trivial|moderate|hard` scheme (3-class is more reliable than 4-way ordinal
  *   on sub-2B models), mapped to `low|high|xhigh`.
@@ -14,6 +15,7 @@
  * the caller falls back to a concrete level and continues the turn.
  */
 import { type AssistantMessage, completeSimple, Effort, type Model } from "@oh-my-pi/pi-ai";
+import { getSupportedEfforts } from "@oh-my-pi/pi-catalog/model-thinking";
 import { prompt } from "@oh-my-pi/pi-utils";
 
 import type { ModelRegistry } from "../config/model-registry";
@@ -30,7 +32,31 @@ import {
 } from "../tiny/models";
 import { tinyModelClient } from "../tiny/title-client";
 
-const DIFFICULTY_SYSTEM_PROMPT = prompt.render(difficultySystemPrompt);
+/**
+ * Rendered classifier prompts, keyed by whether `max` is offered as a label.
+ * Two variants only, so both are memoized on first use.
+ */
+const DIFFICULTY_SYSTEM_PROMPTS: Partial<Record<"max" | "xhigh", string>> = {};
+
+/**
+ * Highest effort this turn's classification may resolve to: the configured
+ * ceiling, further limited by what the target model actually exposes. The
+ * default keeps `auto` one tier below the top, so only an explicit
+ * `ultrathink` reaches {@link Effort.Max}.
+ */
+function autoEffortCeiling(deps: ClassifyDifficultyDeps): Effort {
+	if (deps.settings.get("providers.autoThinkingMaxEffort") !== Effort.Max) return Effort.XHigh;
+	return getSupportedEfforts(deps.model).includes(Effort.Max) ? Effort.Max : Effort.XHigh;
+}
+
+function difficultySystemPromptFor(ceiling: Effort): string {
+	const key = ceiling === Effort.Max ? "max" : "xhigh";
+	const cached = DIFFICULTY_SYSTEM_PROMPTS[key];
+	if (cached !== undefined) return cached;
+	const rendered = prompt.render(difficultySystemPrompt, { allowMax: key === "max" });
+	DIFFICULTY_SYSTEM_PROMPTS[key] = rendered;
+	return rendered;
+}
 
 /** Local classifiers occasionally need more room for chat-template boilerplate. */
 const LOCAL_ANSWER_MAX_TOKENS = 16;
@@ -64,14 +90,18 @@ export async function classifyDifficulty(
 ): Promise<Effort | undefined> {
 	const backend = deps.settings.get("providers.autoThinkingModel");
 	const input = preprocessTinyMessage(promptText);
-	const effort =
-		backend === ONLINE_AUTO_THINKING_MODEL_KEY
-			? await classifyOnline(input, deps)
-			: await classifyLocal(input, backend, deps);
-	return clampAutoThinkingEffort(deps.model, effort);
+	const online = backend === ONLINE_AUTO_THINKING_MODEL_KEY;
+	// The 3-bucket local classifier cannot select `max`, so its ceiling stays at
+	// XHigh whatever the setting says — otherwise a sparse ladder would snap its
+	// `hard` bucket up to a tier it never chose.
+	const ceiling = online ? autoEffortCeiling(deps) : Effort.XHigh;
+	const effort = online ? await classifyOnline(input, deps, ceiling) : await classifyLocal(input, backend, deps);
+	// The ceiling goes into the clamp itself: capping the request alone is not
+	// enough, because a sparse ladder snaps an excluded request back up.
+	return clampAutoThinkingEffort(deps.model, effort, ceiling);
 }
 
-async function classifyOnline(input: string, deps: ClassifyDifficultyDeps): Promise<Effort> {
+async function classifyOnline(input: string, deps: ClassifyDifficultyDeps, ceiling: Effort): Promise<Effort> {
 	const resolved = resolveRoleSelection(["tiny", "smol"], deps.settings, deps.registry.getAvailable());
 	const model = resolved?.model;
 	if (!model) {
@@ -88,7 +118,7 @@ async function classifyOnline(input: string, deps: ClassifyDifficultyDeps): Prom
 	const response = await completeSimple(
 		model,
 		{
-			systemPrompt: [DIFFICULTY_SYSTEM_PROMPT],
+			systemPrompt: [difficultySystemPromptFor(ceiling)],
 			messages: [{ role: "user", content: input, timestamp: Date.now() }],
 		},
 		{
@@ -134,7 +164,13 @@ async function classifyLocal(input: string, modelKey: string, deps: ClassifyDiff
 	return effort;
 }
 
-/** Map the online 4-way level keyword to an {@link Effort}; earliest match wins. */
+/**
+ * Map an online level keyword to an {@link Effort}; earliest match wins.
+ *
+ * `max` is only offered to the classifier when the target model exposes that
+ * tier, but it is always parsed: an unsupported `max` is snapped back down by
+ * {@link clampAutoThinkingEffort} rather than failing the turn.
+ */
 export function parseDifficultyLevel(text: string): Effort | undefined {
 	const lower = text.toLowerCase();
 	const candidates: Array<[number, Effort]> = [];
@@ -142,6 +178,8 @@ export function parseDifficultyLevel(text: string): Effort | undefined {
 	// inside "xhigh" (no word boundary between `x` and `h`), so the two never collide.
 	const xhigh = lower.search(/x[\s_-]?high/);
 	if (xhigh >= 0) candidates.push([xhigh, Effort.XHigh]);
+	const max = lower.search(/\bmax\b/);
+	if (max >= 0) candidates.push([max, Effort.Max]);
 	const high = lower.search(/\bhigh\b/);
 	if (high >= 0) candidates.push([high, Effort.High]);
 	const medium = lower.search(/\bmed(?:ium)?\b/);

package/src/cli/args.ts

@@ -44,6 +44,8 @@ export interface Args {
 	advisor?: boolean;
 	continue?: boolean;
 	resume?: string | true;
+	fromClaude?: boolean;
+	fromCodex?: boolean;
 	help?: boolean;
 	version?: boolean;
 	mode?: Mode;
@@ -227,6 +229,10 @@ export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { ty
 			result.alias = arg.slice("--alias=".length);
 		} else if (arg === "--continue" || arg === "-c") {
 			result.continue = true;
+		} else if (arg === "--from-claude") {
+			result.fromClaude = true;
+		} else if (arg === "--from-codex") {
+			result.fromCodex = true;
 		} else if (arg === "--no-session") {
 			result.noSession = true;
 		} else if (arg === "--no-tools") {

package/src/cli/flag-tables.ts

@@ -290,6 +290,8 @@ export const VALUELESS_FLAGS: ReadonlySet<string> = new Set([
 	"--version",
 	"--allow-home",
 	"--continue",
+	"--from-claude",
+	"--from-codex",
 	"--no-session",
 	"--no-tools",
 	"--no-lsp",

package/src/cli/gallery-fixtures/fs.ts

@@ -1,5 +1,6 @@
 // biome-ignore-all lint/suspicious/noTemplateCurlyInString: sample source-code strings (read fixtures) intentionally contain literal ${...}.
 // Gallery fixtures for the filesystem tools (read, write, glob).
+import type { Usage } from "@oh-my-pi/pi-ai";
 import { ReadToolGroupComponent } from "../../modes/components/read-tool-group";
 import type { GalleryFixture, GalleryFixtureState, GalleryResult } from "./types";
 
@@ -47,6 +48,15 @@ const groupedReadDelimitedPath = groupedReadTargets.join(",");
 const groupedReadRepeatedFile = "packages/coding-agent/src/task/render.ts";
 const groupedReadRepeatedRanges = `${groupedReadRepeatedFile}:507-605,1070-1194,1210-1240,1270-1274`;
 
+const GROUPED_READ_USAGE: Usage = {
+	input: 2400,
+	output: 113,
+	cacheRead: 103_000,
+	cacheWrite: 0,
+	totalTokens: 105_513,
+	cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+
 function textResult(text: string, details?: unknown, isError?: boolean): GalleryResult {
 	return { content: [{ type: "text", text }], details, isError };
 }
@@ -81,6 +91,13 @@ function renderReadGroupFixtureState(state: GalleryFixtureState, width: number,
 		false,
 		"read-delimited",
 	);
+	component.attachUsage(
+		["read-delimited"],
+		GROUPED_READ_USAGE,
+		5300,
+		2200,
+		new Date(2026, 6, 28, 21, 5, 47).getTime(),
+	);
 
 	if (state === "error") {
 		component.updateResult(
@@ -88,10 +105,18 @@ function renderReadGroupFixtureState(state: GalleryFixtureState, width: number,
 			false,
 			"read-ranges",
 		);
+		component.attachUsage(
+			["read-ranges"],
+			GROUPED_READ_USAGE,
+			4700,
+			1900,
+			new Date(2026, 6, 28, 21, 5, 52).getTime(),
+		);
 		return component.render(width);
 	}
 
 	component.updateResult(textResult("Read four render.ts ranges."), false, "read-ranges");
+	component.attachUsage(["read-ranges"], GROUPED_READ_USAGE, 4700, 1900, new Date(2026, 6, 28, 21, 5, 52).getTime());
 	return component.render(width);
 }