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

package/src/cli/args.ts

@@ -109,6 +109,8 @@ export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { ty
 			result.version = true;
 		} else if (arg === "--allow-home") {
 			result.allowHome = true;
+		} else if (arg === "--cwd" && i + 1 < args.length) {
+			result.cwd = args[++i];
 		} else if (arg === "--mode" && i + 1 < args.length) {
 			const mode = args[++i];
 			if (mode === "text" || mode === "json" || mode === "rpc" || mode === "acp" || mode === "rpc-ui") {
@@ -258,7 +260,7 @@ export function getExtraHelpText(): string {
   NODE_EXTRA_CA_CERTS        - CA bundle path (or inline PEM) for server certificate validation
   OPENAI_API_KEY             - OpenAI GPT models
   GEMINI_API_KEY             - Google Gemini models
-  GITHUB_TOKEN               - GitHub Copilot (or GH_TOKEN, COPILOT_GITHUB_TOKEN)
+  COPILOT_GITHUB_TOKEN      - GitHub Copilot
 
   ${chalk.dim("# Additional LLM Providers")}
   AZURE_OPENAI_API_KEY       - Azure OpenAI models

package/src/cli/dry-balance-cli.ts

@@ -19,7 +19,7 @@ import type { CanonicalModelVariant } from "../config/model-equivalence";
 import { type CanonicalModelQueryOptions, ModelRegistry } from "../config/model-registry";
 import {
 	formatModelString,
-	type ModelMatchPreferences,
+	getModelMatchPreferences,
 	resolveAllowedModels,
 	resolveCliModel,
 	resolveModelRoleValue,
@@ -542,9 +542,7 @@ async function resolveDryBalanceModel(
 	settings: Settings | undefined,
 	randomSessionId: () => string,
 ): Promise<{ model: Model<Api>; warning?: string }> {
-	const preferences: ModelMatchPreferences = {
-		usageOrder: settings?.getStorage()?.getModelUsageOrder(),
-	};
+	const preferences = getModelMatchPreferences(settings);
 	if (modelSelector) {
 		const resolved = resolveCliModel({
 			cliModel: modelSelector,

package/src/cli/startup-cwd.ts

@@ -0,0 +1,68 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getProjectDir, normalizePathForComparison, setProjectDir } from "@oh-my-pi/pi-utils";
+import type { Args } from "./args";
+
+async function maybeAutoChdir(parsed: Args): Promise<void> {
+	if (parsed.allowHome || parsed.cwd) {
+		return;
+	}
+
+	const home = os.homedir();
+	if (!home) {
+		return;
+	}
+
+	const normalizePath = normalizePathForComparison;
+
+	const cwd = normalizePath(getProjectDir());
+	const normalizedHome = normalizePath(home);
+	if (cwd !== normalizedHome) {
+		return;
+	}
+
+	const isDirectory = async (p: string) => {
+		try {
+			const s = await fs.stat(p);
+			return s.isDirectory();
+		} catch {
+			return false;
+		}
+	};
+
+	const candidates = [path.join(home, "tmp"), "/tmp", "/var/tmp"];
+	for (const candidate of candidates) {
+		try {
+			if (!(await isDirectory(candidate))) {
+				continue;
+			}
+			setProjectDir(candidate);
+			return;
+		} catch {
+			// Try next candidate.
+		}
+	}
+
+	try {
+		const fallback = os.tmpdir();
+		if (fallback && normalizePath(fallback) !== cwd && (await isDirectory(fallback))) {
+			setProjectDir(fallback);
+		}
+	} catch {
+		// Ignore fallback errors.
+	}
+}
+
+export async function applyStartupCwd(parsed: Args): Promise<void> {
+	if (parsed.cwd) {
+		setProjectDir(parsed.cwd);
+		// setProjectDir resolves the (possibly relative) target against the launch
+		// cwd and chdirs into it. Re-sync parsed.cwd to the resolved absolute path
+		// so downstream consumers (buildSessionOptions, settings/discovery, session
+		// persistence) don't re-resolve a relative string against the new cwd.
+		parsed.cwd = getProjectDir();
+		return;
+	}
+	await maybeAutoChdir(parsed);
+}

package/src/commands/launch.ts

@@ -49,6 +49,9 @@ export default class Index extends Command {
 		"allow-home": Flags.boolean({
 			description: "Allow starting in ~ without auto-switching to a temp dir",
 		}),
+		cwd: Flags.string({
+			description: "Directory to start in (overrides the launch cwd)",
+		}),
 		mode: Flags.string({
 			description: "Output mode: text (default), json, rpc, or rpc-ui",
 			options: ["text", "json", "rpc", "acp", "rpc-ui"],

package/src/commit/model-selection.ts

@@ -3,6 +3,7 @@ import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
 import type { ApiKeyResolverRegistry } from "../config/api-key-resolver";
 import { MODEL_ROLE_IDS } from "../config/model-registry";
 import {
+	getModelMatchPreferences,
 	type ModelLookupRegistry,
 	parseModelPattern,
 	resolveModelRoleValue,
@@ -33,7 +34,7 @@ export async function resolvePrimaryModel(
 	modelRegistry: CommitModelRegistry,
 ): Promise<ResolvedCommitModel> {
 	const available = modelRegistry.getAvailable();
-	const matchPreferences = { usageOrder: settings.getStorage()?.getModelUsageOrder() };
+	const matchPreferences = getModelMatchPreferences(settings);
 	const resolved = override
 		? resolveModelRoleValue(override, available, { settings, matchPreferences, modelRegistry })
 		: resolveRoleSelection(["commit", "smol", ...MODEL_ROLE_IDS], settings, available, modelRegistry);
@@ -73,7 +74,7 @@ export async function resolveSmolModel(
 		}
 	}
 
-	const matchPreferences = { usageOrder: settings.getStorage()?.getModelUsageOrder() };
+	const matchPreferences = getModelMatchPreferences(settings);
 	for (const pattern of MODEL_PRIO.smol) {
 		const candidate = parseModelPattern(pattern, available, matchPreferences, { modelRegistry }).model;
 		if (!candidate) continue;

package/src/config/model-provider-priority.ts

@@ -0,0 +1,55 @@
+const DEFAULT_MODEL_PROVIDER_ORDER = [
+	// First-party / native account providers. Prefer these over relays when the
+	// same upstream model is available in more than one place.
+	"openai-codex",
+	"anthropic",
+	"openai",
+	"google-gemini-cli",
+	"google",
+	"google-vertex",
+	"kimi-code",
+	"moonshot",
+	"qwen-portal",
+	"zai",
+	"xai-oauth",
+	"xai",
+	"mistral",
+	"deepseek",
+	"groq",
+
+	// High-quality aggregators / hosted inference providers.
+	"fireworks",
+	"cerebras",
+	"openrouter",
+	"together",
+
+	// Generic gateways and editor/proxy providers. These are useful when picked
+	// explicitly, but should not win ambiguous automatic role selection.
+	"alibaba-coding-plan",
+	"google-antigravity",
+	"opencode-zen",
+	"gitlab-duo",
+	"opencode-go",
+	"kilo",
+	"vercel-ai-gateway",
+	"cloudflare-ai-gateway",
+	"nanogpt",
+	"github-copilot",
+] as const;
+
+function addProviderRank(rank: Map<string, number>, provider: string): void {
+	const normalized = provider.trim().toLowerCase();
+	if (!normalized || rank.has(normalized)) return;
+	rank.set(normalized, rank.size);
+}
+
+export function buildModelProviderPriorityRank(configuredProviderOrder?: readonly string[]): Map<string, number> {
+	const rank = new Map<string, number>();
+	for (const provider of configuredProviderOrder ?? []) {
+		addProviderRank(rank, provider);
+	}
+	for (const provider of DEFAULT_MODEL_PROVIDER_ORDER) {
+		addProviderRank(rank, provider);
+	}
+	return rank;
+}

package/src/config/model-registry.ts

@@ -118,6 +118,7 @@ import {
 	getModelLikeIdSegments,
 	stripBracketedModelIdAffixes,
 } from "./model-id-affixes";
+import { buildModelProviderPriorityRank } from "./model-provider-priority";
 import {
 	type ModelOverride,
 	type ModelsConfig,
@@ -2208,27 +2209,8 @@ export class ModelRegistry {
 		});
 	}
 
-	#providerRank(models: readonly Model<Api>[]): Map<string, number> {
-		const configuredProviders = getConfiguredProviderOrderFromSettings();
-		const result = new Map<string, number>();
-		let nextRank = 0;
-		for (const provider of configuredProviders) {
-			const normalized = provider.trim().toLowerCase();
-			if (!normalized || result.has(normalized)) {
-				continue;
-			}
-			result.set(normalized, nextRank);
-			nextRank += 1;
-		}
-		for (const model of models) {
-			const normalized = model.provider.toLowerCase();
-			if (result.has(normalized)) {
-				continue;
-			}
-			result.set(normalized, nextRank);
-			nextRank += 1;
-		}
-		return result;
+	#providerRank(): Map<string, number> {
+		return buildModelProviderPriorityRank(getConfiguredProviderOrderFromSettings());
 	}
 
 	#resolveCanonicalVariant(
@@ -2238,7 +2220,7 @@ export class ModelRegistry {
 		if (variants.length === 0) {
 			return undefined;
 		}
-		const providerRank = this.#providerRank(allCandidates);
+		const providerRank = this.#providerRank();
 		const modelOrder = new Map<string, number>();
 		for (let index = 0; index < allCandidates.length; index += 1) {
 			modelOrder.set(formatCanonicalVariantSelector(allCandidates[index]!), index);

package/src/config/model-resolver.ts

@@ -17,6 +17,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import MODEL_PRIO from "../priority.json" with { type: "json" };
 import { parseThinkingLevel, resolveThinkingLevelForModel } from "../thinking";
+import { buildModelProviderPriorityRank } from "./model-provider-priority";
 import { isAuthenticated, kNoAuth, MODEL_ROLE_IDS, type ModelRegistry, type ModelRole } from "./model-registry";
 import type { Settings } from "./settings";
 
@@ -179,7 +180,9 @@ export function resolveProviderModelReference(
 export interface ModelMatchPreferences {
 	/** Most-recently-used model keys (provider/modelId) to prefer when ambiguous. */
 	usageOrder?: string[];
-	/** Providers to deprioritize when no recent usage is available. */
+	/** Provider precedence used for ambiguous unqualified model patterns. */
+	providerOrder?: readonly string[];
+	/** Providers to deprioritize when no recent usage or provider priority is available. */
 	deprioritizeProviders?: string[];
 }
 
@@ -194,6 +197,7 @@ type RestorableModelRegistry = Pick<ModelRegistry, "getAvailable" | "find" | "ge
 interface ModelPreferenceContext {
 	modelUsageRank: Map<string, number>;
 	providerUsageRank: Map<string, number>;
+	providerPriorityRank: Map<string, number>;
 	deprioritizedProviders: Set<string>;
 	modelOrder: Map<string, number>;
 }
@@ -215,14 +219,35 @@ function buildPreferenceContext(
 			providerUsageRank.set(parsed.provider, i);
 		}
 	}
-
-	const deprioritizedProviders = new Set(preferences?.deprioritizeProviders ?? ["openrouter"]);
+	const providerPriorityRank = buildModelProviderPriorityRank(preferences?.providerOrder);
+	const deprioritizedProviders = new Set(preferences?.deprioritizeProviders ?? []);
 	const modelOrder = new Map<string, number>();
 	for (let i = 0; i < availableModels.length; i += 1) {
 		modelOrder.set(formatModelString(availableModels[i]), i);
 	}
 
-	return { modelUsageRank, providerUsageRank, deprioritizedProviders, modelOrder };
+	return { modelUsageRank, providerUsageRank, providerPriorityRank, deprioritizedProviders, modelOrder };
+}
+
+export function getModelMatchPreferences(
+	settings?: Partial<Pick<Settings, "get" | "getStorage">>,
+): ModelMatchPreferences {
+	return {
+		usageOrder: settings?.getStorage?.()?.getModelUsageOrder(),
+		providerOrder: settings?.get?.("modelProviderOrder"),
+	};
+}
+
+function mergeModelMatchPreferences(
+	settings: Settings | undefined,
+	preferences: ModelMatchPreferences | undefined,
+): ModelMatchPreferences {
+	const settingsPreferences = getModelMatchPreferences(settings);
+	return {
+		usageOrder: preferences?.usageOrder ?? settingsPreferences.usageOrder,
+		providerOrder: preferences?.providerOrder ?? settingsPreferences.providerOrder,
+		deprioritizeProviders: preferences?.deprioritizeProviders,
+	};
 }
 
 function pickPreferredModel(candidates: Model<Api>[], context: ModelPreferenceContext): Model<Api> {
@@ -236,6 +261,12 @@ function pickPreferredModel(candidates: Model<Api>[], context: ModelPreferenceCo
 			return (aUsage ?? Number.POSITIVE_INFINITY) - (bUsage ?? Number.POSITIVE_INFINITY);
 		}
 
+		const aProviderPriority = context.providerPriorityRank.get(a.provider.toLowerCase());
+		const bProviderPriority = context.providerPriorityRank.get(b.provider.toLowerCase());
+		if (aProviderPriority !== undefined || bProviderPriority !== undefined) {
+			return (aProviderPriority ?? Number.POSITIVE_INFINITY) - (bProviderPriority ?? Number.POSITIVE_INFINITY);
+		}
+
 		const aProviderUsage = context.providerUsageRank.get(a.provider);
 		const bProviderUsage = context.providerUsageRank.get(b.provider);
 		if (aProviderUsage !== undefined || bProviderUsage !== undefined) {
@@ -618,8 +649,9 @@ export function resolveModelRoleValue(
 	}
 
 	let warning: string | undefined;
+	const matchPreferences = mergeModelMatchPreferences(options?.settings, options?.matchPreferences);
 	for (const effectivePattern of effectivePatterns) {
-		const resolved = parseModelPattern(effectivePattern, availableModels, options?.matchPreferences, {
+		const resolved = parseModelPattern(effectivePattern, availableModels, matchPreferences, {
 			modelRegistry: options?.modelRegistry,
 		});
 		if (resolved.model) {
@@ -720,7 +752,7 @@ export function resolveModelOverride(
 ): { model?: Model<Api>; thinkingLevel?: ThinkingLevel; explicitThinkingLevel: boolean } {
 	if (modelPatterns.length === 0) return { explicitThinkingLevel: false };
 	const availableModels = modelRegistry.getAvailable();
-	const matchPreferences = { usageOrder: settings?.getStorage()?.getModelUsageOrder() };
+	const matchPreferences = getModelMatchPreferences(settings);
 	for (const pattern of modelPatterns) {
 		const { model, thinkingLevel, explicitThinkingLevel } = resolveModelRoleValue(pattern, availableModels, {
 			settings,
@@ -800,7 +832,7 @@ export function resolveRoleSelection(
 	availableModels: Model<Api>[],
 	modelRegistry?: CanonicalModelRegistry,
 ): { model: Model<Api>; thinkingLevel?: ThinkingLevel } | undefined {
-	const matchPreferences = { usageOrder: settings.getStorage()?.getModelUsageOrder() };
+	const matchPreferences = getModelMatchPreferences(settings);
 	for (const role of roles) {
 		const resolved = resolveModelRoleValue(settings.getModelRole(role), availableModels, {
 			settings,

package/src/config/settings.ts

@@ -72,7 +72,7 @@ export interface SettingsOptions {
 /**
  * Get a nested value from an object by path segments.
  */
-function getByPath(obj: RawSettings, segments: string[]): unknown {
+function getByPath(obj: RawSettings, segments: readonly string[]): unknown {
 	let current: unknown = obj;
 	for (const segment of segments) {
 		if (current === null || current === undefined || typeof current !== "object") {
@@ -83,6 +83,10 @@ function getByPath(obj: RawSettings, segments: string[]): unknown {
 	return current;
 }
 
+const SETTING_PATH_SEGMENTS: Record<SettingPath, readonly string[]> = Object.fromEntries(
+	(Object.keys(SETTINGS_SCHEMA) as SettingPath[]).map(settingPath => [settingPath, settingPath.split(".")]),
+) as unknown as Record<SettingPath, readonly string[]>;
+
 /**
  * Set a nested value in an object by path segments.
  * Creates intermediate objects as needed.
@@ -196,6 +200,8 @@ export class Settings {
 	#overrides: RawSettings = {};
 	/** Merged view (global + project + overrides) */
 	#merged: RawSettings = {};
+	/** Cached resolved values from the merged view, including defaults/path scoping */
+	#resolvedCache = new Map<SettingPath, unknown>();
 
 	/** Paths modified during this session (for partial save) */
 	#modified = new Set<string>();
@@ -282,13 +288,15 @@ export class Settings {
 	 * Returns the merged value from global + project + overrides, or the default.
 	 */
 	get<P extends SettingPath>(path: P): SettingValue<P> {
-		const segments = path.split(".");
-		const value = getByPath(this.#merged, segments);
-		if (value !== undefined) {
-			const pathScopedValue = resolvePathScopedStringArray(path, value, this.#cwd);
-			return (pathScopedValue ?? value) as SettingValue<P>;
+		if (this.#resolvedCache.has(path)) {
+			return this.#resolvedCache.get(path) as SettingValue<P>;
 		}
-		return getDefault(path);
+
+		const value = getByPath(this.#merged, SETTING_PATH_SEGMENTS[path]);
+		const resolved =
+			value !== undefined ? (resolvePathScopedStringArray(path, value, this.#cwd) ?? value) : getDefault(path);
+		this.#resolvedCache.set(path, resolved);
+		return resolved as SettingValue<P>;
 	}
 
 	/**
@@ -302,6 +310,7 @@ export class Settings {
 		setByPath(this.#global, segments, value);
 		this.#modified.add(path);
 		this.#rebuildMerged();
+		const next = this.get(path);
 		this.#queueSave();
 
 		// Trigger hook if exists
@@ -309,21 +318,25 @@ export class Settings {
 		if (hook) {
 			hook(value, prev);
 		}
+		this.#fireEffectiveSettingChanged(path, next, prev);
 	}
 
 	/**
 	 * Apply runtime overrides (not persisted).
 	 */
 	override<P extends SettingPath>(path: P, value: SettingValue<P>): void {
+		const prev = this.get(path);
 		const segments = path.split(".");
 		setByPath(this.#overrides, segments, value);
 		this.#rebuildMerged();
+		this.#fireEffectiveSettingChanged(path, this.get(path), prev);
 	}
 
 	/**
 	 * Clear a runtime override.
 	 */
 	clearOverride(path: SettingPath): void {
+		const prev = this.get(path);
 		const segments = path.split(".");
 		let current = this.#overrides;
 		for (let i = 0; i < segments.length - 1; i++) {
@@ -333,6 +346,14 @@ export class Settings {
 		}
 		delete current[segments[segments.length - 1]];
 		this.#rebuildMerged();
+		this.#fireEffectiveSettingChanged(path, this.get(path), prev);
+	}
+
+	#fireEffectiveSettingChanged(path: SettingPath, value: unknown, prev: unknown): void {
+		if (Object.is(value, prev)) return;
+		if (path === "statusLine.sessionAccent") {
+			statusLineSessionAccentSignal.fire();
+		}
 	}
 
 	/**
@@ -842,6 +863,7 @@ export class Settings {
 	#rebuildMerged(): void {
 		this.#merged = this.#deepMerge(this.#deepMerge({}, this.#global), this.#project);
 		this.#merged = this.#deepMerge(this.#merged, this.#overrides);
+		this.#resolvedCache.clear();
 	}
 
 	#fireAllHooks(): void {
@@ -885,6 +907,45 @@ export class Settings {
 
 type SettingHook<P extends SettingPath> = (value: SettingValue<P>, prev: SettingValue<P>) => void;
 
+/**
+ * Minimal change-notification primitive backing the exported `on*Changed`
+ * subscriptions. Holds a listener set, hands out unsubscribe closures, and
+ * isolates errors so a single throwing listener can't abort the rest or bubble
+ * out of `Settings.set()`.
+ *
+ * @typeParam A - argument tuple forwarded to each listener on `fire`.
+ */
+class SettingSignal<A extends unknown[] = []> {
+	#listeners = new Set<(...args: A) => void>();
+
+	constructor(private readonly label: string) {}
+
+	/** Subscribe `cb`; returns an unsubscribe function. */
+	on(cb: (...args: A) => void): () => void {
+		this.#listeners.add(cb);
+		return () => {
+			this.#listeners.delete(cb);
+		};
+	}
+
+	/**
+	 * Invoke every listener with `args`. Iterates a snapshot so a listener may
+	 * (un)subscribe mid-fire without re-entrancy — the Hindsight backend
+	 * re-registers the fresh state's listener on every rebuild — and wraps each
+	 * call so a throwing listener is logged and skipped instead of aborting the
+	 * rest.
+	 */
+	fire(...args: A): void {
+		for (const cb of [...this.#listeners]) {
+			try {
+				cb(...args);
+			} catch (err) {
+				logger.warn(`Settings: ${this.label} hook failed`, { error: String(err) });
+			}
+		}
+	}
+}
+
 const SETTING_HOOKS: Partial<Record<SettingPath, SettingHook<any>>> = {
 	"theme.dark": value => {
 		if (typeof value === "string") {
@@ -917,45 +978,34 @@ const SETTING_HOOKS: Partial<Record<SettingPath, SettingHook<any>>> = {
 	},
 	"provider.appendOnlyContext": value => {
 		if (typeof value === "string") {
-			for (const cb of appendOnlyModeCallbacks) cb(value);
+			appendOnlyModeSignal.fire(value);
 		}
 	},
-	"hindsight.bankId": () => fireHindsightScopeChanged(),
-	"hindsight.bankIdPrefix": () => fireHindsightScopeChanged(),
-	"hindsight.scoping": () => fireHindsightScopeChanged(),
+	"hindsight.bankId": () => hindsightScopeSignal.fire(),
+	"hindsight.bankIdPrefix": () => hindsightScopeSignal.fire(),
+	"hindsight.scoping": () => hindsightScopeSignal.fire(),
 };
-/** Callbacks invoked when `provider.appendOnlyContext` changes at runtime. */
-const appendOnlyModeCallbacks = new Set<(value: string) => void>();
+/** Fires when `provider.appendOnlyContext` changes at runtime. */
+const appendOnlyModeSignal = new SettingSignal<[value: string]>("provider.appendOnlyContext");
 
 /**
  * Subscribe to append-only mode setting changes.
  * Returns an unsubscribe function. Multiple sessions (main + subagents)
  * can register independently without overwriting each other.
  */
-export function onAppendOnlyModeChanged(cb: (value: string) => void): () => void {
-	appendOnlyModeCallbacks.add(cb);
-	return () => {
-		appendOnlyModeCallbacks.delete(cb);
-	};
-}
+export const onAppendOnlyModeChanged = (cb: (value: string) => void) => appendOnlyModeSignal.on(cb);
 
-/** Callbacks fired when any `hindsight.bankId` / `bankIdPrefix` / `scoping` value changes. */
-const hindsightScopeCallbacks = new Set<() => void>();
+/** Fires when `statusLine.sessionAccent` changes at runtime. */
+const statusLineSessionAccentSignal = new SettingSignal("statusLine.sessionAccent");
 
-function fireHindsightScopeChanged(): void {
-	// Snapshot the callback set before invoking — a callback's body is allowed
-	// to subscribe a NEW callback (the Hindsight backend re-registers the
-	// fresh state's listener on every rebuild). Iterating the live Set would
-	// re-invoke those just-added callbacks within the same fire, which spins
-	// in place: subscribe → invoke → subscribe → invoke → …
-	for (const cb of [...hindsightScopeCallbacks]) {
-		try {
-			cb();
-		} catch (err) {
-			logger.warn("Settings: hindsight scope hook failed", { error: String(err) });
-		}
-	}
-}
+/**
+ * Subscribe to session-accent setting changes.
+ * Returns an unsubscribe function. Callers should re-read settings in the callback.
+ */
+export const onStatusLineSessionAccentChanged = (cb: () => void) => statusLineSessionAccentSignal.on(cb);
+
+/** Fires when any `hindsight.bankId` / `bankIdPrefix` / `scoping` value changes. */
+const hindsightScopeSignal = new SettingSignal("hindsight scope");
 
 /**
  * Subscribe to changes in the Hindsight bank-scoping settings. Lets the
@@ -967,12 +1017,7 @@ function fireHindsightScopeChanged(): void {
  * Returns an unsubscribe function. The callback receives no arguments — the
  * caller is expected to re-read the relevant settings via `Settings.get`.
  */
-export function onHindsightScopeChanged(cb: () => void): () => void {
-	hindsightScopeCallbacks.add(cb);
-	return () => {
-		hindsightScopeCallbacks.delete(cb);
-	};
-}
+export const onHindsightScopeChanged = (cb: () => void) => hindsightScopeSignal.on(cb);
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Global Singleton

package/src/debug/index.ts

@@ -195,6 +195,7 @@ export class DebugSelectorComponent extends Container {
 			const result = await createReportBundle({
 				sessionFile: this.ctx.sessionManager.getSessionFile(),
 				settings: this.#getResolvedSettings(),
+				rawSseText: this.#getRawSseText(),
 				cpuProfile,
 				workProfile,
 			});
@@ -253,6 +254,7 @@ export class DebugSelectorComponent extends Container {
 			const result = await createReportBundle({
 				sessionFile: this.ctx.sessionManager.getSessionFile(),
 				settings: this.#getResolvedSettings(),
+				rawSseText: this.#getRawSseText(),
 			});
 
 			loader.stop();
@@ -288,6 +290,7 @@ export class DebugSelectorComponent extends Container {
 			const result = await createReportBundle({
 				sessionFile: this.ctx.sessionManager.getSessionFile(),
 				settings: this.#getResolvedSettings(),
+				rawSseText: this.#getRawSseText(),
 				heapSnapshot,
 			});
 
@@ -490,6 +493,11 @@ export class DebugSelectorComponent extends Container {
 		}
 	}
 
+	#getRawSseText(): string | undefined {
+		const rawSseText = resolveRawSseDebugBuffer(this.ctx.session).toRawText();
+		return rawSseText.trim().length > 0 ? rawSseText : undefined;
+	}
+
 	#getResolvedSettings(): Record<string, unknown> {
 		// Extract key settings for the report
 		return {

package/src/debug/raw-sse-buffer.ts

@@ -152,9 +152,9 @@ export class RawSseDebugBuffer {
 	}
 
 	// Ownership contract for `event.raw`:
-	//   The caller (either `notifyRawSseEvent` in `packages/ai/src/utils/sse-debug.ts`
-	//   or `SseTeeParser.#dispatch` directly) hands us a freshly-allocated
-	//   `string[]` per event and never retains, mutates, or re-dispatches it.
+	//   The caller (`notifyRawSseEvent` in `packages/ai/src/utils/sse-debug.ts`)
+	//   hands us a freshly-allocated `string[]` per event and never retains,
+	//   mutates, or re-dispatches it.
 	//   That lets `trimRawLines` keep the array by reference instead of
 	//   cloning on every chunk — a measurable savings on the streaming hot
 	//   path. If a future observer-chain mutates the array, restore the
@@ -192,7 +192,10 @@ export class RawSseDebugBuffer {
 	toRawText(): string {
 		// Reads the live array directly: `rawRecordText` only computes a string
 		// from each record, so no caller-visible mutation is possible.
-		return this.#records.map(rawRecordText).join("\n");
+		const body = this.#records.map(rawRecordText).join("\n");
+		if (this.#droppedRecords === 0) return body;
+		const dropped = `: omp-debug-dropped records=${this.#droppedRecords} chars=${this.#droppedChars}\n\n`;
+		return body.length > 0 ? `${dropped}${body}` : dropped;
 	}
 
 	#append(record: RawSseDebugRecord, chars: number): void {

package/src/debug/report-bundle.ts

@@ -45,6 +45,8 @@ export interface ReportBundleOptions {
 	heapSnapshot?: HeapSnapshot;
 	/** Work profile (for work scheduling reports) */
 	workProfile?: WorkProfile;
+	/** Raw provider SSE diagnostics captured by the session buffer */
+	rawSseText?: string;
 }
 
 export interface ReportBundleResult {
@@ -70,6 +72,7 @@ export interface DebugLogSource {
  * - env.json: Sanitized environment variables
  * - config.json: Resolved settings
  * - profile.cpuprofile: CPU profile (performance report only)
+ * - raw-sse.txt: Recent raw provider SSE diagnostics (when captured)
  * - profile.md: Markdown CPU profile (performance report only)
  * - heap.heapsnapshot: Heap snapshot (memory report only)
  * - work.folded: Work profile folded stacks (work report only)
@@ -109,6 +112,12 @@ export async function createReportBundle(options: ReportBundleOptions): Promise<
 		files.push("logs.txt");
 	}
 
+	// Recent raw provider SSE diagnostics
+	if (options.rawSseText && options.rawSseText.trim().length > 0) {
+		data["raw-sse.txt"] = options.rawSseText;
+		files.push("raw-sse.txt");
+	}
+
 	// Session file
 	if (options.sessionFile) {
 		try {