The Open Framework for Building Agents
feat(eve): detect stranded session owners and skip their replay (#4479)
prha233c509437ca
diff --git a/packages/eve/src/evals/tool-stubs.integration.test.ts b/packages/eve/src/evals/tool-stubs.integration.test.tsindex 7507b57bd..d1af0b2ac 100644--- a/packages/eve/src/evals/tool-stubs.integration.test.ts+++ b/packages/eve/src/evals/tool-stubs.integration.test.ts@@ -7,12 +7,12 @@ import { createEvalTargetHandle } from "#evals/target.js";import { workflowEntry } from "#execution/session/entry.js";import { reportStubFailureStep } from "#execution/tool-stubs/steps.js";import { dispatchWorkflowSessionCommand } from "#execution/workflow-runtime.js";-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";+import { startSessionOwner, waitForHook } from "#internal/testing/workflow-test-helpers.js";import { createTestRuntime } from "#internal/testing/app-harness.js";import { buildSerializedContext, handoffFollowUp } from "#internal/testing/entry-test-helpers.js";import { mockAgentRouteArgs } from "#internal/testing/mocks/mock-route-args.js";import { failingDeployWorkflow } from "#internal/testing/workflow-tool-fixtures.js";-import { start, type Run } from "#internal/workflow/runtime.js";+import type { Run } from "#internal/workflow/runtime.js";import { EVE_MESSAGE_STREAM_VERSION, EVE_STREAM_VERSION_HEADER } from "#protocol/message.js";import { parseToolStubs } from "#tool-stubs/rules.js";import { STUB_CONTEXT_KEY } from "#tool-stubs/types.js";@@ -61,7 +61,7 @@ it.each(["output processing", "failure reporting", "injected error"])(if (url.origin !== "https://eve.test") return await originalFetch(request, init);if (url.pathname === "/eve/v1/session") {const body = JSON.parse(String(init?.body));- run = await start(workflowEntry, [+ run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",diff --git a/packages/eve/src/execution/eve-workflow-attributes.ts b/packages/eve/src/execution/eve-workflow-attributes.tsindex d9c508b4f..b29622e02 100644--- a/packages/eve/src/execution/eve-workflow-attributes.ts+++ b/packages/eve/src/execution/eve-workflow-attributes.ts@@ -31,6 +31,10 @@* - `$eve.trace_id` — sampled trace seed available in the serialized context when* tagging the run. This is a trace link, not a session-wide trace identity or* confirmation that a destination retained the trace.+ * - `$eve.version` — eve version that started the run; handoff successors+ * and legacy importers re-record their own at boot. Ingress and the stranded+ * replay guard compare it to decide whether the run can still execute+ * - `$eve.session` — public session id a handoff successor owner serves*/import { CHANNEL_CONTEXT_KEY_NAME } from "#context/key-names.js";@@ -52,6 +56,21 @@ import {import { isSampledTrace } from "#tracing/sampled-trace.js";import { resolveForwardedTraceSeed } from "#shared/forwarded-trace-policy.js";+/** eve version recorded on every run eve starts; handoff successors and legacy importers re-record it at boot. */+export const EVE_VERSION_ATTRIBUTE = "$eve.version";++/** Run kind; only runs started as a session or subagent session carry it. */+export const EVE_TYPE_ATTRIBUTE = "$eve.type";++/**+ * Public session id recorded on handoff successor owners. Initial owners omit+ * it: their run id is the session id.+ */+export const EVE_SESSION_ATTRIBUTE = "$eve.session";++/** Root session id of a delegated subagent session run. */+export const EVE_ROOT_ATTRIBUTE = "$eve.root";+/*** Active compiled graph node id for the session's agent. Returned by* `createSessionStep` so workflow bodies don't have to load the bundle@@ -282,7 +301,7 @@ export function buildSessionAttributes(input: {"$eve.is_otel_trace_enabled": isOtelTraceEnabled,"$eve.is_trace_content_visible": isTraceContentVisible,"$eve.trace_id": readSessionTraceId(input.serializedContext),- "$eve.type": "session",+ [EVE_TYPE_ATTRIBUTE]: "session","$eve.trigger": readChannelKind(input.serializedContext),"$eve.title": readSessionTitle(input.serializedContext),};@@ -310,11 +329,11 @@ export function buildSubagentRootAttributes(input: {"$eve.is_otel_trace_enabled": isWorkflowOtelTraceEnabled(input.serializedContext),"$eve.is_trace_content_visible": isWorkflowTraceContentVisible(input.serializedContext),"$eve.trace_id": readSessionTraceId(input.serializedContext),- "$eve.type": "subagent",+ [EVE_TYPE_ATTRIBUTE]: "subagent","$eve.parent": input.parentSessionId,"$eve.parent_call": input.parentCallId,"$eve.parent_turn": input.parentTurnId,- "$eve.root": input.rootSessionId,+ [EVE_ROOT_ATTRIBUTE]: input.rootSessionId,"$eve.subagent": input.identity.nodeId,"$eve.trigger": readChannelKind(input.serializedContext),};diff --git a/packages/eve/src/execution/file-memory.integration.test.ts b/packages/eve/src/execution/file-memory.integration.test.tsindex bf8f35311..fab61c759 100644--- a/packages/eve/src/execution/file-memory.integration.test.ts+++ b/packages/eve/src/execution/file-memory.integration.test.ts@@ -1,9 +1,9 @@+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import { describe, expect, it } from "vitest";import { workflowEntry } from "#execution/session/entry.js";import { createTestRuntime } from "#internal/testing/app-harness.js";import { captureTurnEvents, filterEventsByType } from "#internal/testing/events.js";-import { start } from "#internal/workflow/runtime.js";import { fileMemory, inMemory } from "#public/memory/file/index.js";import { defineMemory } from "#public/memory/index.js";import { byPrincipal } from "#public/memory/scope.js";@@ -78,7 +78,7 @@ describe("file memory integration", () => {});async function runTurn(input: { readonly message: string; readonly principalId: string }) {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",diff --git a/packages/eve/src/execution/install-workflow-world.ts b/packages/eve/src/execution/install-workflow-world.tsnew file mode 100644index 000000000..b196bf366--- /dev/null+++ b/packages/eve/src/execution/install-workflow-world.ts@@ -0,0 +1,19 @@+import { getWorld, setWorld } from "#internal/workflow/runtime.js";+import { guardStrandedSessionReplay } from "#execution/session-inbox/stranded-replay-guard.js";+import {+ validateWorkflowWorld,+ type ValidateWorkflowWorldInput,+} from "#internal/workflow/validate-world.js";++/**+ * Validates a Workflow World, installs it as the runtime singleton, and+ * starts it. Generated World plugins call this so eve owns what wraps the+ * World before its queue begins delivering.+ */+export async function installWorkflowWorld(input: ValidateWorkflowWorldInput): Promise<void> {+ validateWorkflowWorld(input);+ const world = guardStrandedSessionReplay(input.world);+ setWorld(world);+ await getWorld();+ await world.start?.();+}diff --git a/packages/eve/src/execution/legacy-remote-agent/protocol.test.ts b/packages/eve/src/execution/legacy-remote-agent/protocol.test.tsindex 734642097..46a90c1d1 100644--- a/packages/eve/src/execution/legacy-remote-agent/protocol.test.ts+++ b/packages/eve/src/execution/legacy-remote-agent/protocol.test.ts@@ -9,6 +9,8 @@ const getHookByTokenMock = vi.fn();vi.mock("#compiled/@workflow/core/runtime.js", () => ({getHookByToken: (token: string) => getHookByTokenMock(token),+ // Vercel-shaped: owners run on their own deployment, so ingress resumes by token.+ getWorld: async () => ({ capabilities: { deploymentAffinity: true } }),resumeHook: (token: string, payload: unknown) => resumeHookMock(token, payload),}));@@ -34,6 +36,11 @@ describe("legacy task input route", () => {});it("delivers answers to the session behind the capability without replacing its principal", async () => {+ getHookByTokenMock.mockImplementation(async (token: string) => ({+ hookId: "hook-1",+ runId: "run-1",+ token,+ }));resumeHookMock.mockResolvedValue({ runId: "run-1" });const response = await postAnswers(`eve:task-input:${DIGEST}`);diff --git a/packages/eve/src/execution/legacy-session/authorization.test.ts b/packages/eve/src/execution/legacy-session/authorization.test.tsindex 15c0c92f2..11a87b8e2 100644--- a/packages/eve/src/execution/legacy-session/authorization.test.ts+++ b/packages/eve/src/execution/legacy-session/authorization.test.ts@@ -3,6 +3,10 @@ import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";import { resumeAuthorizationCallback, handleExpiredLegacyAuthorization } from "./authorization.js";const mocks = vi.hoisted(() => ({ resolve: vi.fn(), resume: vi.fn() }));vi.mock("#internal/workflow/runtime.js", () => ({ resumeHook: mocks.resume }));+// Owner classification has its own tests; every owner here is runnable.+vi.mock("#execution/session-inbox/owner.js", () => ({+ resumeRunnableHook: (token: string, payload: unknown) => mocks.resume(token, payload),+}));vi.mock("./inbox.js", async (original) => ({...(await original<typeof import("./inbox.js")>()),resolveLegacyInbox: mocks.resolve,diff --git a/packages/eve/src/execution/legacy-session/authorization.ts b/packages/eve/src/execution/legacy-session/authorization.tsindex 1989fcd38..4649f44fb 100644--- a/packages/eve/src/execution/legacy-session/authorization.ts+++ b/packages/eve/src/execution/legacy-session/authorization.ts@@ -1,5 +1,6 @@import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";import type { AuthorizationCallbackPayload } from "#execution/session-inbox/inbox.js";+import { resumeRunnableHook } from "#execution/session-inbox/owner.js";import { resumeHook } from "#internal/workflow/runtime.js";import { isObject } from "#shared/guards.js";import { encodeLegacyCommand, resolveLegacyInbox } from "./inbox.js";@@ -15,7 +16,7 @@ export async function resumeAuthorizationCallback(payload: AuthorizationCallbackPayload,): Promise<void> {try {- await resumeHook(token, payload);+ await resumeRunnableHook(token, payload);return;} catch (error) {if (!HookNotFoundError.is(error)) throw error;diff --git a/packages/eve/src/execution/legacy-session/inbox.test.ts b/packages/eve/src/execution/legacy-session/inbox.test.tsindex 8cb38dab4..f91d9b52e 100644--- a/packages/eve/src/execution/legacy-session/inbox.test.ts+++ b/packages/eve/src/execution/legacy-session/inbox.test.ts@@ -5,6 +5,11 @@ import { sessionCommandHookToken } from "#execution/session-inbox/address.js";import { encodeLegacyCommand, resumeLegacyInbox, UnsupportedLegacySessionError } from "./inbox.js";const { get, resume } = vi.hoisted(() => ({ get: vi.fn(), resume: vi.fn() }));vi.mock("#internal/workflow/runtime.js", () => ({ getHookByToken: get, resumeHook: resume }));+// Owner classification has its own tests; every owner here is runnable.+vi.mock("#execution/session-inbox/owner.js", () => ({+ lookupSessionOwnerHook: (token: string) => get(token),+ resumeRunnableHook: (token: string, payload: unknown) => resume(token, payload),+}));beforeEach(() => {get.mockReset();resume.mockReset();diff --git a/packages/eve/src/execution/legacy-session/inbox.ts b/packages/eve/src/execution/legacy-session/inbox.tsindex fccc07cda..5fac939ff 100644--- a/packages/eve/src/execution/legacy-session/inbox.ts+++ b/packages/eve/src/execution/legacy-session/inbox.ts@@ -9,7 +9,8 @@ import {sessionCommandHookToken,sessionInboxHookToken,} from "#execution/session-inbox/address.js";-import { getHookByToken, resumeHook } from "#internal/workflow/runtime.js";+import { lookupSessionOwnerHook, resumeRunnableHook } from "#execution/session-inbox/owner.js";+import { getHookByToken } from "#internal/workflow/runtime.js";import { isObject } from "#shared/guards.js";type Command = DeliverHookPayload | SessionCommand | SessionTimeoutHookPayload;@@ -38,14 +39,16 @@ const MAX_LEGACY_WIRE_VERSION = 7;export async function resolveLegacyInbox(token: string,): Promise<{ hook: Hook; sessionId: string; current: boolean }> {- const legacy = await getHookByToken(token);+ const legacy = await lookupSessionOwnerHook(token);const metadata = await legacy.metadata;const sessionId =isObject(metadata) && typeof metadata.sessionId === "string"? metadata.sessionId: legacy.runId;try {- const hook = await getHookByToken(sessionInboxHookToken(sessionCommandHookToken(sessionId)));+ const hook = await lookupSessionOwnerHook(+ sessionInboxHookToken(sessionCommandHookToken(sessionId)),+ );return { hook, sessionId, current: true };} catch (error) {if (!HookNotFoundError.is(error)) throw error;@@ -63,7 +66,7 @@ export async function resumeLegacyInbox(token: string, command: Command) {isObject(metadata) ? metadata.sessionInboxWireVersion : undefined,);}- const hook = await resumeHook(target.hook.token, payload);+ const hook = await resumeRunnableHook(target.hook.token, payload);return { ownerRunId: hook.runId, sessionId: Promise.resolve(target.sessionId) };}diff --git a/packages/eve/src/execution/legacy-session/turn-workflow.ts b/packages/eve/src/execution/legacy-session/turn-workflow.tsindex 077121e34..4bb5eaaa2 100644--- a/packages/eve/src/execution/legacy-session/turn-workflow.ts+++ b/packages/eve/src/execution/legacy-session/turn-workflow.ts@@ -5,6 +5,7 @@ import { createSessionInbox } from "#execution/session-inbox/inbox.js";import { failSession, runPreparedSession } from "#execution/session/program.js";import { sessionTimeoutDeadline } from "#execution/session/timeout.js";import { createSessionTimeoutControl } from "#execution/session/timeout-control.js";+import { recordSessionOwnerStep } from "#execution/session/handoff-steps.js";import { completeLegacyDriverStep } from "./completion-step.js";import { interruptLegacySessionStep } from "./interrupt-step.js";import { prepareLegacySessionStep } from "./prepare-step.js";@@ -20,6 +21,7 @@ export async function turnWorkflow(rawInput: unknown): Promise<void> {"use workflow";const prepared = await prepareLegacySessionStep(rawInput);const { sessionId } = prepared.sessionState;+ await recordSessionOwnerStep({ sessionId });const inbox = createSessionInbox(sessionId);try {await inbox.claimSessionHook(sessionCommandHookToken(sessionId));diff --git a/packages/eve/src/execution/session-inbox/address.ts b/packages/eve/src/execution/session-inbox/address.tsindex 6a24c1985..85905765c 100644--- a/packages/eve/src/execution/session-inbox/address.ts+++ b/packages/eve/src/execution/session-inbox/address.ts@@ -30,13 +30,27 @@ export function sessionCommandHookToken(sessionId: string): string {return `eve:session:${sessionId}:inbox`;}+const SESSION_INBOX_HOOK_TOKEN_PREFIX = "eve:inbox:v1:";+/*** Physical hook token for a logical session address. Applied exactly where a* hook is created or resumed, so current-generation hooks stay disjoint from* hooks owned by pre-cutover drivers that used the logical token directly.*/export function sessionInboxHookToken(token: string): string {- return `eve:inbox:v1:${token}`;+ return `${SESSION_INBOX_HOOK_TOKEN_PREFIX}${token}`;+}++/** Whether a physical hook token addresses a current-generation session inbox. */+export function isSessionInboxHookToken(token: string): boolean {+ return token.startsWith(SESSION_INBOX_HOOK_TOKEN_PREFIX);+}++/** Logical address behind a physical session inbox hook token; `undefined` for any other hook. */+export function logicalSessionInboxToken(token: string): string | undefined {+ return isSessionInboxHookToken(token)+ ? token.slice(SESSION_INBOX_HOOK_TOKEN_PREFIX.length)+ : undefined;}/** Marker a releasing owner leaves so ingress can tell "handoff in progress" from "no session". */diff --git a/packages/eve/src/execution/session-inbox/inbox.integration.test.ts b/packages/eve/src/execution/session-inbox/inbox.integration.test.tsindex fc80352b6..b09c6cb41 100644--- a/packages/eve/src/execution/session-inbox/inbox.integration.test.ts+++ b/packages/eve/src/execution/session-inbox/inbox.integration.test.ts@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";import { sessionCommandInboxWorkflow } from "#internal/testing/session-inbox-workflow.js";import { sessionHookPumpWorkflow } from "#internal/testing/session-hook-pump-workflow.js";-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";+import { waitForHook, startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import { getHookByToken, resumeHook, start } from "#internal/workflow/runtime.js";import { sessionCommandHookToken } from "#execution/session-inbox/address.js";import {@@ -33,7 +33,7 @@ describe("session command inbox integration", () => {it("stamps the public session id onto every inbox hook", async () => {const channelToken = "http:session-inbox:session-id";- const run = await start(sessionCommandInboxWorkflow, [{ token: channelToken }]);+ const run = await startSessionOwner(sessionCommandInboxWorkflow, [{ token: channelToken }]);const stableToken = sessionInboxHookToken(sessionCommandHookToken(run.runId));try {diff --git a/packages/eve/src/execution/session-inbox/owner.ts b/packages/eve/src/execution/session-inbox/owner.tsnew file mode 100644index 000000000..0341f0317--- /dev/null+++ b/packages/eve/src/execution/session-inbox/owner.ts@@ -0,0 +1,114 @@+import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";+import { EVE_VERSION_ATTRIBUTE } from "#execution/eve-workflow-attributes.js";+import { isSessionInboxHookToken } from "#execution/session-inbox/address.js";+import {+ findRetiredOwnerRun,+ routesToOwnerDeployment,+ type OwnerRun,+} from "#execution/session-inbox/runnable-owner.js";+import { DevelopmentRunUnavailableError } from "#internal/workflow/development-run-unavailable-error.js";+import { getHookByToken, getWorld, resumeHook, type Hook } from "#internal/workflow/runtime.js";++/**+ * The session's owner was built by another eve version, so this build cannot+ * execute it and ingress refused the command before committing it. Internal:+ * carries the owner run, which never reaches a client.+ */+export class StrandedSessionOwnerError extends Error {+ /** The owner's hook, when ingress looked it up; its metadata names the session. */+ readonly hook: Hook | undefined;+ readonly ownerRun: OwnerRun;++ constructor(ownerRun: OwnerRun, hook?: Hook) {+ super(`Session owner run "${ownerRun.runId}" is stranded.`);+ this.name = "StrandedSessionOwnerError";+ this.hook = hook;+ this.ownerRun = ownerRun;+ }++ get ownerRunId(): string {+ return this.ownerRun.runId;+ }++ /** eve version that built the owner, when it recorded one. */+ get eveVersion(): string | undefined {+ return this.ownerRun.attributes[EVE_VERSION_ATTRIBUTE];+ }+}++/**+ * The single ingress path into a hook: refuses a session inbox whose owner+ * cannot execute before anything is committed, then resumes by token. Any+ * other hook resumes unchecked. Resuming by token rather than by the looked-up+ * hook keeps Workflow's delivery dedup, which a caller-supplied hook disables.+ */+export async function resumeRunnableHook(+ token: string,+ payload: unknown,+): Promise<Awaited<ReturnType<typeof resumeHook>>> {+ if (isSessionInboxHookToken(token)) await assertRunnableSessionInbox(token);+ return await resumeHook(token, payload);+}++/**+ * Throws {@link StrandedSessionOwnerError} when the run holding a physical+ * session inbox token cannot execute. An unheld token passes: resuming it+ * reports the absence. Where the World replays each run on its own+ * deployment, every owner can execute, so nothing is looked up.+ */+export async function assertRunnableSessionInbox(token: string): Promise<void> {+ const world = await getWorld();+ if (routesToOwnerDeployment(world)) return;+ const holder = await findSessionHookHolder(token);+ if (holder !== undefined) await assertRunnableOwner(world, holder.runId, holder.hook);+}++/** {@link assertRunnableSessionInbox} for a hook the caller already looked up. */+export async function assertRunnableSessionOwner(hook: Hook): Promise<void> {+ const world = await getWorld();+ if (routesToOwnerDeployment(world)) return;+ await assertRunnableOwner(world, hook.runId, hook);+}++/**+ * The run holding a session hook token, or `undefined` when none does. The+ * `eve dev` World refuses to expose the hooks of a run it will not execute+ * (a dormant or ineligible generation) and names only the run, so `hook` is+ * then absent. This is the only place that refusal is interpreted.+ */+export async function findSessionHookHolder(+ token: string,+): Promise<{ readonly runId: string; readonly hook?: Hook } | undefined> {+ try {+ const hook = await getHookByToken(token);+ return { hook, runId: hook.runId };+ } catch (error) {+ if (HookNotFoundError.is(error)) return undefined;+ if (DevelopmentRunUnavailableError.is(error)) return { runId: error.runId };+ throw error;+ }+}++/**+ * Looks up a session hook. A run the `eve dev` World refuses to expose is+ * stranded only when another eve version built it; otherwise a restart with+ * `--resume` may run it, so the refusal propagates and nothing is ended.+ */+export async function lookupSessionOwnerHook(token: string): Promise<Hook> {+ try {+ return await getHookByToken(token);+ } catch (error) {+ if (!DevelopmentRunUnavailableError.is(error)) throw error;+ await assertRunnableOwner(await getWorld(), error.runId);+ throw error;+ }+}++async function assertRunnableOwner(+ world: Awaited<ReturnType<typeof getWorld>>,+ runId: string,+ hook?: Hook,+): Promise<void> {+ const ownerRun = await findRetiredOwnerRun(world, runId);+ if (ownerRun !== undefined) throw new StrandedSessionOwnerError(ownerRun, hook);+}diff --git a/packages/eve/src/execution/session-inbox/resume.test.ts b/packages/eve/src/execution/session-inbox/resume.test.tsindex 54ae66e67..a2de49a60 100644--- a/packages/eve/src/execution/session-inbox/resume.test.ts+++ b/packages/eve/src/execution/session-inbox/resume.test.ts@@ -1,16 +1,51 @@-import { sessionInboxHookToken } from "#execution/session-inbox/address.js";-import { afterEach, describe, expect, it, vi } from "vitest";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";-import { sessionCommandHookToken } from "#execution/session-inbox/address.js";-import { resumeSessionInbox } from "#execution/session-inbox/resume.js";+import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";+import {+ sessionCommandHookToken,+ sessionInboxHookToken,+} from "#execution/session-inbox/address.js";+import { StrandedSessionOwnerError } from "#execution/session-inbox/owner.js";+import { resumeSessionInbox, SessionHandoffPendingError } from "#execution/session-inbox/resume.js";+import { resolveInstalledPackageInfo } from "#internal/application/package.js";+import { DevelopmentRunUnavailableError } from "#internal/workflow/development-run-unavailable-error.js";+const getHookByTokenMock = vi.fn();+const getWorldMock = vi.fn();const resumeHookMock = vi.fn();vi.mock("#internal/workflow/runtime.js", () => ({+ getHookByToken: (...args: unknown[]) => getHookByTokenMock(...args),+ getWorld: (...args: unknown[]) => getWorldMock(...args),resumeHook: (...args: unknown[]) => resumeHookMock(...args),}));+/** Vercel-shaped: owners run on their own deployment, so ingress resumes by token without a lookup. */+const vercelWorld = { capabilities: { deploymentAffinity: true } };++/** A World without deployment affinity; owner runs record `ownerEveVersion`. */+function singleDeploymentWorld(ownerEveVersion: string | undefined) {+ return {+ runs: {+ get: vi.fn(async (runId: string) => ({+ attributes: ownerEveVersion === undefined ? {} : { "$eve.version": ownerEveVersion },+ runId,+ })),+ },+ };+}++beforeEach(() => {+ getWorldMock.mockResolvedValue(vercelWorld);+ getHookByTokenMock.mockImplementation(async (token: string) => {+ if (!token.startsWith(sessionInboxHookToken(""))) throw new HookNotFoundError(token);+ return sessionHook("owner-2", token, { sessionId: "session-1" });+ });+});+afterEach(() => {+ getHookByTokenMock.mockReset();+ getWorldMock.mockReset();resumeHookMock.mockReset();});@@ -24,6 +59,26 @@ describe("session inbox resume", () => {expect(receipt.ownerRunId).toBe("owner-2");await expect(receipt.sessionId).resolves.toBe("session-1");expect(resumeHookMock).toHaveBeenCalledWith(sessionInboxHookToken(token), { kind: "clear" });+ expect(getHookByTokenMock).not.toHaveBeenCalled();+ });++ it("reads a runnable owner's version once per process", async () => {+ const world = singleDeploymentWorld(resolveInstalledPackageInfo().version);+ getWorldMock.mockResolvedValue(world);+ const hook = sessionHook("owner-runnable", "channel:runnable", { sessionId: "session-1" });+ getHookByTokenMock.mockResolvedValue(hook);+ resumeHookMock.mockResolvedValue(hook);++ await resumeSessionInbox("channel:runnable", { kind: "clear" });+ await resumeSessionInbox("channel:runnable", { kind: "compact" });++ expect(world.runs.get).toHaveBeenCalledOnce();+ expect(resumeHookMock).toHaveBeenNthCalledWith(1, sessionInboxHookToken("channel:runnable"), {+ kind: "clear",+ });+ expect(resumeHookMock).toHaveBeenNthCalledWith(2, sessionInboxHookToken("channel:runnable"), {+ kind: "compact",+ });});it("resolves a saved public address through the stable token", async () => {@@ -74,8 +129,90 @@ describe("session inbox resume", () => {await expect(receipt.sessionId).rejects.toThrow("command accepted");expect(resumeHookMock).toHaveBeenCalledOnce();});++ it("refuses a retired owner before committing the command", async () => {+ getWorldMock.mockResolvedValue(singleDeploymentWorld("0.0.1"));++ const refusal = await resumeSessionInbox("channel:alias", {+ kind: "send",+ payload: { message: "Alice follows up." },+ }).catch((error: unknown) => error);++ expect(refusal).toBeInstanceOf(StrandedSessionOwnerError);+ expect(refusal).toMatchObject({ eveVersion: "0.0.1", ownerRunId: "owner-2" });+ await expect((refusal as StrandedSessionOwnerError).hook?.metadata).resolves.toEqual({+ sessionId: "session-1",+ });+ expect(resumeHookMock).not.toHaveBeenCalled();+ });++ it("refuses an owner that recorded no eve version as retired", async () => {+ getWorldMock.mockResolvedValue(singleDeploymentWorld(undefined));++ const refusal = await resumeSessionInbox("channel:alias", {+ kind: "send",+ payload: { message: "Alice follows up." },+ }).catch((error: unknown) => error);++ expect(refusal).toBeInstanceOf(StrandedSessionOwnerError);+ expect(refusal).toMatchObject({ eveVersion: undefined, ownerRunId: "owner-2" });+ expect(resumeHookMock).not.toHaveBeenCalled();+ });++ it.each([+ ["retires a dormant eve dev run another eve version built", "0.0.1", true],+ ["keeps a dormant eve dev run this eve version built", undefined, false],+ ])("%s", async (_name, ownerEveVersion, stranded) => {+ getWorldMock.mockResolvedValue(+ singleDeploymentWorld(ownerEveVersion ?? resolveInstalledPackageInfo().version),+ );+ // The `eve dev` World refuses every hook lookup for a dormant run, including the resume's own.+ const dormant = async (token: string) => {+ if (!token.startsWith(sessionInboxHookToken(""))) throw new HookNotFoundError(token);+ throw new DevelopmentRunUnavailableError({ availability: "dormant", runId: "owner-1" });+ };+ getHookByTokenMock.mockImplementation(dormant);+ resumeHookMock.mockImplementation(dormant);++ const refusal = await resumeSessionInbox(+ { sessionId: "session-1" },+ { kind: "send", payload: { message: "Bob checks in." } },+ ).catch((error: unknown) => error);++ // A same-version dormant run may resume with `eve dev --resume`, so it is never ended.+ expect(refusal).toBeInstanceOf(+ stranded ? StrandedSessionOwnerError : DevelopmentRunUnavailableError,+ );+ if (stranded) expect(resumeHookMock).not.toHaveBeenCalled();+ });++ it("does not report a handoff that outlives the retry window as an unowned address", async () => {+ vi.useFakeTimers();+ try {+ resumeHookMock.mockRejectedValue(new HookNotFoundError("inbox"));+ getHookByTokenMock.mockImplementation(async (token: string) =>+ sessionHook("releasing-owner", token, {}),+ );++ const delivery = resumeSessionInbox("channel:alias", {+ kind: "send",+ payload: { message: "Alice asks about the release." },+ }).catch((error: unknown) => error);+ await vi.advanceTimersByTimeAsync(6_000);++ await expect(delivery).resolves.toBeInstanceOf(SessionHandoffPendingError);+ } finally {+ vi.useRealTimers();+ }+ });});function sessionHook(runId: string, token: string, metadata: Record<string, unknown>) {- return { metadata: Promise.resolve(metadata), runId, token };+ return {+ hookId: `hook-${runId}`,+ metadata: Promise.resolve(metadata),+ runId,+ specVersion: 6,+ token,+ };}diff --git a/packages/eve/src/execution/session-inbox/resume.ts b/packages/eve/src/execution/session-inbox/resume.tsindex f06778f96..7103abd37 100644--- a/packages/eve/src/execution/session-inbox/resume.ts+++ b/packages/eve/src/execution/session-inbox/resume.ts@@ -18,7 +18,12 @@ import {sessionInboxHookToken,type SessionInboxAddress,} from "#execution/session-inbox/address.js";-import { getHookByToken, resumeHook } from "#internal/workflow/runtime.js";+import {+ assertRunnableSessionOwner,+ lookupSessionOwnerHook,+ resumeRunnableHook,+} from "#execution/session-inbox/owner.js";+import { getHookByToken, type Hook } from "#internal/workflow/runtime.js";import { isObject } from "#shared/guards.js";/** Longest a delivery waits for a mid-handoff successor to claim its hooks. */@@ -36,20 +41,23 @@ export interface ResumedSessionInboxHook {* deployment handoff the address is briefly unowned; the releasing owner* leaves a marker for that interval, so delivery retries instead of* reporting the session gone and letting a channel start a replacement.+ * The retry window bounds this request, not the handoff: a marker that+ * outlives it throws {@link SessionHandoffPendingError}.*/export async function resumeSessionInbox(address: string | SessionInboxAddress,command: DeliverHookPayload | SessionCommand | SessionTimeoutHookPayload | SessionFailurePayload,): Promise<ResumedSessionInboxHook> {- const token = logicalToken(address);+ const token = logicalSessionToken(address);+ const knownSessionId = typeof address === "string" ? undefined : address.sessionId;const deadline = Date.now() + HANDOFF_RETRY_WINDOW_MS;while (true) {- let hook;+ let hook: Awaited<ReturnType<typeof resumeRunnableHook>>;try {- hook = await resumeHook(sessionInboxHookToken(token), command);+ hook = await resumeRunnableHook(sessionInboxHookToken(token), command);} catch (error) {if (!HookNotFoundError.is(error)) throw error;- if (await isHandoffInProgress(token, deadline)) continue;+ if (await waitWhileHandoffInProgress(token, deadline)) continue;if (command.kind === "session-failure") throw error;return await resumeLegacyInbox(token, command).catch(rethrowUnsupportedAsNotFound);}@@ -59,9 +67,7 @@ export async function resumeSessionInbox(get sessionId() {return (identity ??= (async () => {try {- return typeof address === "string"- ? requireSessionId(await hook.metadata)- : address.sessionId;+ return knownSessionId ?? requireSessionId(await hook.metadata);} catch (cause) {// A failed identity read must never cause a second delivery.throw new AcceptedSessionIdentityError(cause);@@ -72,6 +78,20 @@ export async function resumeSessionInbox(}}+/**+ * The address's owner is still handing off after the request's retry window.+ * Nothing was delivered. The address is not unowned, so callers must not start+ * a session there; the request can be retried.+ */+export class SessionHandoffPendingError extends Error {+ constructor(token: string) {+ super(+ `Session address "${token}" is still changing owners. Nothing was delivered; retry the request.`,+ );+ this.name = "SessionHandoffPendingError";+ }+}+export class AcceptedSessionIdentityError extends Error {constructor(cause: unknown) {super("Session command accepted, but its session identity could not be resolved.", { cause });@@ -103,22 +123,31 @@ function rethrowUnsupportedAsNotFound(error: unknown): never {throw error;}-function logicalToken(address: string | SessionInboxAddress): string {+/** Logical token behind an address: the address itself, or the session's stable command token. */+export function logicalSessionToken(address: string | SessionInboxAddress): string {if (typeof address === "string") return address;if (!isSessionInboxAddress(address))throw new Error("Session inbox target has an invalid address.");return sessionCommandHookToken(address.sessionId);}-/** Waits one retry interval when a handoff marker exists; false once the window closes or no marker exists. */-async function isHandoffInProgress(token: string, deadline: number): Promise<boolean> {- if (Date.now() >= deadline) return false;+/**+ * Waits one retry interval when a handoff marker exists; false when no marker+ * exists. Throws once the window closes with the marker still in place.+ */+async function waitWhileHandoffInProgress(token: string, deadline: number): Promise<boolean> {+ let marker: Hook;try {- await getHookByToken(sessionHandoffMarkerToken(token));+ marker = await lookupSessionOwnerHook(sessionHandoffMarkerToken(token));} catch (error) {if (HookNotFoundError.is(error)) return false;throw error;}+ if (Date.now() >= deadline) {+ // A releasing owner that cannot execute never finishes its handoff.+ await assertRunnableSessionOwner(marker);+ throw new SessionHandoffPendingError(token);+ }await new Promise<void>((resolve) => setTimeout(resolve, HANDOFF_RETRY_INTERVAL_MS));return true;}diff --git a/packages/eve/src/execution/session-inbox/runnable-owner.ts b/packages/eve/src/execution/session-inbox/runnable-owner.tsnew file mode 100644index 000000000..379b31abb--- /dev/null+++ b/packages/eve/src/execution/session-inbox/runnable-owner.ts@@ -0,0 +1,49 @@+import type { World } from "#compiled/@workflow/world/index.js";+import { EVE_VERSION_ATTRIBUTE } from "#execution/eve-workflow-attributes.js";+import { resolveInstalledPackageInfo } from "#internal/application/package.js";++export type OwnerRun = Awaited<ReturnType<World["runs"]["get"]>>;++/** Bounds the process-wide set; a cleared entry only costs one more run read. */+const RUNNABLE_OWNER_CACHE_LIMIT = 10_000;++/**+ * Owner runs this process has seen record the running eve version. A run's+ * version never changes once it starts, so a positive answer stays true for+ * the life of the process; retired owners are never cached.+ */+const runnableOwnerRunIds = new Set<string>();++/**+ * Whether the World replays every run on the deployment that started it+ * (Vercel). There, an owner from another eve version is the normal handoff+ * case, not a stranded one.+ */+export function routesToOwnerDeployment(world: Pick<World, "capabilities">): boolean {+ return world.capabilities?.deploymentAffinity === true;+}++/**+ * Whether this build can replay the owner run. On a World that does not route+ * each run to its own deployment, only one build serves it, so an owner that+ * records another eve version, or none, is retired: nothing can execute it again.+ */+function isRunnableOwnerRun(run: Pick<OwnerRun, "attributes">): boolean {+ return run.attributes[EVE_VERSION_ATTRIBUTE] === resolveInstalledPackageInfo().version;+}++/**+ * The owner run when it is retired, or `undefined` when this build can run it.+ * Reads the run only when it is not already known to be runnable.+ */+export async function findRetiredOwnerRun(+ world: Pick<World, "runs">,+ runId: string,+): Promise<OwnerRun | undefined> {+ if (runnableOwnerRunIds.has(runId)) return undefined;+ const run = await world.runs.get(runId, { resolveData: "none" });+ if (!isRunnableOwnerRun(run)) return run;+ if (runnableOwnerRunIds.size >= RUNNABLE_OWNER_CACHE_LIMIT) runnableOwnerRunIds.clear();+ runnableOwnerRunIds.add(runId);+ return undefined;+}diff --git a/packages/eve/src/execution/session-inbox/stranded-replay-guard.integration.test.ts b/packages/eve/src/execution/session-inbox/stranded-replay-guard.integration.test.tsnew file mode 100644index 000000000..83aeba52b--- /dev/null+++ b/packages/eve/src/execution/session-inbox/stranded-replay-guard.integration.test.ts@@ -0,0 +1,218 @@+import { describe, expect, it, vi } from "vitest";++import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";+import type { World } from "#compiled/@workflow/world/index.js";+import { EVE_VERSION_ATTRIBUTE } from "#execution/eve-workflow-attributes.js";+import {+ SESSION_TIMEOUT_WORKFLOW_NAME,+ WORKFLOW_ENTRY_NAME,+ WORKFLOW_TOOL_RUN_WORKFLOW_NAME,+} from "#execution/stable-workflow-names.js";+import { resolveInstalledPackageInfo } from "#internal/application/package.js";+import { captureLogRecords } from "#internal/testing/log-records.js";+import { parkedAnchorWorkflow } from "#internal/testing/session-inbox-workflow.js";+import { waitForHook } from "#internal/testing/workflow-test-helpers.js";+import { getWorld, start } from "#internal/workflow/runtime.js";+import { guardStrandedSessionReplay } from "#execution/session-inbox/stranded-replay-guard.js";++type QueueHandler = Parameters<World["createQueueHandler"]>[1];++const QUEUE_PREFIX = "__eve_test_wkf_workflow_";+const { name: packageName, version: currentEveVersion } = resolveInstalledPackageInfo();+const SESSION_QUEUE = `${QUEUE_PREFIX}workflow//${packageName}//${WORKFLOW_ENTRY_NAME}`;+const TOOL_QUEUE = `${QUEUE_PREFIX}workflow//${packageName}//${WORKFLOW_TOOL_RUN_WORKFLOW_NAME}`;++/** Parks a run on the shared local World, stamped with the given `$eve.version` and attributes. */+async function parkRun(+ token: string,+ eveVersion: string | undefined,+ attributes: Readonly<Record<string, string>> = {},+) {+ const stamped: Record<string, string> = { ...attributes };+ if (eveVersion !== undefined) stamped[EVE_VERSION_ATTRIBUTE] = eveVersion;+ const run = await start(parkedAnchorWorkflow, [{ token }], {+ allowReservedAttributes: true,+ attributes: stamped,+ });+ await waitForHook(run, { token });+ return run;+}++/**+ * Guards a view of the shared World whose queue hands back the wrapped+ * delivery handler, so the test can deliver messages without a queue.+ */+async function guardedDelivery(capabilities?: World["capabilities"]) {+ const world = Object.create(await getWorld()) as World;+ if (capabilities !== undefined) world.capabilities = capabilities;+ let wrapped: QueueHandler | undefined;+ world.createQueueHandler = (_prefix, handler) => {+ wrapped = handler;+ return async () => new Response();+ };+ const handler = vi.fn<QueueHandler>(async () => undefined);+ guardStrandedSessionReplay(world).createQueueHandler(QUEUE_PREFIX, handler);+ const deliver = async (runId: string, queueName = SESSION_QUEUE) =>+ await wrapped!(+ { runId },+ { attempt: 1, messageId: "msg_1" as never, queueName: queueName as never },+ );+ return { deliver, handler, world };+}++describe("guardStrandedSessionReplay", () => {+ it.each([{ eveVersion: "0.0.1" }, { eveVersion: undefined }])(+ "acknowledges a stranded session from eve $eveVersion without replaying it",+ async ({ eveVersion }) => {+ const logs = captureLogRecords();+ const run = await parkRun(`replay-guard:stranded:${eveVersion}`, eveVersion);+ try {+ const { deliver, handler } = await guardedDelivery();++ await expect(deliver(run.runId)).resolves.toBeUndefined();++ expect(handler).not.toHaveBeenCalled();+ await expect(run.status).resolves.toBe("running");+ expect(logs.records).toContainEqual(+ expect.objectContaining({+ level: "warn",+ message: expect.stringContaining(`stranded session run "${run.runId}"`),+ }),+ );+ } finally {+ await run.cancel();+ }+ },+ );++ it.each([+ { kind: "subagent", eveVersion: "0.0.1", queue: SESSION_QUEUE },+ { kind: "subagent", eveVersion: undefined, queue: SESSION_QUEUE },+ { kind: "workflow tool", eveVersion: "0.0.1", queue: TOOL_QUEUE },+ { kind: "workflow tool", eveVersion: undefined, queue: TOOL_QUEUE },+ ])("retires a $kind from eve $eveVersion without replay", async ({ kind, eveVersion, queue }) => {+ captureLogRecords();+ const token = `replay-guard:retire:${kind}:${eveVersion}`;+ const run = await parkRun(+ token,+ eveVersion,+ kind === "subagent" ? { "$eve.type": "subagent" } : {},+ );+ try {+ const { deliver, handler, world } = await guardedDelivery();++ await expect(deliver(run.runId, queue)).resolves.toBeUndefined();++ expect(handler).not.toHaveBeenCalled();+ await expect(run.status).resolves.toBe("cancelled");+ await expect(world.hooks.getByToken(token)).rejects.toSatisfy(HookNotFoundError.is);+ const events = await world.events.list({ runId: run.runId, resolveData: "all" });+ expect(events.data).toContainEqual(+ expect.objectContaining({+ eventType: "run_cancelled",+ eventData: { cancelReason: "Run retired: its eve deployment is no longer available" },+ }),+ );+ await expect(deliver(run.runId, queue)).resolves.toBeUndefined();+ } finally {+ if ((await run.status) === "running") await run.cancel();+ }+ });++ it("retries a delivery whose run cannot be read instead of replaying it", async () => {+ const run = await parkRun("replay-guard:unreadable", "0.0.1");+ try {+ const { deliver, handler, world } = await guardedDelivery();+ const runs = world.runs;+ world.runs = {+ ...runs,+ get: vi+ .fn()+ .mockRejectedValueOnce(new Error("storage unavailable"))+ .mockImplementation(runs.get.bind(runs)),+ };++ await expect(deliver(run.runId)).rejects.toThrow("storage unavailable");+ expect(handler).not.toHaveBeenCalled();++ captureLogRecords();+ await expect(deliver(run.runId)).resolves.toBeUndefined();+ expect(handler).not.toHaveBeenCalled();+ await expect(run.status).resolves.toBe("running");+ } finally {+ await run.cancel();+ }+ });++ it("retries retirement after a cancellation write fails without replaying the run", async () => {+ captureLogRecords();+ const token = "replay-guard:retry-retirement";+ const run = await parkRun(token, "0.0.1");+ try {+ const { deliver, handler, world } = await guardedDelivery();+ const failure = new Error("storage unavailable");+ world.events = {+ ...world.events,+ create: vi+ .fn()+ .mockRejectedValueOnce(failure)+ .mockImplementation(world.events.create.bind(world.events)),+ };++ await expect(deliver(run.runId, TOOL_QUEUE)).rejects.toThrow("storage unavailable");+ expect(handler).not.toHaveBeenCalled();+ await expect(run.status).resolves.toBe("running");+ await expect(world.hooks.getByToken(token)).resolves.toMatchObject({ runId: run.runId });++ await expect(deliver(run.runId, TOOL_QUEUE)).resolves.toBeUndefined();+ await expect(run.status).resolves.toBe("cancelled");+ expect(handler).not.toHaveBeenCalled();+ } finally {+ if ((await run.status) === "running") await run.cancel();+ }+ });++ it.each([+ { case: "a runnable session run", eveVersion: currentEveVersion, queue: SESSION_QUEUE },+ { case: "a runnable workflow tool run", eveVersion: currentEveVersion, queue: TOOL_QUEUE },+ {+ case: "an older session timeout run",+ eveVersion: "0.0.1",+ queue: `${QUEUE_PREFIX}workflow//${packageName}//${SESSION_TIMEOUT_WORKFLOW_NAME}`,+ },+ {+ case: "another workflow's run",+ eveVersion: "0.0.1",+ queue: `${QUEUE_PREFIX}workflow//${packageName}//turnWorkflow`,+ },+ {+ capabilities: { deploymentAffinity: true },+ case: "an older session run where the World replays it on its own deployment",+ eveVersion: "0.0.1",+ queue: SESSION_QUEUE,+ },+ {+ attributes: { "$eve.type": "subagent" },+ case: "a runnable subagent session run",+ eveVersion: currentEveVersion,+ queue: SESSION_QUEUE,+ },+ {+ capabilities: { deploymentAffinity: true },+ case: "an older workflow tool run on its own deployment",+ eveVersion: "0.0.1",+ queue: TOOL_QUEUE,+ },+ ])("delivers $case", async ({ attributes, capabilities, case: name, eveVersion, queue }) => {+ const run = await parkRun(`replay-guard:${name}`, eveVersion, attributes);+ try {+ const { deliver, handler } = await guardedDelivery(capabilities);++ await deliver(run.runId, queue);++ expect(handler).toHaveBeenCalledOnce();+ } finally {+ await run.cancel();+ }+ });+});diff --git a/packages/eve/src/execution/session-inbox/stranded-replay-guard.ts b/packages/eve/src/execution/session-inbox/stranded-replay-guard.tsnew file mode 100644index 000000000..fbf1096b1--- /dev/null+++ b/packages/eve/src/execution/session-inbox/stranded-replay-guard.ts@@ -0,0 +1,138 @@+import type { World } from "#compiled/@workflow/world/index.js";+import { EVE_TYPE_ATTRIBUTE, EVE_VERSION_ATTRIBUTE } from "#execution/eve-workflow-attributes.js";+import {+ findRetiredOwnerRun,+ routesToOwnerDeployment,+ type OwnerRun,+} from "#execution/session-inbox/runnable-owner.js";+import {+ WORKFLOW_ENTRY_NAME,+ WORKFLOW_TOOL_RUN_WORKFLOW_NAME,+} from "#execution/stable-workflow-names.js";+import { resolveInstalledPackageInfo } from "#internal/application/package.js";+import { createLogger } from "#internal/logging.js";+import {+ isInactiveWorkflowRunError,+ isMissingWorkflowRunError,+} from "#internal/workflow/is-inactive-workflow-run-error.js";+import { cancelRun } from "#internal/workflow/runtime.js";++const log = createLogger("execution.session-inbox.stranded-replay-guard");++/**+ * Makes the World acknowledge, without replaying, queue deliveries for+ * top-level eve session runs that another eve version started. Worlds that+ * re-enqueue their active runs at startup (local, Postgres) would otherwise+ * replay such a run on this build's code and fail it as `CORRUPTED_EVENT_LOG`.+ * A top-level session stays active until ingress replaces it or its timeout+ * ends it. Subagent sessions and workflow tool runs are cancelled instead:+ * no later user message can replace their interrupted work. Ingress refuses+ * the same owners by the same verdict, so preserved owners cannot admit work.+ * Timeout workflows remain runnable so they can end preserved sessions.+ *+ * Mutates and returns `world`; only its `createQueueHandler` changes. Worlds+ * that replay each run on its own deployment are returned untouched.+ */+export function guardStrandedSessionReplay<TWorld extends World>(world: TWorld): TWorld {+ if (routesToOwnerDeployment(world)) return world;+ const { name } = resolveInstalledPackageInfo();+ const guardedWorkflows = new Map<string, GuardedWorkflow>([+ [`workflow//${name}//${WORKFLOW_ENTRY_NAME}`, "session"],+ [`workflow//${name}//${WORKFLOW_TOOL_RUN_WORKFLOW_NAME}`, "tool"],+ ]);+ const createQueueHandler = world.createQueueHandler.bind(world);+ world.createQueueHandler = (queueNamePrefix, handler) =>+ createQueueHandler(queueNamePrefix, async (message, meta) => {+ const workflow = guardedWorkflows.get(meta.queueName.slice(queueNamePrefix.length));+ const runId = readRunId(message);+ if (+ workflow !== undefined &&+ runId !== undefined &&+ (await skipRetiredRun(world, runId, workflow))+ ) {+ return undefined;+ }+ return await handler(message, meta);+ });+ return world;+}++type GuardedWorkflow = "session" | "tool";++/** Applies {@link strandedReplayAction}; true when the delivery must not replay. */+async function skipRetiredRun(+ world: World,+ runId: string,+ workflow: GuardedWorkflow,+): Promise<boolean> {+ const run = await readRetiredRun(world, runId);+ if (run === undefined) return false;+ switch (strandedReplayAction(run, workflow)) {+ case "replay":+ return false;+ case "retire":+ await retireRun(world, run);+ return true;+ case "park":+ logParkedSession(run);+ return true;+ }+}++/**+ * What to do with a delivery for a retired run. Only an active run needs a+ * verdict. A top-level session parks so ingress or its timeout can replace or+ * end it; a subagent session or workflow tool run is retired, because no+ * later user message can replace its interrupted work.+ */+function strandedReplayAction(+ run: OwnerRun,+ workflow: GuardedWorkflow,+): "park" | "replay" | "retire" {+ if (run.status !== "pending" && run.status !== "running") return "replay";+ return workflow === "tool" || run.attributes[EVE_TYPE_ATTRIBUTE] === "subagent"+ ? "retire"+ : "park";+}++/** The run when another eve version started it; `undefined` when this build can replay it. */+async function readRetiredRun(world: World, runId: string): Promise<OwnerRun | undefined> {+ try {+ return await findRetiredOwnerRun(world, runId);+ } catch (error) {+ // A resilient start enqueues before its run is readable; such a run is new.+ if (isMissingWorkflowRunError(error)) return undefined;+ // Anything else is retried by the queue: replaying a retired run would corrupt it.+ throw error;+ }+}++async function retireRun(world: World, run: OwnerRun): Promise<void> {+ try {+ await cancelRun(world, run.runId, {+ cancelReason: "Run retired: its eve deployment is no longer available",+ });+ } catch (error) {+ // A concurrent cancellation or completion has already retired the run.+ if (!isInactiveWorkflowRunError(error)) throw error;+ }+ log.warn("Retired stranded descendant run", {+ runId: run.runId,+ previousEveVersion: run.attributes[EVE_VERSION_ATTRIBUTE] ?? "unknown",+ currentEveVersion: resolveInstalledPackageInfo().version,+ });+}++function logParkedSession(run: OwnerRun): void {+ log.warn(+ `Skipping replay of stranded session run "${run.runId}" (owner eve ${run.attributes[EVE_VERSION_ATTRIBUTE] ?? "unknown"}, current ${resolveInstalledPackageInfo().version}). It remains active until an ordinary channel message, an explicit reset, or its session timeout ends it.`,+ );+}++function readRunId(message: unknown): string | undefined {+ if (typeof message !== "object" || message === null || "__healthCheck" in message) {+ return undefined;+ }+ const runId = (message as { readonly runId?: unknown }).runId;+ return typeof runId === "string" && runId.length > 0 ? runId : undefined;+}diff --git a/packages/eve/src/execution/session-limit-cancellation.integration.test.ts b/packages/eve/src/execution/session-limit-cancellation.integration.test.tsindex 552acd5ee..25e5c4371 100644--- a/packages/eve/src/execution/session-limit-cancellation.integration.test.ts+++ b/packages/eve/src/execution/session-limit-cancellation.integration.test.ts@@ -1,6 +1,7 @@+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import { sessionInboxHookToken } from "#execution/session-inbox/address.js";import { describe, expect, it } from "vitest";-import { resumeHook, start } from "#internal/workflow/runtime.js";+import { resumeHook } from "#internal/workflow/runtime.js";import { createTestRuntime } from "#internal/testing/app-harness.js";import {@@ -88,7 +89,7 @@ describe("session-limit continuation decline integration", () => {const continuationToken = "http:limit-decline-root";await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",diff --git a/packages/eve/src/execution/session-reset.integration.test.ts b/packages/eve/src/execution/session-reset.integration.test.tsindex 61f4ce773..be38650a1 100644--- a/packages/eve/src/execution/session-reset.integration.test.ts+++ b/packages/eve/src/execution/session-reset.integration.test.ts@@ -6,9 +6,8 @@ import { SessionKey } from "#context/keys.js";import { ensureSandboxAccess } from "#execution/sandbox/ensure.js";import { shutdownActiveSandboxHandles } from "#execution/sandbox/active-handles.js";import { sessionCommandInboxWorkflow } from "#internal/testing/session-inbox-workflow.js";-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";+import { waitForHook, startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";-import { start } from "#internal/workflow/runtime.js";import { createWorkflowRuntime } from "#execution/workflow-runtime.js";import { defineSandboxProvider } from "#shared/sandbox-provider.js";import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";@@ -28,7 +27,9 @@ describe("session reset integration", () => {compiledArtifactsSource: {} as RuntimeCompiledArtifactsSource,});const sandboxes = createSessionSandboxHarness();- const first = await start(sessionCommandInboxWorkflow, [{ token: continuationToken }]);+ const first = await startSessionOwner(sessionCommandInboxWorkflow, [+ { token: continuationToken },+ ]);try {await waitForHook(first, { token: sessionInboxHookToken(continuationToken) });@@ -44,7 +45,9 @@ describe("session reset integration", () => {await expect(first.returnValue).resolves.toBeUndefined();await expect(runtime.resolveContinuation(continuationToken)).resolves.toBeUndefined();- const second = await start(sessionCommandInboxWorkflow, [{ token: continuationToken }]);+ const second = await startSessionOwner(sessionCommandInboxWorkflow, [+ { token: continuationToken },+ ]);try {await expect(waitForHook(second, { token: sessionInboxHookToken(continuationToken) }),diff --git a/packages/eve/src/execution/session/entry-authorization.integration.test.ts b/packages/eve/src/execution/session/entry-authorization.integration.test.tsindex 3a1156115..b07372bbf 100644--- a/packages/eve/src/execution/session/entry-authorization.integration.test.ts+++ b/packages/eve/src/execution/session/entry-authorization.integration.test.ts@@ -7,10 +7,10 @@ import { createWorkflowRuntime } from "#execution/workflow-runtime.js";import { slackChannel } from "#public/channels/slack/slackChannel.js";import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";-import { resumeHook, start } from "#internal/workflow/runtime.js";+import { resumeHook } from "#internal/workflow/runtime.js";import { filterEventsByType } from "#internal/testing/events.js";import { createTestRuntime } from "#internal/testing/app-harness.js";-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";+import { startSessionOwner, waitForHook } from "#internal/testing/workflow-test-helpers.js";import { workflowEntry } from "#execution/session/entry.js";import {sessionCommandHookToken,@@ -139,7 +139,7 @@ describe("workflowEntry integration", () => {const continuationToken = "http:workflow-entry-auth-followup";await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -579,7 +579,7 @@ function userAuth(principalId: string) {}async function startWeatherRun(continuationToken: string) {- return await start(workflowEntry, [+ return await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",diff --git a/packages/eve/src/execution/session/entry-handoff-lifetime.integration.test.ts b/packages/eve/src/execution/session/entry-handoff-lifetime.integration.test.tsindex e0b7abd13..a9f36d62b 100644--- a/packages/eve/src/execution/session/entry-handoff-lifetime.integration.test.ts+++ b/packages/eve/src/execution/session/entry-handoff-lifetime.integration.test.ts@@ -1,6 +1,7 @@+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import { DEFAULT_SESSION_TIMEOUT_MS } from "#execution/session/timeout.js";import { assert, describe, expect, it, vi } from "vitest";-import { getWorld, resumeHook, start } from "#internal/workflow/runtime.js";+import { getWorld, resumeHook } from "#internal/workflow/runtime.js";import { hydrateStepReturnValue, hydrateWorkflowArguments } from "@workflow/core/serialization";import { captureTurnEvents } from "#internal/testing/events.js";import { createTestRuntime } from "#internal/testing/app-harness.js";@@ -28,7 +29,7 @@ describe("workflowEntry integration", () => {const runtime = await createTestRuntime({ agent: { name: "workflow-entry-handoff" } });await runtime.run(async () => {- const anchor = await start(workflowEntry, [+ const anchor = await startSessionOwner(workflowEntry, [{kind: "initial",sessionTimeoutMs,@@ -221,7 +222,7 @@ describe("workflowEntry integration", () => {const runtime = await createTestRuntime({ agent: { name: "workflow-entry-compaction" } });await runtime.run(async () => {- const anchor = await start(workflowEntry, [+ const anchor = await startSessionOwner(workflowEntry, [{kind: "initial",sessionTimeoutMs: 60_000,diff --git a/packages/eve/src/execution/session/entry-handoff.integration.test.ts b/packages/eve/src/execution/session/entry-handoff.integration.test.tsindex f63220009..8d00cb715 100644--- a/packages/eve/src/execution/session/entry-handoff.integration.test.ts+++ b/packages/eve/src/execution/session/entry-handoff.integration.test.ts@@ -1,7 +1,8 @@+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import type { HandoffWorkflowEntryInput } from "#execution/session/entry-input.js";import type { RunCreatedEventRequest } from "@workflow/world";import { assert, describe, expect, it, vi } from "vitest";-import { getWorld, resumeHook, start } from "#internal/workflow/runtime.js";+import { getWorld, resumeHook } from "#internal/workflow/runtime.js";import { dehydrateWorkflowArguments, hydrateWorkflowArguments } from "@workflow/core/serialization";import { captureTurnEvents } from "#internal/testing/events.js";import { createTestRuntime } from "#internal/testing/app-harness.js";@@ -29,7 +30,7 @@ describe("workflowEntry integration", () => {const output = captureConsoleOutput();const runtime = await createTestRuntime({ agent: { name: "handoff-validation" } });await runtime.run(async () => {- const anchor = await start(workflowEntry, [+ const anchor = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_a",@@ -178,7 +179,7 @@ describe("workflowEntry integration", () => {const output = captureConsoleOutput();const runtime = await createTestRuntime({ agent: { name: "handoff-checkpoint-version" } });await runtime.run(async () => {- const anchor = await start(workflowEntry, [+ const anchor = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_a",@@ -360,7 +361,7 @@ describe("workflowEntry integration", () => {const output = captureConsoleOutput();const runtime = await createTestRuntime({ agent: { name: "handoff-eve-066-owner" } });await runtime.run(async () => {- const anchor = await start(workflowEntry, [+ const anchor = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_a",@@ -462,7 +463,7 @@ describe("workflowEntry integration", () => {const runtime = await createTestRuntime({ agent: { name: "workflow-entry-handoff" } });await runtime.run(async () => {- const anchor = await start(workflowEntry, [+ const anchor = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_a",@@ -565,7 +566,7 @@ describe("workflowEntry integration", () => {const continuationToken = "http:workflow-entry-handoff-alias";await runtime.run(async () => {- const anchor = await start(workflowEntry, [+ const anchor = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_a",@@ -673,7 +674,7 @@ describe("workflowEntry integration", () => {const runtime = await createTestRuntime({ agent: { name: "workflow-entry-handoff-busy" } });await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_a",diff --git a/packages/eve/src/execution/session/entry.integration.test.ts b/packages/eve/src/execution/session/entry.integration.test.tsindex 6b1d70742..4d6eb57cc 100644--- a/packages/eve/src/execution/session/entry.integration.test.ts+++ b/packages/eve/src/execution/session/entry.integration.test.ts@@ -4,7 +4,7 @@ import { hydrateWorkflowArguments } from "@workflow/core/serialization";import { createChannelAddress } from "#channel/channel-address.js";import { captureTurnEvents, filterEventsByType } from "#internal/testing/events.js";import { createTestRuntime } from "#internal/testing/app-harness.js";-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";+import { waitForHook, startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";import { workflowEntry } from "#execution/session/entry.js";import {@@ -173,7 +173,7 @@ describe("workflowEntry integration", () => {});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -256,7 +256,7 @@ describe("workflowEntry integration", () => {});try {await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -291,7 +291,7 @@ describe("workflowEntry integration", () => {const continuationToken = "http:workflow-entry-conversation";await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -519,7 +519,7 @@ describe("workflowEntry integration", () => {const runtime = await createTestRuntime({ agent: { name: "workflow-entry-id-only" } });await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -549,7 +549,7 @@ describe("workflowEntry integration", () => {const continuationToken = "http:workflow-entry-event-ids";await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -635,7 +635,7 @@ describe("workflowEntry integration", () => {});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -682,7 +682,7 @@ describe("workflowEntry integration", () => {});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -748,7 +748,7 @@ describe("workflowEntry integration", () => {const childContinuationToken = "subagent:parent-session:call-1";await runtime.run(async () => {- const child = await start(workflowEntry, [+ const child = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -848,7 +848,7 @@ describe("workflowEntry integration", () => {const firstCallerToken = "subagent:parent-session:call-1";await runtime.run(async () => {- const child = await start(workflowEntry, [+ const child = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -1207,7 +1207,7 @@ describe("workflowEntry integration", () => {const continuationToken = "http:workflow-entry-hook-owner";await runtime.run(async () => {- const owner = await start(workflowEntry, [+ const owner = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -1227,7 +1227,7 @@ describe("workflowEntry integration", () => {const firstTurn = await ownerStream.nextTurn();expect(firstTurn.at(-1)?.type).toBe("session.waiting");- const contender = await start(workflowEntry, [+ const contender = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -1275,7 +1275,7 @@ describe("workflowEntry integration", () => {} as const;await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -1634,7 +1634,7 @@ async function withHeldApprovalRun(};if (options.auth !== undefined) context.auth = options.auth;await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",diff --git a/packages/eve/src/execution/session/entry.ts b/packages/eve/src/execution/session/entry.tsindex d22edf42a..b8959e5a0 100644--- a/packages/eve/src/execution/session/entry.ts+++ b/packages/eve/src/execution/session/entry.ts@@ -26,6 +26,7 @@ import {sessionCommandHookToken,} from "#execution/session-inbox/address.js";import {+ recordSessionOwnerStep,signalSessionOwnerActivationStep,stopUntrackedChildSessionsStep,validateSessionCheckpointStep,@@ -265,6 +266,7 @@ async function bootHandoffOwner(}({ checkpoint, childRunIdsToStop } = migration);serializedContext = stampSessionIdentity(checkpoint.serializedContext, sessionId);+ await recordSessionOwnerStep({ sessionId });await inbox.claimSessionHooks(sessionHookTokens({ serializedContext, sessionState: checkpoint.sessionState }),);diff --git a/packages/eve/src/execution/session/handoff-steps.ts b/packages/eve/src/execution/session/handoff-steps.tsindex 1dba19c70..9abf5fc0c 100644--- a/packages/eve/src/execution/session/handoff-steps.ts+++ b/packages/eve/src/execution/session/handoff-steps.ts@@ -15,6 +15,11 @@ import {} from "#execution/session/handoff.js";import { createLogger, logError } from "#internal/logging.js";import { cancelRun, getWorld, resumeHook } from "#internal/workflow/runtime.js";+import { resolveInstalledPackageInfo } from "#internal/application/package.js";+import {+ EVE_SESSION_ATTRIBUTE,+ EVE_VERSION_ATTRIBUTE,+} from "#execution/eve-workflow-attributes.js";import { getResolvedRuntimeAgentNode } from "#runtime/graph.js";import { BundleKey } from "#runtime/sessions/runtime-context-keys.js";import { getSandboxEnvironmentRuntime } from "#shared/sandbox-environment.js";@@ -184,6 +189,26 @@ export async function reportSessionHandoffRetainedStep(input: {});}+/**+ * Records the identity of an owner that this deployment's code did not start+ * (a handoff successor or a legacy importer) before it claims any hook:+ * ingress reads `$eve.version` to decide whether the owner can run, so a+ * missing value would strand a healthy session. The value comes from this+ * step's code, not the previous owner's. Unlike observability attributes, a+ * failed write fails the boot.+ */+export async function recordSessionOwnerStep(input: { readonly sessionId: string }): Promise<void> {+ "use step";+ const { setAttributes } = await import("#compiled/@workflow/core/index.js");+ await setAttributes(+ {+ [EVE_SESSION_ATTRIBUTE]: input.sessionId,+ [EVE_VERSION_ATTRIBUTE]: resolveInstalledPackageInfo().version,+ },+ { allowReservedAttributes: true },+ );+}+export async function signalSessionOwnerActivationStep(input: {readonly activation: SessionOwnerActivation;readonly token: string;diff --git a/packages/eve/src/execution/session/timeout-steps.test.ts b/packages/eve/src/execution/session/timeout-steps.test.tsindex c45575eab..f8fbead61 100644--- a/packages/eve/src/execution/session/timeout-steps.test.ts+++ b/packages/eve/src/execution/session/timeout-steps.test.ts@@ -6,15 +6,19 @@ import {startSessionTimeoutStep,} from "#execution/session/timeout-steps.js";import { sessionTimeoutWorkflowReference } from "#execution/workflow-runtime.js";+import { resolveInstalledPackageInfo } from "#internal/application/package.js";+import { sessionInboxHookToken } from "#execution/session-inbox/address.js";+import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";const cancelRunMock = vi.fn();+const getHookByTokenMock = vi.fn();const getWorldMock = vi.fn();const resumeHookMock = vi.fn();const startMock = vi.fn();vi.mock("#compiled/@workflow/core/runtime.js", () => ({cancelRun: (...args: unknown[]) => cancelRunMock(...args),- getHookByToken: (...args: unknown[]) => resumeHookMock(...args),+ getHookByToken: (...args: unknown[]) => getHookByTokenMock(...args),getWorld: (...args: unknown[]) => getWorldMock(...args),resumeHook: (...args: unknown[]) => resumeHookMock(...args),start: (...args: unknown[]) => startMock(...args),@@ -26,12 +30,27 @@ const TIMEOUT_HOOK = {token: "session-1:session-timeout",};+/** A single-deployment World whose owner runs record the given eve version. */+function singleDeploymentWorld(ownerEveVersion = resolveInstalledPackageInfo().version) {+ return {+ getDeploymentId: async () => "dpl_current",+ runs: {+ get: async (runId: string) => ({ attributes: { "$eve.version": ownerEveVersion }, runId }),+ },+ };+}+beforeEach(() => {- getWorldMock.mockResolvedValue({ getDeploymentId: async () => "dpl_current" });+ getHookByTokenMock.mockImplementation(async (token: string) => {+ if (!token.startsWith(sessionInboxHookToken(""))) throw new HookNotFoundError(token);+ return { runId: "session-1", specVersion: 6, token };+ });+ getWorldMock.mockResolvedValue(singleDeploymentWorld());});afterEach(() => {cancelRunMock.mockReset();+ getHookByTokenMock.mockReset();getWorldMock.mockReset();resumeHookMock.mockReset();startMock.mockReset();@@ -50,6 +69,8 @@ describe("session timeout steps", () => {await expect(startSessionTimeoutStep(input)).resolves.toEqual({ runId: "timer-run" });expect(startMock).toHaveBeenCalledWith(sessionTimeoutWorkflowReference, [input], {+ allowReservedAttributes: true,+ attributes: { "$eve.version": resolveInstalledPackageInfo().version },deploymentId: "dpl_current",});});diff --git a/packages/eve/src/execution/session/turn-step.test.ts b/packages/eve/src/execution/session/turn-step.test.tsindex ec3e00bec..804942028 100644--- a/packages/eve/src/execution/session/turn-step.test.ts+++ b/packages/eve/src/execution/session/turn-step.test.ts@@ -233,7 +233,14 @@ vi.mock("../../runtime/sessions/compiled-agent-cache.js", () => ({}));vi.mock("#compiled/@workflow/core/runtime.js", () => ({+ getHookByToken: async (token: string) => {+ const { HookNotFoundError } = await import("#compiled/@workflow/errors/index.js");+ if (!token.startsWith("eve:inbox:v1:")) throw new HookNotFoundError(token);+ return currentSessionHook(token);+ },getRun: (...args: unknown[]) => getRunMock(...args),+ // Vercel-shaped: owners run on their own deployment, so ingress resumes by token.+ getWorld: async () => ({ capabilities: { deploymentAffinity: true } }),resumeHook: (...args: unknown[]) => resumeHookMock(...args),start: (...args: unknown[]) => startMock(...args),}));diff --git a/packages/eve/src/execution/tool-stubs/execution.integration.test.ts b/packages/eve/src/execution/tool-stubs/execution.integration.test.tsindex 3b972debc..ff0219ef2 100644--- a/packages/eve/src/execution/tool-stubs/execution.integration.test.ts+++ b/packages/eve/src/execution/tool-stubs/execution.integration.test.ts@@ -1,8 +1,9 @@import { FatalError } from "#compiled/@workflow/errors/index.js";import { STUB_FAILURE_NAMESPACE, stubResponseNamespace } from "#tool-stubs/types.js";import { describe, expect, it, vi } from "vitest";-import { getWorld, start } from "#internal/workflow/runtime.js";+import { getWorld } from "#internal/workflow/runtime.js";import { createTestRuntime } from "#internal/testing/app-harness.js";+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import { buildSerializedContext, handoffFollowUp } from "#internal/testing/entry-test-helpers.js";import { captureTurnEvents, filterEventsByType } from "#internal/testing/events.js";import { workflowEntry } from "#execution/session/entry.js";@@ -60,7 +61,7 @@ describe("tool replacement through the session runtime", () => {],});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -135,7 +136,7 @@ describe("tool replacement through the session runtime", () => {});await runtime.run(async () => {const message = 'Run deploy_service with service "api"';- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -216,7 +217,7 @@ describe("tool replacement through the session runtime", () => {],});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -300,7 +301,7 @@ describe("tool replacement through the session runtime", () => {],});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -355,7 +356,7 @@ describe("tool replacement through the session runtime", () => {it("replaces the whole agent tool without starting a remote or local agent", async () => {const runtime = await createTestRuntime();await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -410,7 +411,7 @@ describe("tool replacement through the session runtime", () => {],});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -491,7 +492,7 @@ describe("tool replacement through the session runtime", () => {],});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -557,7 +558,7 @@ describe("tool replacement through the session runtime", () => {toolName: "deploy_service",});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",diff --git a/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization-close.integration.test.ts b/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization-close.integration.test.tsindex afe6bd77c..963b32f6a 100644--- a/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization-close.integration.test.ts+++ b/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization-close.integration.test.ts@@ -1,5 +1,6 @@+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import { describe, expect, it } from "vitest";-import { getWorld, start } from "#internal/workflow/runtime.js";+import { getWorld } from "#internal/workflow/runtime.js";import { captureTurnEvents, filterEventsByType } from "#internal/testing/events.js";import { workflowEntry } from "#execution/session/entry.js";import { sessionCommandHookToken } from "#execution/session-inbox/address.js";@@ -24,7 +25,7 @@ describe("workflow step authorization failures", () => {toolName: "deploy_service",});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",diff --git a/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization.integration.test.ts b/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization.integration.test.tsindex a9bdf3c35..5da3d89f7 100644--- a/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization.integration.test.ts+++ b/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization.integration.test.ts@@ -1,5 +1,6 @@+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import { describe, expect, it } from "vitest";-import { getRun, getWorld, start } from "#internal/workflow/runtime.js";+import { getRun, getWorld } from "#internal/workflow/runtime.js";import { captureTurnEvents, filterEventsByType } from "#internal/testing/events.js";import { workflowEntry } from "#execution/session/entry.js";import { hydrateWorkflowReturnValue } from "@workflow/core/serialization";@@ -18,7 +19,7 @@ describe("workflow step authorization", () => {toolName: "deploy_service",});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -63,7 +64,7 @@ describe("workflow step authorization", () => {toolName: "deploy_service",});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",diff --git a/packages/eve/src/execution/tools/workflow/workflow-tool-run-cancellation.integration.test.ts b/packages/eve/src/execution/tools/workflow/workflow-tool-run-cancellation.integration.test.tsindex 91cb5455b..d30bb4a28 100644--- a/packages/eve/src/execution/tools/workflow/workflow-tool-run-cancellation.integration.test.ts+++ b/packages/eve/src/execution/tools/workflow/workflow-tool-run-cancellation.integration.test.ts@@ -1,7 +1,7 @@import { afterEach, describe, expect, it, vi } from "vitest";-import { getWorld, start } from "#internal/workflow/runtime.js";+import { getWorld } from "#internal/workflow/runtime.js";import { captureTurnEvents, filterEventsByType } from "#internal/testing/events.js";-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";+import { waitForHook, startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import { workflowEntry } from "#execution/session/entry.js";import { sessionCommandHookToken } from "#execution/session-inbox/address.js";import { resumeSessionInbox } from "#execution/session-inbox/resume.js";@@ -27,7 +27,7 @@ describe("workflow tool cancellation", () => {await runtime.run(async () => {const before = await listWorkflowToolRunIds();- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",diff --git a/packages/eve/src/execution/tools/workflow/workflow-tool-run.integration.test.ts b/packages/eve/src/execution/tools/workflow/workflow-tool-run.integration.test.tsindex b697ff753..ed2e45d47 100644--- a/packages/eve/src/execution/tools/workflow/workflow-tool-run.integration.test.ts+++ b/packages/eve/src/execution/tools/workflow/workflow-tool-run.integration.test.ts@@ -1,6 +1,7 @@import { afterEach, describe, expect, it, vi } from "vitest";import { hydrateStepArguments } from "#compiled/@workflow/core/serialization.js";-import { getWorld, start } from "#internal/workflow/runtime.js";+import { getWorld } from "#internal/workflow/runtime.js";+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import {captureTurnEvents,containsEventSequence,@@ -39,7 +40,7 @@ describe("workflow tools", () => {toolName: "deploy_service",});const output = await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -63,7 +64,7 @@ describe("workflow tools", () => {});const output = await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -87,7 +88,7 @@ describe("workflow tools", () => {});const output = await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -113,7 +114,7 @@ describe("workflow tools", () => {});const output = await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -145,7 +146,7 @@ describe("workflow tools", () => {});const output = await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -171,7 +172,7 @@ describe("workflow tools", () => {});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -259,7 +260,7 @@ describe("workflow tools", () => {});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -338,7 +339,7 @@ describe("workflow tools", () => {});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -397,7 +398,7 @@ describe("workflow tools", () => {});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -463,7 +464,7 @@ describe("workflow tools", () => {});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -521,7 +522,7 @@ describe("workflow tools", () => {});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -560,7 +561,7 @@ describe("workflow tools", () => {const earlyNote = "Alice notes that the api rollout window opens at noon.";await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",diff --git a/packages/eve/src/execution/turn-cancellation.integration.test.ts b/packages/eve/src/execution/turn-cancellation.integration.test.tsindex 1bbde866c..f71fa5c17 100644--- a/packages/eve/src/execution/turn-cancellation.integration.test.ts+++ b/packages/eve/src/execution/turn-cancellation.integration.test.ts@@ -1,6 +1,6 @@import { sessionInboxHookToken } from "#execution/session-inbox/address.js";import { describe, expect, it } from "vitest";-import { getWorld, resumeHook, start } from "#internal/workflow/runtime.js";+import { getWorld, resumeHook } from "#internal/workflow/runtime.js";import { createTestRuntime, type TestRuntime } from "#internal/testing/app-harness.js";import { mockChannelContext } from "#internal/testing/mocks/mock-channel-operations.js";@@ -9,7 +9,7 @@ import {containsEventSequence,filterEventsByType,} from "#internal/testing/events.js";-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";+import { waitForHook, startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import { ROOT_COMPILED_AGENT_NODE_ID } from "#compiler/manifest.js";import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";import { sessionCommandHookToken } from "#execution/session-inbox/address.js";@@ -345,7 +345,7 @@ describe("turn cancellation integration", () => {});await fixture.runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -435,7 +435,7 @@ describe("turn cancellation integration", () => {});await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -489,7 +489,7 @@ describe("turn cancellation integration", () => {});await fixture.runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -545,7 +545,7 @@ describe("turn cancellation integration", () => {});await fixture.runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -597,7 +597,7 @@ describe("turn cancellation integration", () => {const continuationToken = "http:turn-cancel-tool";await fixture.runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -684,7 +684,7 @@ describe("turn cancellation integration", () => {status: "no_active_turn",});- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -778,7 +778,7 @@ describe("turn cancellation integration", () => {status: "no_active_turn",});- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -854,7 +854,7 @@ describe("turn cancellation integration", () => {const continuationToken = "http:turn-cancel-stale-guard";await fixture.runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -903,7 +903,7 @@ describe("turn cancellation integration", () => {const continuationToken = "http:turn-cancel-late";await runtime.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",diff --git a/packages/eve/src/execution/workflow-runtime.test.ts b/packages/eve/src/execution/workflow-runtime.test.tsindex cd4f754f6..701be939f 100644--- a/packages/eve/src/execution/workflow-runtime.test.ts+++ b/packages/eve/src/execution/workflow-runtime.test.ts@@ -35,6 +35,8 @@ import { captureLogRecords } from "#internal/testing/log-records.js";const getHookByTokenMock = vi.fn();const world = {+ // Vercel-shaped: owners run on their own deployment, so ingress resumes by token.+ capabilities: { deploymentAffinity: true },getDeploymentId: vi.fn(async () => "dpl_current"),};const getRunMock = vi.fn();@@ -188,7 +190,11 @@ describe("session owner starts", () => {sessionId: "anchor-1",}),],- { deploymentId: "deployment-b" },+ {+ deploymentId: "deployment-b",+ allowReservedAttributes: true,+ attributes: { "$eve.version": resolveInstalledPackageInfo().version },+ },);});});@@ -229,7 +235,6 @@ describe("createWorkflowRuntime command dispatch", () => {payload: { message: "hello" },requestId: "req_deliver",});- expect(getHookByTokenMock).not.toHaveBeenCalled();});it.each(["pending", "running", "completed", "failed", "cancelled"])(@@ -267,7 +272,6 @@ describe("createWorkflowRuntime command dispatch", () => {kind: "clear",},);- expect(getHookByTokenMock).not.toHaveBeenCalled();});it("does not report an accepted command as missing when metadata hydration fails", async () => {@@ -310,7 +314,6 @@ describe("createWorkflowRuntime command dispatch", () => {payload: { message: "hello" },},);- expect(getHookByTokenMock).not.toHaveBeenCalled();});it("acknowledges the exact delivery accepted by the session inbox", async () => {@@ -382,7 +385,6 @@ describe("createWorkflowRuntime command dispatch", () => {turnId: "turn-2",},);- expect(getHookByTokenMock).not.toHaveBeenCalled();});it("maps missing and terminal targets to 'no_active_turn'", async () => {@@ -425,9 +427,11 @@ describe("createWorkflowRuntime command dispatch", () => {it("waits for reset to release the stable command inbox", async () => {const { HookNotFoundError } = await import("#compiled/@workflow/errors/index.js");resumeHookMock.mockResolvedValue(currentSessionHook("eve:token", "session-1"));- getHookByTokenMock.mockImplementation(async (token: string) => {- throw new HookNotFoundError(token);- });+ getHookByTokenMock+ .mockResolvedValueOnce(currentSessionHook(sessionInboxHookToken("eve:token"), "session-1"))+ .mockImplementation(async (token: string) => {+ throw new HookNotFoundError(token);+ });await expect(buildRuntime().dispatchContinuation({@@ -592,6 +596,7 @@ describe("createWorkflowRuntime#createSession", () => {"$eve.title": "hello","$eve.trigger": "http","$eve.type": "session",+ "$eve.version": resolveInstalledPackageInfo().version,},deploymentId: "dpl_current",},@@ -763,6 +768,7 @@ describe("createWorkflowRuntime#createSession", () => {"$eve.title": "hello","$eve.trigger": "http","$eve.type": "session",+ "$eve.version": resolveInstalledPackageInfo().version,},deploymentId: "dpl_current",},@@ -808,6 +814,7 @@ describe("createWorkflowRuntime#createSession", () => {"$eve.is_trace_content_visible": "false","$eve.trigger": "subagent","$eve.type": "subagent",+ "$eve.version": resolveInstalledPackageInfo().version,},deploymentId: "dpl_current",});@@ -833,6 +840,7 @@ describe("createWorkflowRuntime#createSession", () => {"$eve.title": "hello","$eve.trigger": "http","$eve.type": "session",+ "$eve.version": resolveInstalledPackageInfo().version,},deploymentId: "dpl_current",});diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.tsindex 64874c6c1..e36490eed 100644--- a/packages/eve/src/execution/workflow-runtime.ts+++ b/packages/eve/src/execution/workflow-runtime.ts@@ -23,6 +23,7 @@ import { serializeContext } from "#context/serialize.js";import {buildSessionAttributes,buildSubagentRootAttributes,+ EVE_VERSION_ATTRIBUTE,readParentLineage,} from "#execution/eve-workflow-attributes.js";import { resolveInstalledPackageInfo } from "#internal/application/package.js";@@ -66,7 +67,9 @@ import {AcceptedSessionIdentityError,resolveSessionInbox,resumeSessionInbox,+ SessionHandoffPendingError,} from "#execution/session-inbox/resume.js";+import { StrandedSessionOwnerError } from "#execution/session-inbox/owner.js";import type { SessionInboxAddress } from "#execution/session-inbox/address.js";import type { DynamicSubagentAgentConfig } from "#runtime/subagents/dynamic-agent-config.js";import { initializeSessionInstrumentation } from "#instrumentation/runtime.js";@@ -279,6 +282,10 @@ export async function startSessionOwnerStep(input: SessionOwnerStartInput): PromsessionWritable: getRun(anchorRunId).getWritable<Uint8Array>(),sessionId: anchorRunId,};+ // The successor is stamped with this eve version at start, because the+ // queue guard runs before it boots. Single-build Worlds share this version;+ // deployment-affine Worlds bypass the guard and the successor records its+ // own version at boot.await startWorkflowOnDeployment(workflowEntryReference,[workflowInput],@@ -298,19 +305,20 @@ async function dispatchWorkflowCommand<TCommand extends SessionCommand>(const resumed = await resumeSessionInbox(token, command);hook = { runId: resumed.ownerRunId, sessionId: await resumed.sessionId };} catch (error) {+ // Each entry point decides what a stranded owner means for its caller.+ if (error instanceof StrandedSessionOwnerError) throw error;+ // A send by session id to a session that still exists asks the caller to+ // retry rather than reporting the session gone.+ const sendBySessionId = command.kind === "send" && typeof token !== "string";+ const retryLater = { status: "session_not_active", retryable: true };+ // The address is owned, so it must never read as absent to a channel.+ if (error instanceof SessionHandoffPendingError) {+ if (sendBySessionId) return retryLater as SessionCommandResult<TCommand>;+ throw error;+ }if (isInactiveCommandTarget(error)) {- if (command.kind === "send" && typeof token !== "string") {- try {- const status = await getRun(token.sessionId).status;- if (status === "pending" || status === "running") {- return {- status: "session_not_active",- retryable: true,- } as SessionCommandResult<TCommand>;- }- } catch (statusError) {- if (!isInactiveCommandTarget(statusError)) throw statusError;- }+ if (sendBySessionId && (await isRunActive(token.sessionId))) {+ return retryLater as SessionCommandResult<TCommand>;}return inactiveCommandResult(command);}@@ -376,6 +384,16 @@ export async function requestWorkflowTurnCancellation(return await dispatchWorkflowCommand({ sessionId: input.sessionId }, command);}+async function isRunActive(runId: string): Promise<boolean> {+ try {+ const status = await getRun(runId).status;+ return status === "pending" || status === "running";+ } catch (error) {+ if (isInactiveCommandTarget(error)) return false;+ throw error;+ }+}+function isInactiveCommandTarget(error: unknown): boolean {if (error instanceof AcceptedSessionIdentityError) return false;if (HookNotFoundError.is(error)) return true;@@ -441,10 +459,10 @@ export async function startWorkflowOnCurrentDeployment<TArgs extends unknown[],}/**- * Starts on the deployment that accepted a delivery when one was stamped,- * otherwise stays on the deployment executing this call.+ * Starts a run on an exact deployment. Every run eve starts records the eve+ * version that started it: ingress and the stranded replay guard read it to+ * decide whether this build can still execute the run.*/-async function startWorkflowOnDeployment<TArgs extends unknown[], TResult>(workflow: WorkflowFunction<TArgs, TResult> | WorkflowMetadata,args: TArgs,@@ -455,7 +473,12 @@ async function startWorkflowOnDeployment<TArgs extends unknown[], TResult>(if (deploymentId.length === 0 || deploymentId === "latest") {throw new Error("Workflow starts require an exact deployment id.");}- return await start(workflow, args, { ...options, deploymentId });+ return await start(workflow, args, {+ ...options,+ allowReservedAttributes: true,+ attributes: { ...options?.attributes, [EVE_VERSION_ATTRIBUTE]: EVE_PACKAGE_INFO.version },+ deploymentId,+ });});}diff --git a/packages/eve/src/internal/application/compiled-artifacts.test.ts b/packages/eve/src/internal/application/compiled-artifacts.test.tsindex 6a05ddb61..d7027e774 100644--- a/packages/eve/src/internal/application/compiled-artifacts.test.ts+++ b/packages/eve/src/internal/application/compiled-artifacts.test.ts@@ -15,17 +15,14 @@ describe("createWorkflowWorldPluginSource", () => {expect(source).toContain('import "/app/.eve/compile/compiled-artifacts-bootstrap.mjs";');expect(source).toContain('import * as workflowWorldModule from "@acme/eve-world";');- expect(source).toContain("import { validateWorkflowWorld } from ");+ expect(source).toContain("import { installWorkflowWorld } from ");expect(source).toContain("const workflowWorld = await createWorldFromModule(workflowWorldModule);",);expect(source).toContain(- 'validateWorkflowWorld({ packageName: "@acme/eve-world", world: workflowWorld });',+ 'await installWorkflowWorld({ packageName: "@acme/eve-world", world: workflowWorld });',);expect(source).not.toContain("resolveLocalWorkflowWorldDataDirectory");- expect(source).toContain("setWorld(workflowWorld);");- expect(source).toContain("await getWorld();");- expect(source).toContain("await workflowWorld.start?.();");});it("configures the vendored local World with eve's app-local data resolver", () => {@@ -55,7 +52,7 @@ describe("createWorkflowWorldPluginSource", () => {expect(source).toMatch(/headers: \{ "User-Agent": "eve\/.+" \}/);expect(source).toContain("applyVercelWorkflowWorldDefaults(workflowWorld);");expect(source.indexOf("applyVercelWorkflowWorldDefaults(workflowWorld);")).toBeLessThan(- source.indexOf("setWorld(workflowWorld);"),+ source.indexOf("await installWorkflowWorld("),);});});@@ -68,9 +65,10 @@ describe("createDevelopmentWorkflowWorldPluginSource", () => {});expect(source).toContain("createDevelopmentWorkflowWorld");- expect(source).toContain("setWorld(createDevelopmentWorkflowWorld());");+ expect(source).toContain(+ "await installWorkflowWorld({ world: createDevelopmentWorkflowWorld() });",+ );expect(source).not.toContain("@workflow/world-local");- expect(source).not.toContain("workflowWorld.start");});it("keeps explicitly configured remote Worlds inside the worker", () => {@@ -80,6 +78,6 @@ describe("createDevelopmentWorkflowWorldPluginSource", () => {});expect(source).toContain('import * as workflowWorldModule from "@acme/eve-world";');- expect(source).toContain("await workflowWorld.start?.();");+ expect(source).toContain("await installWorkflowWorld({");});});diff --git a/packages/eve/src/internal/application/compiled-artifacts.ts b/packages/eve/src/internal/application/compiled-artifacts.tsindex 4621ea7ee..56548789b 100644--- a/packages/eve/src/internal/application/compiled-artifacts.ts+++ b/packages/eve/src/internal/application/compiled-artifacts.ts@@ -300,19 +300,21 @@ export function createCompiledArtifactsBootstrapSource(input: {].join("\n");}+function resolveInstallWorldImportSpecifier(): string {+ return resolvePackageSourceFilePath("src/execution/install-workflow-world.ts");+}+interface WorkflowWorldWiring {/** Import specifier for the `workflowWorldModule` namespace import. */readonly moduleImportSpecifier: string;/** Extra import lines the construction source depends on. */readonly extraImportLines: readonly string[];- /** Named imports pulled from the workflow core runtime. */- readonly runtimeImports: string;/** Statement that assigns `workflowWorld`. */readonly createWorldSource: string;}/**- * Per-world wiring for the generated workflow-world plugin. The four pieces+ * Per-world wiring for the generated workflow-world plugin. The pieces* co-vary and must stay together: a world constructed through an explicit* `createWorld(config)` call must not import `createWorldFromModule`, and* only the vendored local World needs the data-directory resolver import.@@ -339,7 +341,6 @@ const workflowWorld = await workflowWorldModule.createWorld({return {moduleImportSpecifier,extraImportLines: importLines.split("\n"),- runtimeImports: "getWorld, setWorld",createWorldSource,};}@@ -361,15 +362,16 @@ applyVercelWorkflowWorldDefaults(workflowWorld);`.trimStart();extraImportLines: [`import { applyVercelWorkflowWorldDefaults } from ${defaultsImportSpecifier};`,],- runtimeImports: "getWorld, setWorld",createWorldSource,};}+ const workflowRuntimeImportSpecifier = stringifyEsmImportSpecifier(+ resolvePackageCompiledFilePath("src/compiled/@workflow/core/runtime.js"),+ );return {moduleImportSpecifier: packageName,- extraImportLines: [],- runtimeImports: "createWorldFromModule, getWorld, setWorld",+ extraImportLines: [`import { createWorldFromModule } from ${workflowRuntimeImportSpecifier};`],createWorldSource: "const workflowWorld = await createWorldFromModule(workflowWorldModule);",};}@@ -382,26 +384,16 @@ export function createWorkflowWorldPluginSource(input: {const targetWorld = input.configuredWorld ?? input.defaultWorld;const packageName = resolveWorkflowWorldImport(targetWorld);const wiring = resolveWorkflowWorldWiring(packageName);- const workflowRuntimeImportSpecifier = resolvePackageCompiledFilePath(- "src/compiled/@workflow/core/runtime.js",- );- const workflowWorldValidationImportSpecifier = resolvePackageSourceFilePath(- "src/internal/workflow/validate-world.ts",- );return ["// Generated by eve. Do not edit by hand.",`import ${stringifyEsmImportSpecifier(input.compiledArtifactsBootstrapPath)};`,`import * as workflowWorldModule from ${stringifyEsmImportSpecifier(wiring.moduleImportSpecifier)};`,...wiring.extraImportLines,- `import { ${wiring.runtimeImports} } from ${stringifyEsmImportSpecifier(workflowRuntimeImportSpecifier)};`,- `import { validateWorkflowWorld } from ${stringifyEsmImportSpecifier(workflowWorldValidationImportSpecifier)};`,+ `import { installWorkflowWorld } from ${stringifyEsmImportSpecifier(resolveInstallWorldImportSpecifier())};`,"",wiring.createWorldSource,- `validateWorkflowWorld({ packageName: ${JSON.stringify(input.configuredWorld)}, world: workflowWorld });`,- "setWorld(workflowWorld);",- "await getWorld();",- "await workflowWorld.start?.();",+ `await installWorkflowWorld({ packageName: ${JSON.stringify(input.configuredWorld)}, world: workflowWorld });`,"","export default function installWorkflowWorldPlugin() {}","",@@ -427,20 +419,16 @@ export function createDevelopmentWorkflowWorldPluginSource(input: {defaultWorld: "local",});}- const workflowRuntimeImportSpecifier = resolvePackageCompiledFilePath(- "src/compiled/@workflow/core/runtime.js",- );const developmentWorldImportSpecifier = resolvePackageSourceFilePath("src/internal/workflow/development-world-client.ts",);return ["// Generated by eve. Do not edit by hand.",`import ${stringifyEsmImportSpecifier(input.compiledArtifactsBootstrapPath)};`,- `import { getWorld, setWorld } from ${stringifyEsmImportSpecifier(workflowRuntimeImportSpecifier)};`,`import { createDevelopmentWorkflowWorld } from ${stringifyEsmImportSpecifier(developmentWorldImportSpecifier)};`,+ `import { installWorkflowWorld } from ${stringifyEsmImportSpecifier(resolveInstallWorldImportSpecifier())};`,"",- "setWorld(createDevelopmentWorkflowWorld());",- "await getWorld();",+ "await installWorkflowWorld({ world: createDevelopmentWorkflowWorld() });","","export default function installDevelopmentWorkflowWorldPlugin() {}","",diff --git a/packages/eve/src/internal/testing/app-harness.integration.test.ts b/packages/eve/src/internal/testing/app-harness.integration.test.tsindex 07c418541..210b7ae02 100644--- a/packages/eve/src/internal/testing/app-harness.integration.test.ts+++ b/packages/eve/src/internal/testing/app-harness.integration.test.ts@@ -1,5 +1,5 @@+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";import { describe, expect, it } from "vitest";-import { start } from "#internal/workflow/runtime.js";import { workflowEntry } from "#execution/session/entry.js";import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";@@ -48,7 +48,7 @@ describe("AppHarness", () => {const outputs = await Promise.all([runtimeA.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",@@ -62,7 +62,7 @@ describe("AppHarness", () => {return await readFirstTurnReply(run);}),runtimeB.run(async () => {- const run = await start(workflowEntry, [+ const run = await startSessionOwner(workflowEntry, [{kind: "initial",ownerDeploymentId: "dpl_inline",diff --git a/packages/eve/src/internal/testing/session-inbox-workflow.ts b/packages/eve/src/internal/testing/session-inbox-workflow.tsindex a488167c9..569204f7a 100644--- a/packages/eve/src/internal/testing/session-inbox-workflow.ts+++ b/packages/eve/src/internal/testing/session-inbox-workflow.ts@@ -1,18 +1,20 @@-import { getWorkflowMetadata } from "#compiled/@workflow/core/index.js";+import { createHook, getWorkflowMetadata } from "#compiled/@workflow/core/index.js";import { createSessionInbox } from "#execution/session-inbox/inbox.js";import { sessionCommandHookToken } from "#execution/session-inbox/address.js";export async function sessionCommandInboxWorkflow(input: {+ /** Session whose stable inbox this owner holds; a handoff successor names its anchor. */+ readonly sessionId?: string;readonly token: string;}): Promise<void> {"use workflow";- const { workflowRunId } = getWorkflowMetadata();- const inbox = createSessionInbox(workflowRunId);+ const sessionId = input.sessionId ?? getWorkflowMetadata().workflowRunId;+ const inbox = createSessionInbox(sessionId);try {- await inbox.claimSessionHook(sessionCommandHookToken(workflowRunId));+ await inbox.claimSessionHook(sessionCommandHookToken(sessionId));await inbox.claimSessionHook(input.token);while (true) {const payload = await inbox.next();@@ -22,3 +24,11 @@ export async function sessionCommandInboxWorkflow(input: {await inbox.dispose();}}++/** Parks like a session anchor after a handoff: it holds no session address of its own. */+export async function parkedAnchorWorkflow(input: { readonly token: string }): Promise<void> {+ "use workflow";++ using gate = createHook<void>({ token: input.token });+ await gate;+}diff --git a/packages/eve/src/internal/testing/workflow-test-helpers.ts b/packages/eve/src/internal/testing/workflow-test-helpers.tsindex 8b050ace7..6b3ddc1a9 100644--- a/packages/eve/src/internal/testing/workflow-test-helpers.ts+++ b/packages/eve/src/internal/testing/workflow-test-helpers.ts@@ -1,4 +1,23 @@-import { getWorld } from "#internal/workflow/runtime.js";+import { EVE_VERSION_ATTRIBUTE } from "#execution/eve-workflow-attributes.js";+import { resolveInstalledPackageInfo } from "#internal/application/package.js";+import { getWorld, start, type WorkflowFunction } from "#internal/workflow/runtime.js";++/**+ * Starts a session owner run stamped with the running eve version, as+ * `createSession` does. Ingress on single-deployment Worlds treats an owner+ * without the stamp as stranded, so a bare `start` would never accept input.+ */+export async function startSessionOwner<TArgs extends unknown[], TResult>(+ workflow: WorkflowFunction<TArgs, TResult>,+ args: TArgs,+) {+ return await start(workflow, args, {+ allowReservedAttributes: true,+ attributes: {+ [EVE_VERSION_ATTRIBUTE]: resolveInstalledPackageInfo().version,+ },+ });+}interface WorkflowRunLike {readonly runId: string;diff --git a/packages/eve/src/internal/workflow/development-run-unavailable-error.ts b/packages/eve/src/internal/workflow/development-run-unavailable-error.tsnew file mode 100644index 000000000..da33fe707--- /dev/null+++ b/packages/eve/src/internal/workflow/development-run-unavailable-error.ts@@ -0,0 +1,29 @@+const NAME = "DevelopmentRunUnavailableError";++/**+ * Raised by the `eve dev` World when a caller looks up a hook whose run+ * belongs to a generation this dev server will not execute. It crosses the+ * parent/worker boundary as a plain error, so identity is its name and its+ * enumerable fields rather than the class.+ */+export class DevelopmentRunUnavailableError extends Error {+ readonly availability: "dormant" | "ineligible";+ readonly runId: string;++ constructor(input: { readonly availability: "dormant" | "ineligible"; readonly runId: string }) {+ super(+ "Local Workflow run was not resumed. Start a new conversation, or restart eve dev with --resume to attempt recovery.",+ );+ this.name = NAME;+ this.availability = input.availability;+ this.runId = input.runId;+ }++ static is(value: unknown): value is DevelopmentRunUnavailableError {+ return (+ value instanceof Error &&+ value.name === NAME &&+ typeof (value as { runId?: unknown }).runId === "string"+ );+ }+}diff --git a/packages/eve/src/internal/workflow/development-world-server.integration.test.ts b/packages/eve/src/internal/workflow/development-world-server.integration.test.tsindex 4ceced177..c4291c80a 100644--- a/packages/eve/src/internal/workflow/development-world-server.integration.test.ts+++ b/packages/eve/src/internal/workflow/development-world-server.integration.test.ts@@ -1,4 +1,5 @@import { access, mkdir, rm, writeFile } from "node:fs/promises";+import { DevelopmentRunUnavailableError } from "#internal/workflow/development-run-unavailable-error.js";import { join } from "node:path";import { afterEach, describe, expect, it, vi } from "vitest";@@ -404,9 +405,17 @@ describe("parent development Workflow World", () => {await second.start();expect(startupFetch).not.toHaveBeenCalled();startupFetch.mockRestore();- await expect(createDevelopmentWorkflowWorld().hooks.getByToken(token)).rejects.toThrow(- "Local Workflow run was not resumed",- );+ // Ingress reports the session stranded from this error, so its identity+ // must survive the worker boundary.+ const refusal = await createDevelopmentWorkflowWorld()+ .hooks.getByToken(token)+ .catch((error: unknown) => error);+ expect(DevelopmentRunUnavailableError.is(refusal)).toBe(true);+ expect(refusal).toMatchObject({+ availability: "dormant",+ message: expect.stringContaining("Local Workflow run was not resumed"),+ runId,+ });for (const message of [{ runId },{ workflowRunId: runId },diff --git a/packages/eve/src/internal/workflow/development-world-server.ts b/packages/eve/src/internal/workflow/development-world-server.tsindex fac0c9d73..1cb0da5a6 100644--- a/packages/eve/src/internal/workflow/development-world-server.ts+++ b/packages/eve/src/internal/workflow/development-world-server.ts@@ -5,6 +5,7 @@ import {import { listDevelopmentGenerationIds } from "#internal/nitro/dev-runtime-generation-metadata.js";import { cancelExpiredDevelopmentRun } from "#internal/workflow/cancel-expired-development-run.js";+import { DevelopmentRunUnavailableError } from "#internal/workflow/development-run-unavailable-error.js";import type { ValidQueueName, World } from "#compiled/@workflow/world/index.js";import { createWorld } from "#compiled/@workflow/world-local/index.js";import { deriveEveWorkflowQueuePrefix } from "#internal/workflow/queue-namespace.js";@@ -297,9 +298,10 @@ class LocalParentDevelopmentWorkflowWorld implements ParentDevelopmentWorkflowWoconst run = await this.#world.runs.get(hook.runId, { resolveData: "none" });const availability = await this.#generationAvailability(run.deploymentId);if (availability.kind === "dormant" || availability.kind === "ineligible") {- throw new Error(- "Local Workflow run was not resumed. Start a new conversation, or restart eve dev with --resume to attempt recovery.",- );+ throw new DevelopmentRunUnavailableError({+ availability: availability.kind,+ runId: hook.runId,+ });}return hook;}diff --git a/packages/eve/src/runtime/connections/callback-route.test.ts b/packages/eve/src/runtime/connections/callback-route.test.tsindex ec3a169d5..466074bf3 100644--- a/packages/eve/src/runtime/connections/callback-route.test.ts+++ b/packages/eve/src/runtime/connections/callback-route.test.ts@@ -7,6 +7,9 @@ import { handleConnectionCallbackRequest } from "#execution/connections/callbackconst resumeHookMock = vi.fn();vi.mock("#compiled/@workflow/core/runtime.js", () => ({+ getHookByToken: async (token: string) => ({ runId: "owner", specVersion: 6, token }),+ // Vercel-shaped: owners run on their own deployment, so ingress resumes by token.+ getWorld: async () => ({ capabilities: { deploymentAffinity: true } }),resumeHook: (token: string, payload: unknown) => resumeHookMock(token, payload),}));diff --git a/packages/eve/src/subagents/callback-route.ts b/packages/eve/src/subagents/callback-route.tsindex 775c744d9..a82118628 100644--- a/packages/eve/src/subagents/callback-route.ts+++ b/packages/eve/src/subagents/callback-route.ts@@ -1,5 +1,5 @@import { renameLegacyTaskCallback } from "#execution/legacy-remote-agent/protocol.js";-import { resumeHook } from "#internal/workflow/runtime.js";+import { resumeRunnableHook } from "#execution/session-inbox/owner.js";import { z } from "#compiled/zod/index.js";import type { RouteContext } from "#public/definitions/channel.js";import type { RuntimeSubagentChildResult } from "#shared/action-types.js";@@ -182,7 +182,7 @@ export async function handleSessionCallbackRequest(if (result instanceof Response) return result;try {- await resumeHook(+ await resumeRunnableHook(token,forwarded?.success ? forwarded.data : { kind: "runtime-action-result", results: [result] },);