@open-everywhere/provider-teams 0.0.0-stage → 0.1.0

package/agent/channels/teams-front.ts

@@ -0,0 +1,1404 @@
+// The Teams FRONT route — the single-window legs' live wiring, porting slack-front.ts's proven
+// shape to Teams (build order: single-window-generalisation-strategy.md task #46, Teams arm).
+//
+// WHY A FRONT (same reason as Slack): eve's `teamsChannel` owns the public Bot-Framework webhook
+// and dispatches every message activity to its own conversation-session machinery; it exposes no
+// hook that can DIVERT a wake into another channel (`onMessage` has no cross-channel `to`).
+// So the public URL is fronted: the wrapped `teamsChannel` is mounted at an INTERNAL route
+// ({@link INTERNAL_TEAMS_ROUTE}) and OUR route sits at the public {@link PUBLIC_TEAMS_ROUTE}.
+// Both routes live on the SAME channel object (one file slug → one channel name → one session
+// namespace), exactly the slack-front composition.
+//
+// The front route:
+//   1. Verifies the inbound request (eve's PUBLIC `verifyTeamsRequest` — the Bot Connector JWT
+//      against Microsoft's OpenID keys + our app id; fail-closed 401). Unlike the Slack front we
+//      don't re-implement the check: eve exports it. The forward path re-verifies inside
+//      teamsChannel (a fresh Request), so the native path's auth is unchanged — we only ADD a
+//      gate, never weaken one.
+//   2. Parses the activity (eve's public `parseTeamsActivity`). Anything that isn't a message
+//      activity — invokes (HITL card clicks), conversationUpdates, unparseable bodies — FORWARDS
+//      to teamsChannel untouched (the fail-safe default).
+//   3. For a message activity, resolves the SINGLE-WINDOW plan (teams-supervisor.ts
+//      planTeamsSingleWindow: grain singleWindow + the fail-closed Teams privacy floor). NO plan
+//      → FORWARD (byte-identical: with the window gates off, every activity takes today's
+//      native path). A plan → the activity ITSELF is diverted into the unified window —
+//      SINGLE-LEG: Teams fires ONE webhook per message and the floor needs no network, so one
+//      synchronous verdict drives both the native suppression (we don't forward) and the
+//      addressed/ambient wake (we dispatch) — the Slack build's lost-mention window (two legs
+//      disagreeing across webhooks/caches) cannot exist here by construction.
+//   4. Idempotency (two-layer, mirroring slack-front: in-memory + the durable operational store)
+//      and per-container FIFO guard the wake.
+//
+// LEG A here is the Teams AMBIENT ingest: a non-mention channel message on a single-window
+// domain becomes a judged channel-watch wake in the shared window. NOTE the platform reality:
+// Teams only delivers non-mention messages to a bot whose app carries the matching RSC permission
+// — `ChannelMessage.Read.Group` for a team channel, `ChatMessage.Read.Chat` for a chat (both are
+// in teams-app/manifest.json). Without the relevant one, only @mention activities arrive and Leg A
+// is simply never exercised (no code path depends on it firing).
+//
+// CHAT SCOPE IS DELIBERATELY NOT LEG A. The plan's privacy floor (teams-supervisor.ts
+// teamsSingleWindowPrivacyOk) admits `scope === "channel"` only, so a group chat never joins the
+// shared cross-surface window. That is the intended posture, not an oversight: a group chat is a
+// per-person surface, not an org container, so admitting one would breach the floor's whole premise
+// (see the floor's docstring). Widening it is a security decision that needs its own review, not a
+// side effect of a manifest line.
+//
+// LEG E is the AMBIENT ENGAGEMENT SEAM (OPE-1500, contract §2.5) and it covers BOTH containers a
+// Teams engagement can be kept per: a channel's reply chain and a group chat. An @mention marks the
+// conversation engaged, a later plain message in it wakes the agent, and `stand_down` stores the
+// stop. Leg E dispatches nothing itself — it marks, and it suppresses a stood-down conversation
+// above every other branch — so no message is ever handled by both legs. The two legs answer
+// different questions: Leg A is a DOMAIN's opted-in ambient posture (a vouched single-window
+// channel), Leg E is a CONVERSATION's own invitation, and it needs no domain opt-in at all.
+//
+// Both legs depend on the SAME platform grant, and Leg E states it out loud: Microsoft delivers
+// non-mention activities only where the tenant consented to `ChannelMessage.Read.Group` (a channel)
+// or `ChatMessage.Read.Chat` (a chat). Nothing can probe that consent, so teams-engagement.ts proves
+// the grant present on the first non-mention message and logs the named reason once until then.
+
+import { POST, type Channel, type HttpRouteDefinition, type RouteHandlerArgs } from "eve/channels";
+import { verifyTeamsRequest, parseTeamsActivity, teamsThreadRootActivityId, isTeamsInputResponseActivity, type TeamsMessageActivity } from "eve/channels/teams";
+import { sendTeamsActivityBackedOff } from "./teams-connector.js";
+import {
+  buildTeamsAuth,
+  teamsMembershipType,
+  teamsTrustGroup,
+  teamsUserTypeFromMember,
+  withTeamsUserType,
+  type OpenEverywhereTeamsAuth,
+} from "./teams-identity.js";
+import { resolveTeamsUserType, teamsServiceUrlRosterProbe, type TeamsRosterProbe } from "./teams-roster.js";
+import { recordTeamsConversationReference, teamsChannelGrainConversationId, teamsReplyChainRoot } from "./teams-conversation-ref.js";
+import { parseTeamsReaction, routeTeamsStopReaction, type TeamsReactionActivity, type TeamsStopOutcome } from "./teams-stop.js";
+import {
+  clearTeamsRoomStop,
+  markTeamsEngaged,
+  markTeamsRoomWatched,
+  resolveTeamsEngagement,
+  teamsMachineAuthored,
+  teamsRoomWatchStopped,
+  type TeamsEngagementVerdict,
+} from "./teams-engagement.js";
+import { teamsGraphTeamId } from "./teams-graph-team-id.js";
+import {
+  planTeamsSingleWindow,
+  handleTeamsSingleWindowDispatch,
+  teamsSupervisorToken,
+  buildTeamsDmWake,
+  type TeamsSupervisorDeps,
+  type TeamsSingleWindowFacts,
+} from "./teams-supervisor.js";
+import {
+  shouldRotate,
+  EventDedupe,
+  ThreadFifo,
+  divertToUnifiedWindow,
+  divertInboundToUnifiedWindow,
+  supervisorGrainFor,
+  mintRotationToken,
+  claimRuntimeRotation,
+  stampMintedRuntime,
+  grainUsesUnifiedWindow,
+  resolvePartition,
+  domainKeyOf,
+  engagementTierFor,
+  getConfig,
+  getOperationalStore,
+  isVouchedSurface,
+  trustGroupKeyFor,
+  resolveWakeTrustFromContext,
+  stampNonMemberChatAuth,
+  deploymentOrg,
+  appendAudit,
+  getOrCreateDmSeat,
+  touchDmSeat,
+  renderWake,
+  mintWakeId,
+  resolveExternalPolicy,
+  externalPolicyOverrideFor,
+  externalPolicyIsInert,
+  withholdsBody,
+  roomIsSilenced,
+  silentRoomNotice,
+  silentNoticeKey,
+  EXTERNAL_SENDER_NOTICE,
+  EXTERNAL_MENTION_ACK,
+  owesSuppressedMentionAck,
+  suppressionRendering,
+  type ExternalPolicy,
+  type IngestedChatMessage,
+  type AuthorTrustQuery,
+  type SupervisorGrain,
+  type UnifiedWindowWake,
+  type UnifiedWakeOrigin,
+  type Partition,
+  type BindableContext,
+  carryTailForward,
+  type WakeMessageInput,
+  recordWakeTail,
+  tailAuthorGrain,
+  dmWindowRegistryKey,
+  type AttachSessionForCancel,
+  RateLimitExhaustedError,
+  receiptEventTime,
+  spreadVendorTs,
+  seatCatchUp,
+} from "@open-everywhere/core/agent/adapter-api.js";
+
+/** An HTTP route handler — `RouteHandler` isn't a public eve export, so we mirror its shape
+ *  (the exact slack-front mirror). */
+type RouteHandler = (req: Request, args: RouteHandlerArgs) => Promise<Response>;
+
+/** The public URL the Bot Framework POSTs every activity to (the bot registration's endpoint). */
+export const PUBLIC_TEAMS_ROUTE = "/eve/v1/teams";
+/** The internal path the wrapped `teamsChannel` is mounted at (never hit by Teams directly). */
+export const INTERNAL_TEAMS_ROUTE = "/eve/v1/teams/native";
+
+function tlog(msg: string): void {
+  console.log(`[open-everywhere:teams-front] ${msg}`);
+}
+
+// --- the single-window plan for one verified activity (live resolution) ----------------------
+
+/** Everything the front resolved for one activity that the window OWNS — null means "forward to
+ *  the native channel" (the byte-identical default). */
+export interface TeamsFrontPlan {
+  readonly window: UnifiedWindowWake;
+  /** The DOMAIN-GRAIN surface key (`teams/<tenant>/<channel>` after the binding's segment
+   *  sanitisation) — the gate/registry/FIFO/audit key. */
+  readonly surfaceKey: string;
+  readonly partition: Partition;
+  readonly grain: SupervisorGrain;
+  readonly auth: OpenEverywhereTeamsAuth;
+}
+
+/** One auth bag's raw attributes, defensively — the bags this file handles arrive in two shapes
+ *  (`OpenEverywhereTeamsAuth` and the erased attribute-bag the DM divert carries). */
+function teamsAttrs(auth: unknown): Record<string, unknown> {
+  const a = (auth as { attributes?: unknown } | null)?.attributes;
+  return a && typeof a === "object" ? (a as Record<string, unknown>) : {};
+}
+
+/**
+ * Did Teams POSITIVELY refute this author's membership (OPE-489)? Only a resolved `userRole: "guest"`
+ * counts. Absent is NOT a refutation: absence of evidence, and this leg fails OPEN.
+ *
+ * The auth bag carries the verdict once {@link teamsAuthWithUserType} has folded the roster probe's
+ * answer in (OPE-493). Both dispatch paths do that unconditionally; the pre-ack
+ * {@link liveTeamsExternalGate} does it only when the policy could act on the answer.
+ *
+ * The verdict routes through `teamsUserTypeFromMember`, the ONE reader of Teams' guest vocabulary,
+ * rather than re-spelling the string comparison here. A second reader is how "what counts as a
+ * guest" comes to mean two things — and the vocabulary is already subtle (Graph's
+ * `conversationMember.roles` gives an OUT-OF-TENANT external the value `owner`).
+ */
+function teamsAuthorRefuted(auth: unknown): boolean {
+  const a = teamsAttrs(auth);
+  return teamsUserTypeFromMember({ userType: a["user_type"] ?? a["userType"] }) === "guest";
+}
+
+/** The trust registry's GROUP-rung key for this activity's TEAM (OPE-490), so a `team:<id>`
+ *  declaration reaches the room leg exactly as it reaches the binding. Absent on a chat with no
+ *  team, and on a team id that is not a safe key segment (refused, never repaired). */
+function teamsRoomGroupKey(auth: unknown): { readonly groupKey?: string } {
+  const a = teamsAttrs(auth);
+  const tenant = a["tenant_id"] ?? a["tenantId"];
+  const group = teamsTrustGroup(typeof (a["team_id"] ?? a["teamId"]) === "string" ? String(a["team_id"] ?? a["teamId"]) : undefined);
+  if (typeof tenant !== "string" || tenant.length === 0 || !group) return {};
+  return { groupKey: `teams/${tenant}/${group.trustGroup}` };
+}
+
+/**
+ * The auth capture for one inbound activity — the SAME raw-fact stow teams.ts's onMessage builds,
+ * so the diverted wake binds identically to a native turn (identity seam unchanged).
+ *
+ * SYNCHRONOUS, so it carries no `userType`: the roster verdict is a network call. The two dispatch
+ * paths fold it in afterwards with {@link teamsAuthWithUserType}.
+ */
+function authForActivity(a: TeamsMessageActivity): OpenEverywhereTeamsAuth {
+  return buildTeamsAuth({
+    userId: a.from.id,
+    aadObjectId: a.from.aadObjectId,
+    userName: a.from.name,
+    tenantId: a.tenantId ?? a.conversation.tenantId,
+    conversationId: a.conversation.id,
+    channelId: a.teamsChannelId,
+    teamId: a.teamId,
+    serviceUrl: a.serviceUrl,
+    scope: a.scope,
+    membershipType: teamsMembershipType(a.channelData),
+  });
+}
+
+/**
+ * FOLD THE ROSTER VERDICT INTO ONE ACTIVITY'S AUTH CAPTURE (OPE-493) — the ONE step both front
+ * dispatch paths take before they stamp, and the reason the front's author leg is no longer inert.
+ *
+ * Until this existed, `resolveTeamsUserType` ran on NO live path. The front owns channel activities
+ * (the shared window) and personal/group chats (the OPE-357 DM divert), and its capture was built
+ * without a `userType` — so a measured B2B guest woke the window rendered as a `peer`
+ * (session wrun_41KZXE4FGK0GPSJB4JNM4KCMHY, 2026-08-15). The verdict now rides the SAME attribute
+ * the native path uses, so `bindTeams` → `teamsTrust` demotes the guest to `external` and the
+ * OPE-489 author leg answers, with no change of their own.
+ *
+ * THREE CALLERS, TWO LATENCY BUDGETS. The two DISPATCH paths run inside the front's
+ * `waitUntil(fifo.enqueue(…))`, so their roster GET lands AFTER the 200 ack and costs the Bot
+ * Framework nothing — they call this unconditionally. {@link liveTeamsExternalGate} runs BEFORE the
+ * ack, so it calls this only when a grain could act on the answer; its own note carries the reasoning.
+ *
+ * COST: one cached GET per (CHANNEL, user) per `identity.dmTrustTtlMs`, never one per message.
+ * `conversation.id` on a CHANNEL activity is the REPLY-CHAIN id (it carries `;messageid=<root>`), and
+ * `resolveTeamsUserType` strips that suffix for the CACHE KEY, so every reply chain in one channel
+ * shares one entry (OPE-572). The id still reaches the CONNECTOR unstripped — exactly as the native
+ * `teamsOnMessage` passes it, which is the shape the 2026-08-15 live probe measured. Whether the
+ * connector ALSO accepts a thread-qualified id is NOT established; one live GET settles it, and a
+ * refusal fails open like any other non-2xx.
+ *
+ * FAIL-OPEN, TOTALLY: a missing serviceUrl, an HTTP error, a transport throw, an unrecognised body —
+ * every one of them returns the capture UNCHANGED, by reference (see `withTeamsUserType`). The
+ * try/catch covers the probe FACTORY as well as the probe, so no roster failure can take a wake off
+ * the air.
+ *
+ * `probeFor` is the test seam: a FACTORY, not a probe, so a test can script "this activity has no
+ * probe at all" (`() => undefined`) distinctly from "the probe answers nothing". Live callers omit
+ * it and get the activity's own serviceUrl probe.
+ */
+export type TeamsRosterProbeFor = (activity: TeamsMessageActivity) => TeamsRosterProbe | undefined;
+
+async function teamsAuthWithUserType<A extends OpenEverywhereTeamsAuth>(
+  auth: A,
+  a: TeamsMessageActivity,
+  probeFor?: TeamsRosterProbeFor,
+): Promise<A> {
+  const factory: TeamsRosterProbeFor = probeFor ?? ((activity) => teamsServiceUrlRosterProbe(activity.serviceUrl));
+  try {
+    return withTeamsUserType(auth, await resolveTeamsUserType(factory(a), a.conversation.id, a.from.id));
+  } catch {
+    return auth; // no verdict → byte-identical capture
+  }
+}
+
+// --- THE EXTERNAL-PARTICIPANT POLICY (OPE-507 author grain, OPE-504 room grain) ---------------
+//
+// Teams is the strongest adopter after Discord and Notion, and it is the one surface that can answer
+// BOTH grains from vendor evidence: the Bot Connector roster reports `userRole: "guest"` for the
+// author leg (teams-roster.ts), and a Teams
+// SHARED CHANNEL is a positive vendor-external verdict for the room leg. The decision plane is the
+// shared, surface-agnostic access/external-policy.ts — this file contributes only the Teams facts and
+// the Teams consequences.
+//
+// 🔴 THE GATE SITS IN THE FRONT, ABOVE BOTH BRANCHES, WHICH IS WHY IT COVERS THE NATIVE PATH TOO.
+// A suppressed activity is never forwarded to the wrapped `teamsChannel`, so a deployment with the
+// window gates OFF is protected by the same verdict as one with them on. Putting the gate inside
+// `liveTeamsDispatch` would have left every non-single-window Teams deployment unwired.
+
+/**
+ * The resolved external-participant policy for one room: the ORG DEFAULT, with the DOMAIN OVERRIDE
+ * applied when the domain registry can be read. An unreadable registry degrades to the org default —
+ * today's behaviour — rather than throwing, exactly as discord-gateway.ts's `externalPolicyForRoom`
+ * does and for the same reason: the policy plane must never be the thing that takes a surface off
+ * the air.
+ */
+function teamsExternalPolicyForRoom(roomKey: string): ExternalPolicy {
+  try {
+    return resolveExternalPolicy(externalPolicyOverrideFor(roomKey, getConfig().loadDomains()));
+  } catch {
+    return resolveExternalPolicy();
+  }
+}
+
+/**
+ * The AUTHOR-TRUST question for one activity (OPE-516) — the OPERATOR's own declaration of who is
+ * internal in this tenant.
+ *
+ * 🔴 TEAMS NEEDS IT EVEN THOUGH TEAMS CAN REFUTE. The surface refutation (`teamsAuthorRefuted`) reads
+ * a resolved roster `userRole`, which every front path now resolves (OPE-493). It still does not
+ * answer everywhere: a tenant whose bot credential cannot read the roster gets no verdict, and the
+ * probe only ever REFUTES — it never declares anyone internal. The register is the leg that covers
+ * those. It is additive: an unarmed tenant declares nobody and the leg contributes nothing, so a
+ * deployment that has not armed a register sees no behaviour change at all.
+ *
+ * Returns `{}` when the tenant is unreadable — no tenant key, no arming key, no question to ask.
+ */
+export function teamsAuthorFacts(auth: unknown, authorId: string | undefined): { readonly authorTrust?: AuthorTrustQuery } {
+  const a = teamsAttrs(auth);
+  const tenant = a["tenant_id"] ?? a["tenantId"];
+  if (typeof tenant !== "string" || tenant.length === 0) return {};
+  const group = teamsTrustGroup(typeof (a["team_id"] ?? a["teamId"]) === "string" ? String(a["team_id"] ?? a["teamId"]) : undefined);
+  return {
+    authorTrust: {
+      tenantKey: `teams/${tenant}`,
+      ...(authorId ? { authorId } : {}),
+      // The GROUP-rung key this author holds, in the register's own pattern grammar. Teams gives one
+      // rung (the team), not a role list — a member of the team holds `teams/<tenant>/team:<id>`.
+      ...(group ? { memberships: [`teams/${tenant}/${group.trustGroup}`] } : {}),
+    },
+  };
+}
+
+/**
+ * The SURFACE's own vendor-external verdict for one activity: this room spans another organisation.
+ *
+ * A Teams SHARED CHANNEL (`channelData.channel.membershipType === "shared"`) is exactly that — it can
+ * hold members from tenants that are not ours, which is why teams-identity.ts already demotes one to
+ * `external` for the memory tier. Absent or any other value means "not reported", which includes "the
+ * activity did not carry channelData": absence of evidence, and this leg fails OPEN.
+ */
+export function teamsVendorExternal(a: TeamsMessageActivity): boolean {
+  return teamsMembershipType(a.channelData) === "shared";
+}
+
+/**
+ * THE EXTERNAL-PARTICIPANT VERDICT for one Teams activity — pure, so the four outcomes are tested
+ * without a Bot-Framework call, a store or a live tenant. The four values name WHAT THE CALLER OWES;
+ * see {@link DiscordExternalVerdict}'s twin in discord-gateway.ts for the full reasoning.
+ *
+ * 🔴 THE AUTHOR GRAIN IS TESTED FIRST, AND THE ORDER MATTERS — the same ruling Discord's verdict
+ * carries. An excluded author in a silenced room is owed a notice they can act on; the room
+ * announcement tells the whole room something about the room instead.
+ */
+export type TeamsExternalVerdict = "proceed" | "withheld-addressed" | "withheld-ambient" | "silent-room";
+
+export function teamsExternalVerdict(input: {
+  readonly policy: ExternalPolicy;
+  readonly author: IngestedChatMessage;
+  /** The activity @mentions the bot, or arrived in a personal chat — an ADDRESSED message is owed
+   *  an answer. */
+  readonly addressed: boolean;
+  /** A personal or group chat. A DM contributes NO room leg: on a DM the trust plane asks about the
+   *  PARTNER, not about the room. */
+  readonly isDm: boolean;
+  /** The SURFACE's vendor-external verdict — {@link teamsVendorExternal}. */
+  readonly vendorExternal: boolean;
+  /** The DOMAIN-grain surface key of the room, for the operator-declared leg. */
+  readonly roomKey: string;
+  /** The GROUP-rung key of the room's team, when the activity names one. */
+  readonly groupKey?: string;
+}): TeamsExternalVerdict {
+  if (withholdsBody(input.author, input.policy)) return input.addressed ? "withheld-addressed" : "withheld-ambient";
+  const room = input.isDm ? { dm: true } : { surfaceKey: input.roomKey, ...(input.groupKey === undefined ? {} : { groupKey: input.groupKey }) };
+  return roomIsSilenced(
+    { room, ...(input.vendorExternal ? { vendorExternal: true } : {}), ingested: [input.author] },
+    input.policy,
+  )
+    ? "silent-room"
+    : "proceed";
+}
+
+/**
+ * Best-effort Bot-Framework send into the activity's own conversation. Never throws: a notice is
+ * an affordance, and a failed one must not turn a suppressed message into a 500 the Bot Framework
+ * retries. Answers whether the send was accepted, which the OPE-885 ack fallback reads. The
+ * serviceUrl is re-validated by the transport arm's own host allowlist.
+ *
+ * 🔴 A TIGHTENED RETRY POLICY, NOT THE SHARED DEFAULTS (cold review finding, OPE-1237). This
+ * function is reached from `liveTeamsExternalGate`, which `dispatchMessage` (:954) AWAITS before
+ * returning `OK()` on the route Microsoft posts activities to — the same "latency-critical path"
+ * shape `slack-web-api.ts`'s `PROBE_OPERATIONS` exists for. The Bot Framework redelivers on a slow
+ * ack (this file's own dedupe comment states redelivery is FAIL-OPEN), so the shared 60 s budget
+ * would turn one Teams rate-limit episode into a redelivery storm instead of a lost notice. Two
+ * attempts at a 2 s cap, mirroring `auth.test`'s policy exactly.
+ */
+async function postTeamsNotice(a: TeamsMessageActivity, text: string): Promise<boolean> {
+  try {
+    await sendTeamsActivityBackedOff(
+      { serviceUrl: a.serviceUrl, conversationId: a.conversation.id, body: { type: "message", text } },
+      { retry: { maxAttempts: 2, capMs: 2_000 } },
+    );
+    return true;
+  } catch (err) {
+    // 🔴 LOG A RATE-LIMIT EXHAUSTION BEFORE SWALLOWING IT (OPE-1237), mirroring Slack's
+    // slack-events.ts intro fetch. This catch is fail-soft by design, and without this line an
+    // exhausted 429 retry would leave NO trace anywhere — the silent drop the ticket exists to
+    // prevent. Every field is token-free.
+    if (err instanceof RateLimitExhaustedError) {
+      console.warn(`[open-everywhere:teams] rate limited: conversations.activities.send gave up after ${err.attempts} attempts (waited ${err.waitedMs} ms)`);
+    }
+    return false; // silence — see the caller's own no-fallback reasoning
+  }
+}
+
+/**
+ * Tell an EXCLUDED sender that the agent will not act on their message (behaviour 1). Answers
+ * whether the notice reached them.
+ *
+ * 🔴 THIS NOTICE NEVER GOES TO A TEAM CHANNEL, AND THAT RULING STANDS — the same one Discord's
+ * `postExternalSenderNotice` carries. Its text names the organisation, so posting it into the
+ * channel would announce that this person is classified as an outsider: a disclosure about a member
+ * of the room, not a notice to the sender. Teams cannot open a 1:1 with a person the bot has never
+ * met (the Bot Framework needs a conversation reference captured on a prior inbound turn), so there
+ * is no private channel to fall back to. A PERSONAL chat is itself private, so the notice posts
+ * there.
+ *
+ * 🔴 SO A CHANNEL @MENTION ALWAYS ANSWERS `false`, AND THAT IS THE COMMON CASE (OPE-885). The caller
+ * then posts the fixed `EXTERNAL_MENTION_ACK` into the channel instead — a different string, which
+ * names no person, no organisation and no verdict, and is therefore not the disclosure this notice
+ * would have been.
+ */
+async function postTeamsExternalSenderNotice(a: TeamsMessageActivity): Promise<boolean> {
+  if (a.scope !== "personal") return false;
+  return await postTeamsNotice(a, EXTERNAL_SENDER_NOTICE);
+}
+
+/**
+ * Post the suppressed-wake half of the silent-room announcement pair (OPE-504) — AT MOST ONCE PER
+ * ROOM, EVER.
+ *
+ * The claim is DURABLE, not per-process: `claimNotice` writes a permanent row, where an in-memory
+ * marker would re-announce on every cold start — and a cold start happens per serverless invocation,
+ * which would be the periodic announcement the design rejects. FAIL-CLOSED on the claim: if the store
+ * cannot prove the notice is unsaid, the agent stays quiet.
+ */
+async function announceTeamsSilentRoom(a: TeamsMessageActivity, org: string, surfaceKey: string): Promise<boolean> {
+  if (!org) return false;
+  try {
+    const won = await getOperationalStore().claimNotice(org, silentNoticeKey(surfaceKey, "suppressed-wake"), new Date().toISOString());
+    if (!won) return false; // already said, once, forever
+  } catch {
+    return false; // cannot prove it is unsaid ⇒ stay quiet
+  }
+  return await postTeamsNotice(a, silentRoomNotice("suppressed-wake"));
+}
+
+/**
+ * The LIVE gate: resolve the verdict for one verified message activity and pay what it owes.
+ * `true` means SUPPRESSED — the caller acks and forwards nothing.
+ *
+ * FAIL-OPEN on an unresolvable identity. If the auth capture or the partition cannot be built there
+ * is no room key, no tenant and no classification to act on, so the activity takes today's path and
+ * the existing branches apply their own fail-closed rules. Every carriage leg in this plane fails
+ * open, and this one has to as well: a config error must not silently take Teams off the air.
+ *
+ * 🔴 THE ROSTER PROBE IS PAID FOR ONLY WHEN THE POLICY CAN USE IT. This gate runs BEFORE the 200 ack,
+ * so a Bot Connector GET here is latency on EVERY activity — including the ones the front only
+ * forwards — and a slow ack makes the Bot Framework redeliver. The shipped grains (`taint` / `engage`)
+ * can suppress nothing, so `externalPolicyIsInert` skips the probe entirely and an un-opted-in
+ * deployment pays exactly what it paid before. An opted-in one pays one cached GET per
+ * (conversation, user) per TTL. This is the same trade `slack-front.ts` makes on its native
+ * `app_mention` forward, through the same predicate.
+ */
+export async function liveTeamsExternalGate(a: TeamsMessageActivity, probeFor?: TeamsRosterProbeFor): Promise<boolean> {
+  const isDm = a.scope === "personal" || a.scope === "groupChat";
+  let auth: OpenEverywhereTeamsAuth;
+  let partition: Partition;
+  let roomKey: string;
+  try {
+    auth = authForActivity(a);
+    partition = resolvePartition({ channel: { kind: "teams" }, session: { auth: { current: auth } } });
+    // A DM has no parent container to widen to, so it is keyed on its own surface key — the same
+    // split liveTeamsDmDivert makes.
+    roomKey = isDm ? partition.surfaceKey : domainKeyOf(partition);
+  } catch {
+    return false;
+  }
+  const policy = teamsExternalPolicyForRoom(roomKey);
+  // OPE-493: resolve the SURFACE's own refutation, but only when a grain could act on it. Folded in
+  // BEFORE the trust read below, so an opted-in deployment sees the demoted tier as well.
+  if (!externalPolicyIsInert(policy)) auth = await teamsAuthWithUserType(auth, a, probeFor);
+  const trust = resolveWakeTrustFromContext(
+    { channel: { kind: "teams" }, session: { auth: { current: auth as unknown as { attributes?: Readonly<Record<string, string>> } } } },
+    { id: a.from.id, isBot: false },
+    { principalFallback: true },
+  );
+  // EXPLICIT ADDRESSING — one fact, read twice: the verdict owes a private notice on it, and the
+  // OPE-885 ack keys on it. A personal chat is addressing by construction; `isBotMentioned` is
+  // Teams' own mention signal, which a NAME-DROP never sets.
+  const addressed = a.isBotMentioned === true || a.scope === "personal";
+  const verdict = teamsExternalVerdict({
+    policy,
+    // The SAME per-message facts the taint author leg reads: the resolved human tier, the SURFACE's
+    // roster refutation, and the OPERATOR's register question.
+    author: { trust, refuted: teamsAuthorRefuted(auth), ...teamsAuthorFacts(auth, a.from.id) },
+    addressed,
+    isDm,
+    vendorExternal: teamsVendorExternal(a),
+    roomKey,
+    ...teamsRoomGroupKey(auth),
+  });
+  if (verdict === "proceed") return false;
+  // The private notice and the once-ever room announcement both ANSWER the person who addressed us,
+  // and both say more than the ack does — so either suppresses it.
+  let alreadyAnswered = false;
+  if (verdict === "withheld-addressed") alreadyAnswered = await postTeamsExternalSenderNotice(a).catch(() => false);
+  if (verdict === "silent-room") alreadyAnswered = await announceTeamsSilentRoom(a, partition.org, roomKey).catch(() => false);
+  // THE MENTION ACK (OPE-885): an explicit @mention or personal-chat message that got no private
+  // answer gets the one fixed host line, in the conversation it was said in. An AMBIENT message
+  // stays fully dark — `addressed` is false for it, and this is the only gate.
+  const acked =
+    owesSuppressedMentionAck({ addressed, alreadyAnswered }) && (await postTeamsNotice(a, EXTERNAL_MENTION_ACK).catch(() => false));
+  await appendAudit({
+    org: partition.org || deploymentOrg(),
+    platform: "teams",
+    workspace: partition.workspace,
+    surface: roomKey,
+    principalId: a.from.id,
+    action: "teams.external_policy_suppressed",
+    detail: { verdict, conversationId: a.conversation.id, ...suppressionRendering(acked) },
+  }).catch(() => undefined);
+  tlog(`suppressed ${roomKey}: externalPolicy verdict "${verdict}"`);
+  return true;
+}
+
+/**
+ * Resolve the LIVE single-window plan for one verified message activity, fail-closed: any
+ * config/partition error, the gates off, the privacy floor failing, or a missing reply target
+ * all yield null — the front then FORWARDS to the native channel, byte-identical to today.
+ *
+ * The GRAIN + VOUCH are keyed on the DOMAIN-GRAIN key (`teams/<tenant>/<channel>` — a Teams
+ * conversation id names one REPLY CHAIN, so the listable/vouchable container is the channel;
+ * memory/partition.ts's domainKeyOf resolves it via the binding's domainSurface, mirroring the
+ * Discord thread→parent-channel precedent). Operators list/vouch `teams/<tenant>` or
+ * `teams/<tenant>/<channel-id>` (sanitised segments, same as every stored key).
+ */
+export function liveTeamsFrontPlan(a: TeamsMessageActivity): TeamsFrontPlan | null {
+  try {
+    const auth = authForActivity(a);
+    const partition = resolvePartition({ channel: { kind: "teams" }, session: { auth: { current: auth } } });
+    const surfaceKey = domainKeyOf(partition);
+    const grain = supervisorGrainFor(surfaceKey, getConfig().loadDomains());
+    if (!grainUsesUnifiedWindow(grain)) return null; // cross-surface OR solo; common path off-window (byte-identical flag-off)
+    const tenantId = a.tenantId ?? a.conversation.tenantId;
+    // The TEAM rung, derived exactly as identity/binding.ts derives it (see the `vouched` note
+    // below). Undefined on a personal or group chat, and on a malformed team id — `teamsTrustGroup`
+    // validates the charset and `trustGroupKeyFor` validates the `<marker>:<id>` shape, both
+    // fail-closed to no rung.
+    const groupKey = trustGroupKeyFor(partition.workspaceKey, teamsTrustGroup(a.teamId)?.trustGroup);
+    const facts: TeamsSingleWindowFacts = {
+      scope: a.scope,
+      membershipType: teamsMembershipType(a.channelData),
+      tenantId,
+      // The operator's vouch. `isVouchedSurface` WALKS THE DECLARATION RUNGS (OPE-1521), so a
+      // tenant-grain `teams/<tenant>` declaration vouches every room under it, not just the channel
+      // key — and `agent/identity/surfaces.ts` ships such a tenant line. A tenant declaration can't
+      // tell a native internal channel from a Teams CONNECT / shared channel spanning other
+      // tenants, so a shared room whose inbound activity OMITS membershipType passes this floor on
+      // that line. The grain check above already limited us to rooms the domain config enrolls — the
+      // vouch admits a member, it never enrolls one — but that is no second bound: a container entry
+      // claim is legal at tenant grain, and one beside a tenant declaration enrolls the whole
+      // tenant. That is the ruling: a declaration vouches, only a POSITIVE external signal
+      // demotes. Declare the channel rung to narrow the reach. OE_TRUST=internal is still the
+      // deploy-wide blanket switch, and a shared channel is separately refused by the
+      // membershipType guard when the signal IS present.
+      //
+      // 🔴 EVERY RUNG THE BINDING READS IS PASSED HERE TOO (OPE-1538), and that is the whole point:
+      // this floor used to be handed the CHANNEL key alone, so two tiers were invisible to it and
+      // both misses were fail-open. A `public` `teams/<tenant>/team:<id>` team carve-out and a
+      // `public` declaration on ONE reply chain each demoted on the binding and memory planes
+      // (identity/binding.ts passes the conversation key, the channel key and the team rung) while
+      // this floor saw only the tenant entry and admitted the room — at the one gate where admitting
+      // means joining a private cross-surface window. The three keys below are the same three, in
+      // the same preference order, derived through the same helpers: `partition.surfaceKey` is the
+      // reply chain, `surfaceKey` is `domainKeyOf`'s channel, and `trustGroupKeyFor` +
+      // `teamsTrustGroup` build the team rung exactly as the mapper does. One spelling per rung,
+      // across both planes. The team rung is absent on a personal or group chat, which carry no team
+      // id and are refused by the scope check anyway.
+      vouched:
+        isVouchedSurface(partition.surfaceKey, { containerKey: surfaceKey, ...(groupKey === undefined ? {} : { groupKey }) }) ||
+        process.env.OE_TRUST === "internal",
+    };
+    const window = planTeamsSingleWindow(true, a.isBotMentioned, facts, {
+      serviceUrl: a.serviceUrl,
+      conversationId: a.conversation.id,
+      replyToActivityId: teamsThreadRootActivityId(a) ?? undefined,
+      tenantId,
+      // THE FRONT-DOOR RECEIPT (OPE-1716) — a Bot-Framework activity carries no parsed timestamp on
+      // eve's shape (the same fact the trigger's `sentAt` records below), so the ingress row records
+      // our own instant and marks it `receipt`, which the split reporter renders as a LOWER BOUND.
+      // 🔴 Taken HERE, at the plan, not at the route's first byte — so on Teams the vendor→ingress
+      // segment is a floor near zero and says nothing about the vendor's own hop.
+      ...spreadVendorTs(receiptEventTime(Date.now())),
+    });
+    if (!window) return null;
+    return { window, surfaceKey, partition, grain, auth };
+  } catch {
+    return null; // fail-closed → the native path keeps ownership
+  }
+}
+
+// --- the live dispatch (session deps + the diversion) -----------------------------------------
+
+/** Live supervisor deps over the (org, grain.registryKey) channel_session registry — the exact
+ *  notion.ts/linear.ts shape. The wake ALWAYS diverts (teams-supervisor requires the window). */
+/**
+ * EXPORTED FOR THE INGRESS CONTRACT TEST (OPE-1719), not for another caller. `liveTeamsDispatch` is
+ * the only production caller and it is thirty lines below. `scripts/owned-thread-ingress-wiring-test.ts`
+ * drives the `wake` member of THIS object — the real Teams ingress divert — because a test that
+ * reimplemented the wake dep would stay green after somebody moved this leg back to the raw divert,
+ * which is the exact regression the ticket closes.
+ */
+export function liveTeamsSupervisorDeps(plan: TeamsFrontPlan, to: RouteHandlerArgs["to"]): TeamsSupervisorDeps {
+  const org = plan.partition.org;
+  const store = getOperationalStore();
+  const grain = plan.grain;
+  return {
+    async getOrCreateSession(_surfaceKey, channelId, atIso) {
+      // OPE-599: claim the runtime-change rotation BEFORE the row read, and unconditionally (the
+      // mint arm must consume it too). Why, and why here: channels/runtime-rotation.ts.
+      const runtimeChanged = await claimRuntimeRotation({ org, registryKey: grain.registryKey, surfaceKey: plan.surfaceKey, domainName: grain.domainName, atIso });
+      const existing = await store.getChannelSession(org, grain.registryKey);
+      if (!existing) {
+        const row = await store.rotateChannelSession(org, grain.registryKey, mintRotationToken(grain, 1, () => teamsSupervisorToken(channelId, 1)), atIso);
+        // OPE-1821: stamp the pair onto the row this build just minted. Without it the seat's next
+        // wake reads NULL, takes the ADOPTED arm and never rotates for the deploy it crossed.
+        await stampMintedRuntime({ org, registryKey: grain.registryKey, surfaceKey: plan.surfaceKey, domainName: grain.domainName, atIso });
+        return { token: row.token, generation: row.generation, freshGeneration: true, tail: [] as readonly WakeMessageInput[] };
+      }
+      if (shouldRotate(existing, atIso, { runtimeChanged })) {
+        const gen = existing.generation + 1;
+        // OPE-794: read the OUTGOING generation's recorded tail BEFORE minting its successor. On
+        // Teams this is the ONLY continuity there is — the surface exposes no history read.
+        const tail = await carryTailForward(org, grain.registryKey, existing.token);
+        const row = await store.rotateChannelSession(org, grain.registryKey, mintRotationToken(grain, gen, () => teamsSupervisorToken(channelId, gen)), atIso);
+        return { token: row.token, generation: row.generation, freshGeneration: true, tail };
+      }
+      // A resume whose first wake never delivered (first_wake_at NULL) is still "fresh" (H7c). Its
+      // tail is empty — carried and cleared at the rotation that minted this row.
+      // `lastWakeAt` rides out on THIS arm alone: it is the catch-up read's lower bound, and a fresh
+      // or just-rotated generation has none (rotation resets the column).
+      return {
+        token: existing.token,
+        generation: existing.generation,
+        freshGeneration: existing.firstWakeAt == null,
+        tail: [] as readonly WakeMessageInput[],
+        lastWakeAt: existing.lastWakeAt ?? null,
+      };
+    },
+    touchSession: (_surfaceKey, atIso) => store.touchChannelSession(org, grain.registryKey, atIso),
+    // THE SINCE-LAST-WAKE CATCH-UP (OPE-1726), through the shared path core holds. Teams' own fetch
+    // is registered at bundle registration and reads over Microsoft Graph, not the Bot Connector this
+    // wake arrived on. The admission policy is the DOMAIN's, resolved by the shared road itself from
+    // the request's own channel key (OPE-1857). No `trustFor`: this surface has no synchronous
+    // roster probe for a channel author at wake time, so the shared core's FAIL-CLOSED per-sender
+    // default applies.
+    catchUp: (req) => seatCatchUp("teams", req),
+    // OPE-794 — file this wake on the live generation's tail ring. Same key derivation as the
+    // rotation read and the spend counter, so all three target one row.
+    recordWake: (entry, token) => recordWakeTail(org, grain.registryKey, token, entry),
+    now: () => new Date().toISOString(),
+    async wake({ token, auth, message, context, window }) {
+      // SINGLE-WINDOW diversion (channels/unified-window.ts): the wake goes through eve's
+      // cross-channel `to(...).send(...)` into the synthetic `unified` channel, so its effective token is
+      // `unified:<raw>`, shared with the domain's Slack/GitHub/Linear/Notion wakes — ONE context
+      // window. The unified channel's receive registers the wakeId→origin map entry (durably,
+      // BEFORE the send) and re-checks the gates fail-closed. A failure propagates to the FIFO's
+      // loud catch (fail-closed: never delivered without a routable reply target).
+      //
+      // THE OWNED-THREAD INGRESS SEAM (§2.6, OPE-1719) — the INBOUND variant, the one Slack's front
+      // route has always used. A wake landing in a reply chain a live task worker or thread seat
+      // OWNS is dispatched to that owner's token instead of the standing seat's. On Teams the reply
+      // chain IS the thread (`replyToActivityId`), so a plain conversation send stays top-level and
+      // never consults ownership. Flag-off, and on every unowned chain, this is a byte-identical
+      // passthrough to `divertToUnifiedWindow`.
+      await divertInboundToUnifiedWindow(to, {
+        message,
+        ...(context.length > 0 ? { context } : {}),
+        token,
+        window,
+        surfaceKey: plan.surfaceKey,
+        auth: auth as unknown as { attributes?: Record<string, unknown> },
+      });
+    },
+  };
+}
+
+// --- the composed front handler ----------------------------------------------------------------
+
+/** Injectable seams so the front is testable without live JWT verification / a Bot registration. */
+export interface TeamsFrontOptions {
+  /** Verify one inbound request and return the raw body; throw to reject (401). Defaults to
+   *  eve's `verifyTeamsRequest` with env credentials (MICROSOFT_APP_ID / TEAMS_APP_ID) — the
+   *  same fallback the credential-less teamsChannel uses. */
+  readonly verify?: (req: Request) => Promise<string>;
+  readonly dedupe?: EventDedupe;
+  readonly fifo?: ThreadFifo;
+  readonly now?: () => number;
+  /** Durable first-sighting check (true = proceed). Defaults to the operational store. */
+  readonly markEventSeen?: (org: string, key: string, atIso: string) => Promise<boolean>;
+  /** The single-window plan for one verified activity. Defaults to {@link liveTeamsFrontPlan}
+   *  (grain + fail-closed privacy floor); fail-closed null ⇒ forward, byte-identical. */
+  readonly planFor?: (a: TeamsMessageActivity) => TeamsFrontPlan | null;
+  /** The dispatch executor (defaults to the real supervisor dispatch over the live deps). */
+  readonly dispatch?: (a: TeamsMessageActivity, plan: TeamsFrontPlan, to: RouteHandlerArgs["to"]) => Promise<void>;
+  /** The DM window divert (OPE-357) — defaults to {@link liveTeamsDmDivert}. Injected so the front's
+   *  DM-routing decision (predicate + fail-closed to native) is unit-testable without a live store. */
+  readonly dmDivert?: (a: TeamsMessageActivity, auth: OpenEverywhereTeamsAuth, partition: Partition, to: RouteHandlerArgs["to"]) => Promise<void>;
+  /** The external-participant gate (OPE-507/OPE-504) — `true` suppresses the activity. Defaults to
+   *  {@link liveTeamsExternalGate}; injected so the front's ORDERING (above both branches, so the
+   *  native forward is covered too) is unit-testable without a store or a Bot registration. */
+  readonly externalGate?: (a: TeamsMessageActivity) => Promise<boolean>;
+  /** The stop-reaction arm (OPE-898) — defaults to {@link routeTeamsStopReaction} over eve's cancel
+   *  door. Injected so the front's ORDERING (above `parseTeamsActivity`, which never sees a reaction
+   *  activity) is unit-testable without a live session. */
+  readonly stopReaction?: (rx: TeamsReactionActivity, attachSession: AttachSessionForCancel) => Promise<TeamsStopOutcome>;
+  /** The ambient engagement seam's READ (OPE-1500) — defaults to {@link resolveTeamsEngagement}.
+   *  Injected so the front's ORDERING (above both the DM divert and Leg A, so one message is never
+   *  handled by two legs) is unit-testable without an operational store. */
+  readonly engagementSeam?: (a: TeamsMessageActivity, machineAuthored: boolean) => Promise<TeamsEngagementVerdict>;
+  /** The ambient engagement seam's WRITE — defaults to {@link markTeamsEngaged}. Separate from the
+   *  read so a test can assert that exactly one mention marks exactly one row. */
+  readonly markEngaged?: (a: TeamsMessageActivity) => Promise<string | null>;
+  /** Leg A's ROOM-grain stop READ (OPE-1511) — defaults to {@link teamsRoomWatchStopped}. Injected
+   *  so the front's ORDERING (below the mention re-invitation, above the dispatch) is unit-testable
+   *  without an operational store. */
+  readonly roomStopped?: (partition: Partition) => Promise<boolean>;
+  /** Leg A's ROOM-grain wake row WRITE — defaults to {@link markTeamsRoomWatched}. */
+  readonly markRoomWatched?: (partition: Partition, atIso: string) => Promise<void>;
+  /** The @mention's ROOM-grain re-invitation — defaults to {@link clearTeamsRoomStop}. Separate
+   *  from the read so a test can prove a mention is the way back out of a room stop. */
+  readonly clearRoomStop?: (partition: Partition, atIso: string, engagedBy: string) => Promise<void>;
+}
+
+const OK = () => new Response("ok");
+
+// Durable half of the retry dedupe (Bot Framework redelivers on non-200): mirrors slack-front's
+// liveMarkEventSeen — FAIL-OPEN by design (dedupe prevents a double reply, not a security hole).
+const DEDUPE_TTL_MS = 10 * 60_000;
+let warnedDedupeStore = false;
+async function liveMarkEventSeen(org: string, key: string, atIso: string): Promise<boolean> {
+  try {
+    return await getOperationalStore().markEventSeen(org, key, atIso, DEDUPE_TTL_MS);
+  } catch (err) {
+    if (!warnedDedupeStore) {
+      warnedDedupeStore = true;
+      console.warn(`[open-everywhere:teams-front] durable dedupe unavailable — in-memory only: ${String(err)}`);
+    }
+    return true;
+  }
+}
+
+/** A swallowed FIFO wake failure, made durable (mirrors slack-front's recordWakeFailure posture:
+ *  the console line rolls in ~1h; the audit row is the queryable signal). Never throws. */
+function recordTeamsWakeFailure(key: string, err: unknown): void {
+  void appendAudit({
+    org: deploymentOrg(),
+    platform: "teams",
+    workspace: key.split("/")[1] ?? "unknown",
+    surface: key,
+    action: "surface.wake_failed",
+    detail: { fifoKey: key, message: String(err instanceof Error ? err.message : err).slice(0, 500) },
+  }).catch(() => undefined);
+}
+
+/** The live dispatch for one owned activity: per-message trust off the SAME auth capture the
+ *  session binds with, then the teams-supervisor core over the live registry deps.
+ *
+ *  `probeFor` is the roster test seam — see {@link teamsAuthWithUserType}. */
+export async function liveTeamsDispatch(
+  a: TeamsMessageActivity,
+  plan: TeamsFrontPlan,
+  to: RouteHandlerArgs["to"],
+  probeFor?: TeamsRosterProbeFor,
+): Promise<void> {
+  // OPE-493: the roster verdict, resolved ONCE and folded into the capture that everything below
+  // reads — the per-message trust, the author-refutation leg and the auth the session binds with.
+  // Fail-open: no verdict leaves `auth` byte-identical to `plan.auth`.
+  const auth = await teamsAuthWithUserType(plan.auth, a, probeFor);
+  const wakeCtx: BindableContext = { channel: { kind: "teams" }, session: { auth: { current: auth as unknown as { attributes?: Readonly<Record<string, string>> } } } };
+  // isBot:false is safe here: the front's author gate already dropped self/bot-authored
+  // activities, so a dispatched trigger is a positively-human author (the Slack analog drops
+  // authorIsBot in shouldSupervisorWake).
+  const trust = resolveWakeTrustFromContext(wakeCtx, { id: a.from.id, isBot: false }, { principalFallback: true });
+  let engagementTier: ReturnType<typeof engagementTierFor> | undefined;
+  try {
+    engagementTier = engagementTierFor(plan.surfaceKey, getConfig().loadDomains());
+  } catch {
+    engagementTier = undefined; // fail-soft to neutral, same as every other surface
+  }
+  // 🔴 THE GRAPH TEAM ID, NOT THE ACTIVITY'S OWN (OPE-1808). `a.teamId` is the BOT CONNECTOR's team
+  // id (`19:…@thread.tacv2`); every Graph URL the catch-up builds takes the team's Microsoft 365
+  // GROUP id instead. Resolved through the Connector and cached per team — see
+  // channels/teams-graph-team-id.ts. Unresolvable ⇒ absent, and the dispatch then STATES that it
+  // cannot read this surface's history rather than reading an empty window.
+  const graphTeamId = await teamsGraphTeamId(a.teamId, a.serviceUrl);
+  const replyChainRootId = teamsReplyChainRoot(a.conversation.id);
+  // 🔴 ONE EXPRESSION, READ TWICE (OPE-1747): the taint join below and the dispatch's `ingested`
+  // carriage, which is what the TAIL ROW records. Re-deriving it at the second reader would be a
+  // second opinion that can disagree with the first about one author.
+  const triggerFacts: IngestedChatMessage = { trust, refuted: teamsAuthorRefuted(auth), ...teamsAuthorFacts(auth, a.from.id) };
+  await handleTeamsSingleWindowDispatch(
+    {
+      surfaceKey: plan.surfaceKey,
+      // OPE-1528 — the wake row's `container` is the CONVERSATION grain, the same key the post that
+      // answers it files under (`partition.surfaceKey` → session-tail-record.ts `tailWindowFor`).
+      // `plan.surfaceKey` is the DOMAIN grain and belongs to the gate, the registry row and the
+      // audit surface, never to the ring.
+      containerKey: plan.partition.surfaceKey,
+      // 🔴 THE CHANNEL GRAIN, NEVER THE REPLY CHAIN (OPE-1817). Graph addresses a history read as
+      // `/teams/{team}/channels/{channel}`, and a CHANNEL activity's `conversation.id` carries
+      // `;messageid=<root>` — a reply-chain id Graph has no channel by that name for, so the
+      // unstripped fallback was a 404 the catch-up then read as an empty room. `teamsChannelId`
+      // (`channelData.channel.id`) is already at channel grain; the fallback is now stripped to it.
+      channelId: a.teamsChannelId ?? teamsChannelGrainConversationId(a.conversation.id),
+      // The TEAM the channel sits in, in GRAPH's own spelling — present only on a CHANNEL activity
+      // whose Connector team id resolved, and a channel activity is the only shape that has a
+      // Graph-readable history at all. Absent ⇒ the catch-up is skipped, never guessed.
+      ...(graphTeamId ? { teamId: graphTeamId } : {}),
+      // The activity NAMED a team and its Graph id would not resolve — a transient bound on this
+      // wake, which the dispatch states differently from a chat's structural one.
+      ...(!graphTeamId && a.teamId ? { teamAddressUnresolved: true } : {}),
+      // OPE-466 CARRIAGE, over the TRIGGER ONLY (this leg carries no per-message-trust backscroll).
+      // OPE-489: the author leg reads the POSITIVE refutation — a resolved `userRole: "guest"`.
+      //
+      // OPE-493: THE FRONT NOW RUNS THE PROBE. `teamsAuthWithUserType` above resolved the Bot
+      // Connector roster verdict and folded it into `auth`, so the SURFACE refutation answers on this
+      // path exactly as it does on the native one. The roster probe IS live — a real B2B guest returns
+      // `userRole: "guest"` and a tenant member returns `"user"` (measured 2026-08-15). An
+      // unresolved verdict is still absent, and this leg fails OPEN on absence.
+      //
+      // OPE-516/OPE-525: the OPERATOR's register (`teamsAuthorFacts`) is the SECOND source of
+      // refutation, and answers where the roster cannot (a guest the connector will not report, a
+      // tenant whose bot credential cannot read the roster). Unarmed ⇒ it contributes nothing.
+      auth: stampNonMemberChatAuth(auth, [triggerFacts], {
+        surfaceKey: plan.surfaceKey,
+        ...teamsRoomGroupKey(auth),
+      }),
+      // THE SAME ONE ENTRY the join above reads — carried so the dispatch's tail row records it.
+      ingested: [triggerFacts],
+      trigger: {
+        id: a.id,
+        authorId: a.from.id,
+        authorName: a.from.name,
+        // Bot-Framework activities carry no parsed timestamp on eve's shape — the arrival time
+        // is the honest stamp (the same "now" the envelope's current-time uses).
+        sentAt: new Date().toISOString(),
+        text: a.text || "(the message had no text)",
+        trust,
+      },
+      // Thread meta ⇔ the trigger sat inside an EXISTING reply chain (its replyToId); a
+      // top-level channel post starts its own chain and renders container-scoped, mirroring
+      // Slack's threadTs-presence semantics.
+      ...(a.replyToId ? { threadRootId: teamsThreadRootActivityId(a) ?? a.replyToId } : {}),
+      // 🔴 THE READ'S OWN ROOT, AND IT IS NOT `threadRootId` (OPE-1817). The two answer different
+      // questions and only one of them is about Graph:
+      //   • `threadRootId` is the ENVELOPE's thread meta. It is deliberately absent on a top-level
+      //     post, because that post renders container-scoped — Slack's semantics, kept.
+      //   • this one is the CONTAINER THE SEAT IS BOUND TO. `plan.partition.surfaceKey` is the
+      //     CONVERSATION grain (`bindTeams`'s `surface`), and on a channel activity that is always
+      //     one reply chain, named by the `;messageid=<root>` suffix — present on a top-level post
+      //     too, where it is that post's own id.
+      // The catch-up must read THAT chain TOO. `/channels/{c}/messages` returns the channel's
+      // top-level messages, which by Graph's contract carry no replies at all, so a chain that did
+      // carry the message came back empty (ship #206/#207). `wakeAddress` in `teams-read.ts`
+      // already resolves the root this way for `read_thread`; this is the same resolution, brought
+      // to the read the seat's own wake depends on.
+      ...(replyChainRootId ? { replyChainRootId } : {}),
+      engagementTier,
+      window: plan.window,
+    },
+    liveTeamsSupervisorDeps(plan, to),
+  );
+  await appendAudit({
+    org: plan.partition.org,
+    platform: "teams",
+    workspace: plan.partition.workspace,
+    surface: plan.surfaceKey,
+    principalId: a.from.id,
+    action: "teams.dispatched",
+    detail: { addressing: plan.window.addressing ?? "channel-watch", conversationId: a.conversation.id },
+  }).catch(() => undefined);
+}
+
+/**
+ * THE DM WINDOW DIVERT (OPE-357) — a Teams personal/group chat lands in its OWN first-class standing
+ * window (channels/dm-seat.ts), the Teams parity of divertDiscordDmToWindow / slack-front's
+ * scheduleDmWake, and the last DM-family surface to first-class (Slack: OPE-351 stages 2+4; Discord:
+ * OPE-356).
+ *
+ * WHAT IT FIXES. Until now a Teams DM ran on eve's native per-conversation token (teams.ts's
+ * onMessage): a session with no window row, and therefore NO DISPATCHABLE ADDRESS. A DM that delegated
+ * could not be told the answer had arrived — `resolveCallerSeat` took the OPE-306 ANCHOR arm and the
+ * worker posted its own report into the DM (the OPE-358 double-post). A window token IS an address, so
+ * the DM seat now gets the whole standing-seat apparatus for free: woken, redriven, rotated (on the DM
+ * thresholds — `OE_DM_SEAT_ROTATE_*`, never the supervisor's), spend-counted and audited through the
+ * seams every other seat already uses. The worker's direct report-back stops the moment the seat
+ * becomes a real window (its caller now resolves via `ownWindowSeat`, not the anchor) — no two voices
+ * in one DM per delegated turn.
+ *
+ * SEPARATE ADMIT SPACE, NOT A FLOOR BYPASS. This never touches `teamsSingleWindowPrivacyOk`: that floor
+ * refuses `scope !== "channel"` outright because a personal/group chat may never join the SHARED
+ * cross-surface window, and it stays exactly that strict. A DM window is a STRUCTURALLY DIFFERENT,
+ * non-shared address space keyed on the DM's own surface key (`getOrCreateDmSeat`), deliverable to its
+ * own DM and nowhere else — which is precisely why it is safe to admit a DM here without weakening the
+ * channel floor (the Discord `isDm`-before-the-single-window-block precedent).
+ *
+ * 🔴 IT BYPASSES THE ENGAGEMENT GATE — a DM is always answered (see {@link buildTeamsDmWake}). The
+ * SPEND gate is NOT bypassed: `divertToUnifiedWindow` runs its own window-door gate (channels/unified.ts
+ * windowSpendGate), which is exactly the choke point every Teams single-window divert already leans on
+ * (Teams has never front-positioned a pre-gate, unlike Discord).
+ *
+ * FAIL-CLOSED: a seat-resolution or dispatch failure PROPAGATES to the FIFO's loud catch. There is
+ * deliberately NO fall-back to the native send — that would answer the human from a second session with
+ * no window row behind it, the very topology this replaces (and the OPE-351 stranding hazard).
+ */
+export async function liveTeamsDmDivert(
+  a: TeamsMessageActivity,
+  capturedAuth: OpenEverywhereTeamsAuth,
+  partition: Partition,
+  to: RouteHandlerArgs["to"],
+  probeFor?: TeamsRosterProbeFor,
+): Promise<void> {
+  // OPE-493: the roster verdict for the DM PARTNER, folded into the capture before anything reads it.
+  // A Teams DM used to bind `internal` unconditionally (teamsTrust's personal-silo branch), so a B2B
+  // guest DMing the bot lit the `dm` shared memory layer. A resolved guest now demotes it to
+  // `external`, which is what the Slack DM-partner probe has always done. Fail-open: no verdict
+  // leaves the capture byte-identical.
+  const auth = await teamsAuthWithUserType(capturedAuth, a, probeFor);
+  const org = partition.org;
+  const atIso = new Date().toISOString();
+  // A DM has no parent container to widen to, so the seat is keyed on the DM's OWN surface key —
+  // NOT domainKeyOf (which resolves a channel's parent). For a personal/group chat the mapper leaves
+  // domainSurface unset, so partition.surfaceKey already IS the conversation-grain key.
+  const surfaceKey = partition.surfaceKey;
+  const conversationId = a.conversation.id;
+
+  // The seat: create / rotate / resume the DM's own standing window row.
+  const seat = await getOrCreateDmSeat(org, { surfaceKey }, atIso);
+
+  // PER-WAKE TRUST off the SAME auth capture the session binds with; `principalFallback` because a DM
+  // partner is the seat's principal. `isBot:false` is safe — the front's author gate already dropped
+  // self/bot-authored activities before this runs.
+  const wakeCtx: BindableContext = {
+    channel: { kind: "teams" },
+    session: { auth: { current: auth as unknown as { attributes?: Readonly<Record<string, string>> } } },
+  };
+  const trust = resolveWakeTrustFromContext(wakeCtx, { id: a.from.id, isBot: false }, { principalFallback: true });
+  const wakeId = mintWakeId();
+
+  // The frozen reply target: a PLAIN conversation send into the DM — no `replyToActivityId` (a personal
+  // chat has no reply chain; a group chat's chain anchor is not a divert fact) — the shape
+  // teamsPostArm.dispatchUnified already posts back through (serviceUrl + conversationId, no reply
+  // anchor ⇒ plain send). This IS the mint now: the codec's `dmOrigin` arm that used to produce the
+  // same minimal origin for a DM delegation anchor went with the anchor (OPE-368).
+  const origin: UnifiedWakeOrigin = { platform: "teams", serviceUrl: a.serviceUrl, conversationId };
+
+  const rendered = renderWake(
+    buildTeamsDmWake({
+      conversationId,
+      wakeId,
+      ...(seat.freshGeneration && seat.tail.length > 0 ? { tail: seat.tail } : {}),
+      trigger: {
+        id: a.id || "unknown",
+        author: a.from.name ?? a.from.id,
+        authorId: a.from.id,
+        sentAt: atIso,
+        text: a.text || "(the message had no text)",
+        trust,
+      },
+    }),
+  );
+  await divertToUnifiedWindow(to, {
+    message: rendered.message,
+    ...(rendered.context && rendered.context.length > 0 ? { context: rendered.context } : {}),
+    token: seat.token,
+    // `vendorTs` (OPE-1716): the DM leg's own FRONT-DOOR RECEIPT, for the same reason and with the
+    // same limits as the channel leg's — a Bot-Framework activity carries no parsed timestamp. A DM
+    // wake without it would leave its ingress row with no first anchor at all.
+    window: { wakeId, origin, addressing: "direct-mention", ...spreadVendorTs(receiptEventTime(Date.now())) } satisfies UnifiedWindowWake,
+    // Byte-exactly the surface named inside the token — the self-consistency both admission gates match
+    // on, and the whole privacy fence (a DM window is deliverable to ITS OWN DM and nowhere else).
+    surfaceKey,
+    // OPE-466 CARRIAGE: one ingested message, so the join runs over the trigger's own tier.
+    // OPE-489: the author leg reads a positively-resolved `userRole: "guest"`, which the roster probe
+    // above put on this capture (OPE-493); a DM has no room leg (`dm: true` — on a DM the trust plane
+    // asks about the PARTNER, not about the room).
+    auth: stampNonMemberChatAuth(
+      auth as unknown as { attributes?: Record<string, unknown> },
+      [{ trust, refuted: teamsAuthorRefuted(auth), ...teamsAuthorFacts(auth, a.from.id) }],
+      { dm: true },
+    ),
+  });
+  // Record the wake on the seat's own row (turnCount/lastWakeAt feed the rotation thresholds),
+  // best-effort — a touch failure must never affect the reply.
+  await touchDmSeat(org, surfaceKey, atIso).catch(() => undefined);
+  // OPE-794 — file this DM wake on the live seat generation's tail ring, AFTER it landed, and only
+  // the TRIGGER. The registry key is the DM window key, the same row the seat itself lives in.
+  await recordWakeTail(org, dmWindowRegistryKey(surfaceKey), seat.token, {
+    kind: "wake",
+    at: atIso,
+    from: "human", // the front's author gate already dropped self/bot-authored activities
+    trust,
+    // THE AUTHOR GRAIN (OPE-1747) — the same triple the DM's `stampNonMemberChatAuth` join above
+    // reads: the resolved tier, Entra's `userType: "guest"` refutation, and the operator's register.
+    ...tailAuthorGrain({ trust, refuted: teamsAuthorRefuted(auth), ...teamsAuthorFacts(auth, a.from.id) }),
+    author: a.from.name ?? a.from.id,
+    authorId: a.from.id,
+    id: a.id || "unknown",
+    platform: "teams",
+    container: surfaceKey,
+    text: a.text ?? "",
+  });
+  await appendAudit({
+    org,
+    platform: "teams",
+    workspace: partition.workspace,
+    surface: surfaceKey,
+    principalId: a.from.id,
+    action: "teams.dispatched",
+    detail: { addressing: "direct-mention", dmWindow: true, conversationId },
+  }).catch(() => undefined);
+}
+
+/**
+ * Build the front route handler. Verifies (fail-closed 401), classifies, then forwards or
+ * diverts. `innerHandler` is teamsChannel's own POST handler, invoked with a FRESH Request
+ * (re-readable body) + the same {@link RouteHandlerArgs}, so teamsChannel re-verifies and
+ * dispatches exactly as if it owned the URL — byte-identical whenever no plan resolves.
+ */
+export function buildTeamsFrontHandler(innerHandler: RouteHandler, opts: TeamsFrontOptions = {}): RouteHandler {
+  // TODO(teams-front-credentials): the default verify uses env app id only (`{}`). If the wrapped
+  // native teamsChannel is ever built with `credentials.appId` or a custom webhookVerifier, the
+  // front would verify with a DIFFERENT config than the inner re-verify (front could 401 a request
+  // the inner would accept, or vice-versa). Harmless today (teams.ts passes no credentials, so both
+  // sides use the env app id), but if teams.ts starts passing credentials, thread them here via
+  // opts.verify. Needs eve's Channel to expose the inner verifier config to plumb cleanly.
+  const verify = opts.verify ?? ((req: Request) => verifyTeamsRequest(req, {}));
+  const dedupe = opts.dedupe ?? new EventDedupe();
+  const fifo = opts.fifo ?? new ThreadFifo(recordTeamsWakeFailure);
+  const now = opts.now ?? (() => Date.now());
+  const markEventSeen = opts.markEventSeen ?? liveMarkEventSeen;
+  const planFor = opts.planFor ?? liveTeamsFrontPlan;
+  const dispatch = opts.dispatch ?? liveTeamsDispatch;
+  const dmDivert = opts.dmDivert ?? liveTeamsDmDivert;
+  const externalGate = opts.externalGate ?? liveTeamsExternalGate;
+  const stopReaction = opts.stopReaction ?? ((rx: TeamsReactionActivity, attachSession: AttachSessionForCancel) => routeTeamsStopReaction(rx, { attachSession }));
+  const engagementSeam = opts.engagementSeam ?? resolveTeamsEngagement;
+  const markEngaged = opts.markEngaged ?? ((a: TeamsMessageActivity) => markTeamsEngaged(a));
+  const roomStopped = opts.roomStopped ?? teamsRoomWatchStopped;
+  const markRoomWatched = opts.markRoomWatched ?? markTeamsRoomWatched;
+  const clearRoomStop = opts.clearRoomStop ?? clearTeamsRoomStop;
+
+  return async (req: Request, args: RouteHandlerArgs): Promise<Response> => {
+    let rawBody: string;
+    try {
+      rawBody = await verify(req);
+    } catch {
+      return new Response("unauthorized", { status: 401 });
+    }
+    const forward = (): Promise<Response> => {
+      const forwarded = new Request(req.url, { method: "POST", headers: req.headers, body: rawBody });
+      return innerHandler(forwarded, args);
+    };
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(rawBody);
+    } catch {
+      return forward(); // unparseable — let teamsChannel ack it exactly as today
+    }
+    // ── THE STOP REACTION (OPE-898) ──────────────────────────────────────────────────────────────
+    //
+    // POSITION IS LOAD-BEARING. It sits ABOVE `parseTeamsActivity`, because that parser answers only
+    // for `message` activities — a `messageReaction` comes back as null and would fall straight into
+    // the forward below, which is why this affordance did nothing before. It is also the whole point
+    // that this runs in the INGRESS: `cancelAnchoredTurn` mints no session and calls no model, so a
+    // stop stays free and keeps working for a scope that is already over its spend cap.
+    //
+    // ACK, NEVER FORWARD. The native channel has nothing to do with a reaction activity, and the arm
+    // fails closed on every unknown — an unrecognised body simply is not a reaction and returns null.
+    const reaction = parseTeamsReaction(parsed);
+    if (reaction) {
+      args.waitUntil(
+        stopReaction(reaction, args.attachSession).then(
+          (o) => tlog(`reaction in ${reaction.conversationId ?? "?"}: ${o.stopped ? o.outcome : o.reason}`),
+          (err) => tlog(`stop leg failed: ${String(err)}`),
+        ),
+      );
+      return OK();
+    }
+
+    const activity = parseTeamsActivity(parsed);
+    if (!activity || activity.type !== "message") {
+      return forward(); // invokes / conversationUpdates / unknown — the native channel owns them
+    }
+
+    // The author gate, resolved ONCE for every branch below: a self/bot-authored activity never
+    // wakes anything here. It is also the reason the policy gate below skips them — a machine author
+    // is below peer standing but it is not a person outside the organisation (the `relay` ruling in
+    // access/external-policy.ts), so it has no author-grain verdict to receive.
+    // ONE PREDICATE, SHARED WITH THE SEAM (channels/teams-engagement.ts). The native gate needs the
+    // same answer — a machine-authored CHANNEL activity is still forwarded to it — and two spellings
+    // of "is this a bot" is how one of them comes to miss a case the other catches.
+    const machineAuthored = teamsMachineAuthored(activity);
+
+    // ── THE EXTERNAL-PARTICIPANT POLICY (OPE-507 author grain, OPE-504 room grain) ────────────────
+    //
+    // POSITION IS LOAD-BEARING, and for TWO reasons on Teams. It sits above the DM divert and above
+    // `planFor`, so (a) an activity the agent may not act on costs nothing — no seat resolution, no
+    // session mint, no spend read — and (b) a SUPPRESSED activity is never FORWARDED, which is what
+    // extends the policy to a deployment running the native path with the window gates off.
+    //
+    // Both grains are inert under their shipped values (`taint` / `engage`), so this is a no-op on
+    // every deployment that has not opted in.
+    if (!machineAuthored && (await externalGate(activity))) return OK();
+
+    // ── CAPTURE THE CONVERSATION REFERENCE (OPE-887) ─────────────────────────────────────────────
+    //
+    // THE ONE PLACE A PROACTIVE TEAMS ADDRESS EVER COMES FROM. A Bot Framework send needs a regional
+    // `serviceUrl` and a Microsoft-minted conversation id, and neither exists anywhere but on an
+    // inbound activity — so an activity that passes here without being recorded is an address this
+    // deployment can never hold again. Both Teams arms that address a person or a team with no live
+    // turn (the DM arm, the account directory) read what this writes.
+    //
+    // POSITION IS LOAD-BEARING, in both directions. It sits BELOW the external-participant gate, so a
+    // suppressed author never contributes an address the agent could later message; and it sits ABOVE
+    // the DM divert and `planFor`, so it captures EVERY activity this deployment acts on — including
+    // the ones that fall through to the native path when the window gates are off, which no branch
+    // below would have covered.
+    //
+    // AFTER THE ACK, and fail-soft inside: `recordTeamsConversationReference` never throws, and a lost
+    // capture costs a future delivery, never this wake. Machine-authored activities record nothing —
+    // there is no person or team to reach behind a bot.
+    if (!machineAuthored) {
+      args.waitUntil(
+        recordTeamsConversationReference({
+          scope: activity.scope,
+          tenantId: activity.tenantId ?? activity.conversation.tenantId,
+          conversationId: activity.conversation.id,
+          serviceUrl: activity.serviceUrl,
+          userId: activity.from.id,
+          teamId: activity.teamId,
+        }),
+      );
+    }
+
+    // ── LEG E: THE AMBIENT ENGAGEMENT SEAM (OPE-1500, contract §2.5) ─────────────────────────────
+    //
+    // The middle posture, and the one Teams had no form of: an @mention marks the conversation
+    // ENGAGED, a later PLAIN message in it wakes the agent, and `stand_down` stores the stop. The
+    // policy is core's (`channels/engagement.ts` — `markThreadEngaged` / `shouldDeliverReply` / the
+    // durable `stopped` flag); `channels/teams-engagement.ts` translates Teams facts into it.
+    //
+    // POSITION IS LOAD-BEARING, and it is what keeps LEG A AND LEG E FROM DOUBLE-HANDLING ONE
+    // MESSAGE. This block runs ABOVE both the DM divert and `planFor`, and it dispatches NOTHING of
+    // its own. It contributes exactly two decisions, and every wake below stays the property of the
+    // leg that already owned it:
+    //   • THE MARK, on a mention, on EVERY path — including a single-window channel, where Leg A
+    //     answers the mention. Without the mark on that path `stand_down` would have no row to flag
+    //     and would refuse on a surface the verb is supposed to work on.
+    //   • THE SUPPRESSION, on a stood-down conversation, ABOVE EVERYTHING — never diverted, never
+    //     forwarded, so both legs go quiet. This is the half §7.6 of the contract records as
+    //     missing: Leg A's ambient wake reads no registry of its own.
+    //
+    // 🔴 WHAT THIS SUPPRESSION COVERS, AND WHERE THE OTHER HALF LIVES. The `stopped` flag read here
+    // sits on a CONVERSATION row, and only an @mention writes one — so this block closes exactly the
+    // case where somebody invited the agent into a conversation and then asked it to stop. Leg A's
+    // UNDIRECTED ambient wake is a room-grain wake with no conversation row behind it, so it has its
+    // own room-grain stop further down this handler (OPE-1511, search LEG A'S OWN STOP).
+    //
+    // THE TWO ARE NOT INDEPENDENT, and the overlap runs one way. A ROOM stop suppresses an ENGAGED
+    // conversation's ambient follow-up too: that activity resolves `deliver` here, falls through
+    // this block, and is dropped by the room gate below. So a stop asked for in one reply chain
+    // silences a chain whose people did invite the agent. It is the honest reading of a room-grain
+    // ask — `stand_down`'s room copy says "anywhere in this room" — and it errs toward silence,
+    // which is the safe direction for a wake gate. It does NOT run the other way: a CONVERSATION
+    // stop leaves the room row alone, so the rest of the room keeps waking.
+    //
+    // THE DELIVERY HALF IS NOT DECIDED HERE, and deliberately so. The front holds no primitive that
+    // could wake an existing native session, so admitting the activity through the NATIVE mention
+    // gate IS the wake (channels/teams.ts, which asks the same seam). A `deliver` AND a plain `hold`
+    // therefore both fall through to the ordinary forward, and that gate answers. The cost is one
+    // extra registry read on a forwarded non-mention message; the alternative — dropping a `hold`
+    // here — would skip everything eve's own channel does with an activity before `onMessage`, for
+    // no change in outcome. A read is the cheaper mistake to be wrong about.
+    //
+    // Machine-authored activities skip the seam entirely: they wake nothing on any path, so the
+    // registry read would be paid for a message with no decision behind it.
+    const seam: TeamsEngagementVerdict | null = machineAuthored ? null : await engagementSeam(activity, machineAuthored);
+    if (seam?.kind === "engage") {
+      // 🔴 THE MARK IS DEDUPED, AND THE STOP IS WHY. `markThreadEngaged({ participating: true })` is
+      // the re-invitation, so it CLEARS a `stopped` flag — correct for a person's second @mention,
+      // wrong for the Bot Framework REDELIVERING the first one. Redelivery is routine here (a slow
+      // ack is enough, and this mark is itself awaited before the ack). Both layers, exactly as the
+      // wake dedupe below uses them, under a SEPARATE key prefix so neither consumes the other's
+      // first sighting. Fail-open on a store error, same posture as that dedupe.
+      //
+      // 🔴 THIS IS THE CHEAP LAYER, NOT THE GUARANTEE (OPE-1527). Both layers EXPIRE — the in-memory
+      // one with the process, the durable one after DEDUPE_TTL_MS — and a stand-down does not expire
+      // at all, so a redelivery on a fresh process after the TTL sailed through here and lifted the
+      // stop. What actually holds is in the store: the promotion carries the activity id as
+      // `engagedBy`, and the row refuses to clear `stopped` for an id it already recorded
+      // (channels/teams-engagement.ts `markTeamsEngaged`). This layer stays because it saves the
+      // round-trip on the common retry, never because it bounds the replay.
+      const engageKey = `teams-engage:${activity.conversation.id}:${activity.id}`;
+      if (!dedupe.seen(engageKey, now())) {
+        dedupe.mark(engageKey, now());
+        // AWAITED, not deferred: the mark must land before the next message in this conversation is
+        // decided against it, and `markThreadEngaged` already swallows a store failure.
+        if (await markEventSeen(seam.org, engageKey, new Date(now()).toISOString())) await markEngaged(activity);
+      }
+    }
+    if (seam?.kind === "hold" && seam.stopped) {
+      // 🔴 A PARKED QUESTION'S ANSWER IS NEVER SUPPRESSED. eve routes a text HITL reply as an
+      // ordinary `message` activity and branches on it BEFORE `onMessage`, so a blanket early return
+      // here would silently drop the answer to a question the agent itself asked — the exact
+      // silent-HITL-drop shape channels/teams-input-response.ts exists to prevent (OPE-574). Standing
+      // down means "stop following the room", never "stop listening to what I asked you".
+      if (isTeamsInputResponseActivity(activity)) {
+        tlog(`activity ${activity.id} in ${activity.conversation.id}: stood down, but this is an answer to a parked question — forwarded`);
+        return forward();
+      }
+      tlog(`activity ${activity.id} in ${activity.conversation.id}: stood down here — suppressed on BOTH legs until an @mention`);
+      return OK();
+    }
+
+    // FIRST-CLASS DM WINDOW DIVERT (OPE-357). A personal (1:1) or group chat is diverted into its OWN
+    // dedicated DM window — a STRUCTURALLY SEPARATE admit space from the shared channel window. This
+    // sits BEFORE `planFor` deliberately: the single-window privacy floor (teamsSingleWindowPrivacyOk)
+    // refuses `scope !== "channel"` UNCONDITIONALLY and must stay that strict; a DM window never joins
+    // the shared one, so bypassing that floor here is correct, not a weakening (the Discord
+    // `isDm`-before-the-single-window-block precedent). It is UNCONDITIONAL since OPE-368: the
+    // `OE_DM_SEAT_ROTATION=0` hatch that used to sit in this condition (falling through to planFor's
+    // floor, which forwards the DM to the native path) was the last supported way to run a Teams DM on
+    // an un-wakeable native token — the seat class the retired OPE-306 delegation anchor served.
+    if (activity.scope === "personal" || activity.scope === "groupChat") {
+      // Author gate (mirrors the channel branch below): a machine-authored DM activity never wakes a
+      // seat — dropped, not forwarded (a DM window owns this surface; the native path is retired here).
+      if (machineAuthored) return OK();
+      // 🔴 LEG E GATES A GROUP CHAT, AND NEVER A 1:1 (OPE-1500). A personal chat resolves
+      // `unanchored`, so this line cannot fire on one: "a DM is always answered" is unchanged.
+      //
+      // A GROUP CHAT is different, and this narrows what it used to do. The `ChatMessage.Read.Chat`
+      // RSC grant makes Microsoft deliver EVERY group-chat message here, and this divert is
+      // unconditional (OPE-368) — so a granted tenant ran a full agent session on every message any
+      // member typed. The native mention gate (channels/teams.ts) never covered it: a group chat is
+      // diverted here and never forwarded. The seam is the posture that belongs in between — the
+      // chat is answered once it @mentions the agent, and goes quiet again on `stand_down`.
+      //
+      // FAIL-CLOSED, and that is a real second narrowing: `getThreadEngagement` reads a store failure
+      // as "no row" (channels/engagement.ts), so an operational-store outage holds every group chat
+      // rather than answering it. That is the right direction for a wake gate — an unreadable
+      // registry cannot prove the agent was invited — but it means a chat can go quiet for a reason
+      // nobody in it said out loud.
+      if (seam?.kind === "hold") {
+        // 🔴 THE SAME PARKED-QUESTION CARVE-OUT THE STOOD-DOWN BRANCH CARRIES, and this branch needs it
+        // for a WIDER set of holds: a group chat holds whenever it is un-engaged, which includes the
+        // fail-closed hold a store outage produces. A routine can park a question in a chat that holds
+        // for either reason, and dropping the person's answer here would be the silent-HITL-drop shape
+        // channels/teams-input-response.ts exists to prevent (OPE-574). Forwarded, so eve's own HITL
+        // path answers it.
+        if (isTeamsInputResponseActivity(activity)) {
+          tlog(`activity ${activity.id} in ${activity.conversation.id}: group chat not engaged, but this is an answer to a parked question — forwarded`);
+          return forward();
+        }
+        tlog(`activity ${activity.id} in ${activity.conversation.id}: group chat not engaged — ${seam.reason}`);
+        return OK();
+      }
+      // Two-layer idempotency, same as the channel path: an in-memory guard first (no org needed), then
+      // the durable store once the partition is resolved. A Bot-Framework redelivery must never
+      // double-wake; fail-open on a store error (dedupe prevents a double reply, not a security hole).
+      const dmKey = `teams:${activity.conversation.id}:${activity.id}`;
+      if (dedupe.seen(dmKey, now())) return OK();
+      dedupe.mark(dmKey, now());
+      // Resolve the DM's identity ONCE (auth + partition) — fail-closed to the native path on any
+      // binding/partition error, exactly as liveTeamsFrontPlan's own try/catch does.
+      let dm: { auth: OpenEverywhereTeamsAuth; partition: Partition } | null;
+      try {
+        const auth = authForActivity(activity);
+        const partition = resolvePartition({ channel: { kind: "teams" }, session: { auth: { current: auth } } });
+        dm = { auth, partition };
+      } catch {
+        dm = null;
+      }
+      if (!dm) return forward(); // can't anchor the DM to an org ⇒ let the native path own it
+      const { auth: dmAuth, partition: dmPartition } = dm; // const-capture for the deferred FIFO closure
+      if (!(await markEventSeen(dmPartition.org, dmKey, new Date(now()).toISOString()))) return OK();
+      tlog(`activity ${activity.id} on ${dmPartition.surfaceKey}: DM — diverting to its own first-class DM window`);
+      // Per-container FIFO (the same discipline as the channel path): one DM's wakes deliver strictly in
+      // arrival order; a failure lands in the FIFO's loud catch + a durable audit row.
+      args.waitUntil(fifo.enqueue(dmPartition.surfaceKey, () => dmDivert(activity, dmAuth, dmPartition, args.to)));
+      return OK();
+    }
+
+    // THE one single-window decision (single-leg: one webhook, one synchronous verdict). No plan
+    // — gates off, floor failed, config/partition error — ⇒ forward, byte-identical to today.
+    const plan = planFor(activity);
+    if (!plan) return forward();
+
+    // Author gate (mirrors Slack's authorIsBot disqualifier on a kept mention): the window owns
+    // this surface's traffic, and machine-authored activities never wake the shared session —
+    // dropped, not forwarded (forwarding would hand a suppressed surface back to the native
+    // session for bots only, splitting the context the window exists to unify).
+    if (machineAuthored) {
+      tlog(`activity ${activity.id} on ${plan.surfaceKey}: bot/self-authored — dropped (single-window surface, relay is Phase 2)`);
+      return OK();
+    }
+
+    // ── LEG A'S OWN STOP (OPE-1511) ─────────────────────────────────────────────────────────────
+    //
+    // The half the block above could not cover, and now does. Leg A wakes on ANY message in a
+    // vouched single-window channel, including a reply chain nobody ever @mentioned the agent in.
+    // A `stopped` flag lives on an engagement row and only an @mention wrote one, so a person in
+    // such a room could not stop the wake and `stand_down` refused for want of a row. The rule is
+    // that a stored stop exists exactly where a stored wake exists: this leg now stores a ROOM-grain
+    // row on every ambient wake, reads that row's flag here, and `tools/stand_down.ts` marks it when
+    // the conversation grain holds nothing (channels/teams-engagement.ts carries the whole shape).
+    //
+    // AN @MENTION IS THE WAY BACK, and it must run BEFORE the gate or the stop would be a trap: the
+    // mention re-invites the ROOM, and Leg E's own mark re-invites only the conversation. The clear
+    // carries the activity id, so a redelivery of the mention the row records lifts nothing
+    // (OPE-1527; one slot — OPE-1562).
+    // A FAILED clear leaves the room stopped and still answers this mention — the person's next
+    // @mention retries it, which is the safe direction for a write that only ever removes a stop.
+    //
+    // 🔴 NO `.catch()` ON THE GATE, and that asymmetry is deliberate. `teamsRoomWatchStopped` owns
+    // its own failure direction and picks FAIL-CLOSED (hold the wake, its doc says why). A swallow
+    // here would silently invert that to fail-open and hand a stood-down room back to the ambient
+    // leg — the exact defect the read was written to prevent. It never throws.
+    const addressedHere = plan.window.addressing === "direct-mention";
+    if (addressedHere) {
+      await clearRoomStop(plan.partition, new Date(now()).toISOString(), activity.id).catch(() => undefined);
+    } else if (await roomStopped(plan.partition)) {
+      // 🔴 THE SAME PARKED-QUESTION CARVE-OUT the stood-down conversation branch carries. eve routes
+      // a text HITL answer as an ordinary message activity, so dropping one here would silently lose
+      // the answer to a question the agent itself asked (OPE-574).
+      if (isTeamsInputResponseActivity(activity)) {
+        tlog(`activity ${activity.id} on ${plan.surfaceKey}: room stood down, but this is an answer to a parked question — forwarded`);
+        return forward();
+      }
+      tlog(`activity ${activity.id} on ${plan.surfaceKey}: this room was stood down — ambient wake suppressed until an @mention`);
+      return OK();
+    }
+
+    // Two-layer idempotency (in-memory + the durable cross-instance store): a Bot-Framework
+    // redelivery (non-200 → retry, same activity id) must never double-wake. Fail-open on a
+    // store error — dedupe prevents a double reply, not a security hole.
+    const key = `teams:${activity.conversation.id}:${activity.id}`;
+    if (dedupe.seen(key, now())) return OK();
+    dedupe.mark(key, now());
+    if (!(await markEventSeen(plan.partition.org, key, new Date(now()).toISOString()))) return OK();
+
+    tlog(
+      `activity ${activity.id} on ${plan.surfaceKey}: single-window — diverting to the unified supervisor ` +
+        `(${plan.window.addressing === "direct-mention" ? "addressed @mention; native forward suppressed" : "ambient channel-watch"})`,
+    );
+    // THE STORED WAKE THE STORED STOP NEEDS (OPE-1511). Written for the AMBIENT leg only: an
+    // addressed @mention already engages its conversation through Leg E, and it has just re-invited
+    // the room above. Deferred, because it decides nothing about this wake — a lost row costs a
+    // later stop somewhere to land, never a turn.
+    if (!addressedHere) args.waitUntil(markRoomWatched(plan.partition, new Date(now()).toISOString()).catch(() => undefined));
+    // Per-container FIFO (the slack-front supervisor-key discipline): one channel's wakes deliver
+    // strictly in arrival order; a failure lands in the FIFO's loud catch + a durable audit row.
+    args.waitUntil(fifo.enqueue(plan.surfaceKey, () => dispatch(activity, plan, args.to)));
+    return OK();
+  };
+}
+
+/**
+ * Compose the front route with a wrapped `teamsChannel`. `inner` must have been built with
+ * `route: INTERNAL_TEAMS_ROUTE`. Returns the SAME channel value (preserving eve's internal
+ * adapter/receive) with the public front route prepended — so the Bot Framework's URL hits us,
+ * and both routes share one channel name → one session namespace (the frontSlackChannel shape).
+ */
+export function frontTeamsChannel<C extends Channel<any, any, any>>(inner: C, opts: TeamsFrontOptions = {}): C {
+  const innerPost = inner.routes.find(
+    (r): r is HttpRouteDefinition<any> => r.method === "POST" && r.path === INTERNAL_TEAMS_ROUTE,
+  );
+  if (!innerPost) {
+    throw new Error(
+      `frontTeamsChannel: wrapped teamsChannel must be built with route: "${INTERNAL_TEAMS_ROUTE}" ` +
+        `(found paths: ${inner.routes.map((r) => r.path).join(", ")})`,
+    );
+  }
+  const front = buildTeamsFrontHandler(innerPost.handler, opts);
+  return { ...inner, routes: [POST(PUBLIC_TEAMS_ROUTE, front), ...inner.routes] };
+}