@open-everywhere/core 0.1.0

package/agent/model/routing.ts

@@ -0,0 +1,834 @@
+// Domain-routed model — per-channel-group model / provider / reasoning. GENERIC CORE:
+// this module owns the routing DECISION (which route applies to a call's surface) and the
+// thin per-selection wrapper skeleton (fail-soft dispatch, memoization); everything
+// vendor-shaped — how a model id becomes a model instance, how a route's provider hints
+// map onto one call's options — lives behind the ModelBackend seam, implemented per model
+// transport in `@open-everywhere/adapters` (reference: the Vercel AI Gateway backend).
+// Core stays portable: a self-host on OpenRouter / a direct provider SDK writes its own
+// backend and the schema + resolution + wrapper are unchanged (docs/core-app-separation.md).
+//
+// HOW IDENTITY REACHES THE ROUTER (eve 0.22 native `defineDynamic`): the turn model is
+// authored as `defineAgent({ model: defineDynamic({ fallback, events }) })` — eve runs the
+// `step.started` resolver INSIDE the harness and hands it the calling `ctx`
+// (DynamicResolveContext), which is structurally a BindableContext: `ctx.session.auth`
+// carries the same current/initiator principals, `ctx.channel.kind` the platform. So the
+// resolver reconstructs the surface (bindFrom → domain key + dm/public match) straight from
+// ctx and resolves the ModelRoute — NO ALS read, NO module-global surface hint. This is the
+// whole point of the migration: the prior wrapper read the caller off eve's session ALS,
+// which is inert on Vercel's compiled build, and a "surface hint" hook was bolted on to
+// paper over it (bit prod twice). The native resolver ctx works on the hosted build because
+// it is populated by the harness, not scraped from an async-context reach.
+//
+// WHY `step.started`, NOT `turn.started` (eve 0.22 dynamic-model contract — the fix for the
+// regression the migration introduced): the resolver returns a per-selection routed model
+// INSTANCE (makeRoutedModel — a LanguageModel wrapper, needed because eve forwards only the
+// agent-STATIC `reasoning` to the model call, so per-domain reasoning must ride the model).
+// eve's dynamic-model dispatcher (context/dynamic-model-lifecycle.ts dispatchDynamicModelEvent)
+// REJECTS a provider-object return at session/turn scope — those selections must be
+// serialized (a model id string), so a LanguageModel instance is discarded and eve silently
+// falls back to the static `fallback`. Only `step.started` (a virtual, non-serialized
+// selection — LiveStepDynamicModelSelectionKey) accepts an instance and actually runs it
+// (harness/tool-loop.ts resolveActiveRuntimeModel uses `selection.model` directly). Wiring
+// the resolver at `turn.started` therefore killed routing outright AND, because the wrapper's
+// doGenerate never ran, left every usage_events row unstamped (dead cost attribution). The
+// resolver fires once per step now rather than once per turn — cheap (config reads + a memoized
+// pick lookup) and fail-soft, and identity is re-derived from the same ctx each step.
+//
+// WHAT THE RESOLVER RETURNS: `resolvePrimaryModel(ctx, …)` ALWAYS returns a RoutableModel —
+// never null (OPE-412). Routed surfaces get a thin per-selection wrapper; every other path
+// (unrouted, no-op, fail-soft) gets the DEFAULT model constructed concretely, at the exact id
+// eve's static fallback would have run. The wrapper bakes in the route it
+// resolved from ctx and applies it on each doGenerate/doStream — reasoning override
+// (eve forwards only the agent-STATIC `reasoning` to the model call, so per-domain reasoning
+// must ride the model instance) plus the backend's provider-option mapping. Unlike the old
+// wrapper it does NO identity work at call time: the route is a closure constant, resolved
+// once per turn from ctx.
+//
+// ROLES — this file routes ONE slot, and that is deliberate:
+//   primary — `defineAgent.model` = `defineDynamic`; resolved from ctx each step.started.
+//   utility — routed OUTSIDE a session, by SCOPE rather than ctx, for its live consumers: the
+//             dream cycle's judge/distiller and the failure-facet judge
+//             (adapters agent/model/dream-judge.ts `modelRouteFor("utility", …)`).
+//             🔴 It does NOT route compaction, and cannot. eve resolves an authored
+//             `defineAgent.compaction.model` through the AGENT-LEVEL `model` field, so any
+//             model INSTANCE in that slot kills the turn while the agent model is dynamic
+//             (OPE-670). agent/agent.ts authors no compaction model, so eve summarises with the
+//             live turn model — already routed by this file, on the primary path.
+//
+// Per-row cost attribution stamps the resolved id into model/model-stamp.ts's per-session
+// slot; hooks/spend.ts reads it back to attach an exact model to each usage_events row
+// rather than leaning on the assumed-model fallback (per-domain routing means more than one
+// model can be in play in one deployment). The PRIMARY id is stamped by the resolver itself
+// (resolvePrimaryModel, below) — inside the harness-supplied step context, the SAME context
+// the spend hook reads, so the stamp is guaranteed visible REGARDLESS of whether the AI SDK
+// preserves the async context into the wrapper's doGenerate. The wrapper's dispatch ALSO
+// stamps (belt-and-braces).
+//
+// FAIL-SOFT, deliberately NOT fail-closed: routing is a tuning preference, not an access
+// boundary. The resolver NEVER throws (a thrown resolver breaks the turn) — on ANY failure
+// (unbindable ctx, config not registered, resolver error) it resolves to the DEFAULT model and
+// the turn runs on exactly the model eve's static fallback would have picked. Each distinct
+// failure reason is logged once per instance so a silent downgrade is still visible in logs.
+//
+// 🔴 WHY THE FAIL-SOFT PATHS RETURN A MODEL RATHER THAN `null` (OPE-412). They used to return
+// `null`, which eve 0.32 reads as "no dynamic selection" and answers by resolving the static
+// `defineDynamic({ fallback })` reference itself. eve 0.33 REMOVES that affordance: a dynamic
+// resolver that returns null THROWS. Returning `deps.backend.model(defaults.primary.id)`
+// instead is behaviour-preserving TODAY and removes the 0.33 break in advance:
+//   - the id is identical. agent.ts wires `fallback: DEFAULT_MODEL` and `primary.id:
+//     DEFAULT_MODEL` from the same constant, so the concrete model IS eve's static fallback.
+//   - the audit row is unchanged. Every one of these sites already called
+//     `stampModelCall(defaults.primary.id)` — the code already ASSERTED "this call runs the
+//     default"; the return now matches the stamp instead of implying it.
+//   - providerOptions are unchanged. eve's normalizer (runtime/agent/resolve-model.ts
+//     normalizeDynamicRuntimeModelResult) fills a selection that sets no `modelOptions` from
+//     `fallback.providerOptions`, and tool-loop.ts passes the SAME reference
+//     (`dynamicModelDefaultReference ?? modelReference`) as both that `fallback` and the
+//     null-path model — so the two paths carry byte-identical provider options.
+//   - the construction cost is nil: `gateway(id)` is a plain object build, no I/O, measured at
+//     ~1µs, once per step. (NB it is NOT memoized — `makeRoutedModel`'s `inner` map only
+//     memoizes WITHIN one wrapper, and these sites bypass the wrapper entirely. ~1µs/step does
+//     not justify a cache.)
+// The one non-identical detail, and it is cosmetic: eve labels an instance selection
+// `formatLanguageModelGatewayId(model)` = `gateway/<id>` rather than the bare `<id>`. Both are
+// already true of every ROUTED step today, so this makes the fail-soft path match the routed path
+// rather than introducing a new state.
+//
+// ✅ THE WINDOW IS NO LONGER LOST ON ANY OF THESE PATHS (OPE-412, and this supersedes an earlier
+// note here that called the fix "0.33-only" — it was WRONG: `PublicAgentModelSelectionDefinition`
+// exists at 0.32.0). Returning a bare model instance leaves `reference.contextWindowTokens`
+// undefined, which freezes eve's compaction-threshold rescale. The app now wraps THIS FUNCTION'S
+// RETURN — every path of it, at one site — in eve's selection form
+// `{ model, modelContextWindowTokens, modelOptions }` (agent/agent.ts primaryModelSelection), so
+// the window rides every selection. That wrap deliberately lives at the `step.started` boundary
+// and NOT in here: this module is generic core over `RoutableModel`, and threading a selection
+// type through six return paths is exactly the shape in which one path silently forgets it.
+// Keep returning bare `TModel` here.
+
+import type { ModelRole, ModelRoute, Domain, NamedKnobLayer, DomainMatch, ModelReasoning } from "../memory/domain.js";
+import { modelRouteFor, domainMatchFor, reasoningCeilingFor, domainForChannel, criteriaDomain } from "../memory/domain.js";
+import { getConfig } from "../access/config.js";
+import { domainKeyOf, resolvePartition } from "../memory/partition.js";
+import { bindFrom, deploymentOrg, type BindableContext } from "../identity/binding.js";
+// A LEAF import: access/worker-seat-state.ts reaches only `eve/context`, so it closes no cycle here.
+import { currentWorkerWake } from "../access/worker-seat-state.js";
+import { stampModelCall } from "./model-stamp.js";
+import { noteTurnStep, reportStepBoundary, withWrapUpNotice, turnBackstopModel, wrapUpNotice, boundaryStopReply } from "./step-boundary.js";
+import type { ModelPolicy } from "./policy.js";
+import { applyModelPolicyToRoute } from "./policy.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { isDmAnchorWindowToken, isSupervisorShapedToken } from "../channels/window-key.js";
+// The per-routine model role's ONE reader (OPE-1627). `routines/routine.ts` is framework-free and
+// imports nothing from this plane, so the edge is one-way and no cycle can form through it.
+import { routineModelRoleStamped } from "../routines/routine.js";
+import { captureArmed, captureSiteFrom, noteUncalledModelStep, withCapture } from "./call-capture.js";
+import { withStreamDropRetry } from "./stream-drop-retry.js";
+import {
+  abBucketKey,
+  abThreadKey,
+  applyModelAb,
+  decideModelAb,
+  modelAbTestArmed,
+  noteModelAbArm,
+  readModelArm,
+  registeredModelAbTest,
+  resolveModelArm,
+  stampModelArm,
+  type ModelAbInput,
+  type ModelAbTest,
+} from "./ab-test.js";
+
+// Why-null / warning diagnostics, logged once per distinct reason per instance so a broken
+// resolution is still diagnosable without spamming the log on every turn.
+const loggedOnce = new Set<string>();
+function logOnce(kind: "warn" | "log", reason: string): void {
+  if (loggedOnce.has(reason)) return;
+  loggedOnce.add(reason);
+  (kind === "warn" ? console.warn : console.log)(`[open-everywhere:model-routing] ${reason}`);
+}
+
+/**
+ * The call-option surface the router touches. Structurally a subset of the AI SDK's
+ * LanguageModel*CallOptions (`reasoning` is the spec-level provider-agnostic effort
+ * field); everything else passes through untouched.
+ */
+export interface RoutedCallOptions {
+  reasoning?: string;
+  providerOptions?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * The minimal LanguageModel shape the wrapper needs. `doGenerate`/`doStream` params
+ * and results are the backend's business — the wrapper only rewrites the shared
+ * RoutedCallOptions subset and forwards.
+ */
+export interface RoutableModel {
+  readonly specificationVersion: string;
+  readonly provider: string;
+  readonly modelId: string;
+  readonly supportedUrls: unknown;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  doGenerate(options: any): PromiseLike<any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  doStream(options: any): PromiseLike<any>;
+}
+
+/**
+ * A model transport (adapter seam). Owns everything vendor-shaped:
+ *  - `model(id)` — model id (in THIS backend's namespace) → model instance.
+ *  - `applyOptions(route, options, ids)` — map the route's provider hints
+ *    (`ModelRoute.providers`, static transport defaults) onto one call's options.
+ *    A backend with no such concept returns `options` unchanged; core has already
+ *    applied the generic fields (id selection, reasoning) before models are called.
+ */
+export interface ModelBackend<TModel extends RoutableModel = RoutableModel> {
+  model(id: string): TModel;
+  applyOptions(
+    route: ModelRoute,
+    options: RoutedCallOptions,
+    ids: { readonly id: string; readonly defaultId: string },
+  ): RoutedCallOptions;
+}
+
+/** Injectable seams (tests swap all; live wiring uses liveIdentity + a real backend). The
+ *  calling surface is NO LONGER a dep — it is derived from the harness-supplied ctx (see
+ *  resolvePrimaryModel). What remains are the config/identity reads and the backend. */
+export interface RoutingDeps<TModel extends RoutableModel = RoutableModel> {
+  /** The configured domains (throws → treated as "no routes"). */
+  readonly domains: () => readonly Domain[];
+  /** The configured role presets (a rung in the route merge; absent/throws → no rung). */
+  readonly roles?: () => readonly NamedKnobLayer[];
+  /**
+   * The org's model-policy envelope (model/policy.ts), or undefined for none configured.
+   * Optional: a dep that omits this reproduces exactly today's behaviour (no allow-list
+   * clamp, no reasoning ceiling, no provider deny) — the backward-compat guarantee lives
+   * here rather than a getConfig() read, so tests that build RoutingDeps directly (no
+   * registered AppConfig) are unaffected.
+   */
+  readonly modelPolicy?: () => ModelPolicy | undefined;
+  /**
+   * The runtime DOMAIN model/reasoning PICK for `domainName` — the DB-overlay half of the
+   * model-policy envelope (control/writes.ts set_domain_model / clear_domain_model): a
+   * domain admin's runtime self-serve CHOICE, layered UNDER the git route and OVER the
+   * envelope clamp (see resolveRoute — the pick overrides the git route's id/reasoning
+   * BEFORE applyModelPolicyToRoute runs, so it's still allow-list/ceiling-clamped as a
+   * backstop). `domainName` is resolved by the SAME single-hop rule spend/caps.ts's
+   * domainNameForScope uses (an explicit domain, or the dm/public criteria domain — the
+   * `org` pseudo-domain is deliberately NOT a pick-able scope). Optional and FAIL-SOFT: a
+   * dep that omits this (or throws, or resolves null) reproduces exactly today's
+   * git-route-only behaviour. `liveIdentity`'s implementation CACHES the read (see
+   * liveDomainModelPick): the primary resolver runs once per turn and resolves BOTH roles
+   * (which share a domainName), so the second read hits the cache; the spend/connector
+   * overlays are consulted once per turn and have no such cache to mirror.
+   */
+  readonly domainModelPick?: (domainName: string) => Promise<DomainModelPick | null>;
+  /**
+   * The declared MODEL A/B TEST (model/ab-test.ts, OPE-34) — champion vs challenger, or undefined
+   * for none declared. Optional and INERT-when-absent, exactly like `modelPolicy`: a dep that omits
+   * this (or throws, or returns an unarmed test) reproduces today's routing byte for byte. Read
+   * once per primary resolution and passed to `resolveRoute` as its `ab` argument. `liveIdentity`
+   * reads the app's BOOT REGISTRATION rather than `getConfig()`, because an A/B percentage is a
+   * model-choice preference and has no business on the access plane — see model/ab-test.ts.
+   */
+  readonly modelAbTest?: () => ModelAbTest | undefined;
+  readonly backend: ModelBackend<TModel>;
+}
+
+/** The shape a runtime domain-model-pick read resolves to (operational/store.ts's
+ *  DomainModelRow, minus the row's own org/domain/setBy/updatedAt bookkeeping — the
+ *  resolver only needs the two fields that can override a route). */
+export interface DomainModelPick {
+  readonly modelId?: string;
+  readonly reasoning?: ModelReasoning;
+}
+
+// How long a resolved domain-model pick is trusted before the next read re-hits the store.
+// The primary resolver runs once per turn and reads the pick for its domain twice (once per
+// role — primary and the stamped utility, which share a domainName), so this memo lets the
+// second read reuse the first within a turn; 15s is short enough that an admin's
+// set_domain_model takes effect within roughly one turn's latency. A FAILED read is never
+// cached (see liveDomainModelPick) — only a successful resolution (including an explicit
+// "no pick") is memoized, so a transient store outage recovers as soon as it clears.
+const DOMAIN_MODEL_PICK_TTL_MS = 15_000;
+interface DomainModelPickCacheEntry {
+  readonly value: DomainModelPick | null;
+  readonly expiresAt: number;
+}
+const domainModelPickCache = new Map<string, DomainModelPickCacheEntry>();
+
+/** Cached read of one domain's runtime model pick, keyed by (org, domainName). Fail-soft
+ *  at the caller (liveIdentity.domainModelPick) — a store throw here propagates up and is
+ *  swallowed there, never cached, so the next call retries rather than sticking with a
+ *  stale failure. */
+async function liveDomainModelPick(org: string, domainName: string): Promise<DomainModelPick | null> {
+  const key = `${org} ${domainName}`;
+  const now = Date.now();
+  const cached = domainModelPickCache.get(key);
+  if (cached && cached.expiresAt > now) return cached.value;
+  const row = await getOperationalStore().getDomainModel(org, domainName);
+  const value: DomainModelPick | null = row ? { modelId: row.modelId, reasoning: row.reasoning } : null;
+  domainModelPickCache.set(key, { value, expiresAt: now + DOMAIN_MODEL_PICK_TTL_MS });
+  return value;
+}
+
+/**
+ * The live config/identity seams — how the router learns the DOMAINS/ROLES/POLICY and the
+ * runtime DB pick. (The CALLER identity is no longer a seam here — it comes from the
+ * harness ctx handed to the resolver.) Exported so an adapter package can compose these
+ * with its backend without re-reaching into the config registry.
+ */
+export const liveIdentity: Pick<RoutingDeps, "domains" | "roles" | "modelPolicy" | "domainModelPick" | "modelAbTest"> = {
+  domains: () => getConfig().loadDomains(),
+  roles: () => getConfig().loadRoles?.() ?? [],
+  modelPolicy: () => getConfig().loadModelPolicy?.(),
+  modelAbTest: () => registeredModelAbTest(),
+  domainModelPick: async (domainName) => {
+    try {
+      return await liveDomainModelPick(deploymentOrg(), domainName);
+    } catch {
+      return null; // fail-soft — a store failure never blocks the model call, git route stands
+    }
+  },
+};
+
+/**
+ * The surface identity a model call routes by, reconstructed from the harness-supplied
+ * ctx (DynamicResolveContext, structurally a BindableContext). DOMAIN grain (domainKeyOf):
+ * model routes are declared per domain CHANNEL, so a Discord thread routes via its parent
+ * channel (item 22); everywhere else the domain key IS the surface key. Throws only on a
+ * structurally broken ctx — the caller (resolvePrimaryModel) treats any throw as fail-soft.
+ */
+function identityFromContext(ctx: BindableContext): { surfaceKey: string; surfaceMatch: DomainMatch | undefined } {
+  const surfaceKey = domainKeyOf(resolvePartition(ctx));
+  let surfaceMatch: DomainMatch | undefined;
+  try {
+    const b = bindFrom(ctx);
+    surfaceMatch = domainMatchFor(b.mode, b.trust);
+  } catch {
+    surfaceMatch = undefined; // criteria layer simply not consulted — org ← explicit only
+  }
+  return { surfaceKey, surfaceMatch };
+}
+
+/**
+ * Apply the GENERIC route fields to one call: pick the model id and override
+ * `reasoning` (a spec-level AI SDK call option, backend-independent). Provider hints
+ * are then mapped by the backend's applyOptions. Pure — exported for tests.
+ */
+export function applyRoute(
+  route: ModelRoute,
+  options: RoutedCallOptions,
+  defaultId: string,
+): { id: string; options: RoutedCallOptions } {
+  const id = route.id ?? defaultId;
+  return {
+    id,
+    options: route.reasoning !== undefined ? { ...options, reasoning: route.reasoning } : options,
+  };
+}
+
+/**
+ * Resolve the fully-enveloped ModelRoute for one (role, surface) — the routing DECISION,
+ * with NO transport/backend involvement (returns a plain route object). Resolution order,
+ * all allow-list-clamped by the envelope:
+ *   concrete runtime pick (DomainModelPick) > concrete git-config route id > role/domain
+ *   tier (ModelTier) > fallback.
+ * The optional `ab` argument adds ONE rung under all of those (model/ab-test.ts, OPE-34): when the
+ * route names NO MODEL AND NO TIER of its own — so it would run the deployment default — and the
+ * conversation's bucket falls inside the declared percentage, the challenger id is substituted
+ * BEFORE the envelope. It never overrides a concrete pin or a tier, and the envelope still clamps it.
+ * FAIL-SOFT throughout: any failure resolves to `{}` (→ the caller's default model with
+ * backend static defaults), logged once. Exported for tests and for the compaction slot's
+ * own utility resolution.
+ */
+export async function resolveRoute(
+  role: ModelRole,
+  surfaceKey: string,
+  surfaceMatch: DomainMatch | undefined,
+  defaultId: string,
+  deps: RoutingDeps,
+  fallbackRole?: ModelRole,
+  ab?: ModelAbInput,
+): Promise<ModelRoute> {
+  try {
+    const domains = deps.domains();
+    const roles = deps.roles?.() ?? [];
+    // `fallbackRole` (used for the `supervisor` role): when THIS role has no configured route
+    // anywhere in the layer merge, resolve `fallbackRole` instead — so a supervisor session in
+    // a channel with no `supervisor` route behaves EXACTLY like a `primary` turn (the change is
+    // inert until a domain routes `supervisor`). Checked on the raw merged route, before the
+    // runtime pick / envelope, since those are role-agnostic and would otherwise mask "unset".
+    let rawRoute = modelRouteFor(role, surfaceKey, domains, roles, surfaceMatch);
+    if (fallbackRole !== undefined && routeUnset(rawRoute)) {
+      rawRoute = modelRouteFor(fallbackRole, surfaceKey, domains, roles, surfaceMatch);
+    }
+    // The runtime DOMAIN pick overlay (control/writes.ts set_domain_model): a domain admin's
+    // self-serve choice, layered BETWEEN the git route and the envelope clamp below — so a
+    // pick still passes through applyModelPolicyToRoute exactly like the git route always did
+    // (defence in depth: the write tool already validated the pick against the envelope at SET
+    // time, but the envelope may have narrowed since). `domainName` is the SAME single-hop
+    // resolution spend/caps.ts's domainNameForScope uses (explicit domain, else the dm/public
+    // criteria domain — `org` is deliberately not pick-able). Its own try/catch so a broken
+    // pick read loses only the pick, never the whole route.
+    let pickedRoute: ModelRoute = rawRoute;
+    try {
+      const domainName = domainForChannel(surfaceKey, domains)?.name ?? (surfaceMatch ? criteriaDomain(surfaceMatch, domains)?.name : undefined);
+      if (domainName !== undefined) {
+        const pick = await deps.domainModelPick?.(domainName);
+        if (pick && (pick.modelId !== undefined || pick.reasoning !== undefined)) {
+          pickedRoute = {
+            ...rawRoute,
+            // A picked modelId is a concrete id — drops any inherited `tier`, same
+            // mutual-exclusion convention as ModelRoute.tier/modelRouteFor.
+            ...(pick.modelId !== undefined ? { id: pick.modelId, tier: undefined } : {}),
+            ...(pick.reasoning !== undefined ? { reasoning: pick.reasoning } : {}),
+          };
+          logOnce("log", `${role}: domain "${domainName}" runtime pick → ${JSON.stringify(pick)}`);
+        }
+      }
+    } catch (err) {
+      pickedRoute = rawRoute; // fail-soft — a broken pick read never blocks the call, git route stands
+      logOnce("warn", `${role}: domain model pick lookup failed (${String(err)})`);
+    }
+    // THE A/B ARM (model/ab-test.ts, OPE-34) — layered here, BETWEEN the runtime pick and the
+    // envelope, for the same reason the pick is: the substitution is a routing preference and must
+    // still pass the org's model-policy clamp below. `decideModelAb` returns undefined (no
+    // experiment on this route) whenever the test is unarmed OR the route already pins a concrete
+    // model other than the champion — a pin somebody made deliberately is never overruled. Only the
+    // PRIMARY role is ever handed an `ab` argument (see resolveRoutedPrimaryModel), so a supervisor
+    // or utility resolution is untouched.
+    const abDecision = ab ? decideModelAb(pickedRoute, defaultId, ab) : undefined;
+    const armedRoute = applyModelAb(pickedRoute, abDecision);
+    // The model-policy ENVELOPE (model/policy.ts): resolve a `tier` against the org
+    // allow-list, clamp `reasoning` to the per-domain-resolved ceiling, and fail-soft-
+    // substitute a safe model if the resolved id is somehow outside the allow-list /
+    // provider-denied. A dep that omits `modelPolicy` reproduces exactly the pre-envelope
+    // route unchanged (see RoutingDeps.modelPolicy).
+    let policy: ModelPolicy | undefined;
+    try {
+      policy = deps.modelPolicy?.();
+    } catch {
+      policy = undefined;
+    }
+    // The effective reasoning ceiling for THIS surface: the org policy default, raised or
+    // lowered by any domain-layer `reasoningCeiling` (reasoningCeilingFor). Only resolved
+    // when a policy exists (no policy → no clamp at all, backward-compat).
+    let effectiveCeiling: ModelReasoning | undefined;
+    if (policy) {
+      try {
+        effectiveCeiling = reasoningCeilingFor(surfaceKey, domains, roles, surfaceMatch, policy.reasoningCeiling ?? "medium");
+      } catch {
+        effectiveCeiling = undefined;
+      }
+    }
+    // `defaultId` is passed TWICE, as two different claims. As the 3rd argument it is the
+    // last-resort id (what runs when the policy can offer nothing). As `preferredId` it is the
+    // stronger claim this resolver is entitled to make and a bare policy caller is not: it is
+    // THIS ROLE'S OWN configured model (resolvePrimaryModel hands the primary/utility/supervisor
+    // slots their own role's id), so a fail-soft substitution should land there rather than on
+    // whatever the allow-list happens to list cheapest — which, on an allow-list derived from the
+    // roles, can be the vision describer rather than a turn model.
+    const enveloped = applyModelPolicyToRoute(armedRoute, policy, defaultId, effectiveCeiling, defaultId);
+    for (const w of enveloped.warnings) logOnce("warn", `${role}: model policy: ${w}`);
+    // BUILD-PHASE HARD PIN (Tommy 2026-07-17): OE_FORCE_MODEL, when set, forces EVERY resolved route
+    // onto ONE model id — winning over a domain's concrete `id` pin, the runtime domain pick, and the
+    // envelope alike (all applied above; this is the last word). A blunt "pin the whole org to one
+    // model for now" knob, DISTINCT from OE_PRIMARY_MODEL, which is only the DEFAULT id and LOSES to a
+    // domain's concrete pin (e.g. a `supervisor: { id: glm }`). Only the model id is pinned —
+    // `reasoning`/`providers` and the ceiling clamp are untouched; `tier` is dropped (a concrete id and
+    // a tier are mutually exclusive, same convention as the runtime pick). Unset to restore per-domain routing.
+    const forcedId = process.env.OE_FORCE_MODEL?.trim();
+    const route: ModelRoute = forcedId
+      ? { ...armedRoute, id: forcedId, tier: undefined, reasoning: enveloped.reasoning }
+      : { ...armedRoute, id: enveloped.id, reasoning: enveloped.reasoning };
+    // 🔴 THE ARM IS STAMPED FROM WHAT RESOLVED, NEVER FROM WHAT THE BUCKET ASKED FOR. A challenger
+    // the envelope substituted away — or `OE_FORCE_MODEL` pinned over — ran the champion, and the
+    // `usage_events` row and the audit row must say champion. `resolveModelArm` is that comparison; see
+    // model/ab-test.ts. Fail-soft by construction (stampModelArm no-ops outside a session).
+    if (abDecision !== undefined) {
+      const ranId = route.id ?? defaultId;
+      stampModelArm({ arm: resolveModelArm(abDecision, ranId), bucketKey: abDecision.bucketKey, modelId: ranId });
+    }
+    // Observability: a route that actually overrides something is logged once per
+    // surface+shape per instance — the positive signal that per-domain routing is live.
+    if (route.id !== undefined || route.reasoning !== undefined || route.providers !== undefined) {
+      logOnce("log", `${role}: ${surfaceKey} → ${JSON.stringify(route)}`);
+    }
+    return route;
+  } catch (err) {
+    logOnce("warn", `${role}: domain config unavailable (${String(err)}) — default model`);
+    return {};
+  }
+}
+
+/** Whether a resolved route asks for nothing beyond the default model (no id change, no
+ *  reasoning/providers/tier override) — the primary resolver returns `null` for these so
+ *  eve uses its static fallback directly instead of a redundant wrapper. */
+function isNoOpRoute(route: ModelRoute, defaultId: string): boolean {
+  return (route.id ?? defaultId) === defaultId && route.reasoning === undefined && route.providers === undefined && route.tier === undefined;
+}
+
+/** Whether a merged role route (modelRouteFor's output) is entirely UNSET — no layer named
+ *  this role at all. Used by resolveRoute's `fallbackRole` seam: an all-undefined route means
+ *  "nothing configured this role", so fall back to another role's route. (Distinct from
+ *  isNoOpRoute, which is about "resolves to the default model" AFTER the envelope.) */
+function routeUnset(route: ModelRoute): boolean {
+  return route.id === undefined && route.tier === undefined && route.providers === undefined && route.reasoning === undefined;
+}
+
+// The channel-supervisor session's reserved continuation token embeds the `oe-sup:g<gen>`
+// sentinel (channels/slack-events.ts supervisorSentinel / supervisorToken:
+// `${channelId}:oe-sup:g<gen>` via slackContinuationToken). eve hands that token to the
+// step.started resolver as `ctx.channel.continuationToken` (context/dynamic-resolve-context),
+// so a supervisor session is identifiable HERE without any channel-code import. The sentinel
+// can never collide with a real Slack thread ts, so a match is unambiguous. Mirror any change
+// to the sentinel format in slack-events.ts here.
+//
+// UNIFIED cross-surface supervisor: the domain-keyed
+// token `oe-dom:<domain>:oe-sup:g<gen>` (channels/unified-supervisor.ts unifiedSupervisorToken) ALSO
+// ends in `:oe-sup:g<gen>`, so the classifier matches it UNCHANGED — a unified supervisor session
+// resolves the cheap `supervisor` ModelRole exactly like a per-container one. The surface routing
+// (identityFromContext → domainKeyOf) still reads the WOKEN message's real channel off the delivery
+// auth, so per-domain model routing resolves the right domain regardless of which surface a wake
+// arrived on.
+//
+// The old anchored regex `SUPERVISOR_TOKEN_RE = /(?:^|:)oe-sup:g\d+$/` is now the codec's
+// `isSupervisorShapedToken` (channels/window-key.ts) — kind ∈ {window, task, thread-seat,
+// container-supervisor}, byte-identical to the regex over every real + malformed token shape it was
+// ever asked to classify (pinned by scripts/session-id-codec-test.ts), with ONE DELIBERATE widening:
+// OPE-58's `g<n>-<sha>` rotation salt is a genuinely NEW, additive suffix form the old regex never
+// saw — the codec accepts it (still resolves `supervisor`), the old bare oracle would have rejected
+// it (see session-id-codec-test.ts PART 7). Do NOT reintroduce a local regex here.
+
+/**
+ * Is this a channel-supervisor session (→ resolve the `supervisor` ModelRole, the cheap
+ * ambient tier)? True iff the resolver ctx carries a supervisor-SHAPED continuation token (any
+ * OE-structured standing/task/thread/window token). Fail-soft: any missing/odd ctx shape → false
+ * (a normal turn), never throws.
+ *
+ * 🔴 ONE SUBTRACTION FROM "SUPERVISOR-SHAPED": A DM WINDOW (OPE-351). Stage 2 re-seats a DM on a
+ * degenerate window token over the `oe-dm/<surfaceKey>` pseudo-domain, which IS supervisor-shaped —
+ * so without this arm, giving a DM a rotatable window would silently demote every DM turn to the
+ * cheap ambient tier. That is exactly the hazard channels/window-key.ts's dm-seat section already
+ * closed once for the OPE-90 token (`:oe-dm:g` was chosen INERT to every `:oe-sup:g` detector for
+ * this reason): a DM is a person talking to the agent one-to-one, the highest-intent traffic there
+ * is, and it must route to the PRIMARY model. Re-seating it must not undo that ruling.
+ *
+ * WHY HERE AND NOT IN {@link isSupervisorShapedToken}. That predicate is the BROAD "is this an
+ * OE-structured session" test, and the spend counter, the rotation machinery and the registry-key
+ * derivation all want a DM window inside it — a DM window has a real `channel_session` row and a real
+ * generation to bump. Narrowing the codec would break those. The exclusion belongs to the ROLE
+ * question alone, which is this function.
+ *
+ * IT IS ALSO THE RIGHT ANSWER FOR THIS FUNCTION'S OTHER TWO CONSUMERS, which is why it sits here
+ * rather than in resolvePrimaryModel: `renderSupervisorPersona` (instructions/access.ts) and the
+ * mid-session memory re-sync arming (hooks/memory.ts) both key off "is this an ambient supervisor
+ * seat". A DM is not one — it is an addressed 1:1 conversation — and today's native-token DM answers
+ * false for all three. So the exclusion PRESERVES the DM's current posture across the re-seat rather
+ * than changing it, which is the property that makes stage 2 a re-key and not a behaviour change.
+ *
+ * THE ARM FIRES ON EVERY DM WAKE. `channels/dm-seat.ts` `getOrCreateDmSeat` mints the DM seat's token
+ * as `saltSupervisorGeneration(formatWindowToken(dmWindowKey(…)))`, and the Slack, Teams and Discord
+ * DM legs divert each wake onto it — so this is the routing answer a live DM reads. A
+ * DM-anchored WORKER (a `t/` task token on the same pseudo-domain, OPE-306 — which DOES exist today)
+ * is deliberately NOT excluded: it is supervisor-shaped now, it resolves the supervisor role now, and
+ * nothing here changes that. {@link isDmAnchorWindowToken} is standing-grain-only precisely so this
+ * arm cannot reach it.
+ */
+export function isSupervisorSession(ctx: BindableContext): boolean {
+  const token = ctx.channel?.continuationToken;
+  if (isDmAnchorWindowToken(token)) return false;
+  return isSupervisorShapedToken(token);
+}
+
+/**
+ * A per-selection routed model: bakes in a resolved route (via the `getRoute` thunk) and
+ * applies it on each call — id selection + reasoning override (applyRoute) then the
+ * backend's provider-option mapping. NO identity work at call time (the route is a closure
+ * constant / a per-session stamp read). Identity/properties mirror the default inner model;
+ * `do*` delegate with rewritten options. Inner models are memoized per id.
+ *
+ * Used for the primary selection (getRoute = the route resolved from ctx).
+ */
+export function makeRoutedModel<TModel extends RoutableModel>(
+  getRoute: () => ModelRoute,
+  defaults: { readonly id: string },
+  backend: ModelBackend<TModel>,
+): TModel {
+  const inner = new Map<string, TModel>();
+  const modelFor = (id: string): TModel => {
+    let m = inner.get(id);
+    if (!m) {
+      m = backend.model(id);
+      inner.set(id, m);
+    }
+    return m;
+  };
+  const dispatch = (options: RoutedCallOptions): { model: TModel; options: RoutedCallOptions } => {
+    const route = getRoute();
+    const generic = applyRoute(route, options, defaults.id);
+    const mapped = backend.applyOptions(route, generic.options, { id: generic.id, defaultId: defaults.id });
+    // Stamp the id THIS call resolved to (model-stamp.ts) — hooks/spend.ts reads it back
+    // when the following step.completed fires, so the usage_events row carries an EXACT
+    // model. Fail-soft (no-op outside a session) — never blocks the model call.
+    stampModelCall(generic.id);
+    return { model: modelFor(generic.id), options: mapped };
+  };
+  const fallback = modelFor(defaults.id);
+  const routed: RoutableModel = {
+    specificationVersion: fallback.specificationVersion,
+    provider: fallback.provider,
+    modelId: defaults.id,
+    supportedUrls: fallback.supportedUrls,
+    async doGenerate(options: RoutedCallOptions) {
+      const d = dispatch(options);
+      return d.model.doGenerate(d.options);
+    },
+    async doStream(options: RoutedCallOptions) {
+      const d = dispatch(options);
+      return d.model.doStream(d.options);
+    },
+  };
+  return routed as TModel;
+}
+
+/**
+ * The primary (turn) model resolver core: reconstruct the surface from the harness ctx,
+ * resolve the primary route, STAMP the utility route (same identity, for the compaction
+ * slot which has no ctx of its own) AND stamp the resolved primary model id for per-row
+ * cost attribution, and return a per-selection routed model — or the DEFAULT model, built
+ * concretely, when the surface routes to nothing. NEVER returns null (OPE-412 — see the
+ * module header for why, and why it is behaviour-preserving) and NEVER throws (a thrown
+ * resolver breaks the turn); every failure path resolves to the default model at
+ * `defaults.primary.id` and stamps a cleared utility route.
+ *
+ * WHY THE RESOLVER STAMPS THE PRIMARY ID (not just the wrapper's dispatch): the resolver
+ * runs inside the harness-supplied step context — the SAME per-session state container the
+ * spend hook (hooks/spend.ts, `step.completed`) reads back with readModelStamp(). Stamping
+ * here makes the usage_events model column correct even for the NO-OP/default path (no
+ * wrapper is built, so dispatch never runs) and even if the AI SDK were to run the wrapper's
+ * doGenerate outside the resolver's async context. Fail-soft: stampModelCall no-ops outside a
+ * session (model-stamp.ts). The id stamped is exactly what the call will run: the enveloped
+ * `route.id` (or the default when the route names none), matching the dispatch's applyRoute.
+ *
+ * Wire as the `step.started` handler of `defineDynamic({ fallback, events })` on the agent
+ * `model` field (normally via an adapter convenience, e.g. the gateway backend's
+ * `gatewayModelResolver`). NOTE: it MUST be `step.started`, not `turn.started` — eve rejects
+ * a model-INSTANCE return at session/turn scope (see the module header). At `turn.started`
+ * eve discards the wrapper, routing goes dead, and no row is ever stamped.
+ *
+ * THE PER-TURN STEP BOUNDARY WRAPS THIS (model/step-boundary.ts, OPE-407) — see the exported
+ * {@link resolvePrimaryModel} just below. Everything in here is pure ROUTING; the boundary is
+ * counted before any of it runs, so no routing outcome can bypass it.
+ */
+async function resolveRoutedPrimaryModel<TModel extends RoutableModel>(
+  ctx: BindableContext,
+  defaults: { readonly primary: { readonly id: string } },
+  deps: RoutingDeps<TModel>,
+  event?: unknown,
+): Promise<TModel> {
+  // 🔴 CLEAR ANY ARM THIS SESSION STAMPED ON AN EARLIER TURN — FIRST, BEFORE EVERY OTHER LINE. The
+  // slot is per-SESSION and a session outlives a turn, so without this a room that ran one armed
+  // turn would keep reporting that arm forever: on turns the experiment stopped covering, on turns
+  // after the operator switched it off, and — the reason this sits ABOVE the try below rather than
+  // after it — on every fail-soft path here, each of which returns the DEFAULT model while an
+  // uncleared slot would still say `challenger`. That row would contradict its own `model` column.
+  // `resolveRoute` re-stamps when a decision applies; a turn with no decision records no arm.
+  stampModelArm(null);
+  let surfaceKey: string;
+  let surfaceMatch: DomainMatch | undefined;
+  try {
+    const id = identityFromContext(ctx);
+    surfaceKey = id.surfaceKey;
+    surfaceMatch = id.surfaceMatch;
+  } catch (err) {
+    logOnce("warn", `primary: surface unbindable from ctx (${String(err)}) — default model, routing inactive`);
+    stampModelCall(defaults.primary.id); // the default model runs → price the row as the default
+    return deps.backend.model(defaults.primary.id);
+  }
+
+  // Resolve the turn route and wrap it (unless it's a no-op → fallback). A channel-SUPERVISOR
+  // session (identified by its reserved continuation token) resolves the `supervisor` role —
+  // the cheap ambient tier — instead of `primary`, falling back to `primary` when no supervisor
+  // route is configured (so the role is inert until a domain routes it). A normal thread/turn
+  // session resolves `primary` exactly as before. Both share the same static default id.
+  const supervisor = isSupervisorSession(ctx);
+  // THE PER-ROUTINE MODEL ROLE (OPE-1627) — a routine that named one resolves THAT role instead,
+  // and it wins over the supervisor branch above.
+  //
+  // 🔴 IT HAS TO WIN, AND THE REASON IS MEASURED. A routine fire that goes through the unified
+  // window carries a window token, and `isSupervisorSession` answers TRUE for one — so such a fire
+  // already resolves `supervisor` today while a native-path fire of the same routine resolves
+  // `primary`. Reading the stamp after that branch would leave the operator's declared choice
+  // silently overridden on exactly one of the two delivery paths, which is the shape of bug this
+  // field exists to remove rather than add.
+  //
+  // 🔴 UNDEFINED IS INHERIT, and every failure lands there. The stamp is host-set off the stored row
+  // (routines/fire-auth.ts) and re-validated by `routineModelRoleStamped`, so an absent, unknown or
+  // hand-set value leaves this line resolving what it resolved before the field existed. The
+  // fallback role stays `primary` for the same reason the supervisor branch's does: a role the
+  // deployment routes nowhere is INERT, never a downgrade and never an error.
+  let routineRole: ModelRole | undefined;
+  try {
+    // `current ?? initiator` is the SAME precedence identity/binding.ts's own `authOf` reads the
+    // bag under; that helper is module-private, and a routing-side copy of two field names is
+    // cheaper than widening the identity layer's surface for one reader.
+    const auth = ctx.session?.auth?.current ?? ctx.session?.auth?.initiator ?? undefined;
+    routineRole = routineModelRoleStamped(auth?.attributes as Parameters<typeof routineModelRoleStamped>[0]);
+  } catch (err) {
+    logOnce("warn", `primary: routine model-role stamp unreadable (${String(err)}) — inherit`);
+  }
+  /** The role THIS turn resolves. With no routine stamp it is exactly what the two branches above
+   *  always produced, which is what makes the field inert until a routine names one. */
+  const effectiveRole: ModelRole = routineRole ?? (supervisor ? "supervisor" : "primary");
+  // THE A/B INPUT (OPE-34), built ONLY for a turn that resolves the PRIMARY role.
+  //
+  // 🔴 THE EXCLUDED SET IS EVERY OE-STRUCTURED SEAT, not just the ambient supervisor. `supervisor`
+  // here is `isSupervisorSession`, which is `isSupervisorShapedToken` minus the DM anchor — window,
+  // task, thread-seat AND container-supervisor tokens all answer true (channels/window-key.ts). So a
+  // `t/` task WORKER is excluded too, and a person can read a worker's answer. Those turns are out
+  // of the experiment because they resolve the `supervisor` ModelRole, not the champion, so
+  // substituting the challenger there would compare the challenger against whatever the supervisor
+  // route resolved rather than against the champion. Naming the set exactly matters downstream:
+  // `/oe rate` in such a room finds no arm row, and its reply must not claim the test is off.
+  //
+  // Unarmed (or undeclared) ⇒ `undefined`, and `resolveRoute` then behaves exactly as it did before
+  // this feature existed.
+  let ab: ModelAbInput | undefined;
+  try {
+    const test = deps.modelAbTest?.();
+    // The test is keyed on `effectiveRole`, not on `supervisor`, so a routine that named a role
+    // other than `primary` is out of the experiment for the SAME reason a supervisor-shaped seat
+    // is: it does not resolve the champion, so substituting the challenger there would compare the
+    // challenger against whatever that role routed. A routine naming `primary` stays in.
+    if (effectiveRole === "primary" && modelAbTestArmed(test)) ab = { test, bucketKey: abBucketKey(surfaceKey, abThreadKey(ctx)) };
+  } catch (err) {
+    logOnce("warn", `primary: model A/B test read failed (${String(err)}) — no arm`);
+  }
+  let route: ModelRoute;
+  try {
+    route =
+      effectiveRole === "primary"
+        ? await resolveRoute("primary", surfaceKey, surfaceMatch, defaults.primary.id, deps, undefined, ab)
+        : await resolveRoute(effectiveRole, surfaceKey, surfaceMatch, defaults.primary.id, deps, "primary");
+  } catch (err) {
+    logOnce("warn", `primary: route resolution failed (${String(err)}) — default model`);
+    stampModelCall(defaults.primary.id); // fail-soft → the default model runs; price the row as the default
+    return deps.backend.model(defaults.primary.id);
+  }
+  // Stamp the id the call WILL run — for both the default/no-op path (no wrapper is built) and
+  // the routed path (the wrapper's dispatch re-stamps the same id). This is the guaranteed
+  // per-row cost attribution point; see the doc above.
+  stampModelCall(route.id ?? defaults.primary.id);
+  // THE A/B AUDIT ROW (OPE-34) — one row per armed TURN, written from the stamp `resolveRoute`
+  // just wrote, so the audit row and the `usage_events` row can never disagree about the arm. A no-op on
+  // every deployment that has not armed the experiment (nothing stamped ⇒ nothing written), and
+  // best-effort throughout: it never throws and never blocks the model call.
+  noteModelAbArm(ctx, readModelArm(), event);
+  // A no-op route asks for nothing beyond the default (isNoOpRoute: same id, no reasoning/
+  // providers/tier), so skip the wrapper and hand back the bare default model — same id, same
+  // options, one less indirection.
+  if (isNoOpRoute(route, defaults.primary.id)) return deps.backend.model(defaults.primary.id);
+  return makeRoutedModel(() => route, defaults.primary, deps.backend);
+}
+
+/**
+ * THE `step.started` PRIMARY-MODEL RESOLVER — per-domain routing (above) with the PER-TURN STEP
+ * BOUNDARY in front of it (model/step-boundary.ts, OPE-407, which retired the `__oeCeil*` half of
+ * the eve byte-patch). Wire this, not {@link resolveRoutedPrimaryModel}.
+ *
+ * 🔴 THE BOUNDARY IS COUNTED FIRST, BEFORE ANY ROUTE RESOLUTION. Every failure path in the routing
+ * half degrades to the DEFAULT model, so a guard placed after resolution would be skipped on
+ * exactly the paths most likely to accompany a spiral (an unbindable ctx, a broken route read).
+ * Counting first means no routing outcome — routed, no-op or fail-soft — can bypass it. This
+ * ordering IS the guarantee; do not move the call.
+ *
+ * The two tiers (see step-boundary.ts for the full rationale):
+ *   SOFT — past `turn.stepBudget`, the resolved model is wrapped so every call carries a wrap-up
+ *     instruction. The turn is not killed and the model keeps its agency. The routing half always
+ *     hands back a concrete model — the DEFAULT one on the no-op/fail-soft path (OPE-412) — so the
+ *     notice cannot be dodged by an unrouted surface.
+ *   HARD — past `budget × turn.stepBackstopMultiple`, a text-only stub replaces the model entirely.
+ *     It makes no network call, so a runaway stops costing immediately, and its tool-call-free
+ *     assistant message ends the turn through eve's OWN continue-decision.
+ *   CLOSED — the turn had already closed its reply obligation and the host refused its next attempt
+ *     to speak (OPE-1520). The SAME text-only stub ends the turn, one round-trip after the refusal
+ *     rather than at round-trip 121, so a background worker the turn dispatched starts at once.
+ *     Independent of the round-trip count and of whether the step budget is armed at all.
+ *
+ * Still NEVER throws (the fail-soft contract the routing half documents) — every step-boundary
+ * entry point swallows its own failures and degrades to "no boundary".
+ *
+ * `event` is the dynamic-model resolver's own first argument, passed through from
+ * `gatewayModelResolver` (packages/adapters/agent/model/gateway.ts) — `noteTurnStep` needs it to
+ * find a turn id at all (OPE-462: `ctx.session.turn` does not exist on the resolver context; the
+ * event's `data.turnId` is the field that does carry one). Optional so the many unit-test callers
+ * that construct their own turn-bearing `ctx` fixture keep working unchanged.
+ */
+export async function resolvePrimaryModel<TModel extends RoutableModel>(
+  ctx: BindableContext,
+  defaults: { readonly primary: { readonly id: string } },
+  deps: RoutingDeps<TModel>,
+  event?: unknown,
+): Promise<TModel> {
+  // 🔴 OPE-593's `[Agents]` SUBTRACTION USED TO RUN HERE, AND DELIBERATELY NO LONGER DOES.
+  // Through eve 0.47.3 this resolver was handed the tool loop's own turn array as `ctx.messages`,
+  // so an in-place splice here reached the model. eve 0.48.0 builds the model's list through a copy
+  // and a call here became a no-op against the bytes the model receives (OPE-1396). The subtraction
+  // now runs at the eve patch's part-6 seam instead — `access/worker-continuation.ts` installs the
+  // hook and its header carries the measurement. Do not re-add a call here expecting it to work.
+  // AWAITED since OPE-1522: the count and the closeout latch live in a durable per-turn row, so a
+  // turn resumed on a fresh serverless instance continues its count instead of restarting it. The
+  // ordering is unchanged — this is still the FIRST thing the resolver does, before any route
+  // resolution, which is the fail-safe the header above turns on.
+  const boundary = await noteTurnStep(ctx, event);
+  // THE SOAK CAPTURE HOOK (OPE-846), armed by `soak.capture` and OFF on every ordinary deployment.
+  // It decorates the BACKEND rather than the returned model, so every path below — routed wrapper,
+  // no-op default, fail-soft default — is built from a capture-wrapped `backend.model(id)`. That is
+  // the one position that records the bytes the model actually saw: `applyRoute`/`applyOptions` and
+  // the soft wrap-up notice all edit the options OUTSIDE it and flow inward through this seam. When
+  // disarmed `withCapture` returns `deps` unchanged, so the disarmed cost is one boolean read.
+  // See model/call-capture.ts for the sensitivity posture and the cross-check.
+  const captureSite = captureArmed() ? captureSiteFrom(ctx, event) : undefined;
+  const capturingDeps = withCapture(deps, captureSite);
+  // THE DELEGATED WORKER'S ONE STREAM-DROP RETRY (OPE-2132). Armed on the grain-`task` worker bit
+  // alone — `currentWorkerWake()`, the same discriminator every other worker-scoped rule reads, and
+  // strictly narrower than `isSubagentChildContext`, which would buffer subagent children the ticket
+  // never scoped. Wrapped OUTSIDE the capture shim on purpose: a retried attempt is a second model
+  // call and the capture's own cross-check counts calls, so the shim must see both.
+  const retryingDeps = withStreamDropRetry(capturingDeps, currentWorkerWake());
+  // The two TURN-ENDING tiers take one path: both replace the model with the text-only stub, and
+  // they differ only in the text it says (`boundaryStopReply`) and in the audit detail the row
+  // carries. Everything below — the capture excuse, the un-cleared counter, the price stamp — is
+  // true of a closed turn for exactly the reasons it is true of a backstopped one.
+  if (boundary.tier === "hard" || boundary.tier === "closed") {
+    reportStepBoundary(ctx, boundary);
+    // The stub answers from process memory and makes NO network call, so this step completes with
+    // no bytes to capture. Excuse it EXPLICITLY — the capture cross-check must not have to infer
+    // which completed steps were allowed to be missing.
+    noteUncalledModelStep(captureSite);
+    // 🔴 The counter is NOT cleared here, unlike the patched loop's `on trip, delete` behaviour.
+    // A cleared counter would let a turn that somehow continued past the stub start the whole
+    // budget again — i.e. the one case the backstop exists for is the one case a reset would
+    // re-arm. Once a turn is past the backstop it stays past it; the LRU bound in
+    // step-boundary.ts is what keeps the map from growing.
+    // Price the (never-sent) call as the default, exactly like every other fallback path here.
+    stampModelCall(defaults.primary.id);
+    // Deliberately the UNDECORATED backend: the stub never calls this inner model, so a capture
+    // shim here would only allocate and mislead the next reader.
+    return turnBackstopModel(deps.backend.model(defaults.primary.id), boundaryStopReply(boundary));
+  }
+  const routed = await resolveRoutedPrimaryModel(ctx, defaults, retryingDeps, event);
+  if (boundary.tier !== "soft") return routed;
+  reportStepBoundary(ctx, boundary);
+  // `routed` is always concrete now (OPE-412) — on the no-op/fail-soft path it IS
+  // `deps.backend.model(defaults.primary.id)`, which is what this used to substitute via `??`.
+  return withWrapUpNotice(routed, wrapUpNotice(boundary));
+}
+
+// There is deliberately NO compaction-model wrapper here, and no per-session utility stamp to
+// feed one. eve resolves an authored `defineAgent.compaction.model` by re-loading agent.ts and
+// reading its AGENT-LEVEL `model` field, so a wrapper INSTANCE in that slot is never reached and
+// kills the turn while that field is dynamic (OPE-670). Compaction summarises with the live turn
+// model, which `resolvePrimaryModel` above has already routed.