@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.10

package/src/adapter/cloudflare/subagent/runner.ts

@@ -1,20 +1,24 @@
 import {
-  runAgentLoopContinue,
-  convertToLlm,
-  type AgentMessage,
-  type AgentEvent,
-  type AgentTool,
+  type AgentHarnessTool,
+  type HarnessEvent,
+  type Session,
   type StreamFn,
 } from "@earendil-works/pi-agent-core";
-import type {
-  Api,
-  AssistantMessage,
-  Model,
-} from "@earendil-works/pi-ai";
+import {
+  awaitWithContext,
+  BACKGROUND_CONTEXT,
+  withAbortSignal,
+} from "@earendil-works/pi-agent-core/harness/context";
+import type { Api, AssistantMessage, Model, Models } from "@earendil-works/pi-ai";
 import { z } from "zod";
 import { assembleSubagentPrompt } from "../../../lib/prompt";
-import type { AgentType } from "../../../layers/orchestration/subagents/agent-types/contract";
-import { structuredOutputStream } from "../../../pi/runtime-adapter/models";
+import type { AgentType } from "../../../tools/subagent/types/contract";
+import { structuredOutputStream } from "../../../models";
+import {
+  openSessionHarness,
+  type SessionHarness,
+  type SessionHarnessOptions,
+} from "../../../harness";
 
 const RECURSIVE_TOOLS = new Set([
   "run_agent",
@@ -30,17 +34,21 @@ export interface CloudflareSubAgentRun {
   input: unknown;
   model: Model<Api>;
   streamFn: StreamFn;
-  tools: AgentTool[];
+  models?: Models;
+  /** A fresh Pi Session facade is required after each Harness release. */
+  openSession(): Session | Promise<Session>;
+  operationId?: string;
+  /** Tools compiled by the package's single Harness adapter. */
+  tools?: AgentHarnessTool<object | undefined>[];
   signal?: AbortSignal;
   timeoutMs?: number;
-  onEvent?: (event: AgentEvent, signal: AbortSignal) => void | Promise<void>;
+  /** Native operation events for projections that must survive model retries. */
+  onEvent?: (event: HarnessEvent, signal: AbortSignal) => void | Promise<void>;
 }
 
 function textOf(message: AssistantMessage): string {
-  return message.content
-    .flatMap((part) => (part.type === "text" ? [part.text] : []))
-    .join("")
-    .trim();
+  return message.content.flatMap((part) => part.type === "text" ? [part.text] : [])
+    .join("").trim();
 }
 
 function structuredText(text: string): string {
@@ -49,30 +57,22 @@ function structuredText(text: string): string {
 
 function toolErrorText(result: unknown): string {
   if (
-    typeof result === "object" &&
-    result !== null &&
+    typeof result === "object" && result !== null &&
     Array.isArray((result as { content?: unknown }).content)
   ) {
-    const text = (result as { content: unknown[] }).content
-      .flatMap((part) =>
-        typeof part === "object" &&
-        part !== null &&
+    const text = (result as { content: unknown[] }).content.flatMap((part) =>
+      typeof part === "object" && part !== null &&
         (part as { type?: unknown }).type === "text" &&
         typeof (part as { text?: unknown }).text === "string"
-          ? [(part as { text: string }).text]
-          : [],
-      )
-      .join("")
-      .trim();
+        ? [(part as { text: string }).text]
+        : []
+    ).join("").trim();
     if (text) return text;
   }
   return "tool execution failed";
 }
 
-function taskPrompt(
-  input: unknown,
-  outputSchema?: Record<string, unknown>,
-): string {
+function taskPrompt(input: unknown, outputSchema?: Record<string, unknown>): string {
   return [
     "Complete this bounded task.",
     `Input:\n${JSON.stringify(input)}`,
@@ -82,112 +82,166 @@ function taskPrompt(
   ].join("\n\n");
 }
 
-export async function runCloudflareSubAgent(
-  run: CloudflareSubAgentRun,
-): Promise<unknown> {
+function harnessModels(run: CloudflareSubAgentRun, streamFn: StreamFn): Models {
+  const base = run.models;
+  return new Proxy(base ?? {} as Models, {
+    get(target, property) {
+      if (property === "getModel") {
+        return (provider: string, modelId: string) =>
+          provider === run.model.provider && modelId === run.model.id
+            ? run.model
+            : base?.getModel(provider, modelId);
+      }
+      if (property === "streamSimple") return streamFn;
+      const value = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
+/** Execute one bounded mechanism SubAgent through the official AgentHarness. */
+export async function runCloudflareSubAgent(run: CloudflareSubAgentRun): Promise<unknown> {
   const input = run.type.inputSchema.safeParse(run.input);
   if (!input.success) {
-    throw new Error(
-      `SubAgent input failed schema validation: ${input.error.message}`,
-    );
+    throw new Error(`SubAgent input failed schema validation: ${input.error.message}`);
   }
-  for (const tool of run.tools) {
+  const declaredTools = run.tools ?? [];
+  for (const tool of declaredTools) {
     if (RECURSIVE_TOOLS.has(tool.name)) {
       throw new Error(`SubAgent cannot use recursive tool "${tool.name}"`);
     }
   }
   if (run.signal?.aborted) throw new Error("SubAgent run aborted");
-  const { $schema: _, ...outputSchema } = z.toJSONSchema(run.type.outputSchema);
-  const constrainedStream = structuredOutputStream(
-    run.streamFn,
-    run.model,
-    outputSchema,
-  );
 
-  // 这里没有审批闸,也装不了:到这一步工具已经被 compilePiTools 编译成 AgentTool,
-  // requiredExecutionLevel 只挂在编译前的 PiToolCandidate 上,这里读不到。「子 agent 不许挂需审批的工具」
-  // 这条不变量由装配处 createCloudflareSubAgentTools 的启动期断言强制执行。
+  const { $schema: _, ...outputSchema } = z.toJSONSchema(run.type.outputSchema);
+  const structuredStream = structuredOutputStream(run.streamFn, run.model, outputSchema);
+  const streamFn = structuredStream ?? run.streamFn;
+  const operationId = run.operationId ?? crypto.randomUUID();
   const controller = new AbortController();
-  const signal = run.signal ? AbortSignal.any([run.signal, controller.signal]) : controller.signal;
-  const messages: AgentMessage[] = [{
-    role: "user",
-    content: taskPrompt(input.data, constrainedStream ? undefined : outputSchema),
-    timestamp: Date.now(),
-  }];
+  const signal = run.signal
+    ? AbortSignal.any([run.signal, controller.signal])
+    : controller.signal;
+  const context = withAbortSignal(signal, BACKGROUND_CONTEXT);
+  const options = {
+    models: harnessModels(run, streamFn),
+    model: run.model,
+    thinkingLevel: run.type.model === "main" ? "medium" : "off",
+    systemPrompt: assembleSubagentPrompt(run.type.persona),
+    tools: declaredTools,
+    streamOptions: { maxRetries: 0 },
+    toolExecution: "parallel",
+    compaction: { enabled: false, reserveTokens: 1, keepRecentTokens: 1 },
+  } satisfies Omit<SessionHarnessOptions<object | undefined>, "session">;
+  let runtime: SessionHarness<object | undefined> | undefined;
   let toolFailure: { name: string; error: string } | undefined;
-  const emit = async (event: AgentEvent) => {
-    if (event.type === "tool_execution_end" && event.isError) {
-      toolFailure ??= {
-        name: event.toolName,
-        error: toolErrorText(event.result),
-      };
-    }
-    await run.onEvent?.(event, signal);
-  };
 
   let timedOut = false;
   const timeout = setTimeout(() => {
     timedOut = true;
-    controller.abort();
+    controller.abort(new Error("SubAgent run timed out"));
   }, run.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-
-  let newMessages: AgentMessage[];
   try {
-    newMessages = await runAgentLoopContinue(
-      { systemPrompt: assembleSubagentPrompt(run.type.persona), messages, tools: [...run.tools] },
-      { model: run.model, reasoning: run.type.model === "main" ? "medium" : undefined, toolExecution: "parallel", convertToLlm },
-      emit,
-      signal,
-      constrainedStream ?? run.streamFn,
-    );
-  } finally {
-    clearTimeout(timeout);
-  }
-
-  if (timedOut) throw new Error("SubAgent run timed out");
-  if (run.signal?.aborted) throw new Error("SubAgent run aborted");
-
-  const assistant = newMessages
-    .slice()
-    .reverse()
-    .find(
-      (message): message is AssistantMessage => message.role === "assistant",
-    );
-  if (!assistant) throw new Error("SubAgent produced no structured output");
-  if (assistant.stopReason === "deferred") throw new Error("SubAgent deferred responses are not supported");
-  if (assistant.stopReason === "aborted") {
-    throw new Error("SubAgent run aborted");
-  }
-  if (assistant.stopReason === "error") {
-    if (toolFailure) {
+    let settled: Awaited<ReturnType<SessionHarness<object | undefined>["run"]>>;
+    while (true) {
+      signal.throwIfAborted();
+      if (!runtime) {
+        runtime = await openSessionHarness({
+          ...options,
+          session: await run.openSession(),
+        }, context);
+        if (runtime.openOperation && runtime.openOperation.operationId !== operationId) {
+          throw new Error("SubAgent Session has an unrelated open operation");
+        }
+        const harness = runtime.harness;
+        const onEvent = run.onEvent;
+        if (onEvent) {
+          for (const type of ["run_start", "run_resume", "run_end", "turn_start", "message_start", "message_update", "message_end", "tool_start", "tool_update", "tool_end"] as const) {
+            harness.events.on(type, (event) => onEvent(event, signal));
+          }
+        }
+        harness.events.on("tool_end", (event) => {
+          if (event.isError) {
+            toolFailure ??= { name: event.toolName, error: toolErrorText(event.result) };
+          }
+        });
+      }
+      const result = await runtime.run(
+        !runtime.openOperation
+          ? {
+              kind: "prompt",
+              operationId,
+              prompt: taskPrompt(input.data, structuredStream ? undefined : outputSchema),
+            }
+          : undefined,
+        context,
+        { waitForRetry: true, pollDeferred: true },
+      );
+      if (result.kind === "released") {
+        await runtime.close(BACKGROUND_CONTEXT);
+        runtime = undefined;
+        continue;
+      }
+      if (result.kind === "waiting") {
+        const delay = result.reason === "deferred"
+          ? result.deferred.pollAfterMs ?? 1_000
+          : Math.max(0, result.notBefore - Date.now());
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        try {
+          await awaitWithContext(new Promise<void>((resolve) => {
+            timer = setTimeout(resolve, delay);
+          }), context);
+        } finally {
+          clearTimeout(timer);
+        }
+        continue;
+      }
+      settled = result;
+      break;
+    }
+    if (timedOut) throw new Error("SubAgent run timed out");
+    if (run.signal?.aborted || settled.outcome.status === "aborted") {
+      throw new Error("SubAgent run aborted");
+    }
+    if (settled.outcome.status === "failed") {
       throw new Error(
-        `SubAgent tool "${toolFailure.name}" failed: ${toolFailure.error}`,
+        toolFailure
+          ? `SubAgent tool "${toolFailure.name}" failed: ${toolFailure.error}`
+          : `SubAgent model failed: ${settled.outcome.error?.message ?? "unknown provider error"}`,
       );
     }
-    throw new Error(
-      `SubAgent model failed: ${assistant.errorMessage ?? "unknown provider error"}`,
-    );
-  }
-  if (toolFailure) {
-    throw new Error(
-      `SubAgent tool "${toolFailure.name}" failed: ${toolFailure.error}`,
-    );
-  }
-
-  const text = textOf(assistant);
-  if (!text) throw new Error("SubAgent produced no structured output");
-
-  let output: unknown;
-  try {
-    output = JSON.parse(structuredText(text));
-  } catch {
-    throw new Error("SubAgent output is not valid JSON");
-  }
-  const result = run.type.outputSchema.safeParse(output);
-  if (!result.success) {
-    throw new Error(
-      `SubAgent output failed schema validation: ${result.error.message}`,
-    );
+    if (toolFailure) {
+      throw new Error(`SubAgent tool "${toolFailure.name}" failed: ${toolFailure.error}`);
+    }
+    const assistant = (await runtime.lane.findEntries(
+      { type: "message", order: "newestFirst" },
+      context,
+    )).find((entry) => entry.type === "message" && entry.message.role === "assistant");
+    if (!assistant || assistant.type !== "message" || assistant.message.role !== "assistant") {
+      throw new Error("SubAgent produced no structured output");
+    }
+    const text = textOf(assistant.message);
+    if (!text) throw new Error("SubAgent produced no structured output");
+    let output: unknown;
+    try {
+      output = JSON.parse(structuredText(text));
+    } catch {
+      throw new Error("SubAgent output is not valid JSON");
+    }
+    const result = run.type.outputSchema.safeParse(output);
+    if (!result.success) {
+      throw new Error(`SubAgent output failed schema validation: ${result.error.message}`);
+    }
+    return result.data;
+  } catch (error) {
+    if (timedOut) throw new Error("SubAgent run timed out");
+    if (run.signal?.aborted) throw new Error("SubAgent run aborted");
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+    if (signal.aborted && runtime?.openOperation) {
+      await runtime.requestAbort(operationId, BACKGROUND_CONTEXT).catch(() => undefined);
+      await runtime.run(undefined, BACKGROUND_CONTEXT).catch(() => undefined);
+    }
+    await runtime?.close(BACKGROUND_CONTEXT).catch(() => undefined);
   }
-  return result.data;
 }

package/src/adapter/cloudflare/subagent/tools.ts

@@ -9,18 +9,19 @@ import {
 } from "@cloudflare/shell";
 import { stateToolsFromBackend } from "@cloudflare/shell/workers";
 import type {
+  AgentHarnessTool,
   AgentTool,
   AgentToolResult,
 } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
-import type { WorkspacePort } from "../../../kernel/bindings";
-import type { AgentType } from "../../../layers/orchestration/subagents/agent-types/contract";
+import type { WorkspacePort } from "../../../config/ports";
+import type { AgentType } from "../../../tools/subagent/types/contract";
 import {
-  compilePiTools,
-  type CompilePiToolsOptions,
+  compileHarnessTools,
+  type CompileHarnessToolsOptions,
   type PiToolCandidate,
-} from "../../../pi/tool";
-import { workspacePiToolCandidates } from "../../../pi/tool/workspace-sandbox";
+} from "../../../tools";
+import { workspacePiToolCandidates } from "../../../tools/workspace";
 
 const READONLY_WORKSPACE_TOOLS = new Set([
   "read",
@@ -183,14 +184,12 @@ function fetchCandidate(options: {
 }
 
 /**
- * SubAgent 链路上没有审批通道:主链的审批闸在 Runtime 的 execution 适配器里
- * (requiresPiToolApproval → park → 等用户裁决),而子 Agent 直接调用 `runAgentLoopContinue`
- * 直接跑,parked 的请求没有任何界面能落地、也没有人能批。
+ * SubAgent 链路上没有人工审批通道，因此只允许 safe Tool 进入它的 Harness。
  *
  * 只有 `safe` Tool 可以挂到这条没有审批通道的链路；更高档位必须在装配时失败关闭。
  *
  * 所以把这个不变量钉在装配处:要的是「装不上」,不是「跑起来才炸」。而且这里是唯一还能
- * 检查的位置 —— 档位挂在 PiToolCandidate 上,compilePiTools 之后只剩 AgentTool。
+ * 检查必须在 Candidate 被编译为 AgentHarnessTool 之前完成。
  */
 function assertSafeExecutionLevel(
   candidates: readonly PiToolCandidate[],
@@ -221,8 +220,8 @@ export function createCloudflareSubAgentTools(options: {
   workspace: WorkspacePort;
   loader: WorkerLoader;
   outbound: Fetcher;
-  settle: CompilePiToolsOptions["settle"];
-}): AgentTool[] {
+  settle: NonNullable<CompileHarnessToolsOptions["onSettlement"]>;
+}): AgentHarnessTool<object | undefined>[] {
   const workspace = workspacePiToolCandidates(options.workspace).filter(
     (candidate) =>
       options.profile === "capable" ||
@@ -245,7 +244,7 @@ export function createCloudflareSubAgentTools(options: {
   );
   assertSafeExecutionLevel(mounted);
 
-  return compilePiTools(mounted, {
-    settle: options.settle,
+  return compileHarnessTools(mounted, {
+    onSettlement: options.settle,
   });
 }

package/src/adapter/cloudflare/universal-agent/preparation.ts

@@ -8,17 +8,17 @@ import type {
   RuntimePlatformPort,
   RuntimeSubagentPort,
   WorkspacePort,
-} from "../../../kernel/bindings";
-import { decodeSubagentCompletion } from "../../../kernel/subagent-runtime";
-import type { RuntimeDegradation } from "../../../kernel/degradation";
-import type { RuntimeMemoryProfile } from "../../../kernel/profile";
-import { AGENT_TYPES } from "../../../layers/orchestration/subagents/agent-types/registry";
-import type { RuntimeAgentConfigContext } from "../../../runtime-agent-context";
+} from "../../../config/ports";
+import { decodeSubagentCompletion } from "../../../tools/subagent/runtime";
+import type { RuntimeDegradation } from "../../../config/degradation";
+import type { RuntimeMemoryProfile } from "../../../config/profile";
+import { AGENT_TYPES } from "../../../tools/subagent/types/registry";
+import type { RuntimeAgentConfigContext } from "../../../config/agent-context";
 import {
   createBrowserExecutionFactory,
   createWorkspaceCodeExecutionFactory,
   type RuntimeBrowserBinding,
-} from "../../../pi/tool/core-host";
+} from "../../../tools/codemode/adapter";
 import {
   createCloudflareSandboxAdapter,
   type SandboxAdmission,

package/src/adapter/cloudflare/universal-agent/tools.ts

@@ -4,18 +4,16 @@ import type {
   RuntimeSchedulePort,
   RuntimeSubagentPort,
   WorkspacePort,
-} from "../../../kernel/bindings";
-import type { RuntimeDegradation } from "../../../kernel/degradation";
-import type { RuntimeMemoryProfile } from "../../../kernel/profile";
-import type { WorkspaceRevisionRestorePort } from "../../../workspace-versioning";
-import { schedulePiToolCandidates } from "../../../pi/tool/schedule";
-import { workspaceRevisionPiToolCandidate } from "../../../pi/tool/workspace-revision";
-import {
-  sandboxPiToolCandidates,
-} from "../../../pi/tool/workspace-sandbox";
-import type { RuntimeCodeExecutionFactory } from "../../../kernel/bindings";
-import type { ToolAssemblyResult } from "../../../runtime-definition";
-import type { PiToolCandidate } from "../../../pi/tool/compiler";
+} from "../../../config/ports";
+import type { RuntimeDegradation } from "../../../config/degradation";
+import type { RuntimeMemoryProfile } from "../../../config/profile";
+import type { WorkspaceRevisionRestorePort } from "../../../tools/workspace/versioning";
+import { schedulePiToolCandidates } from "../../../tools/schedule";
+import { workspaceRevisionPiToolCandidate } from "../../../tools/workspace/revision";
+import { sandboxPiToolCandidates } from "../../../tools/sandbox";
+import type { RuntimeCodeExecutionFactory } from "../../../config/ports";
+import type { ToolAssemblyResult } from "../../../config/definition";
+import type { PiToolCandidate } from "../../../tools/runtime/contracts";
 
 export function assembleUniversalAgentTools(options: {
   hostTools?: readonly PiToolCandidate[];

package/src/adapter/cloudflare/workspace/git-fs.ts

@@ -27,7 +27,7 @@ import type {
 import type {
   WorkspaceFileInfo,
   WorkspacePort,
-} from "../../../kernel/bindings";
+} from "../../../config/ports";
 
 const PAGE_SIZE = 256;
 

package/src/adapter/cloudflare/workspace/scoped-workspace.ts

@@ -5,7 +5,7 @@ import type {
   WorkspaceStreamWriteOptions,
   WorkspaceQuota,
   WorkspaceUsage,
-} from "../../../kernel/bindings";
+} from "../../../config/ports";
 import type {
   WorkspaceConditionalWriteResult,
   WorkspaceFileVersion,

package/src/adapter/cloudflare/workspace/version-control.ts

@@ -1,11 +1,11 @@
 import * as git from "isomorphic-git";
-import type { WorkspacePort } from "../../../kernel/bindings";
+import type { WorkspacePort } from "../../../config/ports";
 import {
   WorkspaceRevisionNotFoundError,
   type WorkspaceRevision,
   type WorkspaceRevisionManifest,
   type WorkspaceVersionPort,
-} from "../../../workspace-versioning";
+} from "../../../tools/workspace/versioning";
 import { createWorkspaceGitFs } from "./git-fs";
 
 const PAGE_SIZE = 256;

package/src/config/activation.ts

@@ -0,0 +1,140 @@
+import { connectConfiguredMcpServers } from "../lib/mcp";
+import { sha256Hex } from "../lib/artifacts";
+import type { RuntimeCandidate, RuntimeSnapshot } from "./assembler";
+import type { HarnessRuntimeConfig } from "./harness-runtime";
+import type { PreparedPiRuntime, PreparePiRuntimeOptions } from "./pinning";
+import type { RuntimeGatewaySession, RuntimeSubmissionAdmissionHook } from "./ports";
+import { withRuntimeLoadTimeout } from "./runtime-load";
+import type { RuntimeLoadPhase } from "../conversation/state";
+
+export interface ActiveRuntime {
+  readonly snapshot: RuntimeSnapshot;
+  readonly revision: string;
+  readonly runtimeKey: string;
+  readonly pi: PreparedPiRuntime;
+  readonly gatewaySession?: RuntimeGatewaySession;
+  readonly admission?: RuntimeSubmissionAdmissionHook;
+}
+
+async function closeRuntimeGatewaySession(
+  session: RuntimeGatewaySession | undefined,
+  step: string,
+): Promise<void> {
+  if (!session) return;
+  await withRuntimeLoadTimeout(step, () => session.close()).catch(
+    () => undefined,
+  );
+}
+
+interface RuntimeActivationOptions {
+  readonly previous?: ActiveRuntime;
+  readonly pi: HarnessRuntimeConfig;
+  readonly mcpHost: PreparePiRuntimeOptions["mcpHost"] & Parameters<typeof connectConfiguredMcpServers>[0];
+  readonly sessionId: string;
+  readonly createExtensionHostBinding: PreparePiRuntimeOptions["createExtensionHostBinding"];
+  advance(phase: RuntimeLoadPhase): void;
+  isExecuting(): boolean;
+  commit(runtime: ActiveRuntime): void;
+}
+
+/** Prepare optional connections and atomically install a validated Runtime candidate. */
+export async function activateRuntimeCandidate(
+  candidate: RuntimeCandidate,
+  options: RuntimeActivationOptions,
+): Promise<void> {
+  const previous = options.previous;
+  const candidateSnapshot = candidate.snapshot;
+  options.advance("assembly");
+  options.advance("mcp");
+  await connectConfiguredMcpServers(
+    options.mcpHost,
+    candidateSnapshot.profile.mcpServers.filter(server => !server.hostManaged),
+  );
+  const gatewayDegradations = [];
+  let gatewaySession: RuntimeGatewaySession | undefined;
+  if (candidateSnapshot.bindings.gateway) {
+    try {
+      gatewaySession = await withRuntimeLoadTimeout(
+        "gateway.open",
+        () => candidateSnapshot.bindings.gateway!.open(
+          `${options.sessionId}:${crypto.randomUUID()}`,
+        ),
+        {
+          onLateResult: (session) =>
+            closeRuntimeGatewaySession(session, "gateway.close.late"),
+        },
+      );
+    } catch {
+      gatewayDegradations.push({
+        capability: "connector" as const,
+        reason: "unavailable" as const,
+        detail: "Connector Gateway MCP",
+      });
+    }
+  }
+
+  options.advance("pi");
+  let prepared: PreparedPiRuntime;
+  try {
+    prepared = await options.pi.prepare({
+      snapshot: candidateSnapshot,
+      mcpHost: options.mcpHost,
+      gatewaySession,
+      additionalDegradations: gatewayDegradations,
+      createExtensionHostBinding: (permissions, ownContextLabels) =>
+        options.createExtensionHostBinding(
+          permissions,
+          ownContextLabels,
+        ),
+    });
+  } catch (error) {
+    await closeRuntimeGatewaySession(gatewaySession, "gateway.close.failed");
+    throw error;
+  }
+  const revision = await sha256Hex(prepared.revisionDescriptor);
+  const contested = Boolean(previous) &&
+    revision !== previous?.revision &&
+    options.isExecuting();
+  if (contested) {
+    await closeRuntimeGatewaySession(gatewaySession, "gateway.close.contested");
+    throw new Error(
+      "Cannot reload Runtime while a revision-pinned SpringBrand Turn is active",
+    );
+  }
+  const next = Object.freeze({
+    snapshot: candidateSnapshot,
+    revision,
+    runtimeKey: candidate.runtimeKey ?? revision,
+    pi: prepared,
+    ...(gatewaySession ? { gatewaySession } : {}),
+    ...(candidate.admission
+      ? { admission: candidate.admission }
+      : {}),
+  }) satisfies ActiveRuntime;
+  let activated = false;
+  const previousGatewaySession = previous?.gatewaySession;
+  try {
+    for (const [index, guard] of candidate.commitGuards.entries()) {
+      await withRuntimeLoadTimeout(`commit-guard:${index}`, guard);
+    }
+    options.pi.activate(candidateSnapshot);
+    activated = true;
+    options.commit(next);
+  } catch (error) {
+    if (activated && previous) options.pi.activate(previous.snapshot);
+    await closeRuntimeGatewaySession(gatewaySession, "gateway.close.aborted");
+    throw error;
+  }
+  await closeRuntimeGatewaySession(
+    previousGatewaySession,
+    "gateway.close.previous",
+  );
+
+  const degradations = prepared.degradations;
+  if (degradations.length > 0) {
+    console.warn(
+      "[runtime-load:degraded]",
+      JSON.stringify({ degradations }),
+    );
+  }
+}