@open-everywhere/provider-slack 0.1.0

package/agent/channels/slack-wake-backscroll.ts

@@ -0,0 +1,604 @@
+// Wake-time conversation backscroll.
+//
+// The MENTION path enriches a turn with surrounding conversation (slack-context.ts, via Eve's
+// `SlackContext` handle). The WAKE path — a name-drop that pulls the bot into a conversation it
+// was never mentioned in (slack-events.ts routeNameDropEvent) — used to hand the model ONLY the
+// triggering message, so:
+//   (a) a cold name-drop mid-thread arrived with no idea what's being discussed, and
+//   (b) a re-wake after auto-disengage resumed the SAME thread session, which has a GAP for
+//       everything said while the bot was disengaged.
+// This module closes both by fetching recent history at wake time and attaching it as the same
+// `context` strings the mention path uses.
+//
+// WHY A STANDALONE CALLER (not Eve's `ctx`): a wake fires from a raw HTTP route, not a live
+// session, so there's no `SlackContext`/`ctx.slack` to borrow. We call the Web API through OE's
+// `callSlackWebApi` seam (channels/slack-web-api.ts) with the bot token — the same seam every other
+// Slack Web API call uses, so this path inherits the 429 backoff. The message→line mapping,
+// the render, and the UNTRUSTED wrapping are REUSED from slack-context.ts (linesFromMessages /
+// renderContext / ContextLine), so wake context is attributed + fenced byte-identically to the
+// mention path — the untrusted framing is a security invariant (channel content is DATA, never
+// instructions), not decoration, so it must never diverge between the two paths.
+//
+// BOOTSTRAP BACKSCROLL is fail-soft: any error yields no context and never blocks the first wake.
+// SEAT CATCH-UP propagates the same read failure to core's shared fail-soft boundary, so the wake
+// still continues but its `seat.catch_up` row says `failed` rather than `empty` (OPE-1842).
+
+import { callSlackWebApi } from "./slack-web-api.js";
+import { RateLimitExhaustedError } from "@open-everywhere/core/agent/adapter-api.js";
+import { linesFromMessages, readMoreHint } from "./slack-context.js";
+import {
+  renderContext,
+  sinceLastAgentReply,
+  WAKE_BACKSCROLL_MAX,
+  fetchedBackscroll,
+  catchUpSender,
+  type ContextLine,
+  type NormalizedMessage,
+  type BackscrollTrustFor,
+  type SeatAdmissionFn,
+  type SeatCatchUpFetch,
+  type SeatCatchUpRequest,
+  type WakeMessageInput,
+} from "@open-everywhere/core/agent/adapter-api.js";
+
+// Re-export the shared cap so this module's public surface (and its test, which imports it from
+// here) is unchanged after the extraction into context-render.ts (now reached via the barrel).
+export { WAKE_BACKSCROLL_MAX };
+
+/**
+ * The widest THREAD slice this module hands a caller that ADMITS BEFORE IT CAPS (OPE-1744,
+ * {@link WakeBackscrollInput.threadAdmissionSlice}). Five times {@link WAKE_BACKSCROLL_MAX}, so the
+ * policy can look past a long run of refused replies and still fill the ten-line slot; half the page
+ * the thread fetch buys, so the slice stays bounded.
+ * 🔴 IT IS A COST BOUND, AND THE COST IS THE CALLER'S PER-AUTHOR PROBE. Slack's hydration regrades
+ * every returned line before it admits, and that regrade runs one TTL-cached `users.info` per
+ * DISTINCT vouchable author. Handing back the whole 100-reply page would put that fan-out on a busy
+ * thread; the probe fails OPEN, so an exhausted burst demotes nobody and a guest keeps the tier a
+ * confirmed-internal channel gives. The slice is bounded here to keep that burst small.
+ */
+export const THREAD_ADMISSION_MAX = WAKE_BACKSCROLL_MAX * 5;
+
+/** The Slack bot's resolved identity — used to label the agent's own prior posts as `agent`. */
+export interface WakeBotIdentity {
+  readonly userId?: string;
+  readonly botId?: string;
+}
+
+/** A Slack Web-API caller: POSTs `method` with url-encoded `params`, returns parsed JSON or
+ *  undefined on any failure (fail-soft). Injected so the fetcher is unit-testable offline. */
+export type SlackRequester = (method: string, params: Record<string, string>) => Promise<Record<string, unknown> | undefined>;
+
+/** The triggering event, narrowed to what the backscroll needs. */
+export interface WakeBackscrollInput {
+  readonly channelId: string;
+  /** The triggering message's ts. */
+  readonly ts: string;
+  /** Thread root ts — present ⇒ in-thread wake (conversations.replies); absent ⇒ top-level. */
+  readonly threadTs?: string;
+  /**
+   * THREAD LEG ONLY (OPE-1744): hand back the ADMISSION slice — up to {@link THREAD_ADMISSION_MAX}
+   * replies rather than the render cap's {@link WAKE_BACKSCROLL_MAX} — so the caller filters first
+   * and caps after. That is the order channels/seat-admission.ts {@link admitToSeat} states ("filter,
+   * then let the caller cap — never the reverse, or a refused bot's bytes would eat a person's
+   * message out of the cap"). A caller that applies an admission policy asks for it and caps with
+   * `capLines` once the policy has run; every other caller leaves it absent and gets the render-cap
+   * slice it always got.
+   * 🔴 IT MOVES THE CAP, NEVER THE POLICY. The admission stays ABOVE this seam, in the caller, so a
+   * wiring that supplies its own `backscroll` still cannot bypass it — a cap is a budget, not a
+   * security control, which is why this is the half that may cross.
+   * The CHANNEL leg ignores it: its raw fetch asks Slack for {@link WAKE_BACKSCROLL_MAX} messages, so
+   * there is no wider slice to hand back and backfilling would mean buying a bigger page.
+   */
+  readonly threadAdmissionSlice?: boolean;
+}
+
+/** Injected seams so the fetcher runs without a network (tests) but defaults to live Slack. */
+export interface WakeBackscrollDeps {
+  readonly request: SlackRequester;
+  readonly identity: () => Promise<WakeBotIdentity>;
+}
+
+// --- live (bot-token) implementations ---------------------------------------
+
+// Bot-token POST to the Slack Web API via OE's `callSlackWebApi` (channels/slack-web-api.ts), which
+// a wake path can't reach through `ctx` because it fires from a raw HTTP route with no live session.
+// Form-encodes `params` and resolves the token from `SLACK_BOT_TOKEN`. Fail-soft: a missing token
+// makes the seam throw, and any throw → undefined (backscroll never blocks a wake).
+const liveRequest: SlackRequester = async (method, params) => {
+  try {
+    return (await callSlackWebApi({ botToken: undefined, operation: method, body: params })) as Record<string, unknown>;
+  } catch (err) {
+    // 🔴 LOG A RATE-LIMIT EXHAUSTION BEFORE SWALLOWING IT (OPE-1211). Fail-soft is right here — a
+    // backscroll must never block a wake — but an exhausted 429 retry with no trace is the silent
+    // drop the ticket exists to prevent. Every field is token-free.
+    if (err instanceof RateLimitExhaustedError) {
+      console.warn(`[open-everywhere:slack] rate limited: backscroll ${method} gave up after ${err.attempts} attempts (waited ${err.waitedMs} ms)`);
+    }
+    return undefined;
+  }
+};
+
+// The bot's (user_id, bot_id) via auth.test, resolved once (cached). Same shape as
+// slack-front.ts's resolveBotIdentity; a local copy avoids the import cycle noted above. Used
+// only to attribute the agent's own posts in the backscroll — best-effort, never a hard gate.
+let wakeBotIdentityPromise: Promise<WakeBotIdentity> | undefined;
+function liveWakeBotIdentity(): Promise<WakeBotIdentity> {
+  if (!wakeBotIdentityPromise) {
+    wakeBotIdentityPromise = (async () => {
+      const res = await liveRequest("auth.test", {});
+      if (res?.ok === true) {
+        return {
+          userId: typeof res.user_id === "string" ? res.user_id : undefined,
+          botId: typeof res.bot_id === "string" ? res.bot_id : undefined,
+        };
+      }
+      return {};
+    })();
+  }
+  return wakeBotIdentityPromise;
+}
+
+/** Reset the cached wake bot identity (tests only). */
+export function _resetWakeBotIdentity(): void {
+  wakeBotIdentityPromise = undefined;
+}
+
+const liveDeps: WakeBackscrollDeps = { request: liveRequest, identity: liveWakeBotIdentity };
+
+// --- the fetcher ------------------------------------------------------------
+
+/** The RAW-lines result of a name-drop backscroll fetch (W3): the oldest-first
+ *  {@link ContextLine}s — capped at {@link WAKE_BACKSCROLL_MAX}, or at the wider
+ *  {@link THREAD_ADMISSION_MAX} where the caller asked for the thread leg's admission slice
+ *  ({@link WakeBackscrollInput.threadAdmissionSlice}) and caps itself — plus the renderContext
+ *  `source` label and the Slack read-more hint. The renderer
+ *  ({@link renderContext}, called inside renderWake) turns these into the untrusted-wrapped context
+ *  block — so no pre-rendered string ever flows through the wake plumbing. `null` = nothing to add
+ *  OR any failure (always non-fatal). */
+export interface WakeBackscrollLines {
+  readonly lines: readonly ContextLine[];
+  readonly source: string;
+  /** Slack HAS read tools, so the hint names them; renderContext appends it OUTSIDE the untrusted
+   *  block only when the slice actually hit the cap. */
+  readonly readMoreHint: string;
+}
+
+/**
+ * Fetch recent conversation history for a name-drop wake as RAW ContextLines + source + hint (W3) —
+ * the renderer wraps them (renderContext, inside renderWake). `null` = nothing to add OR any
+ * failure (always non-fatal).
+ *
+ * - IN-THREAD wake (`threadTs`): `conversations.replies`, sliced to "since the agent's last reply"
+ *   (see {@link sinceLastAgentReply}); the triggering message itself is excluded (the wake message
+ *   already carries its text). Capped at {@link WAKE_BACKSCROLL_MAX}, or at the wider
+ *   {@link THREAD_ADMISSION_MAX} when the caller asks for the admission slice
+ *   ({@link WakeBackscrollInput.threadAdmissionSlice}).
+ * - TOP-LEVEL wake (no `threadTs`): `conversations.history` with `latest = ts`, `inclusive: false`
+ *   → strictly-older messages only, most recent N.
+ */
+export async function fetchWakeBackscrollLines(input: WakeBackscrollInput, deps: WakeBackscrollDeps = liveDeps): Promise<WakeBackscrollLines | null> {
+  try {
+    const ids = await deps.identity().catch(() => ({} as WakeBotIdentity));
+    if (input.threadTs) {
+      const res = await deps.request("conversations.replies", {
+        channel: input.channelId,
+        ts: input.threadTs,
+        // A single (oldest-anchored) page — no cursor paging. Comfortably covers any realistic
+        // thread; a pathologically long one degrades to "older context only", still fail-soft.
+        limit: "100",
+      });
+      const raw = extractMessages(res);
+      if (!raw) return null;
+      // Drop the trigger itself (its text rides on the wake message, not the backscroll).
+      const priorRaw = raw.filter((m) => (typeof m.ts === "string" ? m.ts : "") !== input.ts);
+      // conversations.replies is oldest-first already — no reverse.
+      const lines = sinceLastAgentReply(linesFromMessages(priorRaw, ids));
+      const source = `slack thread ${input.channelId}/${input.threadTs}`;
+      // The wider ADMISSION slice when the caller admits before it caps (OPE-1744), the render-cap
+      // slice otherwise — see {@link WakeBackscrollInput.threadAdmissionSlice}.
+      return input.threadAdmissionSlice ? backscrollEntry(lines.slice(-THREAD_ADMISSION_MAX), source) : cappedEntry(lines, source);
+    }
+    // Top-level: strictly-older backscroll of the channel (mirrors slack-context's channel path).
+    const res = await deps.request("conversations.history", {
+      channel: input.channelId,
+      latest: input.ts,
+      inclusive: "false",
+      limit: String(WAKE_BACKSCROLL_MAX),
+    });
+    const raw = extractMessages(res);
+    if (!raw) return null;
+    const lines = linesFromMessages(raw, ids);
+    lines.reverse(); // conversations.history is newest-first → oldest-first for rendering
+    return cappedEntry(lines, `slack channel ${input.channelId}`);
+  } catch {
+    return null; // fail-soft: a wake never depends on its backscroll
+  }
+}
+
+/**
+ * Fetch recent conversation history for a name-drop wake, rendered as `context` strings
+ * (untrusted-wrapped, oldest-first, capped at {@link WAKE_BACKSCROLL_MAX}). Empty array = nothing to
+ * add OR any failure. Thin wrapper over {@link fetchWakeBackscrollLines} + the shared renderContext,
+ * so its output stays byte-identical to before the W3 refactor (retained for its existing callers
+ * and byte-identity tests; the live name-drop path now uses the lines variant directly).
+ */
+export async function fetchWakeBackscroll(input: WakeBackscrollInput, deps: WakeBackscrollDeps = liveDeps): Promise<string[]> {
+  const res = await fetchWakeBackscrollLines(input, deps);
+  if (!res) return [];
+  const entry = renderContext(res.lines, res.source, { readMoreHint: res.readMoreHint });
+  return entry ? [entry] : [];
+}
+
+// Pull the `messages` array out of an ok response, or undefined (fail-soft on junk / not-ok).
+function extractMessages(res: Record<string, unknown> | undefined): Array<Record<string, unknown>> | undefined {
+  if (!res || res.ok !== true || !Array.isArray(res.messages)) return undefined;
+  return res.messages as Array<Record<string, unknown>>;
+}
+
+// Return the RAW lines + source + hint — the renderer (renderContext, inside renderWake) does the
+// untrusted-wrap, so wrapping happens in exactly ONE place (W3). `lines` must be oldest-first.
+// Returns null when there's nothing to keep, so the caller renders no context block.
+// The hint is handed over unconditionally: `renderContext` appends it only when the RENDERED slice
+// fills MAX_MESSAGES, so it always describes what the model was shown, never what was fetched.
+function backscrollEntry(lines: readonly ContextLine[], source: string): WakeBackscrollLines | null {
+  if (lines.length === 0) return null;
+  return { lines, source, readMoreHint: readMoreHint() };
+}
+
+// {@link backscrollEntry} with the WAKE_BACKSCROLL_MAX cap applied first (keep the most recent).
+function cappedEntry(lines: readonly ContextLine[], source: string): WakeBackscrollLines | null {
+  return backscrollEntry(lines.slice(-WAKE_BACKSCROLL_MAX), source);
+}
+
+// --- envelope-shaped first-wake backscroll (supervisor context hydration) — SLACK ADAPTER ----
+//
+// The channel-supervisor's FIRST wake on a generation (a brand-new session OR the fresh generation
+// minted by a rotation, slack-events.ts shouldRotate/routeSupervisorEvent) carries channel
+// backscroll rendered as the wake ENVELOPE's own non-trigger `<message>` siblings, grouped into
+// `<session>` blocks (wake-envelope.ts renderWakeEnvelope) — Claude Tag's observed first-wake shape
+// is individual attributed messages, oldest-first, ending at the trigger (claude-tag-behaviour.md
+// §4.1), and OE's is richer: idle-gap-clustered pseudo-sessions with count/time/token bounds
+//.
+//
+// THIS FILE IS THE SLACK FETCH ADAPTER behind the platform-NEUTRAL clustering/bounds core
+// (backscroll-window.ts). Its job: turn conversations.history (+ conversations.replies for thread
+// enrichment) into a visibility-GATED {@link NormalizedMessage}[] window, then hand it to
+// {@link fetchedBackscroll}. Discord/Teams later add their OWN fetch adapter with zero change to the
+// core. FAIL-SOFT ABSOLUTELY throughout, exactly like {@link fetchWakeBackscroll}.
+
+// --- fetch bounds (Slack-specific; the clustering/token bounds live in backscroll-window.ts) ---
+
+/** Reachback (hours) for the raw Slack window: how far back from the trigger conversations.history
+ *  is paginated. Generous enough that the SPINE (the most-recent cluster, exempt from the 36h
+ *  enrichment cap) can still reach across a weekend/overnight gap (~66h Fri-4pm→Mon-10am), yet a
+ *  hard floor that bounds the fetch. 7d default; overridable for ops/testing. */
+export const RAW_FETCH_REACHBACK_HOURS = Number(process.env.OE_SUPERVISOR_BACKSCROLL_REACHBACK_HOURS) || 168;
+
+/** conversations.history page size (Slack max is 1000; 200 keeps each page cheap). */
+const RAW_FETCH_PAGE_LIMIT = 200;
+
+/** Max history pages to paginate — bounds a busy channel's fetch at ≤600 messages so a burst can't
+ *  fan out into an unbounded loop. Combined with the reachback floor (whichever binds first). */
+const RAW_FETCH_MAX_PAGES = 3;
+
+/** Max in-window thread ROOTS to enrich via conversations.replies — bounds the reply fan-out so a
+ *  channel full of threads can't explode into unbounded API calls. */
+const MAX_THREADS_ENRICHED = 8;
+
+/** Single-page reply fetch per thread (mirrors the name-drop thread leg's own 100). */
+const THREAD_REPLIES_LIMIT = 100;
+
+/**
+ * The VISIBILITY / TRUST GATE (spec §Bounds — the load-bearing SECURITY filter): backscroll must
+ * never surface a message it can't ATTRIBUTE. The channel-internal confirmation
+ * (confirmChannelInternalWithMeta) fail-closes the restricted-area / at-rest-isolation dimension
+ * BEFORE this fetcher is ever called. So the per-message gate here KEEPS:
+ *   - the bot's OWN prior posts (`agent` → `self`);
+ *   - identifiable humans (`user` → `human`);
+ *   - ATTRIBUTABLE foreign bots (`bot` WITH a bot id → `bot`) — INCLUDED as MARKED AWARENESS
+ *     (clearly bot-flagged, CONTEXT-ONLY, never a wake trigger). Design intent: the supervisor
+ *     SHOULD see foreign-bot posts, and dropping them breaks CONVERSATIONAL COHERENCE — a human
+ *     replying to a bot's message would otherwise arrive with the bot message missing, so the agent
+ *     couldn't tell what the human is responding to.
+ * and DROPS ONLY:
+ *   - unattributable senders (`unknown`, or a `bot` with no id) — no auth'd author ⇒ fail closed.
+ * (System-subtype noise is already dropped upstream by linesFromMessages.) Foreign-bot messages are
+ * CONTEXT-ONLY on this path: the neutral core never sets `trigger` on backscroll, and the LIVE
+ * trigger gate (slack-events.ts shouldSupervisorWake) still drops bot-authored messages as triggers,
+ * so a bot post is awareness, never a response obligation. Wired explicitly + unit-tested
+ * (slack-wake-backscroll-test.ts) so it can't be forgotten.
+ */
+export function isBackscrollVisible(line: ContextLine): boolean {
+  return (
+    line.senderType === "agent" ||
+    line.senderType === "user" ||
+    (line.senderType === "bot" && line.senderId !== undefined) // attributable foreign bot: marked awareness
+  );
+}
+
+export interface WakeEnvelopeBackscrollInput {
+  readonly channelId: string;
+  /** The triggering message's ts — the window's upper (exclusive) bound and the reachback origin. */
+  readonly ts: string;
+  /** Known thread root for a thread-bound catch-up. Present ⇒ read that thread directly; a root
+   * older than `sinceMs` is absent from `conversations.history` but its newer replies are not. */
+  readonly threadRoot?: string;
+  /** Hours to look back from `ts` for the raw fetch. Defaults to {@link RAW_FETCH_REACHBACK_HOURS}. */
+  readonly reachbackHours?: number;
+  /**
+   * THE CATCH-UP BOUND (OPE-1695 (b)): epoch milliseconds of the seat's own LAST WAKE, so this read
+   * returns what the room said since the seat last looked. It only ever NARROWS the window — the
+   * reachback floor above still applies — so a seat quiet for a month reads the recent tail, and a
+   * seat with no recorded wake reads the bootstrap window exactly as a first wake always did.
+   */
+  readonly sinceMs?: number;
+}
+
+// Pull the pagination cursor from a conversations.history response, or undefined when there's no
+// next page (fail-soft on junk).
+function extractCursor(res: Record<string, unknown> | undefined): string | undefined {
+  const meta = res?.response_metadata as { next_cursor?: unknown } | undefined;
+  const cursor = meta?.next_cursor;
+  return typeof cursor === "string" && cursor.length > 0 ? cursor : undefined;
+}
+
+// Paginate conversations.history backward from `latest` (exclusive) down to `oldest`, bounded by
+// RAW_FETCH_MAX_PAGES. Returns the raw messages (newest-first across pages — the neutral core sorts
+// by ts anyway). Fail-soft: a not-ok/absent page ends pagination with whatever's in hand.
+async function fetchChannelWindow(
+  request: SlackRequester,
+  channelId: string,
+  latest: string,
+  oldest: string,
+): Promise<Array<Record<string, unknown>>> {
+  const all: Array<Record<string, unknown>> = [];
+  let cursor: string | undefined;
+  for (let page = 0; page < RAW_FETCH_MAX_PAGES; page++) {
+    const res = await request("conversations.history", {
+      channel: channelId,
+      latest,
+      inclusive: "false",
+      oldest,
+      limit: String(RAW_FETCH_PAGE_LIMIT),
+      ...(cursor ? { cursor } : {}),
+    });
+    const msgs = extractMessages(res);
+    if (!msgs) break;
+    all.push(...msgs);
+    cursor = extractCursor(res);
+    if (!cursor) break; // no more pages
+  }
+  return all;
+}
+
+// Enrich with thread replies for in-window thread ROOTS (conversations.history returns roots +
+// top-level messages, not the replies inside a thread). BOUNDED: only roots that actually have
+// replies, capped at MAX_THREADS_ENRICHED, one page each. Returns [{ root, msgs }]; fail-soft per
+// thread (a failed reply fetch just omits that thread's replies).
+async function fetchThreadReplies(
+  request: SlackRequester,
+  channelId: string,
+  channelMsgs: ReadonlyArray<Record<string, unknown>>,
+): Promise<Array<{ root: string; msgs: Array<Record<string, unknown>> }>> {
+  const roots: string[] = [];
+  for (const m of channelMsgs) {
+    if (roots.length >= MAX_THREADS_ENRICHED) break;
+    const ts = typeof m.ts === "string" ? m.ts : undefined;
+    const threadTs = typeof m.thread_ts === "string" ? m.thread_ts : undefined;
+    const replyCount = typeof m.reply_count === "number" ? m.reply_count : 0;
+    // A thread root: it IS its own thread anchor (no thread_ts, or thread_ts === ts) and has replies.
+    if (ts && replyCount > 0 && (!threadTs || threadTs === ts)) roots.push(ts);
+  }
+  const out: Array<{ root: string; msgs: Array<Record<string, unknown>> }> = [];
+  for (const root of roots) {
+    const res = await request("conversations.replies", { channel: channelId, ts: root, limit: String(THREAD_REPLIES_LIMIT) });
+    const msgs = extractMessages(res);
+    if (msgs) out.push({ root, msgs });
+  }
+  return out;
+}
+
+// Read one KNOWN thread without first discovering its root through channel history. A standing
+// seat's catch-up window commonly starts after the thread root, so root discovery would answer an
+// empty channel page even when the thread has new replies inside the window (OPE-1920).
+async function fetchKnownThreadReplies(
+  request: SlackRequester,
+  channelId: string,
+  threadRoot: string,
+  oldest: string,
+  latest: string,
+): Promise<Array<{ root: string; msgs: Array<Record<string, unknown>> }>> {
+  const res = await request("conversations.replies", {
+    channel: channelId,
+    ts: threadRoot,
+    oldest,
+    latest,
+    // Keep both endpoints at the transport seam. Core removes the trigger by exact id and enforces
+    // the same bounds again after normalization.
+    inclusive: "true",
+    limit: String(THREAD_REPLIES_LIMIT),
+  });
+  const msgs = extractMessages(res);
+  return msgs ? [{ root: threadRoot, msgs }] : [];
+}
+
+// Normalize ONE raw Slack message → {@link NormalizedMessage}, reusing linesFromMessages for the
+// exact sender classification + system/empty drop, then applying the VISIBILITY GATE. Returns
+// undefined for a dropped (invisible / subtype / empty / unparseable-ts) message.
+function normalizeOne(
+  m: Record<string, unknown>,
+  ids: WakeBotIdentity,
+  type: "channel" | "thread",
+  threadId: string | undefined,
+): NormalizedMessage | undefined {
+  const [line] = linesFromMessages([m], ids);
+  if (!line) return undefined; // system subtype / empty text (dropped upstream)
+  if (!isBackscrollVisible(line)) return undefined; // VISIBILITY GATE (unattributable sender only)
+  const seconds = Number.parseFloat(line.ts);
+  if (!Number.isFinite(seconds)) return undefined;
+  return {
+    id: line.ts,
+    ms: seconds * 1000,
+    // undefined for the bot's OWN posts (agent); the foreign bot's id for a `bot`; the user id for
+    // a human — kept raw for @-tagging / attribution.
+    authorId: line.senderId,
+    // THE SHARED SENDER RULE (OPE-1857): agent → self (our own post); bot → bot (attributable
+    // foreign bot, marked awareness); every other visible line is a `user` → human. `unknown` was
+    // already dropped by the gate above.
+    sender: catchUpSender({ self: line.senderType === "agent", bot: line.senderType === "bot" }),
+    type,
+    threadId,
+    text: line.text,
+  };
+}
+
+/**
+ * SLACK FETCH SEAM: fetch a bounded, visibility-GATED, NORMALIZED backscroll window (channel history
+ * + in-window thread replies) for a supervisor first wake. This is the platform boundary — the
+ * neutral core ({@link fetchedBackscroll}) consumes its output. FAIL-SOFT: any error/failure yields
+ * `[]`. Deduped by message id (a thread root appears in both history and its replies[0]).
+ */
+export async function fetchSlackBackscrollWindow(
+  input: WakeEnvelopeBackscrollInput,
+  deps: WakeBackscrollDeps = liveDeps,
+  failureMode: "soft" | "throw" = "soft",
+): Promise<NormalizedMessage[]> {
+  try {
+    const ids = await deps.identity().catch(() => ({} as WakeBotIdentity));
+    const latestSeconds = Number.parseFloat(input.ts);
+    if (!Number.isFinite(latestSeconds)) return [];
+    const reachbackHours = input.reachbackHours ?? RAW_FETCH_REACHBACK_HOURS;
+    // The reachback floor, then the seat's own last wake where it is LATER — never earlier, so the
+    // catch-up can only narrow the fetch (see {@link WakeEnvelopeBackscrollInput.sinceMs}).
+    const floorSeconds = latestSeconds - reachbackHours * 3600;
+    const sinceSeconds = typeof input.sinceMs === "number" && Number.isFinite(input.sinceMs) ? input.sinceMs / 1000 : undefined;
+    const oldestSeconds = sinceSeconds !== undefined ? Math.max(floorSeconds, sinceSeconds) : floorSeconds;
+    const oldest = String(oldestSeconds);
+
+    // A thread-bound catch-up already knows its root. Read it directly: the root can predate the
+    // lower bound, which makes it undiscoverable through the bounded channel-history page even
+    // though newer replies belong in this wake. Bootstrap/container reads still take the original
+    // channel-history + bounded enrichment path.
+    const channelMsgs = input.threadRoot === undefined ? await fetchChannelWindow(deps.request, input.channelId, input.ts, oldest) : [];
+    const threadGroups =
+      input.threadRoot === undefined
+        ? await fetchThreadReplies(deps.request, input.channelId, channelMsgs)
+        : await fetchKnownThreadReplies(deps.request, input.channelId, input.threadRoot, oldest, input.ts);
+    if (channelMsgs.length === 0 && threadGroups.length === 0) return [];
+
+    const seen = new Set<string>();
+    const out: NormalizedMessage[] = [];
+    const add = (n: NormalizedMessage | undefined) => {
+      if (n && !seen.has(n.id)) {
+        seen.add(n.id);
+        out.push(n);
+      }
+    };
+    for (const m of channelMsgs) add(normalizeOne(m, ids, "channel", undefined));
+    for (const g of threadGroups) {
+      for (const m of g.msgs) {
+        const ts = typeof m.ts === "string" ? m.ts : "";
+        // The root is already a channel message — and so is the TRIGGER when it is a reply inside a
+        // thread whose root is in the window: `conversations.replies` returns it, and the wake
+        // renderer would then show the seat the message that woke it twice, once as context and once
+        // as the live trigger. The channel fetch excludes the trigger with `inclusive: "false"`; this
+        // is the same exclusion on the enrichment leg (the precedent is `linesFromMessages`' own
+        // "drop the trigger itself").
+        // A discovered root is already present in `channelMsgs`; a directly-read root is not, so
+        // let the ordinary lower/upper bounds decide whether it belongs. The trigger always leaves
+        // exactly by id.
+        if ((input.threadRoot === undefined && ts === g.root) || ts === input.ts) continue;
+        const secs = Number.parseFloat(ts);
+        if (Number.isFinite(secs) && secs < oldestSeconds) continue; // reply older than the window
+        if (input.threadRoot !== undefined && Number.isFinite(secs) && secs > latestSeconds) continue; // reply after the trigger
+        add(normalizeOne(m, ids, "thread", g.root));
+      }
+    }
+    return out;
+  } catch (err) {
+    if (failureMode === "throw") throw err;
+    return []; // fail-soft: a first wake never depends on its backscroll
+  }
+}
+
+/**
+ * SLACK'S REGISTERED CATCH-UP FETCH (OPE-1726) — the one thing this surface contributes to the shared
+ * since-last-wake path (core channels/seat-catch-up.ts). It is the SAME window fetch the bootstrap
+ * arm takes ({@link fetchSlackBackscrollWindow}), addressed by the neutral request shape: the seat's
+ * container, bounded below by its last wake and above by the trigger.
+ * 🔴 THE UPPER BOUND IS RE-EXPRESSED AS A SLACK `ts`, because `conversations.history` takes `latest`
+ * in Slack's own seconds-with-fraction form and not epoch ms. `excludeId` IS that ts on this surface
+ * (a Slack ts is both a time and an id), so it is preferred over the derived string — a derived one
+ * can lose the trailing digits Slack's ordering depends on. With neither, the read falls back to
+ * `now`, which is the honest upper bound for a catch-up with no stated trigger.
+ * A transport/read failure propagates to core's shared boundary, which keeps the wake alive and
+ * records `failed` instead of reporting a quiet channel (OPE-1842). Bootstrap callers keep the
+ * window fetch's default fail-soft mode.
+ */
+export async function fetchSlackSeatCatchUp(req: SeatCatchUpRequest, deps: WakeBackscrollDeps = liveDeps): Promise<readonly NormalizedMessage[]> {
+  const latestTs = req.excludeId ?? (req.untilMs !== undefined ? String(req.untilMs / 1000) : String(Date.now() / 1000));
+  const strictDeps: WakeBackscrollDeps = {
+    ...deps,
+    request: async (method, params) => {
+      const res = await deps.request(method, params);
+      if (!res || res.ok !== true || !Array.isArray(res.messages)) {
+        throw new Error(`Slack catch-up ${method} failed`);
+      }
+      return res;
+    },
+  };
+  return fetchSlackBackscrollWindow(
+    { channelId: req.container, ts: latestTs, sinceMs: req.sinceMs, ...(req.threadRoot ? { threadRoot: req.threadRoot } : {}) },
+    strictDeps,
+    "throw",
+  );
+}
+
+/**
+ * A Slack `ts` is a second with a six-digit fraction, so it carries MILLISECOND grain (OPE-1847,
+ * `core/agent/channels/seat-catch-up.ts` {@link SeatCatchUpDeclaration.timestampPrecisionMs}).
+ * 🔴 ONE MILLISECOND IS NOT ZERO WIDENING. The road widens the LOWER bound by nothing here and the
+ * UPPER bound by exactly one millisecond, so a message stamped at the trigger's own instant is
+ * INSIDE the window and `excludeId` is the only thing that removes the trigger. That holds on this
+ * surface twice over: `conversations.history` is called with `inclusive: "false"`, so the trigger
+ * never reaches the fetch, and a message that did would carry its `ts` as its id — the same value
+ * the wake path passes as `excludeId`.
+ * 🔴 THE DECLARATION CANNOT EXPRESS THIS SURFACE'S SUB-MILLISECOND `ts`. The unit is a whole number
+ * of milliseconds, so the road's floor rounds Slack's fraction away. It costs nothing today: the
+ * bound is a bound, not an ordering, and the fetch orders by `ts` itself.
+ * 🔴 IT IS STILL DECLARED, and the parity test requires it. The declaration is what makes "this
+ * surface needs the finest unit" a CHECKED claim rather than an omission, and an omission is
+ * indistinguishable from the GitHub and Notion defect this whole mechanism exists to close.
+ */
+export const SLACK_TIMESTAMP_PRECISION_MS = 1;
+
+/** The registered form — the transport seam is fixed to the live one, so a caller cannot inject past
+ *  the bot token. Tests drive {@link fetchSlackSeatCatchUp} with a canned requester instead. */
+export const slackSeatCatchUpFetch: SeatCatchUpFetch = (req) => fetchSlackSeatCatchUp(req);
+
+/**
+ * Fetch + cluster a standing seat's channel backscroll into session-tagged
+ * {@link WakeMessageInput} entries (oldest-first, no `trigger`; per-message trust via
+ * `trustFor` when the caller supplies the resolver, the fail-closed per-sender default otherwise).
+ * Thin orchestration over the Slack fetch seam ({@link fetchSlackBackscrollWindow}) + the neutral
+ * capped core ({@link fetchedBackscroll}), which applies the domain's `admit` policy. Serves the
+ * BOOTSTRAP window ONLY — a fresh generation's first wake, the one read with no cross-surface twin.
+ * Since OPE-1726 the since-last-wake CATCH-UP is not this function's job: it runs through
+ * {@link fetchSlackSeatCatchUp}, registered into the shared core path (core channels/seat-catch-up.ts
+ * `seatCatchUp`), which owns the bounds, the admission policy and the cap for every surface. This
+ * function still ACCEPTS `input.sinceMs`, but no caller sets it. FAIL-SOFT ABSOLUTELY.
+ */
+export async function fetchWakeEnvelopeBackscroll(
+  input: WakeEnvelopeBackscrollInput,
+  deps: WakeBackscrollDeps = liveDeps,
+  trustFor?: BackscrollTrustFor,
+  admit?: SeatAdmissionFn,
+): Promise<WakeMessageInput[]> {
+  try {
+    const window = await fetchSlackBackscrollWindow(input, deps);
+    if (window.length === 0) return [];
+    return fetchedBackscroll(window, undefined, trustFor, admit);
+  } catch {
+    return []; // fail-soft: a wake never depends on its backscroll
+  }
+}