@gajae-code/coding-agent 0.16.3 → 0.16.6

package/src/system-prompt.ts

@@ -235,6 +235,10 @@ export async function resolvePromptInput(input: string | undefined, description:
 export interface LoadContextFilesOptions {
 	/** Working directory to start walking up from. Default: getProjectDir() */
 	cwd?: string;
+	/** Agent directory backing native user-scope context and system prompt files. */
+	agentDir?: string;
+	/** Resolver-owned classification for `agentDir`; preserve it across HOME/config refreshes. */
+	profileAuthority?: "default" | "custom";
 }
 
 function dedupeExactContextFiles(
@@ -265,7 +269,11 @@ export async function loadProjectContextFilesResult(
 	options: LoadContextFilesOptions = {},
 ): Promise<ProjectContextFilesResult> {
 	const resolvedCwd = options.cwd ?? getProjectDir();
-	const result = await loadCapability(contextFileCapability.id, { cwd: resolvedCwd });
+	const result = await loadCapability(contextFileCapability.id, {
+		cwd: resolvedCwd,
+		agentDir: options.agentDir,
+		profileAuthority: options.profileAuthority,
+	});
 	const items = result.items as ContextFile[];
 
 	// Native user-global context applies everywhere and is least specific, so it
@@ -311,7 +319,11 @@ export async function loadProjectContextFiles(
 export async function loadSystemPromptFiles(options: LoadContextFilesOptions = {}): Promise<string | null> {
 	const resolvedCwd = options.cwd ?? getProjectDir();
 
-	const result = await loadCapability<SystemPromptFile>(systemPromptCapability.id, { cwd: resolvedCwd });
+	const result = await loadCapability<SystemPromptFile>(systemPromptCapability.id, {
+		cwd: resolvedCwd,
+		agentDir: options.agentDir,
+		profileAuthority: options.profileAuthority,
+	});
 
 	if (result.items.length === 0) return null;
 
@@ -368,10 +380,16 @@ export interface BuildSystemPromptOptions {
 	pluginAppendices?: string;
 	/** Repeat full tool descriptions in system prompt. Default: false */
 	repeatToolDescriptions?: boolean;
+	/** Language guidance for internal technical reasoning. Default: off. */
+	reasoningLanguage?: "off" | "english";
 	/** Skills settings for discovery. */
 	skillsSettings?: SkillsSettings;
 	/** Working directory. Default: getProjectDir() */
 	cwd?: string;
+	/** Agent directory backing native user-scope prompt discovery. */
+	agentDir?: string;
+	/** Resolver-owned classification for `agentDir`; preserve it across HOME/config refreshes. */
+	profileAuthority?: "default" | "custom";
 	/** Pre-loaded context files (skips discovery if provided). */
 	contextFiles?: Array<{ path: string; content: string; depth?: number }>;
 	/** Skills provided directly to system prompt construction. */
@@ -542,6 +560,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		appendSystemPrompt,
 		pluginAppendices,
 		repeatToolDescriptions = false,
+		reasoningLanguage = "off",
 		toolNames: providedToolNames,
 		cwd,
 		contextFiles: providedContextFiles,
@@ -600,10 +619,16 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 
 	const systemPromptCustomizationPromise = logger.time("loadSystemPromptFiles", loadSystemPromptFiles, {
 		cwd: resolvedCwd,
+		agentDir: options.agentDir,
+		profileAuthority: options.profileAuthority,
 	});
 	const contextFilesPromise = providedContextFiles
 		? Promise.resolve({ contextFiles: providedContextFiles, warnings: [] })
-		: logger.time("loadProjectContextFiles", loadProjectContextFilesResult, { cwd: resolvedCwd });
+		: logger.time("loadProjectContextFiles", loadProjectContextFilesResult, {
+				cwd: resolvedCwd,
+				agentDir: options.agentDir,
+				profileAuthority: options.profileAuthority,
+			});
 	const workspaceTreePromise =
 		providedWorkspaceTree !== undefined
 			? Promise.resolve(providedWorkspaceTree)
@@ -710,6 +735,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		tools: toolNames,
 		toolInfo,
 		repeatToolDescriptions,
+		reasoningLanguageEnglish: reasoningLanguage === "english",
 		toolRefs,
 		environment,
 		contextFiles: sanitizedContextFiles,

package/src/task/executor.ts

@@ -281,6 +281,9 @@ export interface ExecutorOptions {
 	authStorage?: AuthStorage;
 	modelRegistry?: ModelRegistry;
 	settings?: Settings;
+	/** Parent session's selected agent directory and immutable resolver-owned authority. */
+	agentDir?: string;
+	profileAuthority?: "default" | "custom";
 	/** Parent session's registry; shared by child sessions for IRC routing and roster visibility. */
 	agentRegistry?: AgentRegistry;
 	/**
@@ -300,7 +303,8 @@ export interface ExecutorOptions {
 	managedPersistence?: ManagedTaskPersistence;
 	/**
 	 * The parent session's ENDPOINT-owned AsyncJobManager (resolved by the
-	 * TaskTool via forEndpoint(sessionId) ?? instance()). Model metadata and
+	 * TaskTool via its opaque async endpoint accessor, then the process-global
+	 * fallback). Model metadata and
 	 * live-handle state for THIS subagent are recorded in the SAME manager the
 	 * task job runs in — with concurrent top-level sessions the process-global
 	 * instance belongs to a different session and would surface this subagent
@@ -1951,6 +1955,8 @@ export async function runSubprocessOnce(options: ExecutorOptions): Promise<Singl
 			const { session } = await awaitAbortable(
 				canonicalSdk.createAgentSession({
 					cwd: worktree ?? cwd,
+					agentDir: options.agentDir,
+					profileAuthority: options.profileAuthority,
 					authStorage,
 					modelRegistry,
 					settings: subagentSettings,

package/src/task/index.ts

@@ -375,6 +375,14 @@ function createTaskModeError(text: string): AgentToolResult<TaskToolDetails> {
 	};
 }
 
+/** Remove only strict-provider blank placeholders for the optional caller-authored schema. */
+function normalizeTaskAdmissionParams(params: TaskParams): TaskParams {
+	if (typeof params.schema !== "string" || params.schema.trim() !== "") return params;
+	const normalized = { ...params };
+	delete normalized.schema;
+	return normalized;
+}
+
 function validateTaskModeParams(simpleMode: TaskSimpleMode, params: TaskParams): string | undefined {
 	const { contextEnabled, customSchemaEnabled } = getTaskSimpleModeCapabilities(simpleMode);
 	const disallowedFields: string[] = [];
@@ -888,7 +896,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 	 * thread P1).
 	 */
 	#resolveOwnedJobManager(): AsyncJobManager | undefined {
-		const endpointId = this.session.getSessionId?.() ?? undefined;
+		const endpointId = this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined;
 		return (
 			this.session.getAsyncJobManager?.() ?? AsyncJobManager.forEndpoint(endpointId) ?? AsyncJobManager.instance()
 		);
@@ -900,7 +908,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		signal?: AbortSignal,
 		onUpdate?: AgentToolUpdateCallback<TaskToolDetails>,
 	): Promise<AgentToolResult<TaskToolDetails>> {
-		const params = rawParams as TaskParams;
+		const params = normalizeTaskAdmissionParams(rawParams as TaskParams);
 		const simpleMode = this.#getTaskSimpleMode();
 		const validationError = validateTaskModeParams(simpleMode, params);
 		if (validationError) {
@@ -1245,7 +1253,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					manager,
 					resumeToolCallId ?? descriptor.toolCallId,
 					resumeJobId,
-					this.session.getSessionId?.() ?? undefined,
+					this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined,
 				);
 				return resumeJobId;
 			};
@@ -1477,7 +1485,12 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						},
 					},
 				);
-				registerOwnedIfLineaged(manager, _toolCallId, jobId, this.session.getSessionId?.() ?? undefined);
+				registerOwnedIfLineaged(
+					manager,
+					_toolCallId,
+					jobId,
+					this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined,
+				);
 				startedJobs.push({ jobId, taskId: taskItem.id });
 				if (typeof manager.registerResumeDescriptor === "function") {
 					manager.registerResumeDescriptor(
@@ -2324,6 +2337,8 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						modelRegistry: this.session.modelRegistry,
 						agentRegistry: this.session.agentRegistry,
 						settings: this.session.settings,
+						agentDir: this.session.getSessionAgentDir?.() ?? this.session.settings.getAgentDir(),
+						profileAuthority: this.session.profileAuthority,
 						inheritedServiceTier: this.session.serviceTier,
 						contextFiles,
 						skills: availableSkills,
@@ -2408,6 +2423,8 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						modelRegistry: this.session.modelRegistry,
 						agentRegistry: this.session.agentRegistry,
 						settings: this.session.settings,
+						agentDir: this.session.getSessionAgentDir?.() ?? this.session.settings.getAgentDir(),
+						profileAuthority: this.session.profileAuthority,
 						inheritedServiceTier: this.session.serviceTier,
 						contextFiles,
 						skills: availableSkills,

package/src/tools/bash.ts

@@ -103,6 +103,7 @@ const BASH_ERROR_MAX_BYTES = 4096;
 const ARTIFACT_SAVE_DIAGNOSTIC_MAX_BYTES = 256;
 const BASH_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const MASTER_CAPABILITY_ENV = "GJC_MASTER_CAPABILITY";
+const MASTER_OWNER_SESSION_ENV = "GJC_MASTER_OWNER_SESSION_ID";
 const DEFAULT_AUTO_BACKGROUND_THRESHOLD_MS = 60_000;
 const ACP_RELEASE_TIMEOUT_MS = 1_000;
 const READ_ONLY_BASH_ENV: Record<string, string> = {
@@ -186,8 +187,9 @@ function artifactReferenceIsReachable(text: string, result: BashResult | BashInt
 	);
 }
 
-function suffixPrefixOverlap(source: string, target: string): number {
+export function suffixPrefixOverlap(source: string, target: string): number {
 	if (source.length === 0 || target.length === 0) return 0;
+	if (target.startsWith(source)) return source.length;
 	const prefix = new Uint32Array(target.length);
 	for (let index = 1; index < target.length; index += 1) {
 		let length = prefix[index - 1] ?? 0;
@@ -244,10 +246,17 @@ function failureStatusCause(
 	if (result.cancelled) return leadingStatus ?? lastStatus ?? "Command cancelled";
 	if (isInteractiveResult(result) && result.timedOut) return lastStatus ?? "Command timed out";
 	if (result.exitCode === undefined) return "Command failed: missing exit status";
-	if (result.exitCode !== 0) return `Command exited with code ${result.exitCode}`;
+	if (result.exitCode !== 0) return nonZeroExitCause(result);
 	return undefined;
 }
 
+function nonZeroExitCause(result: BashResult | BashInteractiveResult): string {
+	if ("signal" in result && result.signal) {
+		return `Command terminated by ${result.signal} (exit code ${result.exitCode})`;
+	}
+	return `Command exited with code ${result.exitCode}`;
+}
+
 function removeTrailingFailureCause(text: string, cause: string | undefined): string {
 	if (!cause) return text;
 	for (const suffix of [`\n\n${cause}`, `\n${cause}`, cause]) {
@@ -717,7 +726,12 @@ export function masterCommandEnvOverrides(
 	directMasterSpawn: boolean,
 ): Record<string, string> {
 	if (directMasterSpawn) return {};
-	return Object.fromEntries(Object.entries(env ?? {}).filter(([key]) => key !== MASTER_CAPABILITY_ENV));
+	// The master capability is single-use spawn authority and the owner id is
+	// spawn-lineage identity: neither is ambient state for ordinary Bash or a
+	// chained/pipelined descendant (issue #5374).
+	return Object.fromEntries(
+		Object.entries(env ?? {}).filter(([key]) => key !== MASTER_CAPABILITY_ENV && key !== MASTER_OWNER_SESSION_ENV),
+	);
 }
 
 function escapeBashEnvValueForDisplay(value: string): string {
@@ -896,9 +910,8 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			throw new ToolError(formatBashFailureMessage(result, `${outputText}\n\nCommand failed: missing exit status`));
 		}
 		if (result.exitCode !== 0) {
-			throw new ToolError(
-				formatBashFailureMessage(result, `${outputText}\n\nCommand exited with code ${result.exitCode}`),
-			);
+			const cause = nonZeroExitCause(result);
+			throw new ToolError(formatBashFailureMessage(result, `${outputText}\n\n${cause}`));
 		}
 		return outputText;
 	}
@@ -1107,7 +1120,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			manager.failNow(jobId, jobGeneration, "Bash job owner was torn down.");
 		});
 		void completion.promise.finally(unregisterOwnerCleanup);
-		registerOwnedIfLineaged(manager, options.toolCallId, jobId, this.session.getSessionId?.() ?? undefined);
+		registerOwnedIfLineaged(
+			manager,
+			options.toolCallId,
+			jobId,
+			this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined,
+		);
 
 		return {
 			jobId,
@@ -1132,7 +1150,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 	 * running (review thread P1).
 	 */
 	#resolveOwnedJobManager(): AsyncJobManager | undefined {
-		const endpointId = this.session.getSessionId?.() ?? undefined;
+		const endpointId = this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined;
 		if (this.session.getAsyncJobManager) return this.session.getAsyncJobManager();
 		return AsyncJobManager.forEndpoint(endpointId) ?? AsyncJobManager.instance();
 	}
@@ -1433,7 +1451,10 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		// command that contained shell syntax into a privileged one.
 		const directMasterSpawn = isStrictDirectSdkSpawnCommand(rawCommand) && isStrictDirectSdkSpawnCommand(command);
 		const masterCapability = directMasterSpawn ? this.session.getMasterBashCapability?.() : undefined;
-		const masterOwnerSessionId = directMasterSpawn ? this.session.getMasterOwnerSessionId?.() : undefined;
+		// Master ownership is lineage identity, not session identity: it travels
+		// under its own variable on every bash env so a master-owned child can
+		// still read its OWN id from GJC_SESSION_ID (issue #5374).
+		const masterOwnerSessionId = this.session.getMasterOwnerSessionId?.();
 		const commandEnvOverrides = masterCommandEnvOverrides(expandedEnv, directMasterSpawn);
 		const resolvedEnv = {
 			...buildGjcRuntimeSessionEnv({
@@ -1446,7 +1467,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				: {}),
 			...commandEnvOverrides,
 			...(masterCapability ? { [MASTER_CAPABILITY_ENV]: masterCapability } : {}),
-			...(masterOwnerSessionId ? { GJC_MASTER_OWNER_SESSION_ID: masterOwnerSessionId } : {}),
+			...(masterOwnerSessionId ? { [MASTER_OWNER_SESSION_ENV]: masterOwnerSessionId } : {}),
 			...(this.session.bashRestrictionProfile === "read-only" ? READ_ONLY_BASH_ENV : {}),
 			...(allowedPrefixes && allowedPrefixes.length > 0 ? { [GJC_RESTRICTED_ROLE_AGENT_BASH_ENV]: "1" } : {}),
 		};
@@ -1498,8 +1519,9 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		resolvedEnv: Record<string, string> | undefined,
 	): Promise<BashResult> {
 		const masterCapability = resolvedEnv?.[MASTER_CAPABILITY_ENV];
+		const ownerSessionId = resolvedEnv?.[MASTER_OWNER_SESSION_ENV];
 		const sessionAgentDir = resolvedEnv?.GJC_CODING_AGENT_DIR;
-		if (masterCapability === undefined || sessionAgentDir === undefined)
+		if (masterCapability === undefined || ownerSessionId === undefined || sessionAgentDir === undefined)
 			throw new ToolError("Master spawn authority context is unavailable.");
 		const args = parseDirectSdkSpawnArgs(command);
 		args.agentDir = sessionAgentDir;
@@ -1507,8 +1529,8 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		const request = runSdkSpawn(args, {
 			env: {
 				...process.env,
-				GJC_MASTER_CAPABILITY: masterCapability,
-				GJC_SESSION_ID: resolvedEnv?.GJC_MASTER_OWNER_SESSION_ID ?? this.session.getSessionId?.() ?? undefined,
+				[MASTER_CAPABILITY_ENV]: masterCapability,
+				[MASTER_OWNER_SESSION_ENV]: ownerSessionId,
 				GJC_CODING_AGENT_DIR: sessionAgentDir,
 			},
 		});
@@ -1681,7 +1703,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		// Monitor jobs are exact owned background work of the turn that started
 		// them: register the five-tuple so scope:"owned" terminal abort stops the
 		// monitor too (review thread P2).
-		registerOwnedIfLineaged(manager, opts.toolCallId, jobId, this.session.getSessionId?.() ?? undefined);
+		registerOwnedIfLineaged(
+			manager,
+			opts.toolCallId,
+			jobId,
+			this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined,
+		);
 		currentJobId = jobId;
 		return { jobId, label, commandCwd: prepared.commandCwd };
 	}
@@ -1883,19 +1910,31 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			}
 			if (waitResult.kind === "completed") {
 				ownedManager.acknowledgeDeliveries([job.jobId]);
-				unregisterForegroundOwnedBash(ownedManager, job.jobId, this.session.getSessionId?.() ?? "local");
+				unregisterForegroundOwnedBash(
+					ownedManager,
+					job.jobId,
+					this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? "local",
+				);
 				return waitResult.result;
 			}
 			if (waitResult.kind === "failed") {
 				ownedManager.acknowledgeDeliveries([job.jobId]);
-				unregisterForegroundOwnedBash(ownedManager, job.jobId, this.session.getSessionId?.() ?? "local");
+				unregisterForegroundOwnedBash(
+					ownedManager,
+					job.jobId,
+					this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? "local",
+				);
 				throw waitResult.error;
 			}
 			if (waitResult.kind === "aborted") {
 				ownedManager.cancel(job.jobId);
 				const terminal = await job.completion;
 				ownedManager.acknowledgeDeliveries([job.jobId]);
-				unregisterForegroundOwnedBash(ownedManager, job.jobId, this.session.getSessionId?.() ?? "local");
+				unregisterForegroundOwnedBash(
+					ownedManager,
+					job.jobId,
+					this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? "local",
+				);
 				if (terminal.kind === "failed") {
 					throw new ToolAbortError(
 						formatManagedAbortFailure(terminal.error, terminal.result, job.getLatestText()),
@@ -2357,7 +2396,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			// already ran above, so exactly ONE remote handle exists and is retained
 			// across the fold.
 			const bridgeManager = ownedManager;
-			const bridgeEndpointId = this.session.getSessionId?.() ?? "local";
+			const bridgeEndpointId = this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? "local";
 			const bridgeLabel = command.length > 120 ? `${command.slice(0, 117)}...` : command;
 			const bridgeCompletion = Promise.withResolvers<ManagedBashJobCompletion>();
 			let bridgeForegroundSettled = false;
@@ -2621,7 +2660,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 							throw error;
 						}
 						const ptyGeneration = ptyManager.getJob(ptyJobId)?.generation ?? ptyJobId;
-						registerOwnedIfLineaged(ptyManager, toolCallId, ptyJobId, this.session.getSessionId?.() ?? undefined);
+						registerOwnedIfLineaged(
+							ptyManager,
+							toolCallId,
+							ptyJobId,
+							this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined,
+						);
 						const unregisterPtyOwnerCleanup = ptyManager.registerOwnerCleanup(ptyOwnerId, () => {
 							killPtyOnce();
 							ptyManager.failNow(ptyJobId, ptyGeneration, ownerTeardownText());

package/src/tools/cron.ts

@@ -592,7 +592,7 @@ export class CronTool implements AgentTool<typeof cronSchema, CronToolDetails> {
 	}
 
 	#resolveOwnedJobManager(): AsyncJobManager | undefined {
-		const endpointId = this.session.getSessionId?.() ?? undefined;
+		const endpointId = this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined;
 		return (
 			this.session.getAsyncJobManager?.() ?? AsyncJobManager.forEndpoint(endpointId) ?? AsyncJobManager.instance()
 		);

package/src/tools/fetch.ts

@@ -1167,13 +1167,36 @@ interface ReadUrlCacheEntry {
 	wrappedPreambleChars?: number;
 }
 
+// Entries hold whole-page outputs and image payloads, so this map must stay
+// bounded in long-lived hosts (TUI, SDK broker). Each fetch caches one entry
+// under up to two keys (requested + final URL). FIFO eviction is sufficient:
+// a miss simply refetches, so correctness never depends on a hit.
+export const READ_URL_CACHE_MAX_KEYS = 64;
+
 const readUrlCache = new Map<string, ReadUrlCacheEntry>();
 
 function getReadUrlCacheKey(session: ToolSession, requestedUrl: string, raw: boolean): string {
-	const scope = session.getSessionFile() ?? session.cwd;
+	const sessionFile = session.getSessionFile();
+	const sessionId = session.getSessionId?.();
+	const scope = sessionFile ? `file:${sessionFile}` : sessionId ? `session:${sessionId}` : `cwd:${session.cwd}`;
 	return `${scope}::${raw ? "raw" : "rendered"}::${normalizeUrl(requestedUrl)}`;
 }
 
+/** Test-only seam for deterministic module-global cache assertions. */
+export const readUrlCacheTestHooks = {
+	get size(): number {
+		return readUrlCache.size;
+	},
+	get retainedOutputChars(): number {
+		let total = 0;
+		for (const entry of new Set(readUrlCache.values())) total += entry.output.length;
+		return total;
+	},
+	reset(): void {
+		readUrlCache.clear();
+	},
+};
+
 async function readArtifactOutput(session: ToolSession, artifactId: string): Promise<string | null> {
 	const artifactsDir = session.getArtifactsDir?.();
 	if (!artifactsDir) return null;
@@ -1224,6 +1247,11 @@ async function ensureReadUrlCacheArtifact(session: ToolSession, entry: ReadUrlCa
 function cacheReadUrlEntry(session: ToolSession, requestedUrl: string, raw: boolean, entry: ReadUrlCacheEntry): void {
 	readUrlCache.set(getReadUrlCacheKey(session, requestedUrl, raw), entry);
 	readUrlCache.set(getReadUrlCacheKey(session, entry.details.finalUrl, raw), entry);
+	while (readUrlCache.size > READ_URL_CACHE_MAX_KEYS) {
+		const oldest = readUrlCache.keys().next().value;
+		if (oldest === undefined) break;
+		readUrlCache.delete(oldest);
+	}
 }
 
 async function buildReadUrlCacheEntry(

package/src/tools/gh.ts

@@ -2738,7 +2738,14 @@ export async function getOrFetchIssue(options: IssueViewLookupOptions): Promise<
 		}
 	}
 
-	const doFetch = () => fetchIssueViewFresh(options.cwd, repo, identifier, includeComments, options.signal);
+	const doFetch = (signal?: AbortSignal) =>
+		fetchIssueViewFresh(
+			options.cwd,
+			repo,
+			identifier,
+			includeComments,
+			signal && options.signal ? AbortSignal.any([signal, options.signal]) : (signal ?? options.signal),
+		);
 
 	if (!repo || cacheNumber === undefined) {
 		const fresh = await doFetch();
@@ -2752,6 +2759,7 @@ export async function getOrFetchIssue(options: IssueViewLookupOptions): Promise<
 		includeComments,
 		settings: options.settings,
 		authKey,
+		signal: options.signal,
 		fetchFresh: doFetch,
 	});
 	return {
@@ -2771,7 +2779,14 @@ export async function getOrFetchIssue(options: IssueViewLookupOptions): Promise<
 export async function getOrFetchPr(options: PrViewLookupOptions): Promise<ViewLookupResult<GhPrViewData>> {
 	const includeComments = options.includeComments ?? true;
 	const authKey = options.cacheAuthKey === undefined ? (resolveGithubCacheAuthKey() ?? null) : options.cacheAuthKey;
-	const doFetch = () => fetchPrViewFresh(options.cwd, options.repo, options.number, includeComments, options.signal);
+	const doFetch = (signal?: AbortSignal) =>
+		fetchPrViewFresh(
+			options.cwd,
+			options.repo,
+			options.number,
+			includeComments,
+			signal && options.signal ? AbortSignal.any([signal, options.signal]) : (signal ?? options.signal),
+		);
 	const lookup = await getOrFetchView<GhPrViewData>({
 		repo: options.repo,
 		kind: "pr",
@@ -2779,6 +2794,7 @@ export async function getOrFetchPr(options: PrViewLookupOptions): Promise<ViewLo
 		includeComments,
 		settings: options.settings,
 		authKey,
+		signal: options.signal,
 		fetchFresh: doFetch,
 	});
 	return {
@@ -3121,7 +3137,13 @@ async function fetchPrDiffFresh(
  */
 export async function getOrFetchPrDiff(options: PrDiffLookupOptions): Promise<ViewLookupResult<PrDiffPayload>> {
 	const authKey = options.cacheAuthKey === undefined ? (resolveGithubCacheAuthKey() ?? null) : options.cacheAuthKey;
-	const doFetch = () => fetchPrDiffFresh(options.cwd, options.repo, options.number, options.signal);
+	const doFetch = (signal?: AbortSignal) =>
+		fetchPrDiffFresh(
+			options.cwd,
+			options.repo,
+			options.number,
+			signal && options.signal ? AbortSignal.any([signal, options.signal]) : (signal ?? options.signal),
+		);
 	const lookup = await getOrFetchView<PrDiffPayload>({
 		repo: options.repo,
 		kind: "pr-diff",
@@ -3129,6 +3151,7 @@ export async function getOrFetchPrDiff(options: PrDiffLookupOptions): Promise<Vi
 		includeComments: false,
 		settings: options.settings,
 		authKey,
+		signal: options.signal,
 		fetchFresh: doFetch,
 	});
 	return {

package/src/tools/github-cache.ts

@@ -152,6 +152,26 @@ function evictExpired(db: Database, hardTtlMs: number): void {
  */
 const SWEEP_INTERVAL_MS = 60_000;
 let lastSweepAt = 0;
+const backgroundRefreshes = new Map<string, { generation: number; controller: AbortController }>();
+let backgroundRefreshGeneration = 0;
+const BACKGROUND_REFRESH_TIMEOUT_MS = 30_000;
+
+function cacheIdentityKey(
+	authKey: string,
+	repo: string,
+	kind: CacheKind,
+	number: number,
+	includeComments: boolean,
+): string {
+	return JSON.stringify([authKey, normalizeRepo(repo), kind, number, includeComments]);
+}
+
+function retireBackgroundRefresh(key: string): void {
+	const entry = backgroundRefreshes.get(key);
+	if (!entry) return;
+	entry.controller.abort();
+	backgroundRefreshes.delete(key);
+}
 
 function sweepIfDue(hardTtlMs: number): void {
 	const now = Date.now();
@@ -296,6 +316,12 @@ export function invalidate(
 	includeComments?: boolean,
 	authKey: string = DEFAULT_CACHE_AUTH_KEY,
 ): void {
+	if (includeComments === undefined) {
+		retireBackgroundRefresh(cacheIdentityKey(authKey, repo, kind, number, false));
+		retireBackgroundRefresh(cacheIdentityKey(authKey, repo, kind, number, true));
+	} else {
+		retireBackgroundRefresh(cacheIdentityKey(authKey, repo, kind, number, includeComments));
+	}
 	const db = openDb();
 	if (!db) return;
 	try {
@@ -342,6 +368,9 @@ export function resetForTests(): void {
 	cachedDb = null;
 	openAttempted = false;
 	lastSweepAt = 0;
+	for (const { controller } of backgroundRefreshes.values()) controller.abort();
+	backgroundRefreshes.clear();
+	backgroundRefreshGeneration += 1;
 }
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -365,9 +394,10 @@ export interface CacheLookupOptions<T> {
 	 * must bypass persistent cache reads/writes.
 	 */
 	authKey?: string | null;
-	fetchFresh: () => Promise<FreshResult<T>>;
+	fetchFresh: (signal?: AbortSignal) => Promise<FreshResult<T>>;
 	settings?: Settings | undefined;
 	now?: number;
+	signal?: AbortSignal;
 }
 
 export type CacheStatus = "miss" | "fresh" | "stale" | "disabled";
@@ -448,22 +478,41 @@ function scheduleBackgroundRefresh<T>(
 	kind: CacheKind,
 	number: number,
 	includeComments: boolean,
-	fetchFresh: () => Promise<FreshResult<T>>,
+	fetchFresh: (signal?: AbortSignal) => Promise<FreshResult<T>>,
 ): void {
-	queueMicrotask(() => {
-		const promise = fetchFresh();
-		promise
-			.then(fresh => {
+	const key = cacheIdentityKey(authKey, repo, kind, number, includeComments);
+	if (backgroundRefreshes.has(key)) return;
+	const generation = backgroundRefreshGeneration;
+	const controller = new AbortController();
+	const entry = { generation, controller };
+	backgroundRefreshes.set(key, entry);
+	queueMicrotask(async () => {
+		const timeoutHandle = setTimeout(() => {
+			controller.abort(new Error("GitHub background refresh timed out"));
+			if (backgroundRefreshes.get(key) === entry) backgroundRefreshes.delete(key);
+			logger.debug("github cache: background refresh timed out", { repo, kind, number });
+		}, BACKGROUND_REFRESH_TIMEOUT_MS);
+		try {
+			const fresh = await fetchFresh(controller.signal);
+			if (
+				!controller.signal.aborted &&
+				backgroundRefreshes.get(key) === entry &&
+				backgroundRefreshGeneration === generation
+			) {
 				storeResult(authKey, repo, kind, number, includeComments, fresh, Date.now());
-			})
-			.catch(err => {
-				logger.debug("github cache: background refresh failed", {
-					err: String(err),
-					repo,
-					kind,
-					number,
-				});
+			}
+		} catch (err) {
+			controller.abort();
+			logger.debug("github cache: background refresh failed", {
+				err: String(err),
+				repo,
+				kind,
+				number,
 			});
+		} finally {
+			clearTimeout(timeoutHandle);
+			if (backgroundRefreshes.get(key) === entry) backgroundRefreshes.delete(key);
+		}
 	});
 }
 
@@ -473,9 +522,10 @@ export async function getOrFetchView<T>(options: CacheLookupOptions<T>): Promise
 	const authKey = options.authKey === undefined ? DEFAULT_CACHE_AUTH_KEY : options.authKey;
 
 	if (!ttl.enabled || authKey === null) {
-		const fresh = await options.fetchFresh();
+		const fresh = await options.fetchFresh(options.signal);
 		return { ...fresh, status: "disabled", fetchedAt: now };
 	}
+	const cacheKey = cacheIdentityKey(authKey, options.repo, options.kind, options.number, options.includeComments);
 
 	// Enforce the *configured* hard TTL against on-disk rows. This is what
 	// makes `github.cache.hardTtlSec` a real retention cap rather than a soft
@@ -496,6 +546,7 @@ export async function getOrFetchView<T>(options: CacheLookupOptions<T>): Promise
 			// Past hard TTL: drop the row eagerly so the on-disk exposure window
 			// is bounded even if `fetchFresh()` then fails (network down, gh
 			// auth lapse, etc.) and we never get to overwrite it.
+			retireBackgroundRefresh(cacheKey);
 			invalidate(options.repo, options.kind, options.number, options.includeComments, authKey);
 		} else if (age <= ttl.softMs) {
 			return {
@@ -524,8 +575,9 @@ export async function getOrFetchView<T>(options: CacheLookupOptions<T>): Promise
 		}
 	}
 
-	const fresh = await options.fetchFresh();
+	const fresh = await options.fetchFresh(options.signal);
 	const fetchedAt = Date.now();
+	retireBackgroundRefresh(cacheKey);
 	storeResult(authKey, options.repo, options.kind, options.number, options.includeComments, fresh, fetchedAt);
 	return { ...fresh, status: "miss", fetchedAt };
 }