@gajae-code/coding-agent 0.18.1 → 0.18.6

package/src/session/agent-session.ts

@@ -133,6 +133,7 @@ import {
 	classifyFallbackTrigger,
 	EMPTY_RESPONSE_PROVIDER_CODE,
 	type FallbackAttemptToken,
+	PROVIDER_PROTOCOL_MISMATCH_ERROR_CODE,
 	type FallbackTriggerClass,
 	SERVER_OVERLOADED_PROVIDER_CODE,
 	STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE,
@@ -1210,7 +1211,10 @@ export interface TrackedSendUserMessageOptions extends SendUserMessageOptions {
 	trackSubmission: true;
 }
 
-type SendUserMessageDispatchOptions = SendUserMessageOptions & { trackSubmission?: boolean };
+type SendUserMessageDispatchOptions = SendUserMessageOptions & {
+	trackSubmission?: boolean;
+	expectedSdkRunToken?: string;
+};
 
 type InternalPromptOptions = PromptOptions & { sdkRunToken?: string };
 type InternalCustomMessageOptions = Pick<
@@ -1419,8 +1423,11 @@ const BARE_DEFAULT_WATCHDOG_ERROR =
 const PROVIDER_FIRST_EVENT_TIMEOUT_ERROR = "Provider stream timed out while waiting for the first event";
 const WRAPPED_PROVIDER_FIRST_EVENT_TIMEOUT_ERROR = `Error: ${PROVIDER_FIRST_EVENT_TIMEOUT_ERROR}`;
 const PROVIDER_FIRST_EVENT_TIMEOUT_WITHOUT_ARTICLE_ERROR = "Provider stream timed out while waiting for first event";
-const BARE_DEFAULT_CODEX_OVERLOAD_ERROR = /^Codex error event(?:: .*)? \(code=server_is_overloaded(?:, [^)]+)*\)$/;
-/** Anthropic's typed capacity-overload `error.type`, the only overload code admitted below. */
+const BARE_DEFAULT_CODEX_RETRYABLE_ERROR =
+	/^Codex error event(?:: .*)? \(code=(?:server_is_overloaded|server_error|internal_error)(?:, [^)]+)*\)$/;
+const BARE_DEFAULT_CODEX_RETRYABLE_CODES = new Set(["server_is_overloaded", "server_error", "internal_error"]);
+const BARE_DEFAULT_OVERLOAD_CODES = new Set([SERVER_OVERLOADED_PROVIDER_CODE]);
+/** Anthropic's typed capacity-overload `error.type`, the only Anthropic overload code admitted below. */
 const ANTHROPIC_OVERLOADED_ERROR_TYPE = "overloaded_error";
 const KIMI_CODE_FIRST_EVENT_TIMEOUT_MESSAGES = {
 	"anthropic-messages": new Set([
@@ -1501,8 +1508,8 @@ function isBareDefaultMessageOnlyFirstEventTimeout(message: AssistantMessage): b
 	);
 }
 /**
- * True when the attempt's structured evidence is exactly the provider's typed
- * capacity-overload code and nothing else: no status, no retained retry header,
+ * True when the attempt's structured evidence is exactly an admitted provider
+ * code and nothing else: no status, no retained retry header,
  * no second typed code, no error kind, and none of the transport's other
  * observations (request size, first-event timing, endpoint class, provider retry
  * ceiling). The code arrives statuslessly (a Codex error event, an HTTP 200
@@ -1511,15 +1518,18 @@ function isBareDefaultMessageOnlyFirstEventTimeout(message: AssistantMessage): b
  * attempt is no longer provably that bare capacity rejection. The code is
  * compared case-sensitively, matching the parser and the transport gate.
  */
-function isExactTypedOverloadFacts(message: AssistantMessage): boolean {
+function isExactTypedOverloadFacts(
+	message: AssistantMessage,
+	acceptedProviderCodes: ReadonlySet<string> = BARE_DEFAULT_OVERLOAD_CODES,
+): boolean {
 	if (message.errorKind !== undefined || message.errorStatus !== undefined) return false;
 	const facts = message.transportFailure;
 	if (!facts) return false;
 	return (
-		facts.providerCode === SERVER_OVERLOADED_PROVIDER_CODE &&
+		acceptedProviderCodes.has(facts.providerCode ?? "") &&
 		facts.status === undefined &&
 		facts.anthropicErrorType === undefined &&
-		(facts.openaiErrorCode === undefined || facts.openaiErrorCode === SERVER_OVERLOADED_PROVIDER_CODE) &&
+		(facts.openaiErrorCode === undefined || facts.openaiErrorCode === facts.providerCode) &&
 		(facts.headers === undefined || Object.keys(facts.headers).length === 0) &&
 		facts.requestBytes === undefined &&
 		facts.firstEventElapsedMs === undefined &&
@@ -1548,8 +1558,9 @@ function isStatuslessTypedOverloadFacts(facts: TransportFailureFacts | undefined
 function isBareDefaultCodexOverload(message: AssistantMessage): boolean {
 	return (
 		message.api === "openai-codex-responses" &&
-		BARE_DEFAULT_CODEX_OVERLOAD_ERROR.test(message.errorMessage ?? "") &&
-		(isExactTypedOverloadFacts(message) || !hasBareDefaultRetryDisqualifyingFacts(message)) &&
+		(isExactTypedOverloadFacts(message, BARE_DEFAULT_CODEX_RETRYABLE_CODES) ||
+			(BARE_DEFAULT_CODEX_RETRYABLE_ERROR.test(message.errorMessage ?? "") &&
+				!hasBareDefaultRetryDisqualifyingFacts(message))) &&
 		!assistantMessageHasVisibleOrToolContent(message)
 	);
 }
@@ -5077,6 +5088,7 @@ export class AgentSession {
 		if (lease) this.#deferredAgentEndLeases.delete(pending);
 		this.#startAgentEndPublication(pending, lease);
 	}
+
 	#startAgentEndPublication(pending: AgentSessionEvent, lease?: RunResourceProducerLease): void {
 		this.#agentEndPublicationInFlight++;
 		const pendingScope = (pending as AgentSessionEvent & { scope?: AttemptScopeRef }).scope as
@@ -6166,7 +6178,10 @@ export class AgentSession {
 				path.basename(sessionModeStatePath(this.sessionManager.getCwd(), currentSessionId, active.skill)),
 			);
 			const raw = fs.readFileSync(filePath, "utf-8");
-			const parsed = JSON.parse(raw) as { state?: { intent_contract?: unknown } };
+			const parsed = JSON.parse(raw) as { current_phase?: unknown; state?: { intent_contract?: unknown } };
+			// A persisted final spec moves to handoff. Its next-workflow/approval
+			// asks are not interview rounds and must not require recorder metadata.
+			if (parsed.current_phase !== "interviewing") return undefined;
 			const intentContract = parsed.state?.intent_contract;
 			if (intentContract === undefined) return "topology";
 			assertDeepInterviewIntentManifest(intentContract);
@@ -6318,7 +6333,10 @@ export class AgentSession {
 				},
 			};
 		}
-		const transformedMessages = await this.#transformContext([...this.messages], options.signal);
+		const transformedMessages = await this.#transformContext(
+			this.#withoutEphemeralCustomMessages(this.messages),
+			options.signal,
+		);
 		const convertedMessages = await this.#convertToLlm(transformedMessages);
 		const providerMessages = this.model
 			? normalizeMessagesForProvider(convertedMessages, this.model)
@@ -12297,9 +12315,16 @@ export class AgentSession {
 		return this.agent.activeResourceRunId;
 	}
 
-	/** All messages including custom types like BashExecutionMessage */
+	/**
+	 * All messages including custom types like BashExecutionMessage. Request-scoped
+	 * ephemeral copies are retained only in `agent.state.messages` to keep the provider
+	 * cache prefix stable; they are never part of this public view.
+	 */
 	get messages(): AgentMessage[] {
-		return this.agent.state.messages;
+		const messages = this.agent.state.messages;
+		return messages.some(message => message.role === "custom" && this.#isEphemeralCustomMessageType(message.customType))
+			? this.#withoutEphemeralCustomMessages(messages)
+			: messages;
 	}
 	get transcriptPromptGeneration(): number {
 		return this.#promptGeneration;
@@ -12389,9 +12414,16 @@ export class AgentSession {
 		let continuationSdkRunToken: string | undefined;
 		try {
 			const volatileProjectContextMessage = await this.#buildVolatileProjectContextMessage();
-			this.agent.appendMessage(volatileProjectContextMessage);
+			if (!this.#isLatestRetainedEphemeralCopy(volatileProjectContextMessage)) {
+				this.agent.appendMessage(volatileProjectContextMessage);
+			}
 			const untrustedMcpServerInstructionsMessage = this.#buildUntrustedMcpServerInstructionsMessage();
-			if (untrustedMcpServerInstructionsMessage) this.agent.appendMessage(untrustedMcpServerInstructionsMessage);
+			if (
+				untrustedMcpServerInstructionsMessage &&
+				!this.#isLatestRetainedEphemeralCopy(untrustedMcpServerInstructionsMessage)
+			) {
+				this.agent.appendMessage(untrustedMcpServerInstructionsMessage);
+			}
 			const hindsightState = this.getHindsightSessionState();
 			await hindsightState?.maybeRecallOnAgentStart();
 			hindsightRecall = hindsightState?.getRecallSnippetForInjection();
@@ -12429,7 +12461,6 @@ export class AgentSession {
 			});
 			if (continuationSdkRunToken === undefined) await this.#waitForPostPromptRecovery();
 		} finally {
-			this.#removeEphemeralCustomMessages();
 			await this.#settleEndedInFlight(
 				inFlightPrompt,
 				continuationSdkRunToken === undefined ? "full" : "publication",
@@ -13293,6 +13324,21 @@ export class AgentSession {
 		);
 	}
 
+	/**
+	 * Sent ephemeral copies stay in live state so the provider prefix is stable. A new
+	 * copy is only worth appending when its provider-visible content changed; an
+	 * identical one would just repeat tokens that still count against the window.
+	 */
+	#isLatestRetainedEphemeralCopy(message: CustomMessage): boolean {
+		const messages = this.agent.state.messages;
+		for (let index = messages.length - 1; index >= 0; index--) {
+			const candidate = messages[index];
+			if (candidate?.role !== "custom" || candidate.customType !== message.customType) continue;
+			return JSON.stringify(candidate.content) === JSON.stringify(message.content);
+		}
+		return false;
+	}
+
 	#removeEphemeralCustomMessages(): void {
 		const messages = this.agent.state.messages;
 		const withoutEphemeralMessages = this.#withoutEphemeralCustomMessages(messages);
@@ -13988,8 +14034,6 @@ export class AgentSession {
 				throw new Error(formatNoCredentialOnboardingError(this.model.provider));
 			}
 
-			this.#removeEphemeralCustomMessages();
-
 			// Check if we need to compact before sending (catches aborted responses)
 			const lastAssistant = this.#findLastAssistantMessage();
 			if (lastAssistant && !options?.skipCompactionCheck) {
@@ -14164,9 +14208,16 @@ export class AgentSession {
 					messages.push(goalModeMessage);
 				}
 				const volatileProjectContextMessage = await this.#buildVolatileProjectContextMessage();
-				messages.push(volatileProjectContextMessage);
+				if (!this.#isLatestRetainedEphemeralCopy(volatileProjectContextMessage)) {
+					messages.push(volatileProjectContextMessage);
+				}
 				const untrustedMcpServerInstructionsMessage = this.#buildUntrustedMcpServerInstructionsMessage();
-				if (untrustedMcpServerInstructionsMessage) messages.push(untrustedMcpServerInstructionsMessage);
+				if (
+					untrustedMcpServerInstructionsMessage &&
+					!this.#isLatestRetainedEphemeralCopy(untrustedMcpServerInstructionsMessage)
+				) {
+					messages.push(untrustedMcpServerInstructionsMessage);
+				}
 
 				// Roster: one Phase A claim, revalidated and reused on every attempt;
 				// a superseded claim releases and the prompt proceeds without it.
@@ -14328,7 +14379,6 @@ export class AgentSession {
 				return;
 			throw error;
 		} finally {
-			this.#removeEphemeralCustomMessages();
 			if (rosterClaim) {
 				this.agent.replaceMessages(
 					this.agent.state.messages.filter(
@@ -14606,6 +14656,7 @@ export class AgentSession {
 			onQueuedAfterAdmission?: (message: AgentMessage, cancelQueued: () => boolean) => void;
 			external?: boolean;
 			sdkRunToken?: string;
+			expectedSdkRunToken?: string;
 			forceOneAtATime?: boolean;
 			allowDuringSessionTransition?: boolean;
 			allowCancelAndSubmit?: boolean;
@@ -14622,11 +14673,18 @@ export class AgentSession {
 		const message = { role: "user" as const, content, attribution: "user" as const, timestamp: Date.now() };
 		// Enqueue-time admission: the Agent only accepts a steer into a live,
 		// non-aborted run. Anything else (idle, unwinding after agent_end, another
-		// prompt still in preflight, aborting) has no run to steer, so it is routed
-		// as a sequential follow-up owned by the next turn instead of being parked
-		// in a queue nobody owns.
+		// prompt still in preflight, aborting) has no run to steer. Ordinary steers
+		// become a sequential follow-up owned by the next turn; SDK turn-bound
+		// steers fail closed rather than being delivered to a successor run.
+		if (
+			options?.expectedSdkRunToken !== undefined &&
+			this.#activeSdkRunToken !== options.expectedSdkRunToken
+		)
+			throw Object.assign(new Error("The expected SDK run is not active."), { code: "turn_not_active" });
 		const admission = this.agent.steer(message, options?.forceOneAtATime ? { forceOneAtATime: true } : undefined);
 		if (!admission.admitted) {
+			if (options?.expectedSdkRunToken !== undefined)
+				throw Object.assign(new Error("The expected SDK run is not active."), { code: "turn_not_active" });
 			const queuedFollowUp = await this.#queueFollowUpAfterReservation(message, displayText, {
 				forceOneAtATime: options?.forceOneAtATime,
 				claimsGenuineUserIntent: options?.claimsGenuineUserIntent,
@@ -15779,6 +15837,7 @@ export class AgentSession {
 					onPromoted: onQueuedPromoted,
 					external: true,
 					sdkRunToken: internalOptions?.sdkRunToken,
+					expectedSdkRunToken: internalOptions?.expectedSdkRunToken,
 					forceOneAtATime: options?.queuePolicy === "sequential",
 					onQueuedAfterAdmission: onTrackedQueued,
 					allowDuringSessionTransition: this.#hasCommittedSuccessorTrackedAdmission(options),
@@ -16145,6 +16204,9 @@ export class AgentSession {
 		this.#cachedWorkspaceTree = undefined;
 		this.#cachedWorkspaceTreeAt = 0;
 		this.#pendingWorkspaceTreeRescope = true;
+		// Sent copies name the abandoned root; the rescope already rebuilds the stable
+		// prompt, so there is no cache prefix left to preserve by keeping them.
+		this.#removeEphemeralCustomMessages();
 	}
 
 	/** Skill loading warnings captured by SDK */
@@ -20282,7 +20344,7 @@ export class AgentSession {
 			}
 
 			const handoffText = await generateHandoff(
-				this.agent.state.messages,
+				this.#withoutEphemeralCustomMessages(this.agent.state.messages),
 				model,
 				apiKey,
 				{
@@ -20516,7 +20578,7 @@ export class AgentSession {
 				sessionId: this.sessionId,
 				cwd: this.sessionManager.getCwd(),
 				sessionFile: this.sessionFile,
-				messages: this.agent.state.messages,
+				messages: this.#withoutEphemeralCustomMessages(this.agent.state.messages),
 				customInstructions: options.customInstructions,
 			},
 			options,
@@ -22699,6 +22761,7 @@ export class AgentSession {
 				willRetry && !continuationSkipReason
 					? await this.#scheduleOverflowRetryContinuation(generation, options?.resourceRunId)
 					: false;
+
 			await this.#emitSessionEvent({
 				type: "auto_compaction_end",
 				action,
@@ -22707,6 +22770,7 @@ export class AgentSession {
 				willRetry: overflowContinuationScheduled,
 				continuationSkipReason,
 			});
+
 			if (autoCompactionSignal.aborted) return { kind: "aborted", source: "signal" };
 
 			if (willRetry) {
@@ -22940,6 +23004,7 @@ export class AgentSession {
 			return false;
 		const contextWindow = this.model?.contextWindow ?? 0;
 		if (classifyContextOverflow(message, transportFailure, contextWindow)) return false;
+		if (isBareDefaultCodexOverload(message) && this.settings.get("retry.enabled") !== false) return true;
 		const managedFallback = this.#defaultFallbackChain().chain.entries.length > 1;
 		// An account-specific model rejection that cannot rotate to another
 		// credential stays terminal only on the session's own retry path; managed
@@ -23082,6 +23147,9 @@ export class AgentSession {
 		// Without this the message carries no transport facts and would fall
 		// through to "unknown", which is admitted for bounded retry (#5627).
 		if (message.errorCode === REPETITION_GUARD_ERROR_CODE) return "terminal";
+		// A 2xx body in the wrong protocol replays identically; its embedded body text
+		// (e.g. "HTTP 503") must not be reparsed as a transient failure.
+		if (message.errorCode === PROVIDER_PROTOCOL_MISMATCH_ERROR_CODE) return "terminal";
 		if (message.errorKind === "local_snapshot_failure") return "local_snapshot";
 		if (message.errorKind === "local_buffer_overflow") return "local_buffer_overflow";
 		if (this.#isTypedFirstEventTimeout(message)) return "first_event_timeout";
@@ -24301,6 +24369,7 @@ export class AgentSession {
 			isBareDefaultCodexOverload(message) ||
 			isBareDefaultAnthropicOverload(message) ||
 			isBareDefaultOpenAIResponsesOverload(message);
+		const canReplayCodexProviderOverload = isBareDefaultCodexOverload(message);
 		const reportedRetryMaxAttempts = transportFailure?.retryMaxAttempts;
 		if (reportedRetryMaxAttempts !== undefined) {
 			this.#providerRetryMaxAttempts = Math.min(
@@ -24340,19 +24409,24 @@ export class AgentSession {
 					}
 				: false;
 		}
+		const fallbackTrigger = this.#fallbackTriggerFor(message, !managedFallback, transportFailure);
 		const trigger:
 			| { class: FallbackTriggerClass; retryAfterMs?: number; authDisposition?: AuthDisposition }
-			| undefined = this.#fallbackTriggerFor(message, !managedFallback, transportFailure);
+			| undefined = canReplayCodexProviderOverload ? { class: "server" } : fallbackTrigger;
 		// OpenAI's typed statusless capacity-overload code (issue #5018) must not
 		// gain managed-chain retry/advance authority from its new facts. Before
 		// the code survived transport, this failure reached the session as an
 		// ordinary committed error and surfaced immediately, so mirror that
-		// behavior with the existing exhaustion decision.
+		// behavior with the existing exhaustion decision. However, when called from
+		// the agent_end path (managedOutcome=false), we must return false to allow
+		// proper session termination handling.
 		if (managedFallback && isStatuslessTypedOverloadFacts(transportFailure)) {
-			return this.#managedFallbackExhaustionDecision(
-				message,
-				message.errorMessage || "Model fallback attempt failed",
-			);
+			return managedOutcome
+				? this.#managedFallbackExhaustionDecision(
+						message,
+						message.errorMessage || "Model fallback attempt failed",
+					)
+				: false;
 		}
 		if (!trigger) {
 			return managedOutcome
@@ -24425,8 +24499,15 @@ export class AgentSession {
 		if (!managedFallback && assistantMessageHasVisibleOrToolContent(message)) {
 			return false;
 		}
+		const canReplayUnexpectedSocketClose =
+			classification === "transient" &&
+			isUnexpectedSocketCloseMessage(message.errorMessage ?? "") &&
+			!hasBareDefaultRetryDisqualifyingFacts(message) &&
+			this.#hasCleanRetryReplaySafety;
 		// Bare defaults retain their narrow watchdog and provider capacity-overload
-		// admissions. A first-event timeout adds the typed, content-free,
+		// admissions. A content-free unexpected socket close is replay-safe when
+		// the attempt has no conflicting facts and the retry scope is clean. A
+		// first-event timeout adds the typed, content-free,
 		// current-clean-scope requirement above; other transient watchdogs preserve
 		// legacy behavior. A provider overload is admitted only from that provider's
 		// own typed overload code on a content-free attempt carrying no conflicting
@@ -24435,12 +24516,16 @@ export class AgentSession {
 		if (!managedFallback && !legacyRetryConfigured && !canReplayRotatedCredential && !canReplayEmptyResponse) {
 			if (
 				(!canReplayProviderOverload &&
+					!canReplayUnexpectedSocketClose &&
 					!this.#isTypedFirstEventTimeout(message) &&
 					!messageOnlyWatchdogTimeout &&
 					(hasBareDefaultRetryDisqualifyingFacts(message) ||
 						(classification !== "transient" && classification !== "first_event_timeout") ||
 						!BARE_DEFAULT_WATCHDOG_ERROR.test(message.errorMessage ?? ""))) ||
-				(!firstEventTimeout && !messageOnlyWatchdogTimeout && !this.#hasCleanRetryReplaySafety)
+				(!firstEventTimeout &&
+					!messageOnlyWatchdogTimeout &&
+					!canReplayUnexpectedSocketClose &&
+					!this.#hasCleanRetryReplaySafety)
 			) {
 				return false;
 			}
@@ -24449,6 +24534,7 @@ export class AgentSession {
 			!managedFallback &&
 			classification === "transient" &&
 			!canReplayProviderOverload &&
+			!canReplayUnexpectedSocketClose &&
 			!this.#isIdleStreamStallErrorMessage(message.errorMessage ?? "");
 
 		const failedSelector = managedFallback ? controller.currentSelector() : undefined;
@@ -26024,7 +26110,8 @@ export class AgentSession {
 
 	/** Build a background snapshot with in-flight assistant and optional context. */
 	#buildEphemeralSnapshot(promptText: string, prependMessages?: AgentMessage[]): AgentMessage[] {
-		const messages = [...this.messages];
+		// Side requests run in a fresh provider session with no prefix to preserve.
+		const messages = this.#withoutEphemeralCustomMessages(this.messages);
 		const streaming = this.agent.state.streamMessage;
 		if (streaming && streaming.role === "assistant") {
 			const preservedBlocks: AssistantMessage["content"] = [];
@@ -27256,7 +27343,7 @@ export class AgentSession {
 		const branchEntries = this.sessionManager.getBranch();
 		const latestCompaction = getLatestCompactionEntry(branchEntries);
 		const boundaryTs = latestCompaction ? new Date(latestCompaction.timestamp).getTime() : 0;
-		const anchor = this.#findAnchorableUsageIndex(this.messages, boundaryTs);
+		const anchor = this.#findAnchorableUsageIndex(this.agent.state.messages, boundaryTs);
 		let value: ContextUsage;
 		if (latestCompaction && !anchor) {
 			value = { tokens: null, contextWindow, percent: null, source: "unknown" };
@@ -27279,7 +27366,7 @@ export class AgentSession {
 	}
 
 	#contextUsageCacheKey(model: Model, contextWindow: number): string {
-		const messages = this.messages;
+		const messages = this.agent.state.messages;
 		const lastMessage = messages[messages.length - 1];
 		// Entry and leaf revisions change whenever the active branch changes, avoiding getBranch() on warm reads.
 		const revision = this.sessionManager.revisionSnapshot();
@@ -27428,7 +27515,7 @@ export class AgentSession {
 	 * raw promptTokens/estimatedTokens quotient). Clamped to [0.5, 2] downstream.
 	 */
 	#computeCompactionTokenCorrectionRatio(): number | undefined {
-		const messages = this.messages;
+		const messages = this.agent.state.messages;
 		let lastUsageIndex = -1;
 		let lastUsage: Usage | undefined;
 		for (let i = messages.length - 1; i >= 0; i--) {
@@ -27478,7 +27565,7 @@ export class AgentSession {
 		tokens: number;
 		anchored: boolean;
 	} {
-		const messages = this.messages;
+		const messages = this.agent.state.messages;
 		let anchor = knownAnchor;
 		if (boundaryTs === undefined) {
 			const latestCompaction = getLatestCompactionEntry(this.sessionManager.getBranch());
@@ -27654,7 +27741,7 @@ export class AgentSession {
 	 */
 	formatSessionAsText(): string {
 		return formatSessionDumpText({
-			messages: this.messages,
+			messages: this.#withoutEphemeralCustomMessages(this.messages),
 			systemPrompt: this.agent.state.systemPrompt,
 			model: this.agent.state.model,
 			thinkingLevel: this.#thinkingLevel,

package/src/session/blob-store.ts

@@ -4,6 +4,7 @@ import * as fsp from "node:fs/promises";
 import * as path from "node:path";
 import { exactUnlink } from "@gajae-code/natives";
 import { isEnoent, logger, postmortem } from "@gajae-code/utils";
+import { readLinuxProcStartTimeSync } from "../gjc-runtime/linux-proc";
 
 const BLOB_PREFIX = "blob:sha256:";
 const CANONICAL_BLOB_NAME = /^[0-9a-f]{64}$/;
@@ -46,10 +47,21 @@ const RESIDENT_CACHE_SWEEP_EXPECTED_IO_CODES = new Set([
 ]);
 const ownedResidentCacheInstanceDirs = new Set<string>();
 const activeResidentCacheRootSweeps = new Set<string>();
-let ownResidentCacheProcessStartTimeMs: number | null | undefined;
+let ownResidentCacheProcessStart: ResidentCacheProcessStart | undefined;
 
-/** Marks `startTimeMs` as an absolute instant parsed from a UTC-pinned `ps` render. */
-const RESIDENT_CACHE_START_TIME_BASIS = "utc";
+/** Marks `startTimeMs` as an absolute instant parsed from a UTC-pinned `ps` render (non-Linux). */
+const RESIDENT_CACHE_UTC_START_TIME_BASIS = "utc";
+/**
+ * Prefix for a Linux start identity: `startTimeMs` holds `/proc/<pid>/stat` field 22
+ * (clock ticks since boot) and the suffix is the kernel `boot_id`. Ticks are immune
+ * to wall-clock adjustment; the boot id scopes them to one kernel boot.
+ */
+const RESIDENT_CACHE_LINUX_START_TIME_BASIS_PREFIX = "linux-proc-ticks:";
+
+interface ResidentCacheProcessStart {
+	readonly startTimeMs: number | null;
+	readonly basis: string;
+}
 
 interface ResidentCacheOwnerToken {
 	readonly pid: number;
@@ -240,19 +252,47 @@ function assertResidentCacheDirectoryPathMatchesDescriptor(pathname: string, des
 	assertResidentCacheDirectoryDescriptor(pathname, current, descriptor, uid);
 }
 
-function residentCacheProcessStartTimeMs(pid: number): number | null {
-	if (pid === process.pid && ownResidentCacheProcessStartTimeMs !== undefined) {
-		return ownResidentCacheProcessStartTimeMs;
-	}
+let residentCacheLinuxBootId: string | null | undefined;
 
-	// Mirror file-lock's `ps`-based process incarnation probe, but pin the locale
-	// AND the zone. `lstart` is a zoneless local wall clock rendered by `ps` from
-	// /etc/localtime, while `Date.parse` of a zoneless string binds it to the JS
-	// runtime's own zone. Those are two independent resolutions, so a reader whose
-	// runtime resolves UTC while `ps` renders UTC+9 derives an epoch nine hours off
-	// for the very same live process — and this value's only job is to detect PID
-	// reuse, so a disagreeing reader reports every live owner as reused and the GC
-	// reaps a running session's cache. Pinning TZ on the child fixes the rendering
+function readResidentCacheLinuxBootId(): string | null {
+	if (residentCacheLinuxBootId !== undefined) return residentCacheLinuxBootId;
+	let bootId: string | null = null;
+	try {
+		const text = fs.readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+		if (/^[0-9a-f-]{36}$/.test(text)) bootId = text;
+	} catch {
+		// Without a boot id, tick counts cannot be scoped to one boot.
+	}
+	residentCacheLinuxBootId = bootId;
+	return bootId;
+}
+
+function residentCacheProcessStart(pid: number): ResidentCacheProcessStart {
+	if (pid === process.pid && ownResidentCacheProcessStart !== undefined) return ownResidentCacheProcessStart;
+	const start = process.platform === "linux" ? residentCacheLinuxProcessStart(pid) : residentCacheUtcProcessStart(pid);
+	if (pid === process.pid) ownResidentCacheProcessStart = start;
+	return start;
+}
+
+// `ps -o lstart` is NOT a stable identity on Linux: procps renders it as
+// `btime + starttime_ticks`, and `btime` is re-derived from the current wall clock
+// minus uptime. On hosts whose clock is continuously slewed (WSL2 is the common
+// case) `btime` drifts, so the very same live process reports a start time that
+// moves by seconds to minutes over a session. Any drift reads as PID reuse and the
+// GC reaps a running session's cache. The raw tick count never moves.
+function residentCacheLinuxProcessStart(pid: number): ResidentCacheProcessStart {
+	const bootId = readResidentCacheLinuxBootId();
+	if (bootId === null) return { startTimeMs: null, basis: RESIDENT_CACHE_LINUX_START_TIME_BASIS_PREFIX };
+	const basis = `${RESIDENT_CACHE_LINUX_START_TIME_BASIS_PREFIX}${bootId}`;
+	const ticks = readLinuxProcStartTimeSync(pid);
+	const startTimeMs = ticks === null ? Number.NaN : Number(ticks);
+	return { startTimeMs: Number.isSafeInteger(startTimeMs) ? startTimeMs : null, basis };
+}
+
+function residentCacheUtcProcessStart(pid: number): ResidentCacheProcessStart {
+	// Pin the locale AND the zone. `lstart` is a zoneless local wall clock rendered
+	// by `ps` from /etc/localtime, while `Date.parse` of a zoneless string binds it
+	// to the JS runtime's own zone. Pinning TZ on the child fixes the rendering
 	// side; the explicit GMT suffix fixes the parsing side.
 	let startTimeMs: number | null = null;
 	try {
@@ -269,8 +309,7 @@ function residentCacheProcessStartTimeMs(pid: number): number | null {
 	} catch {
 		// An unavailable process-start source cannot prove PID reuse.
 	}
-	if (pid === process.pid) ownResidentCacheProcessStartTimeMs = startTimeMs;
-	return startTimeMs;
+	return { startTimeMs, basis: RESIDENT_CACHE_UTC_START_TIME_BASIS };
 }
 
 type ResidentCacheOwnerLiveness = "alive" | "dead" | "unknown";
@@ -376,10 +415,11 @@ function readResidentCacheOwnerSnapshot(instanceDir: string, uid: number): Resid
 function writeResidentCacheOwnerToken(instanceDir: string, uid: number): void {
 	const nonce = path.basename(instanceDir).slice("i-".length);
 	if (!nonce) throw new ResidentCacheTrustError("instance_nonce_missing", instanceDir);
+	const ownStart = residentCacheProcessStart(process.pid);
 	const owner: ResidentCacheOwnerToken = {
 		pid: process.pid,
-		startTimeMs: residentCacheProcessStartTimeMs(process.pid),
-		startTimeBasis: RESIDENT_CACHE_START_TIME_BASIS,
+		startTimeMs: ownStart.startTimeMs,
+		startTimeBasis: ownStart.basis,
 		nonce,
 		createdAt: Date.now(),
 	};
@@ -579,26 +619,31 @@ function residentCacheSweepLimit(value: number | undefined, ceiling: number): nu
 	return Math.max(0, Math.min(Math.floor(value), ceiling));
 }
 
-function cachedResidentCacheProcessStartTimeMs(pid: number, cache: Map<number, number | null>): number | null {
-	if (cache.has(pid)) return cache.get(pid) ?? null;
-	const startTimeMs = residentCacheProcessStartTimeMs(pid);
-	cache.set(pid, startTimeMs);
-	return startTimeMs;
+function cachedResidentCacheProcessStart(
+	pid: number,
+	cache: Map<number, ResidentCacheProcessStart>,
+): ResidentCacheProcessStart {
+	const cached = cache.get(pid);
+	if (cached !== undefined) return cached;
+	const start = residentCacheProcessStart(pid);
+	cache.set(pid, start);
+	return start;
 }
 
 function residentCacheOwnerIsStale(
 	owner: ResidentCacheOwnerToken,
-	startTimeCache: Map<number, number | null>,
+	startTimeCache: Map<number, ResidentCacheProcessStart>,
 ): boolean {
 	const liveness = residentCacheOwnerLiveness(owner.pid);
 	if (liveness === "dead") return true;
 	if (liveness !== "alive" || owner.startTimeMs === null) return false;
-	// A token from before the UTC pin carries a zone-dependent wall clock. Comparing
-	// it against an absolute instant would read an ordinary timezone offset as PID
-	// reuse and reap a live owner, so an unlabelled basis leaves reuse unproven.
-	if (owner.startTimeBasis !== RESIDENT_CACHE_START_TIME_BASIS) return false;
-	const currentStartTimeMs = cachedResidentCacheProcessStartTimeMs(owner.pid, startTimeCache);
-	return currentStartTimeMs !== null && currentStartTimeMs !== owner.startTimeMs;
+	const current = cachedResidentCacheProcessStart(owner.pid, startTimeCache);
+	// Start times are comparable only on the same basis (and, on Linux, the same
+	// boot). A token from an older writer (unlabelled zone-dependent wall clock, or
+	// the drifting `ps` render) or another basis leaves reuse unproven, so a live
+	// owner is never reaped on a basis mismatch.
+	if (owner.startTimeBasis !== current.basis) return false;
+	return current.startTimeMs !== null && current.startTimeMs !== owner.startTimeMs;
 }
 
 function reapResidentCacheInstanceDir(
@@ -681,7 +726,7 @@ export async function sweepResidentCacheRoot(root: string, options: ResidentCach
 			// cache state behind.
 			rootDescriptor = openVerifiedResidentCacheDirectory(root, uid);
 			assertResidentCacheDirectoryPathMatchesDescriptor(root, rootDescriptor, uid);
-			const startTimeCache = new Map<number, number | null>();
+			const startTimeCache = new Map<number, ResidentCacheProcessStart>();
 			const entries = fs.opendirSync(root);
 			try {
 				let examined = 0;
@@ -746,7 +791,7 @@ function openVerifiedCacheInstanceDir(root: string, instanceName?: string): stri
 					const staleInstance = readResidentCacheOwnerSnapshot(candidate, uid);
 					if (
 						staleInstance === null ||
-						!residentCacheOwnerIsStale(staleInstance.owner, new Map<number, number | null>()) ||
+						!residentCacheOwnerIsStale(staleInstance.owner, new Map<number, ResidentCacheProcessStart>()) ||
 						!reapResidentCacheInstanceDir(root, rootDescriptor, candidate, staleInstance, uid)
 					) {
 						throw error;