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

package/agent/channels/teams-supervisor.ts

@@ -0,0 +1,638 @@
+// The Microsoft Teams SINGLE-WINDOW core — the eve-FREE tested half of the Teams cross-surface
+// window legs (the FIFTH surface after Slack/GitHub/Linear/Notion; teams-front.ts is the live
+// wiring). Teams is deliberately NARROWER than the other surfaces: it has no per-conversation
+// ambient supervisor of its own, so this core exists ONLY for the single-window mode — every
+// dispatch that reaches it carries a window and is delivered into the synthetic `unified`
+// channel (channels/unified.ts). Flag-off, teams-front forwards every activity to eve's native
+// teamsChannel untouched and nothing in this file runs: byte-identical.
+//
+// WHAT'S REUSED WHOLESALE (zero Teams-specific logic in any of it):
+//   • singleWindowMentionPolicy — the ONE shared mention seam — unified-window.ts
+//   • renderWake + the channel-watch / direct-mention preambles — normalized-wake.ts
+//   • shouldRotate — the pure rotation policy — slack-events.ts (via the live deps)
+// WHAT'S NEW (this file): the Teams PRIVACY FLOOR (the load-bearing decision — see
+// teamsSingleWindowPrivacyOk), the single-window plan, the NormalizedWake builder, and the
+// dispatch core (session get-or-create → build → wake), each mirroring
+// the Notion equivalents (planNotionSingleWindow / buildNotionSupervisorWake /
+// handleNotionSupervisorDispatch) — the closest prior single-leg surface.
+//
+// SINGLE-LEG BY CONSTRUCTION (the Slack build's hard-won lesson): Slack fires TWO webhooks for
+// one @mention (app_mention + its message.channels sibling), and the original two-leg
+// suppress/deliver design could disagree across webhooks and LOSE the mention — the fix was to
+// divert the mention event itself in one leg. Teams never had the hazard: ONE Bot-Framework
+// activity per message, ONE synchronous policy read (the vouch register is a set lookup — no
+// network, no TTL cache to go stale between legs), ONE verdict driving both "suppress the
+// native forward" and "deliver as an addressed wake". There is no second webhook to coordinate
+// with, so neither a lost mention nor a double answer is structurally possible.
+
+import {
+  spreadVendorTs,
+  type VendorEventTime,
+  renderWake,
+  mkMessageTrigger,
+  mintWakeId,
+  singleWindowMentionPolicy,
+  type NormalizedWake,
+  type WakeEngagementTier,
+  type WakeTrust,
+  type SingleWindowMentionPolicy,
+  type UnifiedWindowWake,
+  type WakeMessageInput,
+  tailAuthorGrain,
+  type IngestedChatMessage,
+  type SessionTailWakeRow,
+  seatCatchUpSinceMs,
+  catchUpUnavailableReason,
+  type SeatCatchUpRequest,
+  type SeatCatchUpResult,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import type { OpenEverywhereTeamsAuth } from "./teams-identity.js";
+
+/** The catch-up's REACHBACK FLOOR (hours): how far back a seat that has been quiet for a long time
+ *  reads. 7 days, the same floor every other surface uses. */
+const TEAMS_CATCH_UP_REACHBACK_HOURS = 168;
+
+/**
+ * What a seat is told when THIS wake could not resolve the team's Graph address (OPE-1808). TRUSTED,
+ * OE-authored and CONSTANT, the same posture as core's `catchUpUnavailableReason`, and deliberately
+ * NOT that sentence: this bound is about one wake, not about the surface, and the seat must not be
+ * told Teams cannot read its own history when the next wake may read it perfectly well. It states the
+ * bound the seat has to act on either way — an empty context here is not evidence of a quiet room.
+ */
+const TEAM_ADDRESS_UNRESOLVED_NOTE =
+  "teams: this team's Microsoft 365 group id could not be resolved on this wake, so the channel's history since your last wake is NOT shown. That is a failure to READ, not a quiet room — an absence of messages here says nothing about what was said.";
+
+// --- supervisor token / sentinel (carry the :oe-sup:g infix — load-bearing) ----------
+//
+// hooks/spend.ts isSupervisorToken keys off the `:oe-sup:g` substring to (a) tag the usage-event
+// `kind="supervisor"` and (b) drive the per-generation cumulative-token rotation counter. Carry
+// the infix and the whole cost/rotation apparatus works for free. In practice Teams only ever
+// dispatches on a unified singleWindow grain (the token is unifiedSupervisorToken's), so this
+// per-container form exists for supervisorTokenForGrain's `perContainer` thunk + shape parity
+// with the other surfaces (notionSupervisorToken et al.), not as a live path.
+
+/** The reserved pseudo-thread sentinel for a supervisor generation (mirrors Slack's). */
+function teamsSupervisorSentinel(generation: number): string {
+  return `oe-sup:g${generation}`;
+}
+
+/** The per-container supervisor token for a Teams channel container (the grain fallback —
+ *  see the header note; a live Teams dispatch always resolves the unified domain token). */
+export function teamsSupervisorToken(channelKey: string, generation: number): string {
+  return `teams:${channelKey}:${teamsSupervisorSentinel(generation)}`;
+}
+
+// --- THE PRIVACY FLOOR (fail-closed — the load-bearing security decision) --------------------
+
+/** The host-extracted Teams facts the floor decides from — every field comes off the
+ *  JWT-VERIFIED inbound activity (or the operator's own registers), never model output. */
+export interface TeamsSingleWindowFacts {
+  /** Normalized conversation scope ("personal" | "groupChat" | "channel" | "unknown"). */
+  readonly scope: string | undefined;
+  /** Channel membershipType ("standard" | "private" | "shared") when the activity's channelData
+   *  positively carried it — inbound activities usually OMIT it (teams-identity.ts). */
+  readonly membershipType?: string;
+  /** The tenant (org boundary). Absent ⇒ the surface can't be anchored to an org ⇒ refuse. */
+  readonly tenantId?: string;
+  /** The operator's explicit vouch for THIS surface: isVouchedSurface on the channel key AND the
+   *  team rung, which WALKS the declaration rungs (OPE-1521/OPE-1538), so a tenant-grain
+   *  `teams/<tenant>` declaration vouches every room under it and a `public` `team:<id>` carve-out
+   *  demotes one team out of it — see below. Or the blanket OE_TRUST=internal. Resolved by the
+   *  live wiring (teams-front.ts). */
+  readonly vouched: boolean;
+}
+
+/**
+ * The Teams privacy floor for the cross-surface window, FAIL-CLOSED. Every surface has one so a
+ * public/external surface can never join a private shared window (GitHub: `repository.private
+ * === true`; Slack: positively-confirmed-internal channel/group; Linear: team positively
+ * private; Notion: operator vouch). Teams' rule:
+ *
+ *   ADMIT ⟺ scope === "channel"  AND  tenantId present  AND  membershipType ≠ "shared"
+ *          AND  the OPERATOR VOUCHED the surface (vouch register / OE_TRUST=internal).
+ *
+ * WHY OPERATOR-VOUCH AND NOT A PLATFORM SIGNAL (the Notion posture, deliberately): Teams has NO
+ * reliable in-band fact that means "internal-only, no external eyes".
+ *   • `membershipType` is usually ABSENT on inbound activities, and even when positively
+ *     "standard" or "private" it does NOT exclude tenant GUESTS — a guest (an external identity
+ *     invited into the tenant) sees every standard channel of the teams they're on, and can be a
+ *     member of private channels too. So the memory-gate verdict (teams-identity.ts teamsTrust,
+ *     which reads standard/private+tenant as internal) is deliberately NOT sufficient here —
+ *     the window floor is STRICTER than the memory floor.
+ *   • A Graph roster sweep (TeamMember.Read.All → userType === "Guest") could positively prove
+ *     guest-freedom, but OE has no Graph credential plane wired (the bot speaks Bot Connector
+ *     only), the sweep is racy (membership changes after the check), and Bot-Framework
+ *     pagedMembers' `userRole` is not a documented-reliable field — inventing a weaker signal
+ *     is exactly what the floor doctrine forbids. So: the operator vouches, code enforces.
+ *
+ * ATTACKER ANALYSIS: the leak vector is a message from a surface visible outside the org being
+ * admitted to (and answered from) a private cross-surface window. All four conjuncts are
+ * host-derived: scope/membershipType/tenantId come off the Bot-Connector-signed activity (a
+ * user cannot author channelData — the Teams service stamps it), and the vouch is the
+ * operator's own register. Absence of membershipType never ADMITS (only the vouch admits;
+ * membershipType only REFUSES). The one positive-external fact we CAN see — membershipType ===
+ * "shared", a Teams Connect shared channel spanning tenants — refuses EVEN WHEN VOUCHED (a
+ * positive cross-org fact beats a standing assertion). BUT membershipType is usually ABSENT
+ * inbound, and an absent signal never demotes, so that guard catches only the rooms Teams labels
+ * for us.
+ *
+ * 🔴 THERE IS NO EXACT-GRAIN BACKSTOP BEHIND IT — the operator's declaration IS the protection.
+ * `isVouchedSurface` walks the declaration rungs (OPE-1521), the same most-specific-wins walk every
+ * other trust reader uses, and since OPE-1538 the wiring hands it the TEAM rung too, so the walk
+ * here has the same reach the binding and memory planes have: a `public` `teams/<tenant>/team:<id>`
+ * carve-out now demotes one team out of an internal tenant at this floor, where it used to be
+ * skipped and the room admitted. A coarse `teams/<tenant>` declaration still admits EVERY room under
+ * that tenant that no narrower entry demotes. `agent/identity/surfaces.ts` ships exactly such a tenant line today. A native
+ * internal channel and a cross-tenant Connect/shared channel look alike at that grain, so a
+ * shared room whose inbound activities omit membershipType IS admitted on the tenant line. That is
+ * the ruling, not a gap: a declaration vouches, and only a POSITIVE external signal demotes. The
+ * operator narrows the reach by declaring the channel rung instead. This floor admits or refuses a
+ * room that is ALREADY a window member — it enrolls nobody; the domain CONFIG
+ * (`agent/memory/config/domains.ts`, read by teams-front.ts) enrolls. Do not read that as a second
+ * bound on the reach: a domain's container `reach` entry is legal at TENANT grain, so a tenant claim
+ * beside a tenant declaration puts every room in the tenant through this floor, and config load
+ * cannot enumerate them. In-tree domains name exact channels today. Residual: the standing
+ * "operator vouched something they shouldn't have" residual every vouch surface carries (identical
+ * to vouching a web-published Notion page) — now at whatever grain the operator wrote, so a tenant
+ * declaration carries it for the whole tenant. Personal and group chats
+ * are refused outright: they are per-person surfaces, not org containers, mirroring Slack's
+ * channels/groups-only rule. Residual acceptance: a vouched tenant/channel that LATER gains a
+ * guest is admitted until the operator retracts the vouch — the documented trade of the vouch
+ * posture (identical to Notion's), and strictly safer than any inference we could make.
+ */
+export function teamsSingleWindowPrivacyOk(f: TeamsSingleWindowFacts): boolean {
+  if (f.scope !== "channel") return false; // personal/groupChat/unknown never join the shared window
+  if (!f.tenantId) return false; // no org anchor → fail closed
+  if (f.membershipType === "shared") return false; // positively cross-tenant → refuse even when vouched
+  return f.vouched === true; // the operator's vouch is the ONLY admitting signal
+}
+
+/**
+ * The LIVE-shaped single-window mention decision for one Teams activity — the Teams arm of the
+ * shared seam (unified-window.ts {@link singleWindowMentionPolicy}), next to the Slack
+ * equivalent (slack-events.ts slackSingleWindowMentionPolicy). Pure and SYNCHRONOUS (the floor
+ * needs no network — the vouch register is a set lookup), which is what makes the Teams legs
+ * single-leg by construction: one verdict, no cache to go stale between a suppress read and a
+ * deliver read. Fail-closed throughout: singleWindow off, or any floor conjunct failing, yields
+ * today's split (native owns the mention, no addressed wake).
+ */
+function teamsSingleWindowMentionPolicy(singleWindow: boolean, isMention: boolean, facts: TeamsSingleWindowFacts): SingleWindowMentionPolicy {
+  return singleWindowMentionPolicy(singleWindow, isMention, teamsSingleWindowPrivacyOk(facts));
+}
+
+// --- the single-window plan (pure) ----------------------------------------------------
+
+/** The host-frozen reply-target facts one Teams activity resolves — everything
+ *  {@link planTeamsSingleWindow} needs to mint the wake origin (unified-window.ts's teams arm). */
+export interface TeamsSingleWindowTarget {
+  /** Bot Connector base URL off the verified activity — the reply's transport host. Empty ⇒ no
+   *  routable reply target ⇒ NO window (fail closed, never an unanswerable wake). */
+  readonly serviceUrl: string;
+  /** The Bot Framework conversation id (channel messages carry the reply-chain anchor in it). */
+  readonly conversationId: string;
+  /** The reply-chain ROOT activity id (eve's teamsThreadRootActivityId: the trigger's replyToId
+   *  when it was itself a reply, else the trigger activity) — replyToTeamsActivity's target. */
+  readonly replyToActivityId?: string;
+  readonly tenantId?: string;
+  /** The first latency anchor (OPE-1716), recorded on the ingress row. A Bot-Framework activity
+   *  carries no parsed timestamp on eve's shape, so the caller passes its own FRONT-DOOR RECEIPT —
+   *  which makes the vendor→ingress segment a lower bound, and the row's `vendorTsSource` says so. */
+  readonly vendorTs?: VendorEventTime;
+}
+
+/**
+ * The ONE single-window decision for a Teams delivery, mirroring planNotionSingleWindow: given
+ * the grain's `singleWindow`, whether the activity @mentions the bot, the PRIVACY-FLOOR facts,
+ * and the frozen reply target, return the {@link UnifiedWindowWake} the dispatch should carry —
+ * or undefined for the byte-identical native path (teams-front then FORWARDS the activity to
+ * eve's native teamsChannel exactly as today).
+ *
+ * Teams' mention signal lives in ONE Bot-Framework activity (no Slack-style dual event), and its
+ * "native" handler is the forward this plan suppresses — so suppress-native and divert are the
+ * SAME act, both read off this one verdict (never a double turn, never a gap):
+ *   • @mention on a singleWindow, floor-passing channel → the seam suppresses the native forward
+ *     and stamps `addressing:"direct-mention"` (the terminal-prose delivery bridge's arm);
+ *   • ambient (non-mention) channel message on the same surface → Leg A: the window WITHOUT the
+ *     addressed stamp (judged treatment in the shared window, prose stays hard-dropped);
+ *   • floor fails, singleWindow off, or no routable reply target → undefined (forward — a
+ *     mention then keeps today's native conversation-session turn).
+ */
+export function planTeamsSingleWindow(
+  singleWindow: boolean,
+  isMention: boolean,
+  facts: TeamsSingleWindowFacts,
+  target: TeamsSingleWindowTarget,
+): UnifiedWindowWake | undefined {
+  const policy = teamsSingleWindowMentionPolicy(singleWindow, isMention, facts);
+  // A mention diverts iff the seam suppresses the native forward; an ambient message diverts on
+  // the same `singleWindow && privacyOk` floor (Leg A). Both derive from the seam's one predicate.
+  const divert = isMention ? policy.suppressNative : singleWindow && teamsSingleWindowPrivacyOk(facts);
+  if (!divert) return undefined;
+  if (!target.serviceUrl || !target.conversationId) return undefined; // no frozen reply target ⇒ no window (fail closed)
+  return {
+    wakeId: mintWakeId(),
+    origin: {
+      platform: "teams",
+      serviceUrl: target.serviceUrl,
+      conversationId: target.conversationId,
+      ...(target.replyToActivityId ? { replyToActivityId: target.replyToActivityId } : {}),
+      ...(target.tenantId ? { tenantId: target.tenantId } : {}),
+    },
+    // ADDRESSED @mention ⇒ the seam's stamp marks the wake as OWED a reply, so the envelope tells
+    // the seat it owes an answer through the `reply` tool. Ambient wakes omit it. It is not a delivery
+    // path: a turn that ends in prose is dropped and re-driven once, on every addressing (OPE-1982).
+    ...(policy.addressing !== undefined ? { addressing: policy.addressing } : {}),
+    ...spreadVendorTs(target.vendorTs),
+  };
+}
+
+// --- the wake builder (pure) ---------------------------------------------------------
+
+export interface TeamsSupervisorWakeInput {
+  /** The Teams CHANNEL id (the container — the envelope's `<channel id>`; the conversation id
+   *  when the activity carried no channel id). */
+  readonly channelId: string;
+  /** The trigger activity's facts (host-extracted). */
+  readonly trigger: {
+    readonly id: string;
+    readonly authorId: string;
+    readonly authorName?: string;
+    readonly sentAt: string;
+    readonly text: string;
+    /** Per-message trust tier (identity/wake-trust.ts) — resolved by the live dispatch.
+     *  🔴 REQUIRED (OPE-596): this builder fail-closed to `relay` while its five siblings defaulted
+     *  UPWARD, so all six now refuse the omission at compile time instead of each picking a floor.
+     *  A caller that cannot resolve a tier states the fail-closed one itself: `relay` for a machine
+     *  author, `unauth` for a human the gate cannot vouch. */
+    readonly trust: WakeTrust;
+  };
+  /** Present ⇔ the trigger sat inside an EXISTING reply chain (its replyToId) — envelope thread
+   *  meta only; the reply target is the frozen origin, never this. */
+  readonly threadRootId?: string;
+  /** The seam's addressed verdict (window.addressing === "direct-mention"). */
+  readonly directMention: boolean;
+  /** Host-minted wake id — always present (Teams only dispatches on the single-window path). */
+  readonly wakeId: string;
+  /** Engagement calibration for the judged preamble — channel-watch only. */
+  readonly engagementTier?: WakeEngagementTier;
+  /** The OUTGOING generation's recorded TAIL (OPE-794), rendered as this first wake's backscroll.
+   *  Only a FRESH generation's first wake carries one. */
+  readonly tail?: readonly WakeMessageInput[];
+  /** This surface could not read its own channel since the seat's last wake (core
+   *  channels/seat-catch-up.ts). Rendered as a trusted `<system-note>`; unset ⇒ no note. */
+  readonly catchUpUnavailable?: string;
+}
+
+/**
+ * Build the NormalizedWake for one Teams single-window turn. platform "teams", containerNoun
+ * "channel" (a Teams channel is a channel), locus.channel = the Teams channel, locus.thread =
+ * the reply chain the trigger sat in (when it did). NO PLATFORM-FETCH BOOTSTRAP: the Bot Connector
+ * API this wake arrives over has no message-history read (unlike Slack's conversations.history), so a
+ * FRESH generation carries the RECORDED TAIL of the outgoing generation (OPE-794) and nothing else —
+ * which is why the recorded ring matters more on Teams than anywhere else. A Teams seat with no
+ * recorded tail opens cold, honestly.
+ * 🔴 AN ONGOING GENERATION IS A DIFFERENT QUESTION, AND IT IS ANSWERED (OPE-1726): the since-last-wake
+ * catch-up reads MICROSOFT GRAPH — a different credential and a different transport from the Bot
+ * Connector, the one `read_channel` has always used — so a Teams seat does see what the channel said
+ * between its own wakes. See channels/teams-catch-up.ts; the bootstrap gap above is unchanged.
+ * Always the unified render (platform address + P5 disclosure): Teams has no non-window
+ * supervisor path, so there is no per-container twin to stay byte-identical with.
+ */
+export function buildTeamsSupervisorWake(input: TeamsSupervisorWakeInput): NormalizedWake {
+  return {
+    platform: "teams",
+    reason: input.directMention ? "mention" : "channel-activity",
+    addressing: input.directMention ? "direct-mention" : "channel-watch",
+    // The ambient calibration dial — an addressed mention is owed an answer, so watch-only.
+    engagementTier: input.directMention ? undefined : input.engagementTier,
+    wakeId: input.wakeId,
+    locus: {
+      channel: { id: input.channelId },
+      ...(input.threadRootId ? { thread: { ts: input.threadRootId } } : {}),
+    },
+    ...(input.trigger.authorName ? { participants: [{ id: input.trigger.authorId, name: input.trigger.authorName }] } : {}),
+    backscroll: input.tail && input.tail.length > 0 ? input.tail : undefined,
+    ...(input.catchUpUnavailable !== undefined ? { catchUpUnavailable: input.catchUpUnavailable } : {}),
+    trigger: mkMessageTrigger({
+      from: "human", // bot/self-authored activities are dropped upstream (teams-front's author gate)
+      author: input.trigger.authorName ?? input.trigger.authorId,
+      authorId: input.trigger.authorId,
+      id: input.trigger.id,
+      sentAt: input.trigger.sentAt,
+      // The caller's stated per-person tier — no default (OPE-596).
+      trust: input.trigger.trust,
+      mention: input.directMention,
+      body: input.trigger.text,
+    }),
+  };
+}
+
+// --- the dispatch core (session get-or-create → build → wake → terminal rotate) -------
+
+/** The live supervisor session pointer, as the deps report it (mirrors the other surfaces). */
+export interface TeamsSupervisorSession {
+  readonly token: string;
+  readonly generation: number;
+  readonly freshGeneration: boolean;
+  /** ISO-8601 of the most recent wake this generation delivered (the registry row's `lastWakeAt`),
+   *  or null on a freshly minted/rotated generation — the lower bound of the since-last-wake catch-up
+   *  read (OPE-1726); absent ⇒ no catch-up. */
+  readonly lastWakeAt?: string | null;
+  /** The OUTGOING generation's recorded tail, oldest-first — empty unless this is a fresh
+   *  generation's first wake (OPE-794). */
+  readonly tail: readonly WakeMessageInput[];
+}
+
+/** Deps for {@link handleTeamsSingleWindowDispatch} — injected so the core is unit-testable over
+ *  a mock store + a capture `wake` (scripts/unified-window-test.ts). org is baked into the live
+ *  impl's closures (a deployment fact — teams-front.ts), so it never crosses this boundary. */
+export interface TeamsSupervisorDeps {
+  /** Create-or-fetch the live supervisor session for this surface's grain: generation 1 on first
+   *  sighting, rotate when shouldRotate says it aged out, else the current generation. */
+  readonly getOrCreateSession: (surfaceKey: string, channelId: string, atIso: string) => Promise<TeamsSupervisorSession>;
+  /** Record one wake on the current generation (lastWakeAt/turnCount). Best-effort. */
+  readonly touchSession?: (surfaceKey: string, atIso: string) => Promise<void>;
+  /**
+   * THE SINCE-LAST-WAKE CATCH-UP, through the ONE shared path every surface takes
+   * (channels/seat-catch-up.ts `seatCatchUp`). Optional so older test doubles keep compiling
+   * (absent ⇒ no catch-up, the pre-OPE-1726 behaviour); fail-soft by construction.
+   */
+  readonly catchUp?: (req: SeatCatchUpRequest) => Promise<SeatCatchUpResult>;
+  /**
+   * Record this delivered wake onto the LIVE generation's TAIL ring (OPE-794). Injected because the
+   * entry has to be filed under an ORG and a registry key, and this core deliberately holds neither
+   * — the live wiring does. Absent (a unit test) ⇒ nothing is recorded and the dispatch is
+   * unchanged, which is the same posture `touchSession` takes.
+   */
+  readonly recordWake?: (entry: SessionTailWakeRow, token: string, surfaceKey: string) => Promise<void>;
+
+  /** Deliver the rendered wake. The live wiring (teams-front.ts) ALWAYS diverts through eve's
+   *  cross-channel `receive` into the synthetic `unified` channel (divertToUnifiedWindow) — a
+   *  Teams dispatch has no native send fallback, by construction (window required below). */
+  readonly wake: (input: { token: string; auth: OpenEverywhereTeamsAuth; message: string; context: readonly string[]; window: UnifiedWindowWake }) => Promise<void>;
+  /** Clock seam (defaults to the real clock). */
+  readonly now?: () => string;
+}
+
+/** Everything teams-front hands the dispatch: identity/session facts + the wake parts + the
+ *  REQUIRED window (a Teams dispatch exists only on the single-window path). */
+export interface TeamsSupervisorDispatch {
+  /** The DOMAIN-GRAIN surface key (`teams/<tenant>/<channel>` — memory/partition.ts domainKeyOf):
+   *  the gate/registry/audit key, and what unified.receive re-checks fail-closed. */
+  readonly surfaceKey: string;
+  /**
+   * 🔴 THE ROOM KEY — `partition.surfaceKey`, the CONVERSATION grain (`teams/<tenant>/<conversation
+   * id>`), and NOT {@link surfaceKey} above. It is the `container` this wake row carries, and it is
+   * a CONTRACT with the post row: `channels/session-tail-record.ts` `tailWindowFor` builds a post's
+   * container from `partition.surfaceKey`, and `channels/reply-fold.ts` filters the ring by exact
+   * container equality. Two spellings therefore hide every wake row from the fold policy.
+   *
+   * WHY THE TWO KEYS DIFFER HERE. `bindTeams` (teams-identity.ts) sets `surface` to the conversation
+   * id (one reply chain) and `domainSurface` to the channel id, so `surfaceKey` and `domainKeyOf` are
+   * different strings on Teams. 🔴 TEAMS IS NOT THE ONLY SURFACE THAT SPLITS THEM. `bindDiscord`
+   * (discord-identity.ts) sets `domainSurface` to the parent channel id, so a Discord THREAD splits
+   * the same two grains. Those two are the whole set — `memory/partition.ts` names both, and no other
+   * binding sets `domainSurface`. Slack sets none, so its two keys are one string and
+   * `slack-events.ts` reads `p.surfaceKey` with nothing to get wrong. Discord
+   * passes `input.partition.surfaceKey` explicitly and is correct today; a future change to that ring
+   * row must keep the surface key, for the reason this field exists. Recording the domain key here
+   * made the fold policy refuse a post that a human message had already cleared (OPE-1528, ship #174).
+   */
+  readonly containerKey: string;
+  /** The Teams channel id (envelope container + the per-container token fallback). */
+  readonly channelId: string;
+  /** The TEAM the channel belongs to, in GRAPH's spelling — the Microsoft 365 GROUP id, NOT the
+   *  `channelData.team.id` an activity carries (channels/teams-graph-team-id.ts resolves the one
+   *  into the other; OPE-1808). Graph addresses a channel read as `/teams/{team}/channels/{channel}`,
+   *  so the catch-up needs both ids and neither is derivable from the other. Absent (a chat activity,
+   *  or a team id that would not resolve) ⇒ no catch-up, never a guessed team. */
+  readonly teamId?: string;
+  /** The activity DID name a team and its Graph id would not resolve ON THIS WAKE — the TRANSIENT
+   *  shape, kept apart from the chat shape because the two owe the seat DIFFERENT sentences (the
+   *  catch-up arm below). Absent ⇒ the activity named no team at all. */
+  readonly teamAddressUnresolved?: boolean;
+  readonly auth: OpenEverywhereTeamsAuth;
+  /**
+   * THE AUTHOR FACTS for every message whose bytes enter this wake's context (OPE-1747), in the same
+   * shape and for the same reason the other three seat surfaces carry it. A Teams channel activity is
+   * one message per wake, so the front passes exactly one entry — the resolved tier, the Bot Connector
+   * roster's `userRole: "guest"` refutation, and the OPERATOR's register query.
+   *
+   * 🔴 REQUIRED, NOT OPTIONAL, for the reason `stampNonMemberChatAuth` makes its own `room` argument
+   * required: an optional field lets a new leg silently lose the author question, and a carriage that is
+   * absent looks identical to a carriage that answered "member". The front already computed these facts
+   * for its own taint join; what this field adds is that the TAIL ROW records them, so a tail-built
+   * envelope is judged by the same two legs a freshly-fetched one is. A leg with genuinely nothing to
+   * say passes `[]` and says so on purpose.
+   */
+  readonly ingested: readonly IngestedChatMessage[];
+  readonly trigger: TeamsSupervisorWakeInput["trigger"];
+  readonly threadRootId?: string;
+  /**
+   * 🔴 THE REPLY CHAIN THIS WAKE SITS IN — the second half of the catch-up's read, and NOT {@link
+   * threadRootId} (OPE-1817). A Teams CHANNEL activity always sits in one reply chain, named by its
+   * conversation id's `;messageid=<root>` suffix, and {@link containerKey} is that same conversation
+   * grain. `threadRootId` answers a different question — whether the ENVELOPE renders thread-scoped
+   * — and is deliberately absent on a top-level post.
+   *
+   * Naming the chain matters because Graph's `/channels/{c}/messages` returns TOP-LEVEL messages
+   * ONLY: a reply never appears there. So a wake that named no chain read nothing for a chain that
+   * had carried the message, with no error to see (ship #206, ship #207). The fetch reads the
+   * channel AND the named chain and merges them (channels/teams-catch-up.ts). Absent ⇒ the
+   * conversation names no chain, and the read is the container's alone.
+   */
+  readonly replyChainRootId?: string;
+  readonly engagementTier?: WakeEngagementTier;
+  /** The minted single-window wake (planTeamsSingleWindow) — REQUIRED: without a window there is
+   *  nothing for this dispatch to do (the front forwards to the native channel instead). */
+  readonly window: UnifiedWindowWake;
+}
+
+/**
+ * Route one floor-passing Teams activity to the domain's single-window supervisor: get-or-create
+ * the (unified-grain) session, build + render the wake for that generation, and deliver it via
+ * the wake dep (whose live wiring diverts into the unified channel — registering the durable
+ * wakeId→origin map entry BEFORE the send).
+ *
+ * A DELIVERY failure (the enqueue/divert itself) propagates to the caller's catch. A session that
+ * dies at TURN time does not: nothing here observes it, so the trigger is lost SILENTLY, and no
+ * reactive arm can exist (OPE-174 removed the inert one; channels/session-resume.ts holds the
+ * measurement). The working remedy is PRE-DISPATCH — the live `getOrCreateSession` claims the
+ * OPE-599 runtime-change rotation before this call and hands back a session the running eve build
+ * can read.
+ */
+export async function handleTeamsSingleWindowDispatch(d: TeamsSupervisorDispatch, deps: TeamsSupervisorDeps): Promise<void> {
+  const atIso = deps.now ? deps.now() : new Date().toISOString();
+  const session = await deps.getOrCreateSession(d.surfaceKey, d.channelId, atIso);
+
+  const doWake = async (token: string, generation: number, tail: readonly WakeMessageInput[], catchUpUnavailable?: string) => {
+    const nw = buildTeamsSupervisorWake({
+      channelId: d.channelId,
+      trigger: d.trigger,
+      threadRootId: d.threadRootId,
+      directMention: d.window.addressing === "direct-mention",
+      wakeId: d.window.wakeId,
+      engagementTier: d.engagementTier,
+      tail,
+      catchUpUnavailable,
+    });
+    const { message, context } = renderWake(nw, deps.now);
+    await deps.wake({ token, auth: d.auth, message, context: context ?? [], window: d.window });
+  };
+
+  // A wake failure PROPAGATES to the caller's catch. (OPE-174 removed a terminal-session-death
+  // force-rotate branch here: it could never fire — a conversation-mode session PARKS at eve's
+  // token bound rather than failing, and a turn-time error cannot reject the awaited enqueue
+  // anyway. The reachable handler is core's agent/channels/session-park.ts.)
+  // 🔴 EVERY WAKE READS THE CHANNEL SINCE THE SEAT LAST LOOKED (OPE-1695 (b), brought to Teams by
+  // OPE-1726). A FRESH generation renders its carried tail, as it always did; an ONGOING generation
+  // reads what the channel AND this reply chain said since its own `lastWakeAt`, through the ONE
+  // shared catch-up path — same bounds, same admission policy, same cap as Slack's. The read runs on
+  // MICROSOFT GRAPH, not on the Bot Connector this wake arrived over; see teams-catch-up.ts.
+  // FAIL-SOFT: the shared path never throws, and an unregistered fetch comes back as the UNAVAILABLE
+  // note rather than as a silent empty context.
+  // 🔴 NO TEAM ID STATES ITS BOUND RATHER THAN READING EMPTY, and TWO shapes reach that arm with TWO
+  // DIFFERENT SENTENCES. Graph addresses a history read as `/teams/{team}/channels/{channel}`.
+  //   • A PERSONAL OR GROUP CHAT carries no team at all. That is STRUCTURAL — this surface cannot
+  //     read its own history, ever — so it takes core's own `catchUpUnavailableReason`.
+  //   • A CHANNEL whose Connector team id would not resolve to its Graph one
+  //     (channels/teams-graph-team-id.ts) has no address ON THIS WAKE. That is TRANSIENT, and saying
+  //     "this surface cannot read its own history" over it would tell the seat something false about
+  //     Teams — the exact line core's seat-catch-up.ts draws between a structural absence and a
+  //     failed read. So it gets its own sentence, below.
+  // Either way the wake SAYS SO: skipping in silence would render the same empty context a quiet
+  // channel renders, which is the one thing this whole mechanism exists to stop.
+  // See TeamsSupervisorDispatch.replyChainRootId: the chain this wake sits in is what the read adds
+  // to the channel; the envelope's own thread meta is the fallback for a caller that names only that.
+  const catchUpRoot = d.replyChainRootId ?? d.threadRootId;
+  const catchUp =
+    session.freshGeneration || !deps.catchUp
+      ? undefined
+      : !d.teamId
+        ? {
+            messages: [] as readonly WakeMessageInput[],
+            unavailable: d.teamAddressUnresolved ? TEAM_ADDRESS_UNRESOLVED_NOTE : catchUpUnavailableReason("teams"),
+          }
+        : await deps.catchUp({
+            container: `${d.teamId}/${d.channelId}`,
+            ...(catchUpRoot ? { threadRoot: catchUpRoot } : {}),
+            sinceMs: seatCatchUpSinceMs(session.lastWakeAt, Date.parse(atIso) || Date.now(), TEAMS_CATCH_UP_REACHBACK_HOURS),
+            untilMs: Date.parse(d.trigger.sentAt) || Date.parse(atIso) || Date.now(),
+            excludeId: d.trigger.id,
+            channelKey: d.surfaceKey,
+          });
+  await doWake(session.token, session.generation, session.freshGeneration ? session.tail : (catchUp?.messages ?? []), catchUp?.unavailable);
+  if (deps.touchSession) await deps.touchSession(d.surfaceKey, atIso);
+  if (deps.recordWake) {
+    // AFTER the wake landed, and only the TRIGGER — never the backscroll rendered beside it. That is
+    // what stops a tail inheriting a tail (channels/session-tail.ts).
+    await deps.recordWake(
+      {
+        kind: "wake",
+        at: atIso,
+        from: "human",
+        trust: d.trigger.trust,
+        // THE AUTHOR GRAIN (OPE-1747) — `d.ingested[0]` is the TRIGGER's own facts, the one entry the
+        // front's own `stampNonMemberChatAuth` join reads, resolved through the one core road.
+        // `refuted: false` on an empty carriage is the answer the live wake acted on, never the UNKNOWN
+        // an absent field means — that is reserved for a row persisted before this field existed.
+        ...tailAuthorGrain(d.ingested[0] ?? { trust: d.trigger.trust }),
+        author: d.trigger.authorName ?? d.trigger.authorId,
+        authorId: d.trigger.authorId,
+        id: d.trigger.id,
+        platform: "teams",
+        // The ROOM, not the domain — see TeamsSupervisorDispatch.containerKey. The post that answers
+        // this wake files under `partition.surfaceKey`, and the fold policy compares the two strings.
+        container: d.containerKey,
+        ...(d.threadRootId ? { threadRoot: d.threadRootId } : {}),
+        text: d.trigger.text,
+      },
+      session.token,
+      d.surfaceKey,
+    );
+  }
+}
+
+// --- FIRST-CLASS DM WINDOW (OPE-357) — the Teams twin of buildDiscordDmWake / slackDmWake --------
+//
+// A Teams personal/group chat is diverted into its OWN dedicated DM window (channels/dm-seat.ts),
+// exactly as OPE-356 first-classed Discord DMs and OPE-351 stages 2/4 first-classed Slack's. The
+// pure pieces live here (the eve-free core); teams-front.ts owns the live divert wiring. A DM window
+// is STRUCTURALLY SEPARATE from the shared cross-surface window — it never touches
+// teamsSingleWindowPrivacyOk (whose channel-only floor stays exactly as strict); it is its own admit
+// space, keyed on the DM's surface key.
+
+/** Everything {@link buildTeamsDmWake} needs — deliberately NARROWER than {@link
+ *  TeamsSupervisorWakeInput}: a DM has no channel container and no engagement tier, and both
+ *  absences are a property of the surface rather than a field a caller might or might not fill in
+ *  (the buildDiscordDmWake discipline). */
+export interface TeamsDmWakeInput {
+  /** The DM conversation id — a DM's whole locus (the envelope's `<channel id>`). */
+  readonly conversationId: string;
+  readonly wakeId: string;
+  /** The OUTGOING generation's recorded TAIL (OPE-794), rendered as this first wake's backscroll.
+   *  Only a FRESH generation's first wake carries one. */
+  readonly tail?: readonly WakeMessageInput[];
+  readonly trigger: {
+    readonly id: string;
+    readonly author: string;
+    readonly authorId: string;
+    readonly sentAt: string;
+    readonly text: string;
+    /** Resolved per-wake trust tier (identity/wake-trust.ts). 🔴 REQUIRED (OPE-596) — the field
+     *  used to default to `principal`, the highest tier, on the reasoning that a DM partner IS the
+     *  seat's principal. That reasoning is about the ROOM, and the tier is about the AUTHOR. See
+     *  {@link TeamsSupervisorWakeInput}'s trigger tier. */
+    readonly trust: WakeTrust;
+  };
+}
+
+/**
+ * THE 1:1 (and group) DM WAKE for a first-classed Teams DM window (OPE-357) — the Teams twin of
+ * slack-events.ts's `slackDmWake` and discord-gateway.ts's {@link buildTeamsDmWake} sibling
+ * `buildDiscordDmWake`, and it renders through the SAME core renderer with no platform branch, so all
+ * three surfaces' DM envelopes are one dialect.
+ *
+ * ADDRESSING IS `direct-mention`, ALWAYS, doing the same two jobs it does on Slack/Discord. Semantically
+ * it is simply TRUE: everything said in a DM is said to the agent, which is why this path bypasses the
+ * engagement gate and the name-drop judge entirely — a DM IS ALWAYS ANSWERED. Mechanically it is
+ * LOAD-BEARING: `direct-mention` stamps `oe_addressing` through the divert, which marks the wake as
+ * OWED a reply and selects the `[direct]` preamble's reply mandate. 🔴 IT IS NOT A DELIVERY PATH
+ * (OPE-1982): the addressed-prose bridge it used to arm is deleted, so a DM answer written as prose
+ * rather than a `reply` call is DROPPED on that channel like any other, and re-driven once.
+ *
+ * `reason` is `dm`, not `mention`: the envelope's reason describes the SURFACE SHAPE, and it is the
+ * one reason that survives the OPE-744 collapse of `mention` into `channel-activity` — no other
+ * attribute states "this is a direct-message room". NO `engagementTier` either — that dial raises
+ * the bar for AMBIENT watching, and a DM is always answered.
+ *
+ * NO PLATFORM-FETCH BACKSCROLL, EVER — and here that is not merely the native path's choice (as on
+ * Discord) but a platform fact: the Bot Connector exposes no DM message-history read and the Graph
+ * chat-history endpoint is deliberately unwired (teams-read.ts). So a fresh Teams DM generation
+ * carries the RECORDED TAIL and nothing else. Pure → unit-testable.
+ */
+export function buildTeamsDmWake(input: TeamsDmWakeInput): NormalizedWake {
+  return {
+    platform: "teams",
+    reason: "dm",
+    addressing: "direct-mention",
+    wakeId: input.wakeId,
+    // A DM's container IS the DM conversation: no parent, no thread, and — unlike the channel
+    // builder — no `platform` address stamp, because this window sees exactly one surface.
+    locus: { channel: { id: input.conversationId } },
+    backscroll: input.tail && input.tail.length > 0 ? input.tail : undefined,
+    trigger: mkMessageTrigger({
+      from: "human", // bot/self-authored activities are dropped at the front's author gate
+      author: input.trigger.author,
+      authorId: input.trigger.authorId,
+      id: input.trigger.id,
+      sentAt: input.trigger.sentAt,
+      // The caller's stated per-person tier — no default (OPE-596).
+      trust: input.trigger.trust,
+      // The response-obligation flag, exactly as the Slack/Discord DM wakes carry it.
+      mention: true,
+      body: input.trigger.text,
+    }),
+  };
+}
+