@oh-my-pi/pi-coding-agent 16.2.1 → 16.2.3

package/src/session/session-manager.ts

@@ -39,13 +39,16 @@ import {
 	type SessionHeader,
 	type SessionInitEntry,
 	type SessionMessageEntry,
+	type SessionTitleSource,
 	type SessionTreeNode,
 	type ThinkingLevelChangeEntry,
+	TITLE_CHANGE_ENTRY_TYPE,
+	type TitleChangeEntry,
 	type TtsrInjectionEntry,
 	type UsageStatistics,
 } from "./session-entries";
 import { findMostRecentSession, listAllSessions, listSessions, type SessionInfo } from "./session-listing";
-import { loadEntriesFromFile, resolveBlobRefsInEntries } from "./session-loader";
+import { loadEntriesFromFile, readTitleSlotFromFile, resolveBlobRefsInEntries } from "./session-loader";
 import { generateId, migrateToCurrentVersion } from "./session-migrations";
 import {
 	computeDefaultSessionDir,
@@ -60,6 +63,7 @@ import {
 	type SessionStorage,
 	type SessionStorageWriter,
 } from "./session-storage";
+import { type SessionTitleUpdate, serializeTitleSlot } from "./session-title-slot";
 
 const JSONL_SUFFIX_LENGTH = ".jsonl".length;
 
@@ -298,8 +302,10 @@ interface SessionManagerStateSnapshot {
 	sessionDir: string;
 	sessionId: string;
 	sessionName: string | undefined;
-	titleSource: "auto" | "user" | undefined;
+	titleSource: SessionTitleSource | undefined;
 	sessionFile: string | undefined;
+	titleUpdatedAt: string;
+	hasTitleSlot: boolean;
 	onDisk: boolean;
 	needsRewrite: boolean;
 	header: SessionHeader;
@@ -334,9 +340,11 @@ export class SessionManager {
 
 	#sessionId = "";
 	#sessionName: string | undefined;
-	#titleSource: "auto" | "user" | undefined;
+	#titleSource: SessionTitleSource | undefined;
 	#sessionFile: string | undefined;
 	#header!: SessionHeader;
+	#titleUpdatedAt = "";
+	#hasTitleSlot = true;
 	#entries: SessionEntry[] = [];
 	#index = new SessionEntryIndex();
 
@@ -471,8 +479,17 @@ export class SessionManager {
 		return `${JSON.stringify(prepareEntryForPersistence(entry, this.#blobs))}\n`;
 	}
 
+	#titleSlotLine(): string {
+		return serializeTitleSlot({
+			title: this.#sessionName,
+			source: this.#titleSource,
+			updatedAt: this.#titleUpdatedAt || this.#header.timestamp,
+		});
+	}
+
 	#fileBody(): string {
-		let body = this.#lineFor(this.#header);
+		let body = this.#titleSlotLine();
+		body += this.#lineFor(this.#header);
 		for (const entry of this.#entries) body += this.#lineFor(entry);
 		return body;
 	}
@@ -501,6 +518,7 @@ export class SessionManager {
 			this.#storage.writeTextSync(this.#sessionFile, body);
 			this.#fileIsCurrent = true;
 			this.#rewriteRequired = false;
+			this.#hasTitleSlot = true;
 		} catch (err) {
 			this.#noteDiskFailure(err);
 		}
@@ -523,6 +541,7 @@ export class SessionManager {
 				await this.#storage.writeTextAtomic(sessionFile, this.#fileBody());
 				this.#fileIsCurrent = true;
 				this.#rewriteRequired = false;
+				this.#hasTitleSlot = true;
 			},
 			{ epoch },
 		);
@@ -561,12 +580,67 @@ export class SessionManager {
 		}
 	}
 
+	async #persistTitleChangeEntry(entry: TitleChangeEntry, update: SessionTitleUpdate): Promise<void> {
+		if (!this.#persist || !this.#sessionFile) return;
+		if (this.#diskFailure) throw this.#diskFailure;
+
+		if (!this.#shouldHaveSessionFile()) {
+			this.#fileIsCurrent = false;
+			return;
+		}
+
+		if (
+			!this.#fileIsCurrent ||
+			this.#rewriteRequired ||
+			!this.#hasTitleSlot ||
+			!this.#storage.existsSync(this.#sessionFile)
+		) {
+			await this.#rewriteAtomically();
+			return;
+		}
+
+		const epoch = this.#diskEpoch;
+		const line = this.#lineFor(entry);
+		await this.#scheduleDiskWork(
+			async () => {
+				const sessionFile = this.#sessionFile;
+				if (!sessionFile) return;
+				try {
+					await this.#appendWriter().append(line);
+					await this.#storage.updateSessionTitle(sessionFile, update);
+					this.#fileIsCurrent = true;
+				} catch {
+					await this.#closeWriterHandle();
+					await this.#storage.writeTextAtomic(sessionFile, this.#fileBody());
+					this.#clearDiskError();
+					this.#fileIsCurrent = true;
+					this.#rewriteRequired = false;
+					this.#hasTitleSlot = true;
+				}
+			},
+			{ epoch },
+		);
+	}
+
+	#notifyEntryAppended(entry: SessionEntry): void {
+		const callback = this.onEntryAppended;
+		if (callback) {
+			try {
+				callback(entry);
+			} catch (err) {
+				logger.warn("collab entry hook failed", { error: String(err) });
+			}
+		}
+	}
+
 	#resetToNewSession(options?: NewSessionOptions, forcedSessionFile?: string): string | undefined {
 		this.#diskTail = Promise.resolve();
 		this.#clearDiskError();
 		this.#sessionId = mintSessionId();
 		this.#sessionName = undefined;
 		this.#titleSource = undefined;
+		this.#titleUpdatedAt = "";
+		this.#hasTitleSlot = true;
 
 		const timestamp = nowIso();
 		this.#header = {
@@ -577,6 +651,7 @@ export class SessionManager {
 			cwd: this.#cwd,
 			parentSession: options?.parentSession,
 		};
+		this.#titleUpdatedAt = timestamp;
 
 		this.#entries = [];
 		this.#index.clear();
@@ -611,6 +686,7 @@ export class SessionManager {
 		this.#sessionId = header.id;
 		this.#sessionName = header.title;
 		this.#titleSource = header.titleSource;
+		this.#titleUpdatedAt = header.timestamp;
 		this.#index.rebuild(entries);
 	}
 
@@ -626,15 +702,7 @@ export class SessionManager {
 		this.#entries.push(entry);
 		this.#index.insert(entry);
 		this.#appendToSessionFile(entry);
-
-		const callback = this.onEntryAppended;
-		if (callback) {
-			try {
-				callback(entry);
-			} catch (err) {
-				logger.warn("collab entry hook failed", { error: String(err) });
-			}
-		}
+		this.#notifyEntryAppended(entry);
 	}
 
 	#draftPath(): string | null {
@@ -693,6 +761,8 @@ export class SessionManager {
 			sessionId: this.#sessionId,
 			sessionName: this.#sessionName,
 			titleSource: this.#titleSource,
+			titleUpdatedAt: this.#titleUpdatedAt,
+			hasTitleSlot: this.#hasTitleSlot,
 			sessionFile: this.#sessionFile,
 			onDisk: this.#fileIsCurrent,
 			needsRewrite: this.#rewriteRequired,
@@ -717,6 +787,8 @@ export class SessionManager {
 		this.#applyEntries(snapshot.header, [...snapshot.entries]);
 		this.#sessionName = snapshot.sessionName;
 		this.#titleSource = snapshot.titleSource;
+		this.#titleUpdatedAt = snapshot.titleUpdatedAt;
+		this.#hasTitleSlot = snapshot.hasTitleSlot;
 		this.#artifactManager = null;
 		this.#artifactManagerSessionFile = null;
 		this.#adoptedArtifactManager = null;
@@ -733,6 +805,7 @@ export class SessionManager {
 		this.#sessionFile = resolvedSessionFile;
 		this.#rememberBreadcrumb(this.#cwd, resolvedSessionFile);
 
+		const titleSlot = await readTitleSlotFromFile(resolvedSessionFile, this.#storage);
 		const fileEntries = await loadEntriesFromFile(resolvedSessionFile, this.#storage);
 		if (fileEntries.length === 0) {
 			// Explicit but empty/missing path (e.g. --session flag): start fresh but
@@ -763,6 +836,8 @@ export class SessionManager {
 		}
 
 		this.#applyEntries(header, fileEntries.slice(1) as SessionEntry[]);
+		this.#titleUpdatedAt = titleSlot?.updatedAt ?? header.timestamp;
+		this.#hasTitleSlot = titleSlot !== undefined;
 		this.#fileIsCurrent = true;
 		this.#rewriteRequired = migrated;
 		this.#forceFileCreation = true;
@@ -815,6 +890,8 @@ export class SessionManager {
 		};
 		this.#sessionName = this.#header.title;
 		this.#titleSource = this.#header.titleSource;
+		this.#titleUpdatedAt = timestamp;
+		this.#hasTitleSlot = true;
 		this.#fileIsCurrent = false;
 		this.#rewriteRequired = false;
 		this.#forceFileCreation = true;
@@ -1083,7 +1160,7 @@ export class SessionManager {
 	}
 
 	/** The source that set the session name: "user" (manual/RPC) or "auto" (generated title). */
-	get titleSource(): "auto" | "user" | undefined {
+	get titleSource(): SessionTitleSource | undefined {
 		return this.#titleSource;
 	}
 
@@ -1103,20 +1180,33 @@ export class SessionManager {
 	 * @param source "user" for explicit renames; "auto" for generated titles.
 	 *   Auto titles are ignored once the user has set a name.
 	 */
-	async setSessionName(name: string, source: "auto" | "user" = "auto"): Promise<boolean> {
+	async setSessionName(name: string, source: SessionTitleSource = "auto", trigger?: string): Promise<boolean> {
 		if (this.#titleSource === "user" && source === "auto") return false;
 
 		const title = SessionManager.#cleanTitle(name);
 		if (!title) return false;
 
+		const previousTitle = this.#sessionName;
+		const timestamp = nowIso();
 		this.#sessionName = title;
 		this.#titleSource = source;
+		this.#titleUpdatedAt = timestamp;
 		this.#header.title = title;
 		this.#header.titleSource = source;
 
-		if (this.#persist && this.#sessionFile && this.#storage.existsSync(this.#sessionFile)) {
-			await this.#rewriteAtomically();
-		}
+		const entry: TitleChangeEntry = {
+			type: TITLE_CHANGE_ENTRY_TYPE,
+			...this.#freshEntryFields(),
+			timestamp,
+			title,
+			source,
+		};
+		if (previousTitle) entry.previousTitle = previousTitle;
+		if (trigger) entry.trigger = trigger;
+		this.#entries.push(entry);
+		this.#index.insert(entry);
+		this.#notifyEntryAppended(entry);
+		await this.#persistTitleChangeEntry(entry, { title, source, updatedAt: timestamp });
 
 		this.#notifySessionNameListeners();
 		return true;
@@ -1484,6 +1574,8 @@ export class SessionManager {
 		this.#sessionId = newSessionId;
 		this.#sessionName = header.title;
 		this.#titleSource = header.titleSource;
+		this.#titleUpdatedAt = timestamp;
+		this.#hasTitleSlot = true;
 		this.#index.rebuild(this.#entries);
 		this.#artifactManager = null;
 		this.#artifactManagerSessionFile = null;
@@ -1542,7 +1634,7 @@ export class SessionManager {
 			cwd: path.resolve(cwd),
 		};
 		const file = path.join(sessionDir, `${fileSafeTimestamp(timestamp)}_${id}.jsonl`);
-		storage.writeTextSync(file, `${JSON.stringify(header)}\n`);
+		storage.writeTextSync(file, `${serializeTitleSlot({ updatedAt: timestamp })}${JSON.stringify(header)}\n`);
 		return file;
 	}
 
@@ -1577,6 +1669,8 @@ export class SessionManager {
 		manager.#header.titleSource = sourceHeader?.titleSource;
 		manager.#sessionName = manager.#header.title;
 		manager.#titleSource = manager.#header.titleSource;
+		manager.#titleUpdatedAt = nowIso();
+		manager.#hasTitleSlot = true;
 		manager.#entries = history;
 		manager.#index.rebuild(history);
 		manager.sanitizeLoadedOpenAIResponsesReplayMetadata();

package/src/session/session-persistence.ts

@@ -110,9 +110,8 @@ function truncateForPersistence(obj: unknown, blobStore: BlobStore, key?: string
 		const entries: Array<readonly [string, unknown]> = [];
 		for (const [childKey, value] of Object.entries(obj)) {
 			// Strip transient/redundant properties that shouldn't be persisted.
-			// - partialJson: streaming accumulator for tool call JSON parsing
 			// - jsonlEvents: raw subprocess streaming events (already saved to artifact files)
-			if (childKey === "partialJson" || childKey === "jsonlEvents") {
+			if (childKey === "jsonlEvents") {
 				changed = true;
 				continue;
 			}
@@ -142,6 +141,100 @@ function truncateForPersistence(obj: unknown, blobStore: BlobStore, key?: string
 	return obj;
 }
 
+/**
+ * Read the duplication-relevant fields of an OpenAI Responses reasoning item.
+ * Returns `undefined` for anything that is not a `type: "reasoning"` object, so
+ * non-reasoning payload entries and corrupt signatures are never matched.
+ */
+function readReasoningItem(item: unknown): { encrypted_content?: string; id?: string } | undefined {
+	if (item === null || typeof item !== "object") return undefined;
+	if (!("type" in item) || item.type !== "reasoning") return undefined;
+	const reasoning: { encrypted_content?: string; id?: string } = {};
+	if ("encrypted_content" in item && typeof item.encrypted_content === "string" && item.encrypted_content.length > 0) {
+		reasoning.encrypted_content = item.encrypted_content;
+	}
+	if ("id" in item && typeof item.id === "string" && item.id.length > 0) reasoning.id = item.id;
+	return reasoning;
+}
+
+/**
+ * True when a `thinkingSignature` (a JSON-encoded reasoning item) is already
+ * carried by a reasoning item in the message's provider payload — matched on
+ * `encrypted_content` (the load-bearing blob) when present, else on item `id`.
+ * A signature the payload does not cover is never reported as recoverable, so it
+ * is always kept.
+ */
+function signatureCoveredByPayload(
+	signature: string,
+	encrypted: ReadonlySet<string>,
+	ids: ReadonlySet<string>,
+): boolean {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(signature);
+	} catch {
+		return false;
+	}
+	const reasoning = readReasoningItem(parsed);
+	if (!reasoning) return false;
+	if (reasoning.encrypted_content) return encrypted.has(reasoning.encrypted_content);
+	if (reasoning.id) return ids.has(reasoning.id);
+	return false;
+}
+
+/**
+ * Drop `thinkingSignature` from assistant thinking blocks whose reasoning item is
+ * already carried, verbatim, in the message's OpenAI Responses `providerPayload`.
+ *
+ * Responses/Codex turns mint each reasoning item once and store it twice:
+ * `providerPayload.items` (the authoritative native-history copy that replay and
+ * remote compaction read) and `content[].thinkingSignature`, which is literally
+ * `JSON.stringify(reasoningItem)` — including the large `encrypted_content` blob.
+ * Replay only ever reads the payload; the signature is a no-payload fallback that
+ * same-provider turns never reach and cross-model turns strip as untrustworthy.
+ * Persisting both stores the encrypted reasoning twice for zero token or replay
+ * benefit, so the on-disk copy drops the duplicate signature whenever its
+ * reasoning item is recoverable from the payload. The in-memory entry is left
+ * untouched; only the serialized line is slimmed.
+ */
+function stripReplayedReasoningSignatures(entry: FileEntry): FileEntry {
+	if (entry.type !== "message" || entry.message.role !== "assistant") return entry;
+	const message = entry.message;
+	const payload = message.providerPayload;
+	if (payload?.type !== "openaiResponsesHistory" || !Array.isArray(payload.items)) return entry;
+	const hasSignedThinking = message.content.some(
+		block =>
+			block.type === "thinking" && typeof block.thinkingSignature === "string" && block.thinkingSignature.length > 0,
+	);
+	if (!hasSignedThinking) return entry;
+
+	const encrypted = new Set<string>();
+	const ids = new Set<string>();
+	for (const rawItem of payload.items) {
+		const reasoning = readReasoningItem(rawItem);
+		if (!reasoning) continue;
+		if (reasoning.encrypted_content) encrypted.add(reasoning.encrypted_content);
+		if (reasoning.id) ids.add(reasoning.id);
+	}
+	if (encrypted.size === 0 && ids.size === 0) return entry;
+
+	let changed = false;
+	const content = message.content.map(block => {
+		if (
+			block.type !== "thinking" ||
+			typeof block.thinkingSignature !== "string" ||
+			block.thinkingSignature.length === 0
+		) {
+			return block;
+		}
+		if (!signatureCoveredByPayload(block.thinkingSignature, encrypted, ids)) return block;
+		changed = true;
+		return { ...block, thinkingSignature: undefined };
+	});
+	if (!changed) return entry;
+	return { ...entry, message: { ...message, content } };
+}
+
 export function prepareEntryForPersistence(entry: FileEntry, blobStore: BlobStore): FileEntry {
-	return truncateForPersistence(entry, blobStore) as FileEntry;
+	return truncateForPersistence(stripReplayedReasoningSignatures(entry), blobStore) as FileEntry;
 }

package/src/session/session-storage.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
 import { hasFsCode, isEnoent, logger, peekFileEnds, Snowflake, toError } from "@oh-my-pi/pi-utils";
+import { overlayTitleSlotContent, type SessionTitleUpdate, serializeTitleSlot } from "./session-title-slot";
 
 const utf8Decoder = new TextDecoder("utf-8");
 
@@ -31,6 +32,14 @@ export interface SessionStorage {
 	ensureDirSync(dir: string): void;
 	existsSync(path: string): boolean;
 	writeTextSync(path: string, content: string): void;
+	/**
+	 * Update the current session title through the storage backend.
+	 *
+	 * File-like backends rewrite the fixed-width JSONL title slot; indexed
+	 * backends can store the semantic title fields and synthesize the slot when
+	 * reading.
+	 */
+	updateSessionTitle(path: string, update: SessionTitleUpdate): Promise<void>;
 	statSync(path: string): SessionStorageStat;
 	listFilesSync(dir: string, pattern: string): string[];
 
@@ -163,6 +172,25 @@ export class FileSessionStorage implements SessionStorage {
 		}
 	}
 
+	async updateSessionTitle(fpath: string, update: SessionTitleUpdate): Promise<void> {
+		const fd = fs.openSync(fpath, "r+");
+		try {
+			const buf = Buffer.from(serializeTitleSlot(update), "utf-8");
+			let offset = 0;
+			while (offset < buf.length) {
+				const written = fs.writeSync(fd, buf, offset, buf.length - offset, offset);
+				if (written === 0) {
+					throw new Error("Short write");
+				}
+				offset += written;
+			}
+		} catch (err) {
+			throw toError(err);
+		} finally {
+			fs.closeSync(fd);
+		}
+	}
+
 	statSync(path: string): SessionStorageStat {
 		const stats = fs.statSync(path);
 		return { size: stats.size, mtimeMs: stats.mtimeMs, mtime: stats.mtime };
@@ -526,6 +554,14 @@ export class MemorySessionStorage implements SessionStorage {
 		this.#files.set(path, createMemoryFileEntry(content, Date.now()));
 	}
 
+	async updateSessionTitle(path: string, update: SessionTitleUpdate): Promise<void> {
+		const entry = this.#requireEntry(path);
+		this.#files.set(
+			path,
+			createMemoryFileEntry(overlayTitleSlotContent(materializeMemoryEntry(entry), update), Date.now()),
+		);
+	}
+
 	/**
 	 * Internal O(1) append used by {@link MemorySessionStorageWriter}. Lazily
 	 * creates the entry. External callers should go through `openWriter()`

package/src/session/session-title-slot.ts

@@ -0,0 +1,141 @@
+import {
+	SESSION_TITLE_SLOT_BYTES,
+	SESSION_TITLE_SLOT_ENTRY_TYPE,
+	type SessionTitleSlotEntry,
+	type SessionTitleSource,
+} from "./session-entries";
+
+const utf8Encoder = new TextEncoder();
+
+/** Semantic title update persisted by session storage backends. */
+export interface SessionTitleUpdate {
+	title?: string;
+	source?: SessionTitleSource;
+	updatedAt: string;
+}
+
+function byteLength(value: string): number {
+	return utf8Encoder.encode(value).byteLength;
+}
+
+function titleSlotLine(title: string, source: SessionTitleSource | undefined, updatedAt: string, pad: string): string {
+	const slot: SessionTitleSlotEntry = source
+		? {
+				type: SESSION_TITLE_SLOT_ENTRY_TYPE,
+				v: 1,
+				title,
+				source,
+				updatedAt,
+				pad,
+			}
+		: {
+				type: SESSION_TITLE_SLOT_ENTRY_TYPE,
+				v: 1,
+				title,
+				updatedAt,
+				pad,
+			};
+	return `${JSON.stringify(slot)}\n`;
+}
+
+function truncateTitleForSlot(title: string, source: SessionTitleSource | undefined, updatedAt: string): string {
+	const codePoints = [...title];
+	let low = 0;
+	let high = codePoints.length;
+	let best = "";
+
+	while (low <= high) {
+		const mid = (low + high) >>> 1;
+		const candidate = codePoints.slice(0, mid).join("");
+		if (byteLength(titleSlotLine(candidate, source, updatedAt, "")) <= SESSION_TITLE_SLOT_BYTES) {
+			best = candidate;
+			low = mid + 1;
+		} else {
+			high = mid - 1;
+		}
+	}
+
+	return best;
+}
+
+function isSessionTitleSource(value: unknown): value is SessionTitleSource {
+	return value === "auto" || value === "user";
+}
+
+function parseTitleSlotObject(value: unknown): SessionTitleSlotEntry | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	const record = value as Record<string, unknown>;
+	if (record.type !== SESSION_TITLE_SLOT_ENTRY_TYPE || record.v !== 1) return undefined;
+	if (typeof record.title !== "string" || typeof record.updatedAt !== "string" || typeof record.pad !== "string") {
+		return undefined;
+	}
+	const source = record.source;
+	if (source !== undefined && !isSessionTitleSource(source)) return undefined;
+	const slot: SessionTitleSlotEntry = {
+		type: SESSION_TITLE_SLOT_ENTRY_TYPE,
+		v: 1,
+		title: record.title,
+		updatedAt: record.updatedAt,
+		pad: record.pad,
+	};
+	if (source) slot.source = source;
+	return slot;
+}
+
+/** Parse a physical title slot JSONL line. Returns undefined for legacy headers. */
+export function parseTitleSlotLine(line: string): SessionTitleSlotEntry | undefined {
+	try {
+		return parseTitleSlotObject(JSON.parse(line)) ?? undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Parse the fixed-width title slot from a physical session body. */
+export function parseTitleSlotFromContent(content: string): SessionTitleSlotEntry | undefined {
+	const newlineIndex = content.indexOf("\n");
+	if (newlineIndex < 0) return undefined;
+	return parseTitleSlotLine(content.slice(0, newlineIndex));
+}
+
+/** Convert a parsed title slot to the semantic storage update shape. */
+export function titleUpdateFromSlot(slot: SessionTitleSlotEntry | undefined): SessionTitleUpdate | undefined {
+	if (!slot) return undefined;
+	return {
+		title: slot.title,
+		source: slot.source,
+		updatedAt: slot.updatedAt,
+	};
+}
+
+/** Serialize the fixed-width first-line title slot, exactly 256 UTF-8 bytes including newline. */
+export function serializeTitleSlot(options: SessionTitleUpdate): string {
+	const title = truncateTitleForSlot(options.title ?? "", options.source, options.updatedAt);
+	const unpadded = titleSlotLine(title, options.source, options.updatedAt, "");
+	const padBytes = SESSION_TITLE_SLOT_BYTES - byteLength(unpadded);
+	if (padBytes < 0) throw new Error("Session title slot metadata exceeds fixed slot size");
+	const line = titleSlotLine(title, options.source, options.updatedAt, " ".repeat(padBytes));
+	if (byteLength(line) !== SESSION_TITLE_SLOT_BYTES) {
+		throw new Error("Session title slot serialization failed to produce fixed-width output");
+	}
+	return line;
+}
+
+/** Replace the physical fixed-width title slot in a full session body. */
+export function overlayTitleSlotContent(content: string, update: SessionTitleUpdate): string {
+	const slot = Buffer.from(serializeTitleSlot(update), "utf-8");
+	const existing = Buffer.from(content, "utf-8");
+	if (existing.length <= slot.length) return slot.toString("utf-8");
+	return Buffer.concat([slot, existing.subarray(slot.length)]).toString("utf-8");
+}
+
+/** Replace the physical fixed-width title slot in a prefix byte window. */
+export function overlayTitleSlotPrefix(prefix: string, prefixBytes: number, update: SessionTitleUpdate): string {
+	if (prefixBytes <= 0) return "";
+	const slot = Buffer.from(serializeTitleSlot(update), "utf-8");
+	if (prefixBytes <= slot.length) return slot.subarray(0, prefixBytes).toString("utf-8");
+	const existing = Buffer.from(prefix, "utf-8");
+	return Buffer.concat([slot, existing.subarray(slot.length)])
+		.subarray(0, prefixBytes)
+		.toString("utf-8");
+}

package/src/session/settings-stream-fn.ts

@@ -0,0 +1,49 @@
+/**
+ * Settings-aware stream wrapper shared by the main agent (sdk.ts) and the
+ * advisor agent (AgentSession.#buildAdvisorRuntime).
+ *
+ * Reads OpenRouter / Antigravity routing variants, Responses-family text
+ * verbosity, per-provider in-flight caps, and the loop guard out of `Settings`
+ * per request, layering them onto whatever options the caller passed. Before
+ * this helper existed, advisor turns called bare `streamSimple` while the main
+ * turn went through an inline closure that read these settings — so an advisor on
+ * OpenRouter never saw `providers.openrouterVariant`, breaking sticky routing
+ * and OpenRouter response-cache hits across advisor calls.
+ */
+import type { StreamFn } from "@oh-my-pi/pi-agent-core";
+import { type SimpleStreamOptions, streamSimple } from "@oh-my-pi/pi-ai";
+import { type Settings, validateProviderMaxInFlightRequests } from "../config/settings";
+
+/**
+ * Build a {@link StreamFn} that reads provider routing/guard settings from
+ * `settings` per call and forwards to `base` (defaults to `streamSimple`).
+ *
+ * Caller-supplied `streamOptions` always win — the helper only fills holes.
+ */
+export function createSettingsAwareStreamFn(settings: Settings, base: StreamFn = streamSimple): StreamFn {
+	return (model, context, streamOptions) => {
+		const openrouterRoutingPreset = settings.get("providers.openrouterVariant");
+		const openrouterVariant =
+			openrouterRoutingPreset && openrouterRoutingPreset !== "default" ? openrouterRoutingPreset : undefined;
+		const antigravityEndpointMode = settings.get("providers.antigravityEndpoint");
+		const textVerbosity =
+			model.api === "openai-codex-responses" || model.api === "openai-responses"
+				? settings.get("textVerbosity")
+				: undefined;
+		const merged: SimpleStreamOptions = {
+			...streamOptions,
+			openrouterVariant: streamOptions?.openrouterVariant ?? openrouterVariant,
+			antigravityEndpointMode: streamOptions?.antigravityEndpointMode ?? antigravityEndpointMode,
+			textVerbosity: streamOptions?.textVerbosity ?? textVerbosity,
+			maxInFlightRequests: validateProviderMaxInFlightRequests(
+				streamOptions?.maxInFlightRequests ?? settings.get("providers.maxInFlightRequests"),
+			),
+			loopGuard: {
+				enabled: settings.get("model.loopGuard.enabled"),
+				checkAssistantContent: settings.get("model.loopGuard.checkAssistantContent"),
+				...streamOptions?.loopGuard,
+			},
+		};
+		return base(model, context, merged);
+	};
+}