@oh-my-pi/pi-coding-agent 15.13.3 → 16.0.1

package/src/session/session-dump-format.ts

@@ -2,22 +2,10 @@
  * Plain-text / markdown session formatting (same shape as /dump clipboard export).
  */
 import type { AgentMessage, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import { INTENT_FIELD } from "@oh-my-pi/pi-agent-core";
-import type { AssistantMessage, Model, ToolExample, TSchema } from "@oh-my-pi/pi-ai";
-import { getInbandGrammar, renderToolInventory } from "@oh-my-pi/pi-ai/grammar";
-import { preferredToolSyntax } from "@oh-my-pi/pi-catalog/identity";
-import { canonicalizeMessage } from "../utils/thinking-display";
-import {
-	type BashExecutionMessage,
-	type BranchSummaryMessage,
-	bashExecutionToText,
-	type CompactionSummaryMessage,
-	type CustomMessage,
-	type FileMentionMessage,
-	type HookMessage,
-	type PythonExecutionMessage,
-	pythonExecutionToText,
-} from "./messages";
+import type { Model, ToolExample, TSchema } from "@oh-my-pi/pi-ai";
+import { getDialectDefinition, renderToolInventory } from "@oh-my-pi/pi-ai/dialect";
+import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";
+import { convertToLlm } from "./messages";
 
 /** Minimal tool shape for dump output (matches AgentTool fields used by formatSessionDumpText). */
 export interface SessionDumpToolInfo {
@@ -40,7 +28,7 @@ export interface FormatSessionDumpTextOptions {
  */
 export function formatSessionDumpText(options: FormatSessionDumpTextOptions): string {
 	const lines: string[] = [];
-	const grammar = getInbandGrammar(preferredToolSyntax(options.model?.id ?? ""));
+	const definition = getDialectDefinition(preferredDialect(options.model?.id ?? ""));
 
 	const systemPrompt = options.systemPrompt?.filter(prompt => prompt.length > 0) ?? [];
 	if (systemPrompt.length > 0) {
@@ -62,125 +50,21 @@ export function formatSessionDumpText(options: FormatSessionDumpTextOptions): st
 	lines.push("\n");
 
 	const tools = options.tools ?? [];
-	if (tools.length > 0) {
+	const inventoryTools = tools.map(tool => ({
+		name: tool.name,
+		description: tool.description,
+		parameters: tool.parameters as TSchema,
+		examples: tool.examples,
+	}));
+	if (inventoryTools.length > 0) {
 		lines.push("## Available Tools\n");
-		const inventoryTools = tools.map(tool => ({
-			name: tool.name,
-			description: tool.description,
-			parameters: tool.parameters as TSchema,
-			examples: tool.examples,
-		}));
 		lines.push(renderToolInventory(inventoryTools, options.model?.id ?? ""));
 		lines.push("\n");
 	}
 
-	for (const msg of options.messages) {
-		if (msg.role === "user" || msg.role === "developer") {
-			lines.push(msg.role === "developer" ? "## Developer\n" : "## User\n");
-			if (typeof msg.content === "string") {
-				lines.push(msg.content);
-			} else {
-				for (const c of msg.content) {
-					if (c.type === "text") {
-						lines.push(c.text);
-					} else if (c.type === "image") {
-						lines.push("[Image]");
-					}
-				}
-			}
-			lines.push("\n");
-		} else if (msg.role === "assistant") {
-			const assistantMsg = msg as AssistantMessage;
-			lines.push("## Assistant\n");
-
-			for (const c of assistantMsg.content) {
-				if (c.type === "text") {
-					lines.push(c.text);
-				} else if (c.type === "thinking") {
-					const thinking = canonicalizeMessage(c.thinking);
-					if (thinking.length === 0) continue;
-					lines.push("<thinking>");
-					lines.push(thinking);
-					lines.push("</thinking>\n");
-				} else if (c.type === "toolCall") {
-					const args = { ...(c.arguments as Record<string, unknown>) };
-					delete args[INTENT_FIELD];
-					lines.push(grammar.renderToolCall({ ...c, arguments: args }));
-				}
-			}
-			lines.push("");
-		} else if (msg.role === "toolResult") {
-			lines.push(`### Tool Result: ${msg.toolName}`);
-			if (msg.isError) {
-				lines.push("(error)");
-			}
-			for (const c of msg.content) {
-				if (c.type === "text") {
-					lines.push("```");
-					lines.push(c.text);
-					lines.push("```");
-				} else if (c.type === "image") {
-					lines.push("[Image output]");
-				}
-			}
-			lines.push("");
-		} else if (msg.role === "bashExecution") {
-			const bashMsg = msg as BashExecutionMessage;
-			if (!bashMsg.excludeFromContext) {
-				lines.push("## Bash Execution\n");
-				lines.push(bashExecutionToText(bashMsg));
-				lines.push("\n");
-			}
-		} else if (msg.role === "pythonExecution") {
-			const pythonMsg = msg as PythonExecutionMessage;
-			if (!pythonMsg.excludeFromContext) {
-				lines.push("## Python Execution\n");
-				lines.push(pythonExecutionToText(pythonMsg));
-				lines.push("\n");
-			}
-		} else if (msg.role === "custom" || msg.role === "hookMessage") {
-			const customMsg = msg as CustomMessage | HookMessage;
-			lines.push(`## ${customMsg.customType}\n`);
-			if (typeof customMsg.content === "string") {
-				lines.push(customMsg.content);
-			} else {
-				for (const c of customMsg.content) {
-					if (c.type === "text") {
-						lines.push(c.text);
-					} else if (c.type === "image") {
-						lines.push("[Image]");
-					}
-				}
-			}
-			lines.push("\n");
-		} else if (msg.role === "branchSummary") {
-			const branchMsg = msg as BranchSummaryMessage;
-			lines.push("## Branch Summary\n");
-			lines.push(`(from branch: ${branchMsg.fromId})\n`);
-			lines.push(branchMsg.summary);
-			lines.push("\n");
-		} else if (msg.role === "compactionSummary") {
-			const compactMsg = msg as CompactionSummaryMessage;
-			lines.push("## Compaction Summary\n");
-			lines.push(`(${compactMsg.tokensBefore} tokens before compaction)\n`);
-			lines.push(compactMsg.summary);
-			lines.push("\n");
-		} else if (msg.role === "fileMention") {
-			const fileMsg = msg as FileMentionMessage;
-			lines.push("## File Mention\n");
-			for (const file of fileMsg.files) {
-				lines.push(`<file path="${file.path}">`);
-				if (file.content) {
-					lines.push(file.content);
-				}
-				if (file.image) {
-					lines.push("[Image attached]");
-				}
-				lines.push("</file>\n");
-			}
-			lines.push("\n");
-		}
-	}
+	lines.push("## Transcript\n");
+	lines.push(definition.renderTranscript(convertToLlm([...options.messages]), { tools: inventoryTools }));
+	lines.push("\n");
 
 	return lines.join("\n").trim();
 }

package/src/session/session-history-format.ts

@@ -22,6 +22,10 @@ import type {
 export interface HistoryFormatOptions {
 	/** Optional H1 prepended to the transcript. */
 	title?: string;
+	/** Render assistant thinking blocks (default: elided). */
+	includeThinking?: boolean;
+	/** Render tool intent comment before tool call lines. */
+	includeToolIntent?: boolean;
 }
 
 /** Max length of the primary-arg summary inside `→ tool(...)` lines. */
@@ -100,17 +104,30 @@ function toolCallLine(
 	name: string,
 	args: Record<string, unknown> | undefined,
 	result: ToolResultMessage | undefined,
+	includeToolIntent?: boolean,
 ): string {
 	const head = `→ ${name}(${primaryArg(args)})`;
-	if (!result) return `${head} ⇒ pending`;
-	const text = contentToText(result.content);
-	const lines = lineCount(text);
-	const count = `${lines} ${lines === 1 ? "line" : "lines"}`;
-	if (result.isError) {
-		const firstLine = oneLine(text.split("\n", 1)[0] ?? "");
-		return firstLine ? `${head} ⇒ error · ${count} — ${firstLine}` : `${head} ⇒ error · ${count}`;
+	let base: string;
+	if (!result) {
+		base = `${head} ⇒ pending`;
+	} else {
+		const text = contentToText(result.content);
+		const lines = lineCount(text);
+		const count = `${lines} ${lines === 1 ? "line" : "lines"}`;
+		if (result.isError) {
+			const firstLine = oneLine(text.split("\n", 1)[0] ?? "");
+			base = firstLine ? `${head} ⇒ error · ${count} — ${firstLine}` : `${head} ⇒ error · ${count}`;
+		} else {
+			base = `${head} ⇒ ok · ${count}`;
+		}
+	}
+
+	const intent = includeToolIntent ? args?.[INTENT_FIELD] : undefined;
+	if (typeof intent === "string" && intent.trim()) {
+		const formattedIntent = oneLine(intent, 80);
+		return `# ${formattedIntent}\n${base}`;
 	}
-	return `${head} ⇒ ok · ${count}`;
+	return base;
 }
 
 /** One line for a user-initiated `!`/`$` execution. */
@@ -193,9 +210,11 @@ export function formatSessionHistoryMarkdown(messages: unknown[], opts?: History
 					} else if (block.type === "toolCall") {
 						const result = resultsByCallId.get(block.id);
 						if (result) consumed.add(block.id);
-						body.push(toolCallLine(block.name, block.arguments, result));
+						body.push(toolCallLine(block.name, block.arguments, result, opts?.includeToolIntent));
+					} else if (opts?.includeThinking && block.type === "thinking" && block.thinking.trim()) {
+						body.push(`_thinking:_ ${block.thinking}`);
 					}
-					// thinking / redactedThinking elided entirely
+					// redactedThinking elided entirely (no readable text)
 				}
 				if (body.length === 0) break;
 				lines.push("## assistant", "", ...body, "");
@@ -204,7 +223,7 @@ export function formatSessionHistoryMarkdown(messages: unknown[], opts?: History
 			case "toolResult": {
 				// Normally consumed by its toolCall; orphans (e.g. truncated history) get their own line.
 				if (consumed.has(msg.toolCallId)) break;
-				lines.push(toolCallLine(msg.toolName, undefined, msg), "");
+				lines.push(toolCallLine(msg.toolName, undefined, msg, opts?.includeToolIntent), "");
 				break;
 			}
 			case "bashExecution": {

package/src/session/session-manager.ts

@@ -1522,15 +1522,17 @@ export class SessionManager {
 	/**
 	 * Open a specific session file.
 	 * @param sessionDir Optional dir for /new or /branch; defaults to the file's parent.
+	 * @param options.initialCwd Cwd to use when the file is empty or missing.
 	 */
 	static async open(
 		filePath: string,
 		sessionDir?: string,
 		storage: SessionStorage = new FileSessionStorage(),
+		options?: { initialCwd?: string },
 	): Promise<SessionManager> {
 		const loaded = await loadEntriesFromFile(filePath, storage);
 		const header = loaded.find(entry => entry.type === "session") as SessionHeader | undefined;
-		const cwd = header?.cwd ?? getProjectDir();
+		const cwd = header?.cwd ?? options?.initialCwd ?? getProjectDir();
 		const dir = sessionDir ?? path.dirname(path.resolve(filePath));
 		const manager = new SessionManager(cwd, dir, true, storage);
 		await manager.setSessionFile(filePath);

package/src/session/yield-queue.ts

@@ -6,6 +6,8 @@ export interface YieldDispatcher<P> {
 	isStale?(entry: P): boolean;
 	/** Produce one batched AgentMessage from non-stale entries. Return null to skip. */
 	build(survivors: P[]): AgentMessage | null;
+	/** If true, entries for this kind are drained only by {@link drainLazy} and never trigger the idle flush. */
+	skipIdleFlush?: boolean;
 }
 
 export interface YieldQueueOptions {
@@ -20,6 +22,7 @@ type YieldFlushMode = "streaming" | "idle";
 interface StoredDispatcher {
 	isStale?: (entry: unknown) => boolean;
 	build: (survivors: unknown[]) => AgentMessage | null;
+	skipIdleFlush?: boolean;
 }
 
 function formatError(error: unknown): string {
@@ -40,6 +43,7 @@ export class YieldQueue {
 		const stored: StoredDispatcher = {
 			...(dispatcher.isStale ? { isStale: entry => dispatcher.isStale?.(entry as P) ?? false } : {}),
 			build: survivors => dispatcher.build(survivors as P[]),
+			...(dispatcher.skipIdleFlush ? { skipIdleFlush: true } : {}),
 		};
 		this.#dispatchers.set(kind, stored);
 		return () => {
@@ -60,7 +64,7 @@ export class YieldQueue {
 			this.#entries.set(kind, entries);
 		}
 		entries.push(entry);
-		if (!this.#options.isStreaming()) {
+		if (!this.#options.isStreaming() && !this.#dispatchers.get(kind)!.skipIdleFlush) {
 			this.#scheduleIdleFlush();
 		}
 	}

package/src/slash-commands/builtin-registry.ts

@@ -419,6 +419,103 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "advisor",
+		description: "Toggle the advisor (a second model that reviews each turn and injects notes)",
+		acpDescription: "Toggle advisor",
+		acpInputHint: "[on|off|status|dump [raw]]",
+		subcommands: [
+			{ name: "on", description: "Enable the advisor" },
+			{ name: "off", description: "Disable the advisor" },
+			{ name: "status", description: "Show advisor status" },
+			{ name: "dump", description: "Copy the advisor's transcript to clipboard", usage: "[raw]" },
+		],
+		allowArgs: true,
+		handle: async (command, runtime) => {
+			const { verb, rest } = parseSubcommand(command.args);
+			if (!verb || verb === "toggle") {
+				const active = runtime.session.toggleAdvisorEnabled();
+				const configured = runtime.session.isAdvisorEnabled();
+				if (active) {
+					await runtime.output("Advisor enabled.");
+				} else if (configured) {
+					await runtime.output("Advisor setting enabled, but no model is assigned to the 'advisor' role.");
+				} else {
+					await runtime.output("Advisor disabled.");
+				}
+				return commandConsumed();
+			}
+			if (verb === "on") {
+				const active = runtime.session.setAdvisorEnabled(true);
+				await runtime.output(
+					active ? "Advisor enabled." : "Advisor setting enabled, but no model is assigned to the 'advisor' role.",
+				);
+				return commandConsumed();
+			}
+			if (verb === "off") {
+				runtime.session.setAdvisorEnabled(false);
+				await runtime.output("Advisor disabled.");
+				return commandConsumed();
+			}
+			if (verb === "status") {
+				await runtime.output(runtime.session.formatAdvisorStatus());
+				return commandConsumed();
+			}
+			if (verb === "dump") {
+				const isRaw = rest.toLowerCase() === "raw";
+				const text = runtime.session.formatAdvisorHistoryAsText({ compact: !isRaw });
+				await runtime.output(text ?? "Advisor is not active for this session.");
+				return commandConsumed();
+			}
+			return usage("Usage: /advisor [on|off|status|dump [raw]]", runtime);
+		},
+		handleTui: async (command, runtime) => {
+			const { verb, rest } = parseSubcommand(command.args);
+			if (!verb || verb === "toggle") {
+				const active = runtime.ctx.session.toggleAdvisorEnabled();
+				const configured = runtime.ctx.session.isAdvisorEnabled();
+				if (active) {
+					runtime.ctx.showStatus("Advisor enabled.");
+				} else if (configured) {
+					runtime.ctx.showStatus("Advisor setting enabled, but no model is assigned to the 'advisor' role.");
+				} else {
+					runtime.ctx.showStatus("Advisor disabled.");
+				}
+				refreshStatusLine(runtime.ctx);
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			if (verb === "on") {
+				const active = runtime.ctx.session.setAdvisorEnabled(true);
+				runtime.ctx.showStatus(
+					active ? "Advisor enabled." : "Advisor setting enabled, but no model is assigned to the 'advisor' role.",
+				);
+				refreshStatusLine(runtime.ctx);
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			if (verb === "off") {
+				runtime.ctx.session.setAdvisorEnabled(false);
+				runtime.ctx.showStatus("Advisor disabled.");
+				refreshStatusLine(runtime.ctx);
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			if (verb === "status") {
+				await runtime.ctx.handleAdvisorStatusCommand();
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			if (verb === "dump") {
+				const isRaw = rest.toLowerCase() === "raw";
+				runtime.ctx.handleAdvisorDumpCommand(isRaw);
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			runtime.ctx.showStatus("Usage: /advisor [on|off|status|dump [raw]]");
+			runtime.ctx.editor.setText("");
+		},
+	},
 	{
 		name: "export",
 		description: "Export session to HTML file",
@@ -450,13 +547,17 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 		name: "dump",
 		description: "Copy session transcript to clipboard",
 		acpDescription: "Return full transcript as plain text",
-		handle: async (_command, runtime) => {
-			const text = runtime.session.formatSessionAsText();
+		inlineHint: "[raw]",
+		allowArgs: true,
+		handle: async (command, runtime) => {
+			const isRaw = command.args.trim().toLowerCase() === "raw";
+			const text = runtime.session.formatSessionAsText({ compact: !isRaw });
 			await runtime.output(text || "No messages to dump yet.");
 			return commandConsumed();
 		},
-		handleTui: async (_command, runtime) => {
-			await runtime.ctx.handleDumpCommand();
+		handleTui: (command, runtime) => {
+			const isRaw = command.args.trim().toLowerCase() === "raw";
+			runtime.ctx.handleDumpCommand(isRaw);
 			runtime.ctx.editor.setText("");
 		},
 	},

package/src/system-prompt.ts

@@ -5,7 +5,7 @@
 import * as os from "node:os";
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import type { ToolExample, TSchema } from "@oh-my-pi/pi-ai";
-import { renderToolInventory } from "@oh-my-pi/pi-ai/grammar";
+import { renderToolInventory } from "@oh-my-pi/pi-ai/dialect";
 import { $env, getGpuCachePath, getProjectDir, hasFsCode, isEnoent, logger, prompt } from "@oh-my-pi/pi-utils";
 import { $ } from "bun";
 import { contextFileCapability } from "./capability/context-file";

package/src/task/executor.ts

@@ -33,7 +33,7 @@ import { type CreateAgentSessionOptions, createAgentSession, discoverAuthStorage
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import type { ArtifactManager } from "../session/artifacts";
 import type { AuthStorage } from "../session/auth-storage";
-import { SKILL_PROMPT_MESSAGE_TYPE } from "../session/messages";
+import { SKILL_PROMPT_MESSAGE_TYPE, USER_INTERRUPT_LABEL } from "../session/messages";
 import { SessionManager } from "../session/session-manager";
 import { truncateTail } from "../session/streaming-output";
 import type { ContextFileEntry } from "../tools";
@@ -1829,9 +1829,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				? resolvedThinkingLevel
 				: (thinkingLevel ?? resolvedThinkingLevel);
 
+			const effectiveCwd = worktree ?? cwd;
 			const sessionManager = sessionFile
-				? await awaitAbortable(SessionManager.open(sessionFile))
-				: SessionManager.inMemory(worktree ?? cwd);
+				? await awaitAbortable(SessionManager.open(sessionFile, undefined, undefined, { initialCwd: effectiveCwd }))
+				: SessionManager.inMemory(effectiveCwd);
 			if (options.parentArtifactManager) {
 				sessionManager.adoptArtifactManager(options.parentArtifactManager);
 			}
@@ -2047,7 +2048,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					{
 						getModel: () => session.model,
 						isIdle: () => !session.isStreaming,
-						abort: () => session.abort(),
+						abort: () => session.abort({ reason: USER_INTERRUPT_LABEL }),
 						hasPendingMessages: () => session.queuedMessageCount > 0,
 						shutdown: () => {},
 						getContextUsage: () => session.getContextUsage(),

package/src/task/index.ts

@@ -366,6 +366,49 @@ export function buildSpecializationAdvisory(
 	);
 }
 
+/**
+ * Suggestion — never a rejection — nudging the spawner to coordinate via `irc`
+ * when one call creates ≥2 live siblings and it still holds spawn capacity.
+ * Returns undefined when there is nothing to coordinate or IRC is unavailable.
+ */
+export function buildCoordinationAdvisory(
+	items: TaskItem[],
+	depthCapacity: boolean,
+	ircEnabled: boolean,
+): string | undefined {
+	if (!depthCapacity || !ircEnabled || items.length < 2) return undefined;
+	return (
+		`Coordinate: ${items.length} siblings are running together. If their work overlaps, have them ` +
+		`message each other via \`irc\` (by id, or "all" to broadcast) before editing shared files — ` +
+		`live coordination beats a serial handoff. Check \`irc\` op:"list" to see who is doing what.`
+	);
+}
+
+/**
+ * Compose the non-blocking advisory appended to a `task` result: the
+ * specialization nudge, plus — only when the siblings keep running after this
+ * call (`willRunAsync`) — the coordination suggestion. Coordination is gated on
+ * async because a sync fanout's siblings have already finished, so a
+ * "coordinate while they run" hint would misfire. Returns undefined when
+ * neither applies.
+ */
+export function composeSpawnAdvisory(args: {
+	agentName: string | undefined;
+	items: TaskItem[];
+	depthCapacity: boolean;
+	ircEnabled: boolean;
+	willRunAsync: boolean;
+}): string | undefined {
+	return (
+		[
+			buildSpecializationAdvisory(args.agentName, args.items, args.depthCapacity),
+			args.willRunAsync ? buildCoordinationAdvisory(args.items, args.depthCapacity, args.ircEnabled) : undefined,
+		]
+			.filter(Boolean)
+			.join("\n\n") || undefined
+	);
+}
+
 /** Sentinel for async jobs whose subagent finished with a failing result; progress is already updated. */
 class TaskJobError extends Error {}
 
@@ -539,16 +582,35 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			this.session.settings.get("task.maxRecursionDepth") ?? 2,
 			this.session.taskDepth ?? 0,
 		);
-		const advisory = buildSpecializationAdvisory(params.agent, spawnItems, depthCapacity);
+		const ircEnabled = isIrcEnabled(this.session.settings, this.session.taskDepth ?? 0);
+		// Coordination only makes sense when the siblings keep running after this
+		// call returns (async). In the sync fallback they have already completed,
+		// so a "coordinate while they run" hint would misfire.
+		const willRunAsync = !!manager && selectedAgent?.blocking !== true;
+		const advisory = this.session.suppressSpawnAdvisory
+			? undefined
+			: composeSpawnAdvisory({
+					agentName: params.agent,
+					items: spawnItems,
+					depthCapacity,
+					ircEnabled,
+					willRunAsync,
+				});
+		// Returns a fresh result (copied content array, copied text part) rather
+		// than mutating the caller's — task results are short-lived here, but an
+		// in-place edit on a shared/cached AgentToolResult would be a hidden trap.
 		const withAdvisory = (result: AgentToolResult<TaskToolDetails>): AgentToolResult<TaskToolDetails> => {
 			if (!advisory) return result;
-			const textPart = result.content.find(part => part.type === "text");
-			if (textPart && typeof textPart.text === "string") {
-				textPart.text = `${textPart.text}\n\n${advisory}`;
-			} else {
-				result.content.push({ type: "text", text: advisory });
-			}
-			return result;
+			let appended = false;
+			const content = result.content.map(part => {
+				if (!appended && part.type === "text" && typeof part.text === "string") {
+					appended = true;
+					return { ...part, text: `${part.text}\n\n${advisory}` };
+				}
+				return part;
+			});
+			if (!appended) content.push({ type: "text", text: advisory });
+			return { ...result, content };
 		};
 		if (!asyncEnabled || !manager || selectedAgent?.blocking === true) {
 			// Sync fallback: async execution disabled, orphaned host that never
@@ -614,7 +676,6 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			},
 		});
 
-		const ircEnabled = isIrcEnabled(this.session.settings, this.session.taskDepth ?? 0);
 		const started: Array<{ agentId: string; jobId: string; description?: string }> = [];
 		const failedSchedules: string[] = [];
 		for (const spawn of spawns) {

package/src/tools/github-cache.ts

@@ -8,10 +8,11 @@
  *   helpers swallow open/IO failures and degrade to "no cache" so a corrupt or
  *   unreadable DB never blocks a `gh` call.
  *
- * TTL:
  *   Soft TTL → return cached row directly.
- *   Past soft TTL but within hard TTL → return cached row AND schedule a
- *     background refresh (errors logged, never thrown).
+ *   Stateful issue/PR rows past soft TTL but within hard TTL → refresh
+ *     synchronously, falling back to the cached row if the live fetch fails.
+ *   Expensive PR diff rows past soft TTL but within hard TTL → return cached
+ *     row AND schedule a background refresh (errors logged, never thrown).
  *   Past hard TTL → treat as miss and fetch fresh.
  */
 
@@ -21,6 +22,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { getGithubCacheDbPath, logger } from "@oh-my-pi/pi-utils";
 import type { Settings } from "../config/settings";
+import { ToolAbortError } from "./tool-errors";
 
 // ────────────────────────────────────────────────────────────────────────────
 // Storage layer
@@ -449,7 +451,7 @@ export interface CacheLookupOptions<T> {
 	now?: number;
 }
 
-export type CacheStatus = "miss" | "fresh" | "stale" | "disabled";
+export type CacheStatus = "miss" | "fresh" | "refreshed" | "stale" | "disabled";
 
 export interface CacheLookupResult<T> {
 	rendered: string;
@@ -595,7 +597,7 @@ export async function getOrFetchView<T>(options: CacheLookupOptions<T>): Promise
 				status: "fresh",
 				fetchedAt: cached.fetchedAt,
 			};
-		} else {
+		} else if (options.kind === "pr-diff") {
 			scheduleBackgroundRefresh(
 				authKey,
 				options.repo,
@@ -611,6 +613,28 @@ export async function getOrFetchView<T>(options: CacheLookupOptions<T>): Promise
 				status: "stale",
 				fetchedAt: cached.fetchedAt,
 			};
+		} else {
+			try {
+				const fresh = await options.fetchFresh();
+				const fetchedAt = Date.now();
+				storeResult(authKey, options.repo, options.kind, options.number, options.includeComments, fresh, fetchedAt);
+				return { ...fresh, status: "refreshed", fetchedAt };
+			} catch (err) {
+				if (err instanceof ToolAbortError) throw err;
+				logger.debug("github cache: synchronous refresh failed; returning stale view", {
+					err: String(err),
+					repo: options.repo,
+					kind: options.kind,
+					number: options.number,
+				});
+				return {
+					rendered: cached.rendered,
+					sourceUrl: cached.sourceUrl,
+					payload: cached.payload,
+					status: "stale",
+					fetchedAt: cached.fetchedAt,
+				};
+			}
 		}
 	}
 
@@ -624,7 +648,7 @@ export async function getOrFetchView<T>(options: CacheLookupOptions<T>): Promise
  * Human-friendly freshness note for protocol-handler `notes[]` rendering.
  */
 export function formatFreshnessNote(status: CacheStatus, fetchedAtMs: number, now: number = Date.now()): string {
-	if (status === "miss") return "Fetched live";
+	if (status === "miss" || status === "refreshed") return "Fetched live";
 	if (status === "disabled") return "Cache disabled; fetched live";
 	const ageSec = Math.max(0, Math.round((now - fetchedAtMs) / 1000));
 	const human =
@@ -633,6 +657,7 @@ export function formatFreshnessNote(status: CacheStatus, fetchedAtMs: number, no
 			: ageSec < 3600
 				? `${Math.round(ageSec / 60)}m ago`
 				: `${Math.round(ageSec / 3600)}h ago`;
-	if (status === "stale") return `Cached: ${human} (refreshing in background)`;
+	if (status === "stale")
+		return `WARNING: showing cached content from ${human}; live refresh failed or is still running`;
 	return `Cached: ${human}`;
 }