Skip to content

Linger is An Open-Source Personal Agent That Runs Fully on Your PC. We aim to break Big Tech’s grip on AI by bringing powerful local AI to everyday computers through efficient model–harness co-design, so everyone can run their own.

82.2 KB
Raw Blame
import { randomUUID } from "node:crypto";
import {
  isLocalComputerOfflineError,
  LocalComputerModelError,
} from "../runner-gateway/local-computer-management.js";
import { LOCAL_COMPUTER_IDLE_TIMEOUT_MS } from "../runner-gateway/local-computer-management.js";
import {
  claimAgentFailureAlert,
  createAgentLogger,
  type AgentLogger,
} from "../observability/agent-log.js";
import type { ComposedContextFeatures } from "../agent-features/compose.js";
import type { BuiltinAgentFeatures } from "../agent-features/builtin.js";
import type { RunWakeKind } from "../agent-features/inbox-source/types.js";
import { TOOL_APPROVAL_FEATURE_ID } from "../agent-features/tool-approval/index.js";
import { inboxInputFact } from "../agent-features/inbox-source/accepted-fact.js";
import type {
  ContextBootstrap,
  FeatureSubmitOptions,
  FeatureSubmitResult,
  MaintenanceAction,
  MaintenanceOutcome,
  MaintenanceSkipReason,
  MaintenanceTrigger,
} from "../agent-features/contracts.js";
import { renderAcceptedNotification } from "../prompt/accepted-notification.js";
import {
  type ActivatedContextRuntime,
  type ContextRuntimeActivator,
  ContextRuntimeCleanupError,
  isUnconfirmedContextRuntimeCleanup,
} from "./activation.js";
import {
  AgentManagerError,
  isActivationPending,
  type ExecutionContextMessageDelivery,
} from "./agent-manager-api.js";
import {
  composeExecutorFeatures,
  instructedAgent,
} from "./context-features.js";
import {
  encodeExecutionContextRef,
  type ContextTargetResidency,
  type ExecutionContextRecord,
  type ExecutionContextRef,
} from "./context-ref.js";
import type {
  ContextRuntimeStatePort,
  MessageSteer,
} from "./context-runtime-state.js";
import type { ExecutorHost } from "./executor-host.js";
import type { Ghost } from "./ghost.js";
import {
  type RuntimeHistoryInspection,
  type RuntimeHistoryOptions,
  unavailableRuntimeHistory,
} from "./history.js";
import { ContextAdmission } from "./lifecycle-coordinator.js";
import {
  ProviderSessionInspectionError,
  runtimeSessionAwaitsFirstRun,
  type RuntimeExecutionFailure,
  type RuntimeSession,
} from "./provider.js";
import {
  RunLoop,
  type CompactSessionOptions,
  type CompactSessionResult,
} from "./run-loop.js";
import type { RuntimeStatusPublisher } from "./runtime-status.js";
import type {
  ActorId,
  AgentDefinition,
  AgentManagerStatus,
  ContextActivity,
  IdleSuspendResult,
  LocalTurnObservation,
  LocalTurnTerminal,
  Message,
  NonEmptyReadonlyArray,
  ResolvedAgentIdentity,
  RunCancellationStatus,
} from "./types.js";

export type ContextRuntimeStateFactory<TRuntimeSettings> = (input: {
  readonly ref: ExecutionContextRef;
  readonly configurationRevision: string;
  readonly runtime: TRuntimeSettings;
}) => Promise<ContextRuntimeStatePort>;

/** A read of a Context's persisted native History without its Runtime. */
export interface RuntimeHistoryInspectionRequest<TRuntimeSettings> {
  readonly ref: ExecutionContextRef;
  readonly runtime: TRuntimeSettings;
  readonly session: RuntimeSession;
  readonly options: RuntimeHistoryOptions;
}

/** Process-wide services every Context executor runs its Runtime with. */
export interface ExecutorServices<TRuntimeSettings> {
  readonly activator: ContextRuntimeActivator<TRuntimeSettings>;
  readonly stateFactory: ContextRuntimeStateFactory<TRuntimeSettings>;
  readonly statusPublisher?: RuntimeStatusPublisher;
  /** Reads persisted Runtime History while no Runtime is active. */
  readonly inspectPersistedHistory?: (
    request: RuntimeHistoryInspectionRequest<TRuntimeSettings>,
  ) => Promise<RuntimeHistoryInspection>;
}

export type PreparationSource =
  | "room_preparation"
  | "room_presence"
  | "restart_restore";

export interface ContextExecutorOptions<TRuntimeSettings> {
  readonly host: ExecutorHost<
    ContextExecutor<TRuntimeSettings>,
    TRuntimeSettings
  >;
  readonly services: ExecutorServices<TRuntimeSettings>;
  readonly features: Pick<BuiltinAgentFeatures, "composeContext">;
  readonly record: ExecutionContextRecord;
  readonly bootstrap: ContextBootstrap;
  readonly ghost: Readonly<Ghost<TRuntimeSettings>> & {
    readonly actorId: ActorId;
  };
  readonly identity: ResolvedAgentIdentity;
  /** The registry's logger of this Context. */
  readonly logger: AgentLogger;
}

const UNUSED_CONTEXT_PREPARATION_IDLE_MS = 30_000;
// Native compaction normally takes seconds; this only bounds a stuck Runtime.
const SESSION_COMPACTION_TIMEOUT_MS = 10 * 60_000;

/**
 * One Context instance: its residency and lifecycle transitions, its
 * serialized input admission, its composed features, and the Runtime it
 * activates with its Run loop. A configuration or Runtime change replaces
 * the whole instance; state that outlives an instance stays in the registry
 * behind {@link ExecutorHost}.
 */
export class ContextExecutor<TRuntimeSettings> {
  readonly ref: Readonly<ExecutionContextRef>;
  readonly key: string;
  /** The record this instance was created from. */
  readonly record: ExecutionContextRecord;
  readonly configurationRevision: string;
  /** The Ghost's Runtime revision this instance's Runtime was created for. */
  readonly runtimeRevision: string;
  readonly identity: ResolvedAgentIdentity;
  readonly runtime: Readonly<TRuntimeSettings>;

  readonly #host: ExecutorHost<
    ContextExecutor<TRuntimeSettings>,
    TRuntimeSettings
  >;
  readonly #services: ExecutorServices<TRuntimeSettings>;
  readonly #ghost: ContextExecutorOptions<TRuntimeSettings>["ghost"];
  readonly #bootstrap: ContextBootstrap;
  readonly #contextLogger: AgentLogger;
  readonly #featureLogger: AgentLogger;
  readonly #composeFeatures: Pick<BuiltinAgentFeatures, "composeContext">;

  // Residency and lifecycle transitions.
  #status: AgentManagerStatus;
  #targetResidency: ContextTargetResidency;
  #transitionTail: Promise<void> = Promise.resolve();
  readonly #activeTransitions = new Map<"activate", Promise<void>>();
  #idleTimer: ReturnType<typeof setTimeout> | null = null;
  // Set while the Context was activated without input and no input used it yet.
  #preparation: { source: PreparationSource; atMs: number } | null = null;
  #idleSuspendFailure: { attempts: number; retryAtMs: number | null } | null =
    null;
  // Store revisions may classify this failure, but must not repeat activation.
  #automaticActivationFailure: { readonly error: unknown } | null = null;

  // Features and admission. The admission boundary exists before the sources
  // bind, so a source delivery during binding already linearizes; before
  // publication the instance is valid only while it is bound. `#ready`
  // resolves at publication and rejects on a failed bind, so a delivery
  // admitted during binding defers its activation kick without blocking the
  // source's delivery return.
  readonly #featureScope = new AbortController();
  readonly #admission = new ContextAdmission();
  #features: ComposedContextFeatures | null = null;
  #bound = false;
  #published = false;
  readonly #ready: Promise<void>;
  #resolveReady!: () => void;
  #rejectReady!: (error: unknown) => void;
  #forwardTurnTerminals = true;

  // The Runtime.
  #runtimeLogger: AgentLogger = createAgentLogger({ component: "shell" });
  #runtimeAgent: AgentDefinition | null = null;
  #state: ContextRuntimeStatePort | null = null;
  #activatedRuntime: ActivatedContextRuntime | null = null;
  #execution: RunLoop | null = null;
  #activationPromise: Promise<void> | null = null;
  #activationCleanupFailure: ContextRuntimeCleanupError | null = null;
  #activationAbortController: AbortController | null = null;
  #activationAborted = false;
  #deactivationPromise: Promise<boolean> | null = null;
  #runtimeRecoveryPromise: Promise<void> | null = null;
  #desiredRuntimeState: "active" | "suspended" | "stopped" = "suspended";
  #providerReady = false;
  #activationFinishedAtMs: number | undefined;
  #idleSince: number | null = null;
  #reportedActivity: ContextActivity | null = null;
  #stopped = false;
  readonly #lifecycleController = new AbortController();
  #stopCompleted = false;
  #stopPromise: Promise<void> | null = null;
  #permanentDeletionPromise: Promise<void> | null = null;
  #steerRead: Promise<void> | null = null;
  #steerReadAgain = false;

  constructor(options: ContextExecutorOptions<TRuntimeSettings>) {
    const { record, ghost } = options;
    this.ref = Object.freeze({ ...record.ref });
    this.key = encodeExecutionContextRef(record.ref);
    this.record = record;
    this.configurationRevision = ghost.revision;
    this.runtimeRevision = ghost.runtimeRevision ?? ghost.revision;
    this.identity = options.identity;
    this.runtime = ghost.runtime;
    this.#host = options.host;
    this.#services = options.services;
    this.#ghost = ghost;
    this.#bootstrap = options.bootstrap;
    this.#contextLogger = options.logger;
    this.#featureLogger = options.logger.child({ tenantId: ghost.tenantId });
    this.#composeFeatures = options.features;
    this.#targetResidency = record.targetResidency;
    this.#status =
      record.targetResidency === "suspended" && options.bootstrap !== "new"
        ? "suspended"
        : "created";
    this.#ready = new Promise<void>((resolve, reject) => {
      this.#resolveReady = resolve;
      this.#rejectReady = reject;
    });
    // A failed bind rejects every queued activation intent; with no delivery
    // the rejection must still not surface as an unhandled rejection.
    void this.#ready.catch(() => undefined);
  }

  get status(): AgentManagerStatus {
    return this.#status;
  }

  get targetResidency(): ContextTargetResidency {
    return this.#targetResidency;
  }

  get preparation(): {
    readonly source: PreparationSource;
    readonly atMs: number;
  } | null {
    return this.#preparation;
  }

  get hasActiveTransitions(): boolean {
    return this.#activeTransitions.size > 0;
  }

  get activationInFlight(): boolean {
    return this.#activeTransitions.has("activate");
  }

  get automaticActivationFailure(): { readonly error: unknown } | null {
    return this.#automaticActivationFailure;
  }

  clearAutomaticActivationFailure(): void {
    this.#automaticActivationFailure = null;
  }

  /** Resolves at publication; rejects when the bind failed. */
  get ready(): Promise<void> {
    return this.#ready;
  }

  get features(): ComposedContextFeatures {
    if (!this.#features) throw new Error("Context features are not composed");
    return this.#features;
  }

  /**
   * Composes the features and opens the Runtime state. On failure the
   * caller abandons the instance.
   */
  async open(): Promise<void> {
    const composed = composeExecutorFeatures({
      record: this.record,
      ghost: this.#ghost,
      identity: this.identity,
      binding: {
        signal: this.#featureScope.signal,
        isBound: () => this.#bound,
        activeRunId: () => this.activeRunId() ?? undefined,
        steer: (runId, message, options) =>
          this.#featureSteer(runId, message, options),
        followUp: (message, options) => this.#featureFollowUp(message, options),
        // Bound, not wrapped: the wake reaches the claim with no forwarding
        // frame between the feature host and the executor.
        takeUpQueuedInput: this.takeUpQueuedInput.bind(this),
        onTimer: (name) => {
          this.features.onTimer(name);
          this.#host.trackBackground(
            this.runMaintenance({ kind: "timer", name }),
            this.ref,
            "maintenance.timer_failed",
          );
        },
        trackBackground: (operation, ref, event, fields) =>
          this.#host.trackBackground(operation, ref, event, fields),
      },
      features: this.#composeFeatures,
      logger: this.#featureLogger,
    });
    this.#features = composed;
    // Each activation renders the instructions again with the facts it
    // reads; until one does, they are the full version with the connected
    // app commands.
    this.#runtimeAgent = Object.freeze(
      snapshotConfiguration(
        instructedAgent(composed, this.#ghost.agent, this.record, {
          connectedApps: true,
          connectedAppKeys: [],
          connectableAppKeys: [],
          compactInstructions: false,
        }),
      ),
    );
    this.#runtimeLogger = this.#runtimeLogger.child({
      agentId: this.ref.agentId,
      agentName: this.#runtimeAgent.name,
      contextKey: this.key,
      contextKind: this.ref.kind,
    });
    this.#state = await this.#services.stateFactory({
      ref: this.ref,
      configurationRevision: this.configurationRevision,
      runtime: this.runtime,
    });
    // Logging must not add a remote authorization read.
    this.#log("info", "shell.created");
  }

  /**
   * Binds the feature sources while the instance is still unpublished:
   * immediate host callbacks resolve through this bound instance, and the
   * registry publishes it only after binding completes, so a half-wired
   * Context is never observable as ready. A source delivery during binding
   * still commits durably through the already-live admission boundary.
   */
  async bindSources(): Promise<void> {
    this.#bound = true;
    await this.features.bindSources({ bootstrap: this.#bootstrap });
  }

  /**
   * Publication completes the boundary: queued activation intents may now
   * run, and later admissions validate through registry ownership only.
   */
  publish(): void {
    this.#published = true;
    this.#resolveReady();
  }

  /**
   * Cleans up a creation that failed before publication. Serialized
   * invalidation converges an in-flight bind-time delivery's durable commit
   * first; only then may the instance lose its binding and cleanup start.
   * Returns the cleanup failures.
   */
  async abandon(error: unknown): Promise<unknown[]> {
    const cleanupErrors: unknown[] = [];
    try {
      await this.#admission.run(() => {
        this.#bound = false;
        this.#featureScope.abort();
        this.#rejectReady(error);
      });
    } catch (cleanupError) {
      cleanupErrors.push(cleanupError);
    }
    try {
      await this.#features?.release();
    } catch (cleanupError) {
      cleanupErrors.push(cleanupError);
    }
    try {
      await this.stop();
    } catch (cleanupError) {
      cleanupErrors.push(cleanupError);
    }
    // Terminal forwarding stays live while the Runtime drains; stop it last.
    this.stopForwardingTurnTerminals();
    return cleanupErrors;
  }

  /** Later Run terminals no longer reach the features. */
  stopForwardingTurnTerminals(): void {
    this.#forwardTurnTerminals = false;
  }

  // ---------------------------------------------------------------------
  // Input admission

  /**
   * Final instance check inside the serialized admission boundary. Before
   * publication the instance counts only while bound; afterwards only
   * registry ownership counts. A superseded or stopped instance reports
   * "context_replaced"; an invalidated still-owned one reports
   * "context_released".
   */
  admissionFailure(): "context_released" | "context_replaced" | null {
    const owned = this.#host.owns(this) || (!this.#published && this.#bound);
    if (!owned || this.#status === "stopped") return "context_replaced";
    if (this.#featureScope.signal.aborted) return "context_released";
    return null;
  }

  /** Accepts a trusted turn; the caller requests activation afterwards. */
  async acceptTrustedTurn(
    messages: ExecutionContextMessageDelivery["messages"],
  ): Promise<string> {
    const { runId } = await this.#acceptCurrentInput(async () => {
      const accepted = await this.submitTrustedTurn(snapshotMessages(messages));
      this.usePreparedContext();
      return accepted;
    });
    return runId;
  }

  /** Steers a trusted message into the active Run; null when there is none. */
  steerActiveTurn(message: Message): Promise<string | null> {
    return this.#admission.run(async () => {
      if (this.#host.isTerminal(this.ref) || this.admissionFailure() !== null)
        return null;
      const runId = this.activeRunId();
      if (!runId) return null;
      try {
        await this.acceptTrustedNotification(runId, snapshotMessage(message));
      } catch (error) {
        // The turn ended or was fenced while steering; the caller queues.
        this.#contextLogger.log("info", "trusted_steer.not_steerable", {
          error,
          runId,
        });
        return null;
      }
      return runId;
    });
  }

  async #acceptCurrentInput<T>(
    accept: () => Promise<T>,
    gate?: () => boolean,
  ): Promise<T> {
    // Cold and unused prepared Contexts may have a superseded profile.
    // Once input adopts a Runtime, retain its accepted configuration and work.
    // Readiness preparation may await remote authority, so it stays outside
    // the admission boundary; everything after it is serialized.
    if (this.#status !== "active" || this.#preparation !== null) {
      await this.#host.withConfigTiming(this.ref, "preaccept", () =>
        this.#host.assertActivationReady(
          this.ref.agentId,
          this.configurationRevision,
        ),
      );
    }
    this.#host.assertAgentAvailable(this.ref.agentId);
    return this.#admission.run(() => {
      if (this.#host.isTerminal(this.ref))
        throw new TerminalExecutionContextError(this.ref);
      // Ownership rechecked at the durable-acceptance fence: an admission
      // already inside linearizes before a later-queued invalidation, so a
      // replaced, released, or stopped instance can never accept after the
      // fact.
      if (this.admissionFailure() !== null) {
        throw new AgentManagerError(
          "agent_revision_conflict",
          "Execution Context was replaced before input acceptance; retry with its current configuration",
        );
      }
      // Feature submissions evaluate their validity check at this same final
      // boundary so nothing accepted during the wait can slip through.
      if (gate && !gate()) throw new FeatureSubmissionSkippedError();
      return accept();
    });
  }

  /**
   * Feature-owned steer into the Run of this instance. The final boundary
   * rechecks the instance, its active Run, and the feature's canSubmit after
   * all waits; a replaced or invalidated instance resolves as skipped
   * instead of reaching a same-ref successor.
   */
  #featureSteer(
    runId: string,
    message: Message,
    options?: FeatureSubmitOptions,
  ): Promise<FeatureSubmitResult> {
    return this.#host.duringOpen(async () => {
      if (!this.#bound || this.#featureScope.signal.aborted)
        return { status: "skipped", reason: "context_released" };
      return this.#admission.run(async () => {
        // Terminal tombstone checked before instance/run/canSubmit, matching
        // the durable-acceptance fence in #acceptCurrentInput.
        if (this.#host.isTerminal(this.ref))
          return { status: "skipped" as const, reason: "context_terminal" };
        const failure = this.admissionFailure();
        if (failure) return { status: "skipped" as const, reason: failure };
        if (this.activeRunId() !== runId)
          return { status: "skipped" as const, reason: "run_inactive" };
        if (options?.canSubmit && !options.canSubmit())
          return { status: "skipped" as const, reason: "stale" };
        const result = await this.acceptTrustedNotification(runId, message);
        return {
          status:
            result === "already_accepted" ? "already_accepted" : "accepted",
        } as const;
      });
    });
  }

  /**
   * Feature-owned trusted follow-up turn on this instance. The instance
   * check and canSubmit gate run at the final durable-acceptance boundary.
   */
  #featureFollowUp(
    message: Message,
    options?: FeatureSubmitOptions,
  ): Promise<FeatureSubmitResult> {
    return this.#host.duringOpen(async () => {
      if (!this.#bound || this.#featureScope.signal.aborted)
        return { status: "skipped", reason: "context_released" };
      try {
        await this.#acceptCurrentInput(async () => {
          const accepted = await this.submitTrustedTurn([message]);
          this.usePreparedContext();
          return accepted;
        }, options?.canSubmit);
      } catch (error) {
        if (error instanceof FeatureSubmissionSkippedError)
          return { status: "skipped", reason: "stale" };
        if (
          error instanceof AgentManagerError &&
          error.code === "agent_revision_conflict"
        )
          return {
            status: "skipped",
            reason: this.admissionFailure() ?? "context_replaced",
          };
        if (error instanceof TerminalExecutionContextError)
          return { status: "skipped", reason: "context_terminal" };
        throw error;
      }
      this.trackTransition(
        this.#ready.then(() => this.requestActive("trusted_turn")),
        "activation.after_trusted_turn_failed",
      );
      return { status: "accepted" };
    });
  }

  /**
   * Serialized invalidation of this instance's admission boundary: it
   * linearizes after every already-queued admission's durable commit, so a
   * stop path can never abort a committed fact mid-flight, and every
   * later-queued submission resolves skipped instead of accepting.
   */
  invalidateAdmission(): Promise<void> {
    return this.#admission.run(() => {
      this.#featureScope.abort();
    });
  }

  /**
   * Invalidates the admission when the check still holds inside the
   * boundary; resolves whether it did.
   */
  invalidateAdmissionIf(check: () => boolean): Promise<boolean> {
    return this.#admission.run(() => {
      if (!check()) return false;
      this.#featureScope.abort();
      return true;
    });
  }

  /**
   * Context disposal: invalidate the FeatureContext first so in-flight
   * feature submissions resolve as skipped, then stop bound sources in
   * reverse order.
   */
  async releaseFeatures(): Promise<void> {
    await this.invalidateAdmission();
    await this.features.release();
  }

  /**
   * Stop-path teardown shared by every owner: the serialized invalidation
   * must converge before any Runtime stop starts; afterwards source release
   * and the Runtime stop clean disjoint resources, so a failure in one never
   * skips the other.
   */
  async invalidateAndStop(stop: () => Promise<void>): Promise<unknown[]> {
    const failures: unknown[] = [];
    try {
      await this.invalidateAdmission();
    } catch (error) {
      failures.push(error);
    }
    const cleanup = await Promise.allSettled([
      invokeClose(() => this.features.release()),
      invokeClose(stop),
    ]);
    for (const result of cleanup) {
      if (result.status === "rejected") failures.push(result.reason);
    }
    return failures;
  }

  // ---------------------------------------------------------------------
  // Queued input

  /**
   * TeamHub queued Inbox input for this Context. A ready Runtime claims it
   * at once; otherwise activation goes through the registry's lifecycle
   * queue, and the activated Runtime reads its work.
   */
  async takeUpQueuedInput(kind: RunWakeKind): Promise<void> {
    // An unused preparation takes the slow path, which re-reads the Agent's
    // configuration once: a profile edit does not notify Agent Service, and
    // TeamHub accepts the first Session only at the revision its Run was
    // claimed under, so the first Run must not adopt an older preparation.
    if (
      this.#isReadyForQueuedInput() &&
      this.#preparation === null &&
      !(await this.#host.isSuperseded(this))
    ) {
      this.notifyQueuedInput(kind);
      return;
    }
    await this.#ready;
    await this.#host.takeUpQueuedInputSlow(this, kind);
  }

  #isReadyForQueuedInput(): boolean {
    return (
      this.#status === "active" &&
      this.isRuntimeReady() &&
      this.#targetResidency === "active"
    );
  }

  // ---------------------------------------------------------------------
  // Residency transitions

  /** Marks an activation without input; real input adopts it. */
  markPreparation(source: PreparationSource): void {
    this.#preparation = { source, atMs: Date.now() };
  }

  /** Whether a configuration refresh may replace this instance now. */
  canRefreshConfiguration(): boolean {
    return (
      this.#status === "suspended" ||
      this.#status === "created" ||
      (this.#status === "active" &&
        this.#preparation !== null &&
        !this.isBusy())
    );
  }

  requestActive(reason: string, persistTarget = true): Promise<void> {
    const requestedAt = performance.now();
    if (
      reason === "trusted_turn" ||
      reason === "start" ||
      reason === "resume" ||
      reason === "queued_input"
    ) {
      this.usePreparedContext();
    }
    this.#host.clearLazyRestore(this.ref);
    // Management refresh and recovery are not input. Preserve an unused
    // preparation's existing expiry instead of restarting its 30-second clock.
    if (this.#preparation === null) this.clearIdleTimer();
    this.#targetResidency = "active";
    const activationKey = "activate";
    const current = this.#activeTransitions.get(activationKey);
    if (current) return current;
    const operation = this.#appendTransition(async () => {
      const transitionStartedAt = performance.now();
      if (persistTarget) {
        await this.#host.persistTargetResidency(this.ref, "active");
      }
      if (this.#status === "active" && this.isRuntimeReady()) {
        this.#automaticActivationFailure = null;
        this.scheduleIdleTimer();
        return;
      }
      if (this.#status === "stopped") {
        throw new AgentManagerError(
          "invalid_state",
          `Execution Context ${this.key} has been stopped`,
        );
      }

      const activationCheckStartedAt = performance.now();
      await this.#host.checkActivationOrDefer(this);
      const activationCheckedAt = performance.now();
      const fallback = this.#status;
      this.#status = "starting";
      const logger = this.#contextLogger;
      logger.log("info", "activation.started", {
        reason,
        fallback,
        transitionWaitMs: Math.round(transitionStartedAt - requestedAt),
        activationCheckMs: Math.round(
          activationCheckedAt - activationCheckStartedAt,
        ),
      });
      try {
        await this.start();
        this.#status = "active";
        this.#idleSuspendFailure = null;
        this.#automaticActivationFailure = null;
        logger.log("info", "activation.completed", { reason });
        this.notifyWorkAvailable();
        this.scheduleIdleTimer();
      } catch (error) {
        this.#automaticActivationFailure = { error };
        this.#status = fallback;
        if (isActivationPending(error)) {
          // Runtime activation already released its resources. Retry via
          // the lifecycle queue after this shared Context operation exits.
          // This rethrows after restore_deferred; a temporary configuration
          // fence intentionally skips activation.failed and its failure alert.
          await this.#host.checkActivationOrDefer(this, error);
        }
        if (
          this.#host.shouldSuspendRestoreFailure(this.ref, this.runtime, error)
        ) {
          await this.#host.checkActivationOrDefer(this);
        }
        if (
          ["trusted_turn", "start", "resume", "queued_input"].includes(
            reason,
          ) &&
          this.#host.isRecoverableRestoreFailure(this.ref, this.runtime, error)
        ) {
          await this.#host.retryActivationLater(this, error);
        }
        const computerOffline = isLocalComputerOfflineError(error);
        const ownsFailureAlert = computerOffline
          ? false
          : claimAgentFailureAlert(error);
        logger.log(
          computerOffline ? "info" : ownsFailureAlert ? "error" : "warn",
          computerOffline
            ? "activation.waiting_for_computer"
            : "activation.failed",
          {
            reason,
            error,
            ...(computerOffline
              ? {}
              : ownsFailureAlert
                ? {}
                : { alertAggregated: true }),
          },
        );
        throw error;
      }
    });
    const promise = operation.finally(() => {
      if (this.#activeTransitions.get(activationKey) === promise) {
        this.#activeTransitions.delete(activationKey);
      }
    });
    this.#activeTransitions.set(activationKey, promise);
    return promise;
  }

  requestSuspend(persistTarget = true): Promise<void> {
    this.#preparation = null;
    this.clearIdleTimer();
    this.#targetResidency = "suspended";
    return this.#appendTransition(async () => {
      if (persistTarget) {
        await this.#host.persistTargetResidency(this.ref, "suspended");
      }
      if (this.#status === "suspended") {
        this.#automaticActivationFailure = null;
        return;
      }
      if (this.#status === "stopped") {
        throw new AgentManagerError(
          "invalid_state",
          `Execution Context ${this.key} has been stopped`,
        );
      }
      await this.suspend();
      this.#status = "suspended";
      this.#idleSuspendFailure = null;
      this.#automaticActivationFailure = null;
    });
  }

  requestStop(): Promise<void> {
    this.clearIdleTimer();
    return this.#appendTransition(async () => {
      if (this.#status === "stopped") return;
      await this.stop();
      this.#status = "stopped";
    });
  }

  requestPermanentStop(): Promise<void> {
    this.clearIdleTimer();
    // Abort a blocked activation first so the queued permanent stop is not
    // held behind it for the full activation deadline.
    this.abortActivation(
      new Error("Execution Context is being permanently stopped"),
    );
    return this.#appendTransition(async () => {
      await this.#deletePermanent();
      this.#status = "stopped";
    });
  }

  /**
   * Shutdown stop: waits for the queued transitions and stops the Runtime
   * within the remaining Run grace period. The process restarts, so a Run
   * still active then goes back to the queue and resumes in the next
   * process instead of ending canceled.
   */
  async stopForShutdown(
    stop: (operation: () => Promise<void>) => Promise<void>,
    gracePeriodMs: () => number,
  ): Promise<void> {
    await Promise.all([
      this.#transitionTail.catch(() => undefined),
      stop(() =>
        this.stop({ gracePeriodMs: gracePeriodMs(), resumeActiveRun: true }),
      ),
    ]);
    this.#status = "stopped";
  }

  #appendTransition(operation: () => Promise<void>): Promise<void> {
    const transition = this.#transitionTail
      .catch(() => undefined)
      .then(operation);
    this.#transitionTail = transition;
    return transition;
  }

  trackTransition(
    transition: Promise<void>,
    event: string,
    fields?: Readonly<Record<string, unknown>>,
  ): void {
    this.#host.trackBackground(transition, this.ref, event, fields);
  }

  // ---------------------------------------------------------------------
  // Maintenance

  /**
   * Feature timer entry: ask the Context's features for a maintenance action
   * and run it. A suspended Context is activated without persisting an
   * active target and suspended again afterwards; an offline Computer is
   * skipped rather than waited for.
   */
  runMaintenance(trigger: MaintenanceTrigger): Promise<void> {
    return this.#host.runContext(this.ref, async () => {
      if (
        this.#host.isClosing() ||
        !this.#host.holds(this) ||
        this.#featureScope.signal.aborted
      )
        return;
      const action = this.features.decideMaintenance(trigger);
      if (!action) return;
      const wasActive =
        this.#targetResidency === "active" && this.#status === "active";
      if (!wasActive) {
        if (!this.#host.canRunMaintenance(this.runtime)) {
          this.#finishSkippedMaintenance(trigger, action, "unavailable");
          return;
        }
        try {
          await this.requestActive("maintenance", false);
        } catch (error) {
          // The in-memory target must not stay active for a failed wake.
          if (this.#status !== "active")
            await this.requestSuspend().catch(() => undefined);
          throw error;
        }
      }
      await this.#appendTransition(async () => {
        await this.#executeMaintenance(trigger, action);
      });
      // A Context woken only for maintenance goes back to sleep; input that
      // arrived meanwhile keeps it active through its own activation request.
      if (
        !wasActive &&
        this.#host.owns(this) &&
        !this.isBusy() &&
        !this.#activeTransitions.has("activate")
      )
        await this.requestSuspend();
    });
  }

  /**
   * Runs one maintenance action on the active Runtime. Never throws: every
   * outcome, including a skip, is reported to the features' onMaintenance.
   */
  async #executeMaintenance(
    trigger: MaintenanceTrigger,
    action: MaintenanceAction,
  ): Promise<MaintenanceOutcome> {
    const features = this.features;
    const finish = (outcome: MaintenanceOutcome): MaintenanceOutcome => {
      features.onMaintenance({
        phase: "finished",
        trigger,
        action,
        outcome,
      });
      this.#contextLogger.log(
        outcome.status === "failed" ? "warn" : "info",
        "maintenance.finished",
        {
          trigger: trigger.kind,
          action: action.kind,
          reason: action.reason,
          status: outcome.status,
          ...(outcome.status === "skipped" ? { skipped: outcome.reason } : {}),
          ...(outcome.status === "failed" ? { error: outcome.error } : {}),
        },
      );
      return outcome;
    };
    if (this.#status !== "active" || this.isBusy())
      return finish({ status: "skipped", reason: "busy" });
    features.onMaintenance({ phase: "started", trigger, action });
    try {
      const result = await this.compactSession({
        ...(action.instructions ? { instructions: action.instructions } : {}),
        signal: AbortSignal.any([
          this.#featureScope.signal,
          AbortSignal.timeout(SESSION_COMPACTION_TIMEOUT_MS),
        ]),
      });
      return finish(
        result.status === "compacted"
          ? { status: "completed" }
          : {
              status: "skipped",
              reason:
                result.status === "unsupported" ? "unavailable" : result.status,
            },
      );
    } catch (error) {
      return finish({ status: "failed", error });
    }
  }

  #finishSkippedMaintenance(
    trigger: MaintenanceTrigger,
    action: MaintenanceAction,
    reason: MaintenanceSkipReason,
  ): void {
    this.features.onMaintenance({
      phase: "finished",
      trigger,
      action,
      outcome: { status: "skipped", reason },
    });
    this.#contextLogger.log("info", "maintenance.finished", {
      trigger: trigger.kind,
      action: action.kind,
      reason: action.reason,
      status: "skipped",
      skipped: reason,
    });
  }

  // ---------------------------------------------------------------------
  // Idle suspend

  #onActivityChanged(activity: ContextActivity): void {
    if (!this.#host.owns(this) || this.#status === "stopped") return;
    if (this.activeRunId()) this.usePreparedContext();
    if (activity === "busy") {
      this.clearIdleTimer();
      return;
    }
    this.scheduleIdleTimer();
  }

  #isLazyRestoreIdle(): boolean {
    // A lazily restored active Context has no Runtime yet but follows the same idle policy.
    return (
      this.#host.hasLazyRestore(this.ref) &&
      this.#status === "created" &&
      this.#targetResidency === "active"
    );
  }

  scheduleIdleTimer(delayMs = this.#idleTimeout()): void {
    if (
      this.#host.isClosing() ||
      this.#host.isDeletingAgent(this.ref.agentId) ||
      this.#idleTimer ||
      this.#idleSuspendFailure?.retryAtMs === null ||
      this.#targetResidency !== "active" ||
      (this.#status !== "active" && !this.#isLazyRestoreIdle())
    ) {
      return;
    }
    const timer = setTimeout(
      () => {
        if (this.#idleTimer === timer) {
          this.#idleTimer = null;
        }
        this.#host.trackBackground(
          this.#attemptIdleSuspend(),
          this.ref,
          "idle_suspend.failed",
        );
      },
      Math.max(
        0,
        this.#idleSuspendFailure?.retryAtMs !== undefined
          ? this.#idleSuspendFailure.retryAtMs - Date.now()
          : delayMs,
      ),
    );
    this.#idleTimer = timer;
  }

  clearIdleTimer(): void {
    if (!this.#idleTimer) return;
    clearTimeout(this.#idleTimer);
    this.#idleTimer = null;
  }

  /**
   * A presence hint keeps an idle Runtime warm for another idle window, so a
   * person still in the Room does not wait for a cold start.
   */
  renewIdleWindow(): void {
    if (!this.#idleTimer) return;
    this.clearIdleTimer();
    this.scheduleIdleTimer();
  }

  #attemptIdleSuspend(): Promise<void> {
    return this.#appendTransition(async () => {
      const idleTimeoutMs = this.#idleTimeout();
      if (this.#isLazyRestoreIdle()) {
        if (!this.#host.holds(this)) return;
        if (this.isBusy()) {
          this.scheduleIdleTimer();
          return;
        }
        // No Runtime was started, so the Runtime is not called; a later
        // activation sees the fallback "suspended" status and resumes.
        this.#host.clearLazyRestore(this.ref);
        this.#status = "suspended";
        this.#contextLogger.log("info", "idle_suspend.lazy_restore_suspended");
        await this.#commitIdleSuspend();
        return;
      }
      if (
        !this.#host.holds(this) ||
        this.#targetResidency !== "active" ||
        this.#status !== "active" ||
        this.isBusy()
      ) {
        return;
      }
      const previousFailure = this.#idleSuspendFailure;
      if (previousFailure?.retryAtMs === null) return;
      // Maintenance runs once per idle window, before the first suspend
      // attempt; a cleanup retry is not a new window.
      if (!previousFailure) {
        const trigger = { kind: "idle_suspend" } as const;
        const action = this.features.decideMaintenance(trigger);
        if (action) {
          await this.#executeMaintenance(trigger, action);
          if (
            !this.#host.holds(this) ||
            this.#status !== "active" ||
            this.isBusy()
          )
            return;
        }
      }
      const attempt = (previousFailure?.attempts ?? 0) + 1;
      this.#contextLogger.log("info", "idle_suspend.attempt_started", {
        attempt,
        previousFailurePending: previousFailure !== null,
      });
      const wasUnusedPreparation = this.#preparation !== null;
      let result: IdleSuspendResult;
      try {
        // Failed cleanup already passed idle admission. Continue it after the
        // retry backoff; the Runtime still checks busy and pending work with zero.
        result = await this.trySuspendAfterIdle(
          previousFailure ? 0 : idleTimeoutMs,
        );
      } catch (error) {
        // Old Daemons report unavailable Registration as non-retryable generic
        // CONTEXT_VIEW_FAILED. Give that ambiguous failure a bounded new attempt;
        // explicit identity/recovery failures cannot be repaired automatically.
        const blocked = idleCleanupRequiresIntervention(error) || attempt >= 3;
        this.#idleSuspendFailure = {
          attempts: attempt,
          retryAtMs: blocked
            ? null
            : Date.now() + (attempt === 1 ? 1_000 : 5_000),
        };
        this.clearIdleTimer();
        this.#contextLogger.log("warn", "idle_suspend.attempt_failed", {
          attempt,
          error,
        });
        if (blocked) {
          this.#contextLogger.log("warn", "idle_suspend.blocked", {
            attempt,
            reason: attempt >= 3 ? "retry_exhausted" : "intervention_required",
            previousFailurePending: true,
            error,
          });
        } else {
          this.scheduleIdleTimer();
        }
        return;
      }
      // The Provider can finish an old idle transition after the Context was
      // bound again. Only its original binding may change durable residency.
      if (!this.#host.holds(this)) return;
      if (result.status === "suspended") {
        this.#idleSuspendFailure = null;
        this.#status = "suspended";
        // Input can queue activation while idle teardown awaits the Provider.
        // Preserve that intention, including a later explicit suspend, instead
        // of letting this older idle transition overwrite it.
        if (
          this.#activeTransitions.has("activate") ||
          (wasUnusedPreparation && this.#preparation === null)
        ) {
          return;
        }
        await this.#commitIdleSuspend();
        return;
      }
      if (result.retryAfterMs !== undefined) {
        if (this.#idleSuspendFailure) {
          this.#idleSuspendFailure.retryAtMs = Date.now() + result.retryAfterMs;
        }
        this.scheduleIdleTimer(result.retryAfterMs);
      }
    });
  }

  async #commitIdleSuspend(): Promise<void> {
    this.#preparation = null;
    this.#targetResidency = "suspended";
    await this.#host.persistTargetResidency(this.ref, "suspended");
    if (this.#host.holds(this)) {
      await this.#host.releaseIdleContext(this.ref);
    }
  }

  #idleTimeout(): number {
    // A restart-restored Context keeps the normal idle window.
    const preparation = this.#preparation;
    return preparation && preparation.source !== "restart_restore"
      ? UNUSED_CONTEXT_PREPARATION_IDLE_MS
      : LOCAL_COMPUTER_IDLE_TIMEOUT_MS;
  }

  usePreparedContext(): void {
    const preparation = this.#preparation;
    if (!preparation) return;
    this.#preparation = null;
    this.#contextLogger.log("info", "binding.prepared_context_adopted", {
      source: preparation.source,
      preparedForMs: Date.now() - preparation.atMs,
      activationInFlight: this.#activeTransitions.has("activate"),
    });
    this.clearIdleTimer();
    this.scheduleIdleTimer();
  }

  // ---------------------------------------------------------------------
  // Runtime

  /** Activates the Runtime, or resumes its persisted session. */
  async start(): Promise<void> {
    this.#assertNotStopped();
    this.#requireState();
    this.#desiredRuntimeState = "active";
    for (;;) {
      if (this.#runtimeRecoveryPromise) {
        await this.#runtimeRecoveryPromise;
      }
      if (this.#providerReady) return;
      if (this.#deactivationPromise) await this.#deactivationPromise;
      if (this.#activationPromise) {
        await this.#activationPromise;
        if (this.#providerReady) return;
        continue;
      }
      await this.#discardStaleRuntimeSession();
      const mode =
        (await this.#requireState().getRuntimeSession()) === null
          ? "start"
          : "resume";
      await this.#beginActivation(mode);
      return;
    }
  }

  async suspend(): Promise<void> {
    this.#assertNotStopped();
    if (!this.#providerReady) {
      this.#desiredRuntimeState = "suspended";
      this.#activationAbortController?.abort(
        new Error("Context Runtime suspension requested"),
      );
      return;
    }
    if (!this.#isIdle()) {
      throw runtimeError("busy", "Context Runtime is busy");
    }
    this.#desiredRuntimeState = "suspended";
    const suspended = await this.#deactivate({
      cancelActive: false,
      requireIdle: true,
    });
    if (!suspended) {
      this.#desiredRuntimeState = "active";
      throw runtimeError("busy", "Context Runtime became busy");
    }
  }

  async trySuspendAfterIdle(idleForMs: number): Promise<IdleSuspendResult> {
    this.#assertNotStopped();
    if (!Number.isSafeInteger(idleForMs) || idleForMs < 0) {
      throw new TypeError("idleForMs must be a non-negative safe integer");
    }
    if (!this.#providerReady || !this.#isIdle()) {
      return { status: "not_idle" };
    }
    const now = Date.now();
    this.#idleSince ??= now;
    const remaining = idleForMs - (now - this.#idleSince);
    if (remaining > 0) {
      return { status: "not_idle", retryAfterMs: remaining };
    }
    this.#desiredRuntimeState = "suspended";
    const suspended = await this.#deactivate({
      cancelActive: false,
      requireIdle: true,
    });
    if (!suspended) this.#desiredRuntimeState = "active";
    return suspended ? { status: "suspended" } : { status: "not_idle" };
  }

  isBusy(): boolean {
    return Boolean(
      this.#activationPromise ||
      this.#deactivationPromise ||
      this.#runtimeRecoveryPromise ||
      (this.#execution?.activeOperations ?? 0) > 0 ||
      this.#state?.hasPendingWork(),
    );
  }

  isRuntimeReady(): boolean {
    // Once teardown starts, committed input needs a serialized reactivation
    // even while the Provider's native cleanup has not finished yet.
    return this.#providerReady && this.#deactivationPromise === null;
  }

  activeRunId(): string | null {
    return this.#execution?.activeRunId() ?? null;
  }

  /**
   * Advisory, never throws: after a Room-presence activation, start the
   * Provider early for an active, idle Runtime with no accepted input.
   */
  prestartProviderForPresence(): void {
    const runtime = this.#activatedRuntime;
    if (
      !this.isRuntimeReady() ||
      runtime === null ||
      this.activeRunId() !== null ||
      this.#state?.acceptedInputPending?.() === true
    ) {
      return;
    }
    runtime.provider.prepareForPresence?.(runtime.runtimeSession);
  }

  /** Wakes an active Runtime after durable work arrives outside it. */
  notifyWorkAvailable(): void {
    this.#assertNotStopped();
    this.#execution?.notifyWorkAvailable();
    this.#notifyActivityChanged();
  }

  /**
   * A Message transaction queued a Run (queued) or a steer for the running
   * Run (steered) of this Context. Claims the Run without another work-state
   * read, or reads the steers and hands them to the running Run.
   */
  notifyQueuedInput(kind: RunWakeKind): void {
    this.#assertNotStopped();
    const execution = this.#execution;
    if (!execution) return;
    if (kind === "queued" && this.#state?.noteQueuedRun) {
      this.#state.noteQueuedRun();
      execution.notifyWorkAvailable({ workStateAlreadyFresh: true });
    } else if (kind === "steered") {
      // The execution loop may be busy running the Run this steer joins, so
      // read the steers now instead of waiting for its next refresh.
      this.#readMessageSteers();
    } else {
      execution.notifyWorkAvailable();
    }
    this.#notifyActivityChanged();
  }

  /**
   * Native compaction of the idle active session. No Run is claimed while it
   * runs, and durable work arriving meanwhile aborts it (history unchanged),
   * so the Context keeps reporting idle and input is never deferred for it.
   */
  async compactSession(
    options: CompactSessionOptions,
  ): Promise<CompactSessionResult> {
    this.#assertNotStopped();
    const execution = this.#execution;
    if (!execution || !this.#isIdle()) return { status: "busy" };
    const startedAt = Date.now();
    const result = await execution.compactSession(options);
    this.#log("info", "runtime.session_compaction.finished", {
      status: result.status,
      durationMs: Date.now() - startedAt,
      ...(result.status === "compacted" && result.preTokens !== undefined
        ? { preTokens: result.preTokens }
        : {}),
    });
    return result;
  }

  async inspectRuntimeHistory(
    options: RuntimeHistoryOptions,
  ): Promise<RuntimeHistoryInspection> {
    this.#assertNotStopped();
    options.signal?.throwIfAborted();
    const runtime = this.#activatedRuntime;
    const runtimeName =
      runtime?.runtimeName ?? configuredRuntimeName(this.runtime);
    const persistedInspector = this.#services.inspectPersistedHistory;
    if (!runtime?.provider.inspectHistory && !persistedInspector) {
      const reason = runtime
        ? "Runtime provider does not expose history inspection"
        : "Persisted Runtime history inspection is unavailable";
      return unavailableRuntimeHistory(
        runtimeName,
        reason,
        runtime ? "unsupported" : "unavailable",
      );
    }
    try {
      if (runtime?.provider.inspectHistory) {
        return await runtime.provider.inspectHistory(
          runtime.runtimeSession,
          options,
        );
      }
      const session = await this.#requireState().getRuntimeSession();
      if (!session) {
        return unavailableRuntimeHistory(
          runtimeName,
          "Runtime session is unavailable",
        );
      }
      return await persistedInspector!({
        ref: this.ref,
        runtime: this.runtime,
        session,
        options,
      });
    } catch (error) {
      if (options.signal?.aborted) throw error;
      if (error instanceof ProviderSessionInspectionError) {
        return unavailableRuntimeHistory(
          runtimeName,
          error.message,
          error.status,
        );
      }
      // The reason the Activity log shows is deliberately generic. Without
      // this log the only record of why History failed is lost, which is how
      // a Runner-state condition ends up looking like a broken Activity log.
      this.#log("warn", "runtime.history_inspection.failed", {
        runtimeName,
        error,
      });
      return unavailableRuntimeHistory(
        runtimeName,
        "Runtime provider history inspection failed",
      );
    }
  }

  async stop(
    options: {
      readonly gracePeriodMs?: number;
      readonly resumeActiveRun?: boolean;
    } = {},
  ): Promise<void> {
    if (this.#stopCompleted) return;
    if (this.#stopPromise) return this.#stopPromise;
    this.#stopped = true;
    this.#desiredRuntimeState = "stopped";
    this.#activationAbortController?.abort();
    const gracePeriodMs = options.gracePeriodMs ?? 0;
    const resumable = options.resumeActiveRun === true;
    this.#execution?.requestDrain({
      cancelActive: gracePeriodMs <= 0,
      resumable,
    });
    const stopping = (async () => {
      const failures: unknown[] = [];
      if (gracePeriodMs > 0 && this.#execution) {
        let timer: ReturnType<typeof setTimeout> | undefined;
        this.#log("info", "runtime.shutdown.waiting", { gracePeriodMs });
        try {
          await Promise.race([
            this.#execution
              .drain({ cancelActive: false })
              .catch(() => undefined),
            new Promise<void>((resolve) => {
              timer = setTimeout(resolve, gracePeriodMs);
            }),
          ]);
        } finally {
          if (timer) clearTimeout(timer);
        }
      }
      this.#lifecycleController.abort(new Error("Context Runtime stopped"));
      this.#execution?.requestDrain({ cancelActive: true, resumable });
      this.#log("info", "runtime.shutdown.cancel_remaining");
      if (this.#activationPromise) {
        await this.#activationPromise.catch((error: unknown) => {
          if (!(error instanceof ActivationCancelledError))
            failures.push(error);
        });
      }
      try {
        await this.#deactivate({ cancelActive: true, requireIdle: false });
      } catch (error) {
        failures.push(error);
      }
      if (this.#runtimeRecoveryPromise) {
        await this.#runtimeRecoveryPromise.catch((error: unknown) =>
          failures.push(error),
        );
      }
      if (
        this.#activationCleanupFailure &&
        !failures.includes(this.#activationCleanupFailure)
      )
        failures.push(this.#activationCleanupFailure);
      try {
        await this.#state?.close();
      } catch (error) {
        failures.push(error);
      }
      if (failures.length === 1) throw failures[0];
      if (failures.length > 1) {
        throw new AggregateError(failures, "Context Runtime stop failed");
      }
      this.#stopCompleted = true;
      this.#log("info", "runtime.lifecycle.stopped");
    })();
    this.#stopPromise = stopping;
    try {
      await stopping;
    } finally {
      if (!this.#stopCompleted && this.#stopPromise === stopping) {
        this.#stopPromise = null;
      }
    }
  }

  // Activation owns the configuration-revision refresh. Read-only Debug
  // inspection materializes the same Context without it, so History still
  // reads the last checkpointed session after an Agent profile edit.
  async #discardStaleRuntimeSession(): Promise<void> {
    const state = this.#requireState();
    if (!state.discardStaleRuntimeSession) return;
    await state.discardStaleRuntimeSession();
  }

  /** Cancels an in-flight or later activation; a permanent stop follows. */
  abortActivation(reason: Error): void {
    // Sticky: a permanent stop follows, so an activation queued behind this
    // call must not start either.
    this.#activationAborted = true;
    this.#activationAbortController?.abort(reason);
  }

  #deletePermanent(): Promise<void> {
    if (this.#permanentDeletionPromise) return this.#permanentDeletionPromise;
    // Native Provider state lives on the owning Computer. Agent Service only
    // stops the Runtime; the Computer retires its own native files.
    const deletion = this.stop();
    this.#permanentDeletionPromise = deletion;
    void deletion.catch(() => {
      if (this.#permanentDeletionPromise === deletion) {
        this.#permanentDeletionPromise = null;
      }
    });
    return deletion;
  }

  async submitTrustedTurn(
    messages: NonEmptyReadonlyArray<Message>,
  ): Promise<{ readonly runId: string }> {
    this.#assertNotStopped();
    const runId = await this.#requireState().enqueueTrustedTurn(messages);
    this.#log("debug", "trusted_turn.persisted", {
      runId,
      messageCount: messages.length,
      messageIds: messages.map(({ messageId }) => messageId),
    });
    this.#execution?.notifyWorkAvailable();
    this.#notifyActivityChanged();
    return { runId };
  }

  async acceptTrustedNotification(
    executionRunRef: string,
    message: Message,
  ): Promise<"accepted" | "already_accepted"> {
    this.#assertNotStopped();
    const execution = this.#execution;
    if (!execution || execution.activeRunId() !== executionRunRef) {
      throw new Error(
        "Trusted notification target is not the active Local Run",
      );
    }
    const notification: Message = Object.freeze({
      ...message,
      trustedNotification: true,
    });
    const accepted = await this.#requireState().acceptTrustedNotification(
      executionRunRef,
      notification,
    );
    if (accepted.status === "already_accepted") return "already_accepted";
    // "accepted" reports the durable commit, never model consumption. The steer
    // dispatch is tracked by the execution loop's steerOperations and converges
    // through drain/stop exactly like the Inbox steer dispatch above.
    void execution
      .steer(accepted.groupId, [notification], this.#lifecycleController.signal)
      .catch((error: unknown) => {
        this.#log("warn", "trusted_notification.dispatch_failed", {
          error,
          executionRunRef,
        });
      });
    return "accepted";
  }

  async cancelTrustedTurn(
    messages: ExecutionContextMessageDelivery["messages"],
  ): Promise<{
    readonly runId: string;
    readonly status: RunCancellationStatus;
  }> {
    this.#assertNotStopped();
    const canceled = await this.#requireState().cancelTrustedTurn(
      snapshotMessages(messages),
    );
    const status =
      canceled.status === "cancel_requested" && this.#execution
        ? await this.#execution.requestCancellation(canceled.runId)
        : canceled.status;
    this.#notifyActivityChanged();
    if (status === "canceled") {
      const terminal = (await this.#requireState().getLocalRun(canceled.runId))
        ?.terminal;
      if (terminal) this.#emitTurnTerminal(canceled.runId, terminal);
    }
    return { runId: canceled.runId, status };
  }

  async observeTurn(runId: string): Promise<LocalTurnObservation | null> {
    this.#assertNotStopped();
    if (!runId.trim()) throw new TypeError("Local Run ID must not be empty");
    const run = await this.#requireState().getLocalRun(runId);
    if (!run) return null;
    return {
      runId: run.runId,
      status: run.status,
      ...(run.terminal ? { terminal: snapshotTerminal(run.terminal) } : {}),
    };
  }

  async cancelRun(runId: string): Promise<RunCancellationStatus> {
    this.#assertNotStopped();
    if (!runId.trim()) throw new TypeError("Local Run ID must not be empty");
    const status = this.#execution
      ? await this.#execution.requestCancellation(runId)
      : await this.#requireState().cancelLocalRun(runId);
    this.#notifyActivityChanged();
    if (status === "canceled") {
      const terminal = (await this.#requireState().getLocalRun(runId))
        ?.terminal;
      if (terminal) this.#emitTurnTerminal(runId, terminal);
    }
    return status;
  }

  #beginActivation(mode: "start" | "resume"): Promise<void> {
    if (this.#activationCleanupFailure)
      return Promise.reject(this.#activationCleanupFailure);
    if (this.#activationPromise) return this.#activationPromise;
    if (this.#activationAborted)
      return Promise.reject(new ActivationCancelledError());
    const abortController = new AbortController();
    this.#activationAbortController = abortController;
    const task = this.#activate(mode, abortController.signal).finally(() => {
      if (this.#activationPromise === task) this.#activationPromise = null;
      if (this.#activationAbortController === abortController) {
        this.#activationAbortController = null;
      }
      this.#notifyActivityChanged();
    });
    this.#activationPromise = task;
    this.#notifyActivityChanged();
    return task;
  }

  async #activate(
    mode: "start" | "resume",
    signal: AbortSignal,
  ): Promise<void> {
    const state = this.#requireState();
    const agent = this.#runtimeAgent!;
    const features = this.features;
    const previousSession =
      mode === "resume" ? await requirePersistedSession(state) : undefined;
    const startedAt = Date.now();
    const activationId = randomUUID();
    this.#log("info", "runtime.activation.started", {
      activationId,
      mode,
    });
    let activated: ActivatedContextRuntime | null = null;
    let initialSessionCheckpointed = false;
    try {
      // Preflight may wait for a Local Computer to reconnect.
      await this.#services.activator.preflight?.({
        ref: this.ref,
        runtime: this.runtime,
        signal,
        activationId,
      });
      if (signal.aborted || this.#stopped) throw new ActivationCancelledError();
      const executionEpoch = state.executionEpoch?.();
      const savedResources = await state.getExecutionResources?.();
      activated = await this.#services.activator.activate({
        ref: this.ref,
        ...(this.record.sharedTaskScope
          ? { sharedTaskScope: this.record.sharedTaskScope }
          : {}),
        tenantId: this.#ghost.tenantId,
        actorId: this.#ghost.actorId,
        agentType: this.identity.agentType,
        // The tool approval feature matches only where Runs review Runtime
        // permission prompts.
        ...(features.matched.includes(TOOL_APPROVAL_FEATURE_ID)
          ? { permissionReview: true as const }
          : {}),
        renderDeveloperInstructions: (facts) =>
          instructedAgent(features, this.#ghost.agent, this.record, facts)
            .developerInstructions,
        activationId,
        mode,
        ...(previousSession ? { previousSession } : {}),
        acceptedInputSinceMs: () =>
          state.acceptedInputPending?.()
            ? state.earliestAcceptedInputMs?.()
            : undefined,
        ...(executionEpoch ? { executionEpoch } : {}),
        agent,
        runtime: this.runtime,
        resources: this.#ghost.resources,
        checkpointRuntimeSession: async (session) => {
          if (runtimeSessionAwaitsFirstRun(session)) return;
          const checkpointStartedAt = Date.now();
          await state.setRuntimeSession(session);
          this.#log("info", "runtime.activation.session_checkpointed", {
            activationId,
            durationMs: Date.now() - checkpointStartedAt,
          });
        },
        signal,
      });
      if (signal.aborted || this.#stopped) throw new ActivationCancelledError();
      const activeRuntime = activated;
      if (!runtimeSessionAwaitsFirstRun(activated.runtimeSession)) {
        const checkpointStartedAt = Date.now();
        await state.setRuntimeSession(
          activated.runtimeSession,
          activated.executionResources ?? null,
        );
        this.#log("info", "runtime.activation.session_checkpointed", {
          activationId,
          durationMs: Date.now() - checkpointStartedAt,
        });
        initialSessionCheckpointed = true;
      }
      if (
        !initialSessionCheckpointed &&
        !activated.executionResources &&
        savedResources
      ) {
        await state.clearRuntimeSession();
      }
      // A retried Run keeps the resources its first attempt started with.
      let retainedExecutionRunId: string | undefined;
      const execution = new RunLoop({
        executionContextRef: this.ref,
        activationFinishedAtMs: () => this.#activationFinishedAtMs,
        logger: this.#runtimeLogger,
        provider: activated.provider,
        runtimeName: activated.runtimeName,
        runtimeSession: activated.runtimeSession,
        newSession: mode === "start",
        ...(activeRuntime.prepareNextRun
          ? {
              prepareNextRun: async (nextSignal: AbortSignal) => {
                // The terminal callback clears the common case locally; only
                // a retry needs to recheck that its Run is still unsettled.
                const run = retainedExecutionRunId
                  ? await state.getLocalRun(retainedExecutionRunId)
                  : null;
                if (
                  run &&
                  (run.status === "queued" || run.status === "running")
                )
                  return true;
                retainedExecutionRunId = undefined;
                if (await activeRuntime.prepareNextRun!(nextSignal))
                  return true;
                this.#replaceChangedRuntime(activeRuntime);
                return false;
              },
            }
          : {}),
        ...(activeRuntime.executionResources
          ? {
              beforeStartRun: async (runId: string) => {
                if (!state.setExecutionResources)
                  throw new Error(
                    "Agent resources require execution checkpoints",
                  );
                // Checkpointed with the Run's Session, not before it starts.
                await state.setExecutionResources(
                  activeRuntime.executionResources!,
                );
                retainedExecutionRunId = runId;
              },
            }
          : {}),
        ...(this.#services.statusPublisher
          ? { runtimeStatusPublisher: this.#services.statusPublisher }
          : {}),
        state,
        onActiveRunContextChanged: (context) =>
          activeRuntime.setActiveRunContext(context),
        onActivityChanged: () => this.#notifyActivityChanged(),
        onRunTerminal: (runId, terminal) => {
          if (retainedExecutionRunId === runId)
            retainedExecutionRunId = undefined;
          this.#emitTurnTerminal(runId, terminal);
        },
        // Feature-aware canonical rebuild plus ordered input contributions run
        // here — inside the loop's try/requeue/terminal boundary — so a
        // throwing contribution fails or requeues execution AFTER the durable
        // acceptance fact was already returned. Plain canonical Messages keep
        // their acceptedNotification payload and are re-rendered with the
        // contributor; other Messages pass through unchanged. There is no
        // silent fallback and nothing transient is persisted.
        prepareInput: (message) =>
          features.prepareInput(
            renderAcceptedNotification(
              message as unknown as Record<string, unknown>,
              (input) => features.notificationContext(input),
              // Coordination reminders cover the Agent's own initiations.
              this.#ghost.actorId,
            ),
          ),
        onRunEvent: (event) => features.onRunEvent(event),
        onRunClaimed: (runId, messages) => {
          for (const message of messages)
            this.#observeInboxInput(message, { kind: "enqueue", runId });
        },
        onWorkStateRefreshed: () => this.#takeUpMessageSteers(),
      });
      this.#activatedRuntime = activated;
      this.#execution = execution;
      this.#providerReady = true;
      await state.refreshWorkState?.();
      if (!this.#providerReady) {
        throw new Error("Context Runtime was fenced during activation");
      }
      this.#activationFinishedAtMs = Date.now();
      execution.start({ workStateAlreadyFresh: true });
      // Steers listed by the activation read wait for this execution.
      this.#takeUpMessageSteers();
      this.#notifyActivityChanged();
      const durationMs = Date.now() - startedAt;
      this.#log("info", "runtime.activation.completed", {
        activationId,
        mode,
        runtimeName: activated.runtimeName,
        durationMs,
      });
    } catch (error) {
      if (error instanceof ContextRuntimeCleanupError)
        this.#activationCleanupFailure = error;
      if (activated) {
        if (this.#activatedRuntime === activated) {
          this.#providerReady = false;
          this.#execution = null;
          this.#activatedRuntime = null;
        }
        try {
          await activated.deactivate();
        } catch (cleanupError) {
          this.#activationCleanupFailure = new ContextRuntimeCleanupError([
            error,
            cleanupError,
          ]);
          throw this.#activationCleanupFailure;
        }
      }
      this.#providerReady = false;
      const waitingForComputer = isLocalComputerOfflineError(error);
      // A cancelled activation is expected, not a failure to alert on.
      const quiet = waitingForComputer || signal.aborted;
      const ownsFailureAlert = quiet ? false : claimAgentFailureAlert(error);
      this.#log(
        quiet ? "info" : ownsFailureAlert ? "error" : "warn",
        waitingForComputer
          ? "runtime.activation.waiting_for_computer"
          : "runtime.activation.failed",
        {
          activationId,
          mode,
          durationMs: Date.now() - startedAt,
          error,
          ...(quiet || ownsFailureAlert ? {} : { alertAggregated: true }),
        },
      );
      if (
        error instanceof LocalComputerModelError &&
        !signal.aborted &&
        !this.#stopped
      ) {
        await this.#failQueuedRuns(error.failure, activationId);
      }
      throw signal.aborted &&
        !(error instanceof ActivationCancelledError) &&
        !(error instanceof ContextRuntimeCleanupError)
        ? new ActivationCancelledError()
        : error;
    }
  }

  /**
   * Activation cannot succeed until the Agent's configuration changes, so
   * every queued Run would wait silently. Finish each one as failed with the
   * public cause, so the Room shows it on the Human's message. A later input
   * activates again and meets the current configuration.
   */
  async #failQueuedRuns(
    failure: RuntimeExecutionFailure,
    activationId: string,
  ): Promise<void> {
    const state = this.#requireState();
    const epoch = state.executionEpoch?.();
    const terminal = {
      type: "failed",
      error: "Runtime activation failed",
      failure,
    } as const;
    try {
      for (;;) {
        const claimed = await state.claimLocalRun();
        if (!claimed) return;
        // Opening the Run status lets TeamHub show the terminal in the Room.
        if (this.#services.statusPublisher && epoch) {
          await this.#services.statusPublisher
            .open({
              executionId: claimed.runId,
              ref: this.ref,
              epoch,
              sourceInboxIds: [
                ...new Set(
                  claimed.messages.flatMap(
                    ({ sourceInboxIds }) => sourceInboxIds ?? [],
                  ),
                ),
              ],
            })
            .catch((error: unknown) => {
              this.#log("warn", "runtime_status.open_failed", {
                runId: claimed.runId,
                error,
              });
            });
        }
        const settled = await state.finishLocalRun(claimed.runId, terminal);
        this.#log("info", "runtime.activation.queued_run_failed", {
          activationId,
          runId: claimed.runId,
          failureCode: failure.code,
        });
        if (settled !== "upstream_canceled")
          this.#emitTurnTerminal(claimed.runId, terminal);
      }
    } catch (error) {
      // The activation error stays the outcome; unsettled Runs stay queued.
      this.#log("warn", "runtime.activation.queued_run_fail_failed", {
        activationId,
        error,
      });
    }
  }

  // The Agent's effective resources changed before the next Run: drain the
  // current Runtime and activate it again with the new resources.
  #replaceChangedRuntime(runtime: ActivatedContextRuntime): void {
    if (this.#activatedRuntime !== runtime || this.#stopped) return;
    this.#providerReady = false;
    this.#execution?.requestDrain({ cancelActive: false });
    this.#notifyActivityChanged();
    this.#log("info", "runtime.lifecycle.interrupted", {
      error: new AgentResourceConfigurationChangedError(),
    });
    if (
      this.#desiredRuntimeState !== "active" ||
      this.#runtimeRecoveryPromise
    ) {
      return;
    }
    const recovery = this.#recoverRuntime(runtime)
      .catch((error: unknown) => {
        this.#log("error", "runtime.recovery.failed", { error });
      })
      .finally(() => {
        if (this.#runtimeRecoveryPromise === recovery) {
          this.#runtimeRecoveryPromise = null;
        }
        this.#notifyActivityChanged();
      });
    this.#runtimeRecoveryPromise = recovery;
  }

  async #recoverRuntime(runtime: ActivatedContextRuntime): Promise<void> {
    const startedAt = Date.now();
    const preparationExecution = this.#execution;
    let cleanupFailure: unknown;
    if (this.#activatedRuntime === runtime) {
      try {
        await this.#deactivate({ cancelActive: false, requireIdle: false });
      } catch (error) {
        cleanupFailure = error;
      }
    }
    if (cleanupFailure) {
      throw new Error("Runtime recovery cleanup failed", {
        cause: cleanupFailure,
      });
    }
    if (this.#desiredRuntimeState !== "active" || this.#stopped) return;

    // A Context whose Runtime Session awaits its first Run has nothing to resume.
    const mode =
      (await this.#requireState().getRuntimeSession()) === null
        ? "start"
        : "resume";
    const maxAttempts = 2;
    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
      try {
        await this.#beginActivation(mode);
        this.#log("info", "runtime.recovery.completed", {
          attempt,
          durationMs: Date.now() - startedAt,
        });
        return;
      } catch (error) {
        if (
          this.#desiredRuntimeState !== "active" ||
          this.#stopped ||
          error instanceof ActivationCancelledError ||
          error instanceof ContextRuntimeCleanupError
        ) {
          return;
        }
        this.#log(
          attempt < maxAttempts ? "warn" : "error",
          "runtime.recovery.activation_failed",
          { attempt, maxAttempts, error },
        );
        if (attempt === maxAttempts && preparationExecution) {
          await preparationExecution.failNextRunPreparation(
            error,
            this.#lifecycleController.signal,
          );
        }
      }
    }
  }

  #deactivate(options: {
    readonly cancelActive: boolean;
    readonly requireIdle: boolean;
  }): Promise<boolean> {
    if (this.#deactivationPromise) return this.#deactivationPromise;
    const task = this.#performDeactivation(options).finally(() => {
      if (this.#deactivationPromise === task) this.#deactivationPromise = null;
      this.#notifyActivityChanged();
    });
    this.#deactivationPromise = task;
    this.#notifyActivityChanged();
    return task;
  }

  async #performDeactivation(options: {
    readonly cancelActive: boolean;
    readonly requireIdle: boolean;
  }): Promise<boolean> {
    if (this.#activationPromise) {
      await this.#activationPromise;
    }
    if (!this.#activatedRuntime) return true;
    const execution = this.#execution;
    const activated = this.#activatedRuntime;
    const failures: unknown[] = [];

    try {
      await execution?.drain({ cancelActive: options.cancelActive });
    } catch (error) {
      failures.push(error);
    }
    if (
      failures.length === 0 &&
      options.requireIdle &&
      this.#providerReady &&
      this.#requireState().hasPendingWork()
    ) {
      execution?.start();
      this.#notifyActivityChanged();
      return false;
    }

    try {
      await activated.deactivate();
      this.#providerReady = false;
      this.#execution = null;
      this.#activatedRuntime = null;
      this.#idleSince = null;
    } catch (error) {
      // A failed cleanup is not proof that the native writer stopped. Retain
      // the handle so another stop cannot falsely report success and permit
      // a replacement Context to start alongside it.
      failures.push(error);
    }
    if (failures.length === 1) throw failures[0];
    if (failures.length > 1) {
      throw new AggregateError(failures, "Context Runtime cleanup failed");
    }
    this.#log("info", "runtime.lifecycle.suspended");
    return true;
  }

  #isIdle(): boolean {
    if (
      !this.#providerReady ||
      this.#activationPromise !== null ||
      this.#deactivationPromise !== null ||
      (this.#execution?.activeOperations ?? 0) > 0
    ) {
      return false;
    }
    return !this.#requireState().hasPendingWork();
  }

  // One work-state read at a time; a hint during a read reads once more.
  #readMessageSteers(): void {
    if (this.#steerRead) {
      this.#steerReadAgain = true;
      return;
    }
    const state = this.#state;
    if (!state?.refreshWorkState) {
      this.#takeUpMessageSteers();
      return;
    }
    this.#steerRead = (async () => {
      do {
        this.#steerReadAgain = false;
        await state.refreshWorkState!();
        this.#takeUpMessageSteers();
        // A queued Run the read found still needs the loop.
        if (state.hasQueuedRuns()) this.#execution?.notifyWorkAvailable();
      } while (this.#steerReadAgain && !this.#stopped);
    })()
      .catch((error: unknown) => {
        // The fallback scan or the next hint reads them again.
        this.#log("warn", "message_steer.read_failed", { error });
      })
      .finally(() => {
        this.#steerRead = null;
      });
  }

  // Hands each new Message steer to the running Run. Without an execution it
  // stays listed, so activation reads it again.
  #takeUpMessageSteers(): void {
    const execution = this.#execution;
    const state = this.#state;
    if (!execution || !state?.takeMessageSteers || this.#stopped) return;
    for (const steer of state.takeMessageSteers()) {
      if (steer.message.runtimeResponses?.length) {
        void this.#answerRuntimeQuestion(steer);
        continue;
      }
      this.#observeInboxInput(steer.message, {
        kind: "steer",
        groupId: steer.groupId,
      });
      void execution
        .steer(
          steer.groupId,
          [steer.message],
          this.#lifecycleController.signal,
          steer.inboxId,
        )
        .catch((error: unknown) => {
          this.#log("warn", "message_steer.dispatch_failed", {
            groupId: steer.groupId,
            inputId: steer.inputId,
            error,
          });
        });
    }
  }

  // A Human's answer reaches the Run that asked; once that Run is gone the
  // answer is settled as uncertain so the Context no longer waits on it.
  async #answerRuntimeQuestion(steer: MessageSteer): Promise<void> {
    const state = this.#requireState();
    const runId = steer.runId;
    let outcome: "applied" | "uncertain" = "uncertain";
    try {
      const execution = this.#execution;
      if (execution && runId && execution.activeRunId() === runId) {
        for (const response of steer.message.runtimeResponses ?? [])
          await execution.respondToHumanInteraction(response);
        outcome = "applied";
      }
    } catch (error) {
      this.#log("warn", "message_steer.runtime_response_failed", {
        groupId: steer.groupId,
        error,
      });
    }
    if (!runId) return;
    try {
      await state.completeSteer(steer.groupId, runId, outcome);
    } catch (error) {
      this.#log("warn", "message_steer.settle_failed", {
        groupId: steer.groupId,
        error,
      });
    }
  }

  #observeInboxInput(
    message: Message,
    dispatch:
      | { readonly kind: "enqueue"; readonly runId: string }
      | { readonly kind: "steer"; readonly groupId: string },
  ): void {
    try {
      const fact = inboxInputFact(message, dispatch);
      if (fact) this.#features?.afterInboxInputAccepted(fact);
    } catch (error) {
      this.#log("warn", "inbox_input.observation_failed", {
        messageId: message.messageId,
        error,
      });
    }
  }

  #notifyActivityChanged(): void {
    if (!this.#state || this.#stopCompleted) return;
    let activity: ContextActivity;
    try {
      activity = this.#isIdle() ? "idle" : "busy";
    } catch {
      return;
    }
    if (activity === "idle") {
      this.#idleSince ??= Date.now();
    } else {
      this.#idleSince = null;
    }
    if (activity === this.#reportedActivity) return;
    this.#reportedActivity = activity;
    try {
      this.#onActivityChanged(activity);
    } catch (error) {
      this.#log("warn", "shell.activity_callback_failed", { error });
    }
  }

  #emitTurnTerminal(runId: string, terminal: LocalTurnTerminal): void {
    if (!this.#forwardTurnTerminals) return;
    try {
      if (this.#host.owns(this)) this.usePreparedContext();
      this.#features?.onRunTerminal({
        runId,
        terminal: snapshotTerminal(terminal),
      });
    } catch (error) {
      this.#log("warn", "trusted_turn.listener_failed", { runId, error });
    }
  }

  #requireState(): ContextRuntimeStatePort {
    if (!this.#state) throw new Error("Context Runtime state is unavailable");
    return this.#state;
  }

  #assertNotStopped(): void {
    if (this.#stopped)
      throw runtimeError("stopped", "Context Runtime has been stopped");
  }

  #log(
    level: "debug" | "info" | "warn" | "error",
    event: string,
    fields: Record<string, unknown> = {},
  ): void {
    this.#runtimeLogger.log(level, event, fields);
  }
}

/** Internal control-flow marker: the submission gate declined at the fence. */
class FeatureSubmissionSkippedError extends Error {
  constructor() {
    super("Feature submission skipped at the final boundary");
    this.name = "FeatureSubmissionSkippedError";
  }
}

export class TerminalExecutionContextError extends AgentManagerError {
  constructor(ref: ExecutionContextRef) {
    super(
      "binding_not_found",
      `Execution Context ${encodeExecutionContextRef(ref)} is terminal`,
    );
    this.name = "TerminalExecutionContextError";
  }
}

class ActivationCancelledError extends Error {
  constructor() {
    super("Context Runtime activation was cancelled");
    this.name = "ActivationCancelledError";
  }
}

class AgentResourceConfigurationChangedError extends Error {
  constructor() {
    super("Agent resource configuration changed");
  }
}

const invokeClose = (operation: () => void | Promise<void>): Promise<void> => {
  try {
    return Promise.resolve(operation());
  } catch (error) {
    return Promise.reject(error);
  }
};

const snapshotMessages = (
  messages: ExecutionContextMessageDelivery["messages"],
): NonEmptyReadonlyArray<Message> => {
  const first = snapshotMessage(messages[0]);
  return [first, ...messages.slice(1).map(snapshotMessage)];
};

const snapshotMessage = (
  message: ExecutionContextMessageDelivery["messages"][number],
): Message => ({
  messageId: message.messageId,
  ...(message.notificationRender
    ? { notificationRender: { ...message.notificationRender } }
    : {}),
  ...(message.invocationMessageIds
    ? { invocationMessageIds: [...message.invocationMessageIds] }
    : {}),
  ...(message.runtimeResponses
    ? { runtimeResponses: structuredClone(message.runtimeResponses) }
    : {}),
  rawMessage: message.rawMessage,
  segments: [
    { ...message.segments[0] },
    ...message.segments.slice(1).map((segment) => ({ ...segment })),
  ],
  ...(message.sourceInboxIds
    ? { sourceInboxIds: [...message.sourceInboxIds] }
    : {}),
});

const snapshotTerminal = (terminal: LocalTurnTerminal): LocalTurnTerminal =>
  terminal.type === "succeeded"
    ? Object.freeze({
        type: "succeeded",
        ...(terminal.finalResponse === undefined
          ? {}
          : { finalResponse: terminal.finalResponse }),
      })
    : terminal.type === "failed"
      ? Object.freeze({ type: "failed", error: terminal.error })
      : Object.freeze({ type: "canceled" });

const requirePersistedSession = async (state: ContextRuntimeStatePort) => {
  const session = await state.getRuntimeSession();
  if (session === null || session === undefined) {
    throw new Error(
      "Context Runtime has no persisted Runtime Session to resume",
    );
  }
  return session;
};

const configuredRuntimeName = (runtime: unknown): string => {
  if (typeof runtime !== "object" || runtime === null) return "unknown";
  const settings = runtime as Record<string, unknown>;
  if (settings.type === "local") {
    const placement = settings.placement;
    if (typeof placement === "object" && placement !== null) {
      const runtimeType = (placement as Record<string, unknown>).runtimeType;
      if (typeof runtimeType === "string" && runtimeType.length > 0) {
        return runtimeType;
      }
    }
  }
  return typeof settings.type === "string" && settings.type.length > 0
    ? settings.type
    : "unknown";
};

const runtimeError = (
  code: "busy" | "stopped",
  message: string,
): Error & { code: "busy" | "stopped" } =>
  Object.assign(new Error(message), { code });

const idleCleanupRequiresIntervention = (error: unknown): boolean => {
  if (isUnconfirmedContextRuntimeCleanup(error)) return true;
  if (error instanceof AggregateError) {
    return error.errors.some(idleCleanupRequiresIntervention);
  }
  return false;
};

const snapshotConfiguration = <T>(value: T): T =>
  snapshotConfigurationValue(value, new WeakMap<object, object>());

const snapshotConfigurationValue = <T>(
  value: T,
  snapshots: WeakMap<object, object>,
): T => {
  if (
    value === null ||
    (typeof value !== "object" && typeof value !== "function")
  ) {
    return value;
  }
  if (typeof value === "function") return value;
  const existing = snapshots.get(value);
  if (existing) return existing as T;
  if (Array.isArray(value)) {
    const snapshot: unknown[] = [];
    snapshots.set(value, snapshot);
    snapshot.push(
      ...value.map((entry) => snapshotConfigurationValue(entry, snapshots)),
    );
    return Object.freeze(snapshot) as T;
  }
  const snapshot: Record<string, unknown> = {};
  snapshots.set(value, snapshot);
  for (const [key, entry] of Object.entries(value)) {
    snapshot[key] = snapshotConfigurationValue(entry, snapshots);
  }
  return Object.freeze(snapshot) as T;
};