resolveContextEngine,

resolveContextEngineOwnerPluginId,

} from "../../context-engine/registry.js";

import { emitAgentPlanEvent } from "../../infra/agent-events.js";

import { emitAgentPlanEvent, registerAgentRunContext } from "../../infra/agent-events.js";

import { sleepWithAbort } from "../../infra/backoff.js";

import { freezeDiagnosticTraceContext } from "../../infra/diagnostic-trace-context.js";

import { formatErrorMessage } from "../../infra/errors.js";

const nextSessionFile = compactResult.result?.sessionFile;

if (nextSessionId && nextSessionId !== activeSessionId) {

activeSessionId = nextSessionId;

// Keep the run context's sessionId tracking the live session so

// lifecycle persistence isn't treated as stale after a legitimate

// mid-run compaction rotation (#88538).

registerAgentRunContext(params.runId, { sessionId: activeSessionId });

}

if (nextSessionFile && nextSessionFile !== activeSessionFile) {

activeSessionFile = nextSessionFile;

const timedOutDuringToolExecution = attempt.timedOutDuringToolExecution ?? false;

if (sessionIdUsed && sessionIdUsed !== activeSessionId) {

activeSessionId = sessionIdUsed;

// Track the live session for lifecycle persistence identity (#88538).

registerAgentRunContext(params.runId, { sessionId: activeSessionId });

}

if (sessionFileUsed && sessionFileUsed !== activeSessionFile) {

activeSessionFile = sessionFileUsed;

if (params.sessionKey) {

registerAgentRunContext(runId, {

sessionKey: params.sessionKey,

...(params.followupRun.run.sessionId ? { sessionId: params.followupRun.run.sessionId } : {}),

verboseLevel: params.resolvedVerboseLevel,

isHeartbeat: params.isHeartbeat,

isControlUiVisible: shouldSurfaceToControlUi,

if (run.sessionKey) {

registerAgentRunContext(runId, {

sessionKey: run.sessionKey,

...(run.sessionId ? { sessionId: run.sessionId } : {}),

verboseLevel: run.verboseLevel,

isControlUiVisible: shouldSurfaceToControlUi,

});

import {

deriveGatewaySessionLifecycleSnapshot,

derivePersistedSessionLifecyclePatch,

isStaleLifecycleEventForSession,

} from "./session-lifecycle-state.js";

describe("session lifecycle state", () => {

it("treats a pre-reset run's lifecycle event as stale once the row's sessionId rotated (#88538)", () => {

expect(

isStaleLifecycleEventForSession({ owningSessionId: "old-id", currentSessionId: "new-id" }),

).toBe(true);

});

it("applies lifecycle events whose owning sessionId matches the current row", () => {

expect(

isStaleLifecycleEventForSession({ owningSessionId: "same-id", currentSessionId: "same-id" }),

).toBe(false);

});

it("does not guard when the owning sessionId is unknown (preserves legacy behavior)", () => {

expect(

isStaleLifecycleEventForSession({ owningSessionId: undefined, currentSessionId: "new-id" }),

).toBe(false);

});

it("reactivates completed sessions on lifecycle start", () => {

expect(

deriveGatewaySessionLifecycleSnapshot({

type LifecyclePhase = "start" | "end" | "error";

type LifecycleEventLike = Pick<AgentEventPayload, "ts"> & {

type LifecycleEventLike = Pick<AgentEventPayload, "ts" | "sessionId"> & {

data?: {

phase?: unknown;

startedAt?: unknown;

};

}

/**

* A pre-`sessions.reset` run's lifecycle event must not mutate a session row

* whose sessionId was rotated by the reset. True only when both the owning

* run's sessionId and the current row's sessionId are known and differ.

*/

export function isStaleLifecycleEventForSession(params: {

owningSessionId?: string;

currentSessionId?: string;

}): boolean {

return Boolean(

params.owningSessionId &&

params.currentSessionId &&

params.owningSessionId !== params.currentSessionId,

);

}

export async function persistGatewaySessionLifecycleEvent(params: {

sessionKey: string;

agentId?: string;

return;

}

const owningSessionId =

typeof params.event.sessionId === "string" && params.event.sessionId

? params.event.sessionId

: undefined;

await updateSessionStoreEntry({

storePath: sessionEntry.storePath,

sessionKey: sessionEntry.canonicalKey,

skipMaintenance: true,

takeCacheOwnership: true,

update: async (entry) =>

derivePersistedSessionLifecyclePatch({

update: async (entry) => {

// Reject a pre-reset run's lifecycle event: sessions.reset rotates the row

// to a new sessionId under the same sessionKey, so an old in-flight run's

// late start/end/error must not overwrite the fresh row's status (#88538).

if (isStaleLifecycleEventForSession({ owningSessionId, currentSessionId: entry.sessionId })) {

return null;

}

return derivePersistedSessionLifecyclePatch({

entry,

event: params.event,

}),

});

},

});

}

expect(getAgentRunContext("run-1")).toBeUndefined();

});

test("stamps the owning sessionId onto lifecycle events for reset-stale guarding (#88538)", () => {

registerAgentRunContext("run-1", { sessionKey: "main", sessionId: "old-session-id" });

const seen: Array<{ stream: string; sessionId?: string }> = [];

const stop = onAgentEvent((evt) => {

if (evt.runId === "run-1") {

seen.push({ stream: evt.stream, sessionId: evt.sessionId });

}

});

emitAgentEvent({ runId: "run-1", stream: "lifecycle", data: { phase: "error" } });

emitAgentEvent({ runId: "run-1", stream: "item", data: {} });

stop();

expect(seen.find((evt) => evt.stream === "lifecycle")?.sessionId).toBe("old-session-id");

// Only lifecycle events carry the sessionId; other streams stay unstamped.

expect(seen.find((evt) => evt.stream === "item")?.sessionId).toBeUndefined();

});

test("refreshes the stamped sessionId after a mid-run session rotation (#88538)", () => {

registerAgentRunContext("run-1", { sessionKey: "main", sessionId: "start-id" });

// A legitimate compaction rotation re-registers the run with its new session.

registerAgentRunContext("run-1", { sessionId: "rotated-id" });

let stamped: string | undefined;

const stop = onAgentEvent((evt) => {

if (evt.runId === "run-1" && evt.stream === "lifecycle") {

stamped = evt.sessionId;

}

});

emitAgentEvent({ runId: "run-1", stream: "lifecycle", data: { phase: "end" } });

stop();

// Terminal event carries the rotated id, so persistence won't treat the

// run as stale against the row it rotated to.

expect(stamped).toBe("rotated-id");

});

test("maintains monotonic seq per runId", () => {

const seen: Record<string, number[]> = {};

const stop = onAgentEvent((evt) => {

ts: number;

data: Record<string, unknown>;

sessionKey?: string;

/**

* sessionId the run was bound to when it started. Lifecycle persistence uses

* this to reject terminal events from a pre-`sessions.reset` run that would

* otherwise clobber the rotated session row resolved by the shared sessionKey.

*/

sessionId?: string;

agentId?: string;

};

export type AgentRunContext = {

sessionKey?: string;

/** Owning run's sessionId; stamped onto lifecycle events (see AgentEventPayload.sessionId). */

sessionId?: string;

verboseLevel?: VerboseLevel;

isHeartbeat?: boolean;

/** Whether control UI clients should receive chat/agent updates for this run. */

if (context.sessionKey && existing.sessionKey !== context.sessionKey) {

existing.sessionKey = context.sessionKey;

}

if (context.sessionId && existing.sessionId !== context.sessionId) {

existing.sessionId = context.sessionId;

}

if (context.verboseLevel && existing.verboseLevel !== context.verboseLevel) {

existing.verboseLevel = context.verboseLevel;

}

// stream remains redacted for hidden runs because it is observational only.

const preserveSessionKey = isControlUiVisible || event.stream === "lifecycle";

const sessionKey = preserveSessionKey ? (eventSessionKey ?? context?.sessionKey) : undefined;

// Stamp lifecycle events with the owning sessionId (see AgentEventPayload) at

// emit time, since the run context can be cleared before the terminal persists.

const sessionId =

event.stream === "lifecycle" ? (event.sessionId ?? context?.sessionId) : event.sessionId;

const enriched: AgentEventPayload = {

...event,

sessionKey,

...(sessionId ? { sessionId } : {}),

seq: nextSeq,

ts: Date.now(),

};