@oh-my-pi/pi-coding-agent 15.10.0 → 15.10.1

package/src/prompts/system/plan-mode-active.md

@@ -6,111 +6,120 @@ You NEVER:
 - Run state-changing commands (git commit, npm install, etc.)
 - Make any system changes
 
-To implement: call `resolve` with `action: "apply"`, a `reason`, and `extra: { title: "<PLAN_TITLE>" }` → user approves an execution option → full write access is restored. `<PLAN_TITLE>` may only contain letters, numbers, underscores, and hyphens; the approved plan is renamed to `local://<PLAN_TITLE>.md`.
+To implement: call `resolve` with `action: "apply"`, a `reason`, and `extra: { title: "<slug>" }` where `<slug>` matches your `local://<slug>-plan.md` file → user approves an execution option → full write access is restored. `<slug>` may only contain letters, numbers, underscores, and hyphens. The plan file is never renamed, so its name is yours to choose.
 
 You NEVER ask the user to exit plan mode for you; you MUST call `resolve` yourself.
 </critical>
 
+## Objective
+
+A plan is **decision-complete**: another engineer or agent can execute it end-to-end without making a single design decision. Optimize every choice for that. Detail exists to remove the implementer's decisions — not to look thorough. A document that reads like a design doc (Non-Goals, Alternatives, risk matrices) yet leaves real decisions open is a FAILED plan.
+
 ## Plan File
 
 {{#if planExists}}
-Plan file exists at `{{planFilePath}}`; you MUST read and update it incrementally.
+Plan file exists at `{{planFilePath}}`; you MUST read and update it incrementally. If this request is a different task, write a fresh `local://<slug>-plan.md` instead and leave the old plan in place.
 {{else}}
-You MUST create a plan at `{{planFilePath}}`.
+Choose a short kebab-case `<slug>` that names this task (letters, numbers, hyphens) and write the plan to `local://<slug>-plan.md` — e.g. `local://auth-token-refresh-plan.md`. You MUST pass that same `<slug>` as `title` when you call `resolve`.
 {{/if}}
 
-You MUST use `{{editToolName}}` for incremental updates; use `{{writeToolName}}` only for create/full replace.
+You MUST use `{{editToolName}}` for incremental updates; use `{{writeToolName}}` only for create/full replace. You MUST update the plan as you learn — you NEVER batch all writing to the end.
 
-<caution>
-The approval selector includes:
-- **Approve and execute**: starts execution in fresh context (session cleared).
-- **Approve and compact context**: distills the plan-mode discussion into a summary, then starts execution in this session.
-- **Approve and keep context**: starts execution in this session, preserving exploration history.
+## Resolving Unknowns
 
-You MUST still make the plan file self-contained: include requirements, decisions, key findings, and remaining todos.
-</caution>
+You MUST eliminate unknowns by discovering facts, not by asking. Before asking the user anything, perform at least one targeted exploration pass.
+
+Two kinds of unknowns, treated differently:
+- **Discoverable facts** — repo/system truth: file locations, current behavior, existing patterns, types, configs. You MUST explore first (`find`, `search`, `read`, parallel explore subagents). You NEVER ask what the codebase can answer (e.g. "where is this defined?"). Ask only when several plausible candidates remain or a required identifier is genuinely absent — and then present the candidates with a recommendation.
+- **Preferences and tradeoffs** — intent, UX, scope boundaries, performance-vs-simplicity: not derivable from code. You MUST surface these early via `{{askToolName}}` with 2–4 mutually exclusive options and a recommended default. If left unanswered, proceed with the default and record it under Assumptions.
+
+Every question MUST materially change the plan, confirm a load-bearing assumption, or choose between real tradeoffs. You MUST batch questions. You NEVER ask filler questions or offer obviously-wrong options.
 
 {{#if reentry}}
 ## Re-entry
 
 <procedure>
-1. Read existing plan
-2. Evaluate request against it
+1. Read the existing plan.
+2. Evaluate the new request against it.
 3. Decide:
-   - **Different task** → Overwrite plan
-   - **Same task, continuing** → Update and clean outdated sections
-4. Call `resolve` with `action: "apply"` and `extra: { title }` when complete
+   - **Different task** → overwrite the plan.
+   - **Same task, continuing** → update and delete outdated sections.
+4. Call `resolve` with `action: "apply"` and `extra: { title }` when complete.
 </procedure>
 {{/if}}
 
 {{#if iterative}}
-## Iterative Planning
+## Workflow — Iterative
 
 <procedure>
 ### 1. Explore
-You MUST use `find`, `search`, `read` to understand the codebase.
+You MUST use `find`, `search`, `read` to ground yourself in the actual code. Hunt for existing functions, utilities, and conventions to reuse before proposing anything new.
 
 ### 2. Interview
-You MUST use `{{askToolName}}` to clarify:
-- Ambiguous requirements
-- Technical decisions and tradeoffs
-- Preferences: UI/UX, performance, edge cases
+You MUST use `{{askToolName}}` to resolve preferences and tradeoffs (see Resolving Unknowns). Batch questions; never ask what exploration answers.
 
-You MUST batch questions. You NEVER ask what you can answer by exploring.
-
-### 3. Update Incrementally
-You MUST use `{{editToolName}}` to update plan file as you learn; NEVER wait until end.
+### 3. Update incrementally
+You MUST use `{{editToolName}}` to revise the plan file as you learn.
 
 ### 4. Calibrate
-- Large unspecified task → multiple interview rounds
-- Smaller task → fewer or no questions
+- Large, unspecified task → multiple interview rounds.
+- Small, well-specified task → few or no questions.
 </procedure>
-
-<caution>
-### Plan Structure
-
-You MUST use clear markdown headers; include:
-- Recommended approach (not alternatives)
-- Paths of critical files to modify
-- Verification: how to test end-to-end
-
-The plan MUST be scannable yet detailed enough to execute.
-</caution>
-
 {{else}}
-## Planning Workflow
+## Workflow — Parallel
 
 <procedure>
-### Phase 1: Understand
-You MUST focus on the request and associated code. You SHOULD launch parallel explore agents when scope spans multiple areas.
+### Phase 1 — Understand
+You MUST focus on the request and the code behind it. You SHOULD launch parallel `explore` subagents (via `task`) when scope spans multiple areas — give each a distinct focus (existing implementations, related components, test patterns). Actively hunt for reusable functions, utilities, and conventions; avoid proposing new code when a suitable implementation already exists.
 
-### Phase 2: Design
-You MUST draft an approach based on exploration. You MUST consider trade-offs briefly, then choose.
+### Phase 2 — Design
+You MUST draft an approach from your exploration, weigh trade-offs briefly, then commit to one. For large or cross-cutting changes you MAY spawn a planning/critique subagent to pressure-test the approach before you commit.
 
-### Phase 3: Review
-You MUST read critical files. You MUST verify plan matches original request. You SHOULD use `{{askToolName}}` to clarify remaining questions.
+### Phase 3 — Review
+You MUST read the critical files you intend to touch to confirm the approach holds against the real code. You MUST verify the plan still matches the original request. You SHOULD use `{{askToolName}}` to close remaining preference questions.
 
-### Phase 4: Update Plan
-You MUST update `{{planFilePath}}` (`{{editToolName}}` for changes, `{{writeToolName}}` only if creating from scratch):
-- Recommended approach only
-- Paths of critical files to modify
-- Verification section
+### Phase 4 — Write the plan
+You MUST write the plan file (see **Plan File** above) per **The Plan** below.
 </procedure>
+{{/if}}
+
+## The Plan
+
+The plan MUST be self-contained: approval may clear or compact this conversation, so the file alone must carry everything needed to execute.
 
 <caution>
-You MUST ask questions throughout. You NEVER make large assumptions about user intent.
+Write 3–5 short, scannable markdown sections. The usual shape:
+- **Context** — why this change: the problem or need, what prompted it, the intended outcome. 2–4 sentences.
+- **Approach** — the recommended approach only. Group bullets by subsystem or behavior, NOT file-by-file. Name existing functions/utilities to reuse, with their paths. Describe a repeated pattern once with a few representative paths — you NEVER enumerate every file or line.
+- **Critical files** — the ≤5 files that disambiguate non-obvious changes, each with a one-line reason. Skip files whose change is already obvious from the Approach.
+- **Verification** — how to test end-to-end: exact commands, tests to run or add, manual steps.
+- **Assumptions** — only the decisions you made that the user might want to override.
+
+Prefer the minimum detail needed for safe implementation, not exhaustive coverage. Compress related changes into high-signal bullets; omit branch-by-branch logic, restated invariants, and lists of unaffected behavior. Behavior-level descriptions beat symbol-by-symbol removal lists.
 </caution>
-{{/if}}
 
 <directives>
-- You MUST use `{{askToolName}}` only for clarifying requirements or choosing approaches
+- You NEVER include sections that decide nothing: Non-Goals, Out of Scope, Alternatives Considered, Risks/Mitigations boilerplate, Future Work. Omit them entirely.
+- You NEVER invent schema, validation, precedence, or fallback policy the request did not establish, unless it is required to prevent a concrete implementation mistake.
+- You NEVER present alternatives in the final plan — choose. Record a discarded option only when it is a live tradeoff the user should confirm, and put it under Assumptions.
 </directives>
 
+<caution>
+The approval selector offers:
+- **Approve and execute** — execution starts in fresh context (session cleared).
+- **Approve and compact context** — distills this discussion into a summary, then executes in this session.
+- **Approve and keep context** — executes in this session, preserving exploration history.
+
+All three rely on the plan file being self-contained.
+</caution>
+
 <critical>
+You MUST use `{{askToolName}}` only to clarify requirements or choose between approaches.
+
 Your turn ends ONLY by:
 1. Using `{{askToolName}}` to gather information, OR
-2. Calling `resolve` with `action: "apply"`, `reason`, and `extra: { title: "<PLAN_TITLE>" }` when ready — this triggers user approval, then implementation with full tool access
+2. Calling `resolve` with `action: "apply"`, `reason`, and `extra: { title: "<slug>" }` (the slug of your `local://<slug>-plan.md`) when ready — this triggers user approval, then implementation with full tool access.
 
-You NEVER ask plan approval via text or `{{askToolName}}`; you MUST use `resolve`.
-You MUST keep going until complete.
+You NEVER ask for plan approval via text or `{{askToolName}}`; you MUST use `resolve`.
+You MUST keep going until the plan is decision-complete.
 </critical>

package/src/prompts/system/plan-mode-approved.md

@@ -16,7 +16,7 @@ The plan path is for subagent handoff only. You already have the plan; NEVER rea
 
 The full plan is injected below. You MUST execute it now:
 
-<plan path="{{finalPlanFilePath}}">
+<plan path="{{planFilePath}}">
 {{planContent}}
 </plan>
 

package/src/sdk.ts

@@ -10,7 +10,6 @@ import {
 } from "@oh-my-pi/pi-agent-core";
 import {
 	type CredentialDisabledEvent,
-	isUsageLimitError,
 	type Message,
 	type Model,
 	type SimpleStreamOptions,
@@ -24,7 +23,6 @@ import type { Component } from "@oh-my-pi/pi-tui";
 import {
 	$env,
 	$flag,
-	extractRetryHint,
 	getAgentDbPath,
 	getAgentDir,
 	getAuthBrokerSnapshotCachePath,
@@ -39,6 +37,7 @@ import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled } from ".
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability, setActiveRules } from "./capability/rule";
 import { bucketRules } from "./capability/rule-buckets";
+import { createApiKeyResolver } from "./config/api-key-resolver";
 import { shouldEnableAppendOnlyContext } from "./config/append-only-context-mode";
 import { ModelRegistry } from "./config/model-registry";
 import {
@@ -280,6 +279,8 @@ export interface CreateAgentSessionOptions {
 	/** Optional provider-facing session identifier for prompt caches and sticky auth selection.
 	 * Keeps persisted session files isolated while reusing provider-side caches. */
 	providerSessionId?: string;
+	/** Optional provider-facing prompt cache key, distinct from request lineage. */
+	providerPromptCacheKey?: string;
 
 	/** Custom tools to register (in addition to built-in tools). Accepts both CustomTool and ToolDefinition. */
 	customTools?: (CustomTool | ToolDefinition)[];
@@ -2001,6 +2002,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			onPayload,
 			onResponse,
 			sessionId: providerSessionId,
+			promptCacheKey: options.providerPromptCacheKey,
 			transformContext,
 			steeringMode: settings.get("steeringMode") ?? "one-at-a-time",
 			followUpMode: settings.get("followUpMode") ?? "one-at-a-time",
@@ -2017,9 +2019,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			kimiApiFormat: settings.get("providers.kimiApiFormat") ?? "anthropic",
 			preferWebsockets: preferOpenAICodexWebsockets,
 			getToolContext: tc => toolContextStore.getContext(tc),
-			getApiKey: async provider => {
+			getApiKey: async (provider, ctx) => {
 				// Read agent.sessionId at call time so credential selection stays aligned
 				// with metadataResolver after /new, fork, resume, or branch switches.
+				// Retry steps (ctx carries an auth error) drive the central a/b/c
+				// policy — force-refresh the same account, then rotate to a sibling —
+				// and may legitimately yield no key when every account is exhausted.
+				if (ctx?.error !== undefined) {
+					return createApiKeyResolver(modelRegistry, provider, { sessionId: agent.sessionId })(ctx);
+				}
 				const key = await modelRegistry.getApiKeyForProvider(provider, agent.sessionId);
 				if (!key) {
 					throw new Error(`No API key found for provider "${provider}"`);
@@ -2033,40 +2041,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				return streamSimple(streamModel, context, {
 					...streamOptions,
 					openrouterVariant: streamOptions?.openrouterVariant ?? openrouterVariant,
-					onAuthError: async (provider, oldKey, error) => {
-						const message = error instanceof Error ? error.message : String(error);
-						// streamSimple invokes this for both 401 auth failures AND
-						// rotatable usage-limit errors (Codex usage_limit_reached,
-						// Anthropic usage_limit_reached, etc.). The two need
-						// different storage actions: a real 401 means the credential
-						// is bad and should be marked suspect; a usage limit just
-						// means this account is parked until reset and should be
-						// temporarily blocked so a sibling can pick the request up.
-						if (isUsageLimitError(message)) {
-							const retryAfterMs = extractRetryHint(undefined, message);
-							const switched = await modelRegistry.authStorage.markUsageLimitReached(provider, agent.sessionId, {
-								retryAfterMs,
-								signal: streamOptions?.signal,
-							});
-							logger.debug("Retrying provider request after usage-limit block", {
-								provider,
-								switched,
-								retryAfterMs,
-								error: message,
-							});
-							if (!switched) return undefined;
-							return modelRegistry.getApiKeyForProvider(provider, agent.sessionId);
-						}
-						await modelRegistry.authStorage.invalidateCredentialMatching(provider, oldKey, {
-							signal: streamOptions?.signal,
-							sessionId: agent.sessionId,
-						});
-						logger.debug("Retrying provider request after credential invalidation", {
-							provider,
-							error: message,
-						});
-						return modelRegistry.getApiKeyForProvider(provider, agent.sessionId);
-					},
 				});
 			},
 			cursorExecHandlers,

package/src/session/agent-session.ts

@@ -471,6 +471,12 @@ export interface SessionStats {
 	cost: number;
 }
 
+export interface FreshSessionResult {
+	previousSessionId: string;
+	sessionId: string;
+	closedProviderSessions: number;
+}
+
 /** Internal marker for hook messages queued through the agent loop */
 // ============================================================================
 // Constants
@@ -922,6 +928,7 @@ export class AgentSession {
 	#agentId: string | undefined;
 	#agentRegistry: AgentRegistry | undefined;
 	#providerSessionId: string | undefined;
+	#freshProviderSessionId: string | undefined;
 	#isDisposed = false;
 	// Extension system
 	#extensionRunner: ExtensionRunner | undefined = undefined;
@@ -1275,6 +1282,14 @@ export class AgentSession {
 		return this.#modelRegistry;
 	}
 
+	get asyncJobManager(): AsyncJobManager | undefined {
+		return this.#asyncJobManager;
+	}
+
+	getAgentId(): string | undefined {
+		return this.#agentId;
+	}
+
 	/** Advance the tool-choice queue and return the next directive for the upcoming LLM call. */
 	nextToolChoice(): ToolChoice | undefined {
 		return this.#toolChoiceQueue.nextToolChoice();
@@ -1681,7 +1696,7 @@ export class AgentSession {
 							// Abort the stream immediately — do not gate on extension callbacks
 							this.#ttsrAbortPending = true;
 							this.#ensureTtsrResumePromise();
-							this.agent.abort();
+							this.agent.abort(this.#formatTtsrAbortReason(matches));
 							// Notify extensions (fire-and-forget, does not block abort)
 							this.#emitSessionEvent({ type: "ttsr_triggered", rules: matches }).catch(() => {});
 							// Schedule retry after a short delay
@@ -2162,6 +2177,12 @@ export class AgentSession {
 		}
 	}
 
+	#formatTtsrAbortReason(rules: Rule[]): string {
+		const label = rules.length === 1 ? "rule" : "rules";
+		const ruleNames = rules.map(rule => rule.name).join(", ");
+		return `TTSR matched ${label}: ${ruleNames}`;
+	}
+
 	/** Get TTSR injection payload and clear pending injections. */
 	#getTtsrInjectionContent(): { content: string; rules: Rule[] } | undefined {
 		if (this.#pendingTtsrInjections.length === 0) return undefined;
@@ -2185,13 +2206,20 @@ export class AgentSession {
 	 * project, `~`-relative when it lives under home, else the raw path.
 	 */
 	#displayRulePath(rulePath: string): string {
-		const cwdRel = relativePathWithinRoot(this.sessionManager.getCwd(), rulePath);
+		const cwdRel =
+			relativePathWithinRoot(this.sessionManager.getCwd(), rulePath) ??
+			this.#displayPathWithinRoot(this.sessionManager.getCwd(), rulePath);
 		if (cwdRel) return cwdRel;
 		const homeRel = relativePathWithinRoot(os.homedir(), rulePath);
 		if (homeRel) return `~/${homeRel}`;
 		return rulePath;
 	}
 
+	#displayPathWithinRoot(root: string, candidate: string): string | null {
+		const relative = path.relative(path.resolve(root), path.resolve(candidate));
+		return relative && !relative.startsWith("..") && !path.isAbsolute(relative) ? relative : null;
+	}
+
 	#addPendingTtsrInjections(rules: Rule[]): void {
 		const seen = new Set(this.#pendingTtsrInjections.map(rule => rule.name));
 		for (const rule of rules) {
@@ -2946,6 +2974,10 @@ export class AgentSession {
 		this.#unsubscribeAgent = this.agent.subscribe(this.#handleAgentEvent);
 	}
 
+	#activeProviderSessionId(sessionId?: string): string {
+		return this.#freshProviderSessionId ?? this.#providerSessionId ?? sessionId ?? this.sessionManager.getSessionId();
+	}
+
 	/**
 	 * Set agent.sessionId from the session manager and install a dynamic
 	 * metadata resolver so every Anthropic API request carries
@@ -2958,7 +2990,7 @@ export class AgentSession {
 	 * `#syncAgentSessionId()` on every such event.
 	 */
 	#syncAgentSessionId(sessionId?: string): void {
-		const sid = this.#providerSessionId ?? sessionId ?? this.sessionManager.getSessionId();
+		const sid = this.#activeProviderSessionId(sessionId);
 		this.agent.sessionId = sid;
 		this.agent.setMetadataResolver((provider: string) =>
 			buildSessionMetadata(sid, provider, this.#modelRegistry.authStorage),
@@ -3088,6 +3120,23 @@ export class AgentSession {
 		this.#providerSessionState.clear();
 	}
 
+	freshSession(): FreshSessionResult | undefined {
+		if (this.isStreaming) return undefined;
+		const previousSessionId = this.sessionId;
+		const closedProviderSessions = this.#providerSessionState.size;
+		this.#closeAllProviderSessions("fresh session");
+		this.#freshProviderSessionId = Bun.randomUUIDv7();
+		this.#syncAgentSessionId();
+		this.#rekeyHindsightMemoryForCurrentSessionId();
+		this.#rekeyMnemopiMemoryForCurrentSessionId();
+		this.agent.appendOnlyContext?.invalidateForModelChange();
+		return {
+			previousSessionId,
+			sessionId: this.sessionId,
+			closedProviderSessions,
+		};
+	}
+
 	// =========================================================================
 	// Read-only State Access
 	// =========================================================================
@@ -3992,7 +4041,7 @@ export class AgentSession {
 
 	/** Current session ID */
 	get sessionId(): string {
-		return this.#providerSessionId ?? this.sessionManager.getSessionId();
+		return this.#activeProviderSessionId();
 	}
 	getEvalSessionId(): string | null {
 		if (this.#parentEvalSessionId !== undefined) return this.#parentEvalSessionId;
@@ -5091,8 +5140,13 @@ export class AgentSession {
 
 	/**
 	 * Abort current operation and wait for agent to become idle.
+	 *
+	 * `reason` (e.g. `USER_INTERRUPT_LABEL`) rides the agent's `AbortController`
+	 * and surfaces verbatim on the aborted assistant message's `errorMessage`, so
+	 * the transcript can distinguish a deliberate user interrupt from an opaque
+	 * abort. Omit it for internal/lifecycle aborts.
 	 */
-	async abort(options?: { goalReason?: "interrupted" | "internal" }): Promise<void> {
+	async abort(options?: { goalReason?: "interrupted" | "internal"; reason?: string }): Promise<void> {
 		this.abortRetry();
 		this.#promptGeneration++;
 		this.#scheduledHiddenNextTurnGeneration = undefined;
@@ -5101,7 +5155,7 @@ export class AgentSession {
 		this.abortBash();
 		this.abortEval();
 		const postPromptDrain = this.#cancelPostPromptTasks();
-		this.agent.abort();
+		this.agent.abort(options?.reason);
 		await postPromptDrain;
 		await this.agent.waitForIdle();
 		await this.#goalRuntime.onTaskAborted({ reason: options?.goalReason ?? "interrupted" });
@@ -5118,6 +5172,19 @@ export class AgentSession {
 		}
 	}
 
+	/**
+	 * Abort active work, then immediately resume the agent so queued steer/follow-up
+	 * messages drain instead of waiting for another natural turn boundary.
+	 */
+	async interruptAndFlushQueuedMessages(options?: { reason?: string }): Promise<void> {
+		if (!this.agent.hasQueuedMessages()) return;
+		await this.abort({ reason: options?.reason });
+		if (!this.agent.hasQueuedMessages()) return;
+		if (this.isCompacting || this.isGeneratingHandoff) return;
+		await this.#maybeRestoreRetryFallbackPrimary();
+		await this.agent.continue();
+	}
+
 	/**
 	 * Start a new session, optionally with initial messages and parent tracking.
 	 * Clears all messages and starts a new session.
@@ -5162,6 +5229,7 @@ export class AgentSession {
 		}
 		await this.sessionManager.newSession(options);
 		this.setTodoPhases([]);
+		this.#freshProviderSessionId = undefined;
 		this.#syncAgentSessionId();
 		this.#rekeyHindsightMemoryForCurrentSessionId();
 		this.#rekeyMnemopiMemoryForCurrentSessionId();
@@ -5259,6 +5327,7 @@ export class AgentSession {
 		}
 
 		// Update agent session ID
+		this.#freshProviderSessionId = undefined;
 		this.#syncAgentSessionId();
 		this.#rekeyHindsightMemoryForCurrentSessionId();
 		this.#rekeyMnemopiMemoryForCurrentSessionId();
@@ -6226,6 +6295,7 @@ export class AgentSession {
 			this.#cancelOwnAsyncJobs();
 			await this.sessionManager.newSession(previousSessionFile ? { parentSession: previousSessionFile } : undefined);
 			this.agent.reset();
+			this.#freshProviderSessionId = undefined;
 			this.#syncAgentSessionId();
 			this.#rekeyHindsightMemoryForCurrentSessionId();
 			this.#rekeyMnemopiMemoryForCurrentSessionId();
@@ -8941,6 +9011,7 @@ export class AgentSession {
 		const previousTools = [...this.agent.state.tools];
 		const previousBaseSystemPrompt = this.#baseSystemPrompt;
 		const previousSystemPrompt = this.agent.state.systemPrompt;
+		const previousFreshProviderSessionId = this.#freshProviderSessionId;
 		const previousFallbackSelectedMCPToolNames = previousSessionFile
 			? this.#getSessionDefaultSelectedMCPToolNames(previousSessionFile)
 			: undefined;
@@ -8952,6 +9023,9 @@ export class AgentSession {
 
 		try {
 			await this.sessionManager.setSessionFile(sessionPath);
+			if (switchingToDifferentSession) {
+				this.#freshProviderSessionId = undefined;
+			}
 			this.#syncAgentSessionId();
 			this.#rekeyHindsightMemoryForCurrentSessionId();
 			this.#rekeyMnemopiMemoryForCurrentSessionId();
@@ -9061,6 +9135,7 @@ export class AgentSession {
 			return true;
 		} catch (error) {
 			this.sessionManager.restoreState(previousSessionState);
+			this.#freshProviderSessionId = previousFreshProviderSessionId;
 			this.#syncAgentSessionId(previousSessionState.sessionId);
 			this.#rekeyHindsightMemoryForCurrentSessionId();
 			this.#rekeyMnemopiMemoryForCurrentSessionId();
@@ -9159,6 +9234,7 @@ export class AgentSession {
 			this.sessionManager.createBranchedSession(selectedEntry.parentId);
 		}
 		this.#syncTodoPhasesFromBranch();
+		this.#freshProviderSessionId = undefined;
 		this.#syncAgentSessionId();
 		this.#rekeyHindsightMemoryForCurrentSessionId();
 		this.#rekeyMnemopiMemoryForCurrentSessionId();

package/src/session/messages.ts

@@ -70,6 +70,32 @@ export function isSilentAbort(errorMessage: string | undefined): boolean {
 	return errorMessage === SILENT_ABORT_MARKER;
 }
 
+/** Reason threaded through `AbortController.abort(reason)` when the user aborts
+ *  the turn with Esc (see `AgentSession.abort`). The agent surfaces it verbatim
+ *  on the aborted assistant message's `errorMessage`, so the transcript reads as
+ *  a deliberate user interrupt instead of an opaque failure. */
+export const USER_INTERRUPT_LABEL = "Interrupted by user";
+
+/** Sentinel `errorMessage` the agent stamps on any abort that carried no custom
+ *  reason (bare `abort()`). Renderers treat it as "no specific reason given". */
+const GENERIC_ABORT_SENTINEL = "Request was aborted";
+
+/** Resolve the operator-facing label for an aborted assistant turn. A custom
+ *  abort reason (e.g. `USER_INTERRUPT_LABEL`) threaded onto `errorMessage` is
+ *  shown verbatim; aborts with no threaded reason fall back to the retry-aware
+ *  generic label. Centralizes the live-stream (`EventController`), replay
+ *  (`ui-helpers`), and component (`AssistantMessageComponent`) render paths so
+ *  they stay in lockstep. */
+export function resolveAbortLabel(errorMessage: string | undefined, retryAttempt = 0): string {
+	if (errorMessage && errorMessage !== GENERIC_ABORT_SENTINEL && !isSilentAbort(errorMessage)) {
+		return errorMessage;
+	}
+	if (retryAttempt > 0) {
+		return `Aborted after ${retryAttempt} retry attempt${retryAttempt > 1 ? "s" : ""}`;
+	}
+	return "Operation aborted";
+}
+
 /** Extract the optional `__pendingDisplayTag` field from a CustomMessage's
  *  `details` blob. Safe over `unknown`; returns undefined when the field is
  *  absent or non-string. */

package/src/session/session-manager.ts

@@ -1967,6 +1967,7 @@ export class SessionManager {
 	#inMemoryArtifacts: Map<string, string> | null = null;
 	#inMemoryArtifactCounter = 0;
 	readonly #blobStore: BlobStore;
+	#suppressBreadcrumb = false;
 
 	private constructor(
 		private cwd: string,
@@ -1981,6 +1982,11 @@ export class SessionManager {
 		// Note: call _initSession() or _initSessionFile() after construction
 	}
 
+	#maybeWriteBreadcrumb(cwd: string, sessionFile: string): void {
+		if (this.#suppressBreadcrumb) return;
+		writeTerminalBreadcrumb(cwd, sessionFile);
+	}
+
 	/** Puts a binary blob into the blob store and returns the blob reference */
 	async putBlob(data: Buffer, options?: BlobPutOptions): Promise<BlobPutResult> {
 		return this.#blobStore.put(data, options);
@@ -2027,7 +2033,7 @@ export class SessionManager {
 		this.#adoptedArtifactManager = null;
 		this.#buildIndex();
 		if (this.#sessionFile) {
-			writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
+			this.#maybeWriteBreadcrumb(this.cwd, this.#sessionFile);
 		}
 	}
 
@@ -2047,7 +2053,7 @@ export class SessionManager {
 		this.#persistError = undefined;
 		this.#persistErrorReported = false;
 		this.#sessionFile = path.resolve(sessionFile);
-		writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
+		this.#maybeWriteBreadcrumb(this.cwd, this.#sessionFile);
 		this.#fileEntries = await loadEntriesFromFile(this.#sessionFile, this.storage);
 		if (this.#fileEntries.length > 0) {
 			const header = this.#fileEntries.find(e => e.type === "session") as SessionHeader | undefined;
@@ -2064,7 +2070,7 @@ export class SessionManager {
 			if (headerCwd && headerCwd !== this.cwd) {
 				this.cwd = headerCwd;
 				this.sessionDir = path.resolve(this.#sessionFile, "..");
-				writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
+				this.#maybeWriteBreadcrumb(this.cwd, this.#sessionFile);
 			}
 
 			this.#needsFullRewriteOnNextPersist = migrateToCurrentVersion(this.#fileEntries);
@@ -2245,7 +2251,7 @@ export class SessionManager {
 
 		// Update terminal breadcrumb
 		if (this.#sessionFile) {
-			writeTerminalBreadcrumb(resolvedCwd, this.#sessionFile);
+			this.#maybeWriteBreadcrumb(resolvedCwd, this.#sessionFile);
 		}
 	}
 
@@ -2280,7 +2286,7 @@ export class SessionManager {
 		if (this.persist) {
 			const fileTimestamp = timestamp.replace(/[:.]/g, "-");
 			this.#sessionFile = path.join(this.getSessionDir(), `${fileTimestamp}_${this.#sessionId}.jsonl`);
-			writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
+			this.#maybeWriteBreadcrumb(this.cwd, this.#sessionFile);
 		}
 		return this.#sessionFile;
 	}
@@ -3429,9 +3435,11 @@ export class SessionManager {
 		cwd: string,
 		sessionDir?: string,
 		storage: SessionStorage = new FileSessionStorage(),
+		options?: { suppressBreadcrumb?: boolean },
 	): Promise<SessionManager> {
 		const dir = sessionDir ?? SessionManager.getDefaultSessionDir(cwd, undefined, storage);
 		const manager = new SessionManager(cwd, dir, true, storage);
+		manager.#suppressBreadcrumb = options?.suppressBreadcrumb === true;
 		const forkEntries = structuredClone(await loadEntriesFromFile(sourcePath, storage)) as FileEntry[];
 		migrateToCurrentVersion(forkEntries);
 		await resolveBlobRefsInEntries(forkEntries, manager.#blobStore);