@open-everywhere/core 0.1.0

package/agent/channels/dm-audience.ts

@@ -0,0 +1,346 @@
+// dm-audience — may this deployment START a direct message with this person, and has the person told it to stop? Tier P2 is NOT a consent handshake: the recipient is never asked before the first useful message, and what they get instead is a stop that really works. Four controls answer four different parties — the OPERATOR's grant, the first delivery's approval CARD, the RECIPIENT's stop, and the AUDIT row that names the person and the grant that allowed the message.
+// CONTROL 2 DOES NOT REPEAT, and that is the honest bound of this tier: after the first delivery the model authors bytes that reach a person with no human between, so a doc describing tier P2 as carded is describing the first message only. The stop is a different marker from `stand_down`, which still refuses in a DM: this one IS read, before every proactive delivery, and it is not a trap, because it suppresses only DMs the AGENT starts — the person's own messages still wake the seat.
+
+import { appendAudit } from "../audit/audit.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { surfaceKeySegment } from "../identity/binding.js";
+import { dispatchDirectMessage, type DirectMessageAction, type DirectMessageDelivery } from "./post-arms.js";
+import type { DmAudienceRow } from "../operational/store.js";
+import { resourceAddress } from "../access/resource-grant.js";
+import { proactiveDmPlaneRow, type ProactiveDmPlane } from "./proactive-dm-manifest.js";
+
+/** The resource type a PERSON is addressed as — the `<type>` rung of `slack:person/U0123ABC`. One
+ *  word for one thing: it is also the word the closed table in access/resource-grant.ts implements. */
+export const PERSON_RESOURCE_TYPE = "person";
+
+/**
+ * The canonical person address for a (platform, member id) pair — the ONE spelling the grant, the card, the audit row and the `dm_audience` key all quote, byte for byte.
+ * The id is carried in its SURFACE-KEY spelling: a no-op for a platform whose member ids are already safe, and load-bearing for one whose ids are not. Without it an operator's grant address and the RECIPIENT's own stop would key on two different strings, and a stop that keys on a string no grant can name is a stop that does not work.
+ */
+export function personAddress(platform: string, principalId: string): string {
+  return resourceAddress(platform, PERSON_RESOURCE_TYPE, surfaceKeySegment(principalId));
+}
+
+/** The audit action a recipient's STOP writes. One greppable string, shared with its test — and
+ *  named for what happened rather than for the verb, so it survives a rename. */
+export const DM_STOP_ACTION = "dm.audience.stopped";
+
+/** The audit action a recipient's RESUME writes. */
+export const DM_RESUME_ACTION = "dm.audience.resumed";
+
+/** What {@link readDmAudience} answers. Deliberately NOT the raw row: the questions a caller actually
+ *  asks are booleans, and a caller that reads timestamps has to re-derive them. */
+export interface DmAudienceState {
+  /** The recipient has stopped proactive DMs. A live grant does not override this. */
+  readonly stopped: boolean;
+  /** A proactive DM has already landed under this grant, so a later one FLOWS rather than cards. */
+  readonly delivered: boolean;
+  /**
+   * The store answered. FALSE means it did not, and `stopped` is then a fail-closed GUESS rather than a fact about this person.
+   * A CALLER MUST NOT REPORT AN UNREADABLE STORE AS A PERSON'S DECISION. Suppressing is right; telling the model "they asked you to stop" when nobody asked is a fabrication.
+   */
+  readonly readable: boolean;
+  /** The raw row, for a caller that renders the trail (an operator read, an audit detail). */
+  readonly row: DmAudienceRow | null;
+}
+
+/**
+ * This person's DM-audience state. A STORE FAILURE READS AS STOPPED — the fail-closed direction, and the opposite of most fail-softs in this tree, on purpose: of the two ways to be wrong here, only "we sent a message to somebody who told us not to" is unrecoverable.
+ * It also reads as NOT delivered, so the first message after the store recovers takes the card again, which is the same direction. It sets `readable: false` in that branch, and the distinction is not cosmetic — see the field's own doc.
+ */
+export async function readDmAudience(org: string, address: string): Promise<DmAudienceState> {
+  try {
+    const row = await getOperationalStore().getDmAudience(org, address);
+    return { stopped: row?.stoppedAt !== undefined, delivered: row?.firstDmAt !== undefined, readable: true, row };
+  } catch (err) {
+    console.warn(`[open-everywhere:dm-audience] getDmAudience failed (${address}): ${String(err)} — suppressing this delivery`);
+    return { stopped: true, delivered: false, readable: false, row: null };
+  }
+}
+
+/**
+ * Record that a proactive DM landed. Best-effort: the message is already delivered, so a failed bookkeeping write must not turn a successful send into an error the model reports as a failure.
+ * The COST of that failure is bounded and in the safe direction — the next delivery takes the card again — and it never re-opens a stop, because the store's upsert does not touch the stopped field at all.
+ */
+export async function noteDmAudienceDelivery(org: string, address: string, at: string): Promise<void> {
+  try {
+    await getOperationalStore().markDmAudienceDelivered(org, address, at);
+  } catch (err) {
+    console.warn(`[open-everywhere:dm-audience] markDmAudienceDelivered failed (${address}): ${String(err)}`);
+  }
+}
+
+/** What a stop/resume call did. `changed` is false when the state was already what was asked for —
+ *  which the caller must report honestly rather than claiming an act that did not happen. */
+export interface DmAudienceChange {
+  readonly changed: boolean;
+}
+
+/**
+ * The recipient STOPS proactive DMs.
+ * THIS THROWS ON A STORE FAILURE, and it is the one place in this module that does: a stop the person believes landed and did not would have the seat say "I have stopped" while the next delivery arrives anyway. A failed stop must read as a failed stop.
+ */
+export async function stopDmAudience(input: {
+  readonly org: string;
+  readonly address: string;
+  readonly at: string;
+  /** The person's own platform/workspace, for the audit row's subject columns. */
+  readonly platform: string;
+  readonly workspace: string;
+  readonly principalId: string;
+}): Promise<DmAudienceChange> {
+  const before = await getOperationalStore().getDmAudience(input.org, input.address);
+  await getOperationalStore().setDmAudienceStopped(input.org, input.address, input.at);
+  const changed = before?.stoppedAt === undefined;
+  await noteAudienceChange(DM_STOP_ACTION, input, changed);
+  return { changed };
+}
+
+/**
+ * The recipient RESUMES proactive DMs — the other half of a first-class stop.
+ * ONLY THE RECIPIENT LIFTS THEIR OWN STOP, and no config act does: removing the grant and adding it back writes the same address, so the row is still found and the person is still stopped. It throws on a store failure for {@link stopDmAudience}'s reason in the other direction.
+ */
+export async function resumeDmAudience(input: {
+  readonly org: string;
+  readonly address: string;
+  readonly platform: string;
+  readonly workspace: string;
+  readonly principalId: string;
+}): Promise<DmAudienceChange> {
+  const changed = await getOperationalStore().clearDmAudienceStopped(input.org, input.address);
+  await noteAudienceChange(DM_RESUME_ACTION, input, changed);
+  return { changed };
+}
+
+/** One audit row per stop/resume — ids and the outcome only, never message text. Best-effort: the
+ *  durable write already succeeded, and losing the row must not undo the person's decision. */
+async function noteAudienceChange(
+  action: string,
+  input: { readonly org: string; readonly address: string; readonly platform: string; readonly workspace: string; readonly principalId: string },
+  changed: boolean,
+): Promise<void> {
+  try {
+    await appendAudit({
+      org: input.org,
+      platform: input.platform,
+      workspace: input.workspace || "unknown",
+      principalId: input.principalId,
+      action,
+      // `changed` false means the state already said this — worth seeing in the trail, because a
+      // person repeating a stop is evidence the first one did not feel like it worked.
+      detail: { address: input.address, changed },
+    });
+  } catch (err) {
+    console.warn(`[open-everywhere:audit] ${action} row was not written: ${String(err)}`);
+  }
+}
+
+/** The audit action every proactive DM delivery writes — carded or flowing. ONE string, so a
+ *  reviewer greps once and the two paths can never file under two names. */
+const DM_DELIVERY_ACTION = "chat.dm";
+
+/** Where an audit row's subject columns come from. The two delivery paths resolve them differently —
+ *  one from a frozen scope key, one from a live partition — so the caller supplies them and
+ *  {@link deliverProactiveDm} never has to know which path it is on. */
+export interface DmDeliveryWhere {
+  readonly org: string;
+  readonly platform: string;
+  readonly workspace: string;
+  /** Optional, because `whereFromScope` cannot always name a surface from a frozen scope key. An
+   *  absent surface is left OFF the row rather than filled with a placeholder — a fabricated value
+   *  in a queryable audit column is worse than a missing one. */
+  readonly surface?: string;
+}
+
+/** The audit action every refused proactive DM writes — one greppable string for every plane and every boundary, so a reviewer counts refusals once rather than per call site. */
+export const DM_REFUSED_ACTION = "dm.refused";
+
+/**
+ * Thrown by {@link assertProactiveDmAllowed}, and therefore by {@link deliverProactiveDm}: this person may not be sent an agent-started direct message right now.
+ * `unreadable` is NEVER folded into `stopped`. Reporting an outage as a person's decision states a fact about them that nobody established — the same split {@link DmAudienceState.readable} draws, for the same reason.
+ */
+export class ProactiveDmRefusedError extends Error {
+  constructor(
+    readonly plane: ProactiveDmPlane,
+    readonly platform: string,
+    /** The RECIPIENT's bare platform member id. */
+    readonly recipientId: string,
+    /** The address the stop is keyed on — what the audit row names. */
+    readonly address: string,
+    readonly boundary: "stopped" | "unreadable",
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** What a caller is told when the RECIPIENT refused. ONE sentence, spelled once and shared by the road and by `access/chat-dm-grant.ts`'s propose-time fence: two planes that describe one boundary in two ways is how a person's stop starts meaning two different things. */
+export function dmStoppedRefusalMessage(platform: string, recipientId: string): string {
+  return (
+    `${platform} person "${recipientId}" asked this agent to stop sending them direct messages, so nothing ` +
+    `was sent. That boundary is theirs and no configuration overrides it — only they can lift it, by telling the ` +
+    `agent in their own DM. Say so plainly rather than trying another route to reach them.`
+  );
+}
+
+/** What a caller is told when the stop could NOT BE READ. Never folded into {@link dmStoppedRefusalMessage}: reporting an outage as a person's decision states a fact about them that nobody established. */
+export function dmUnreadableRefusalMessage(platform: string, recipientId: string): string {
+  return (
+    `nothing was sent to ${platform} person "${recipientId}": this deployment could not read whether they ` +
+    `have asked the agent to stop, and it will not send a direct message it cannot check. Nobody refused you — say ` +
+    `that the check itself failed, and that an operator should look at the store.`
+  );
+}
+
+/**
+ * THE GATE ON THE ROAD: may this deployment start a direct message with this person, on this plane, right now? It reads the recipient's own stop and REFUSES ahead of the send, and it writes the refusal row itself, so every plane files one shape under one action name.
+ * It is exported for the one caller that must ask BEFORE it spends something it cannot give back — `deliverGrantOwnerNotice` claims a once-per-grant notice, and a claim burnt on a delivery that was never allowed is a notice the owner can never receive. {@link deliverProactiveDm} calls it again at the send, which is the control; an early call is an optimisation, never a substitute.
+ */
+export async function assertProactiveDmAllowed(input: {
+  readonly where: DmDeliveryWhere;
+  readonly plane: ProactiveDmPlane;
+  readonly platform: string;
+  readonly recipientId: string;
+  readonly address: string;
+  /** Who the refused message would have been sent FOR. Carried onto the row when the caller can name
+   *  one, left off when it cannot — the same positive-only rule `access/chat-dm-grant.ts` follows. */
+  readonly attributedTo?: string;
+}): Promise<void> {
+  // A plane with no row in the manifest THROWS here rather than sending: an undeclared plane is one
+  // nobody ruled on, and the safe reading of "nobody ruled" is not "send it".
+  proactiveDmPlaneRow(input.plane);
+  const audience = await readDmAudience(input.where.org, input.address);
+  if (audience.readable && !audience.stopped) return;
+  const refusal = audience.readable
+    ? new ProactiveDmRefusedError(
+        input.plane,
+        input.platform,
+        input.recipientId,
+        input.address,
+        "stopped",
+        dmStoppedRefusalMessage(input.platform, input.recipientId),
+      )
+    : new ProactiveDmRefusedError(
+        input.plane,
+        input.platform,
+        input.recipientId,
+        input.address,
+        "unreadable",
+        dmUnreadableRefusalMessage(input.platform, input.recipientId),
+      );
+  await auditProactiveDmRefusal(input.where, refusal, input.attributedTo);
+  throw refusal;
+}
+
+/** The refusal row. NEVER throws — losing it must not turn one refusal into a different error, nor
+ *  unwind before the throw the caller owes. Ids and boundaries only, never message text. */
+async function auditProactiveDmRefusal(where: DmDeliveryWhere, refusal: ProactiveDmRefusedError, attributedTo?: string): Promise<void> {
+  try {
+    // 🔴 `platform` NAMES THE REFUSED PERSON'S SURFACE, so `workspace` and `surface` must not name a
+    // FOREIGN caller's — a Slack room may ask to borrow a Discord owner's credential, and a Discord
+    // row stamped with a Slack workspace is the fabricated queryable column `DmDeliveryWhere` calls
+    // worse than a missing one. Same guard, same reason, as `access/chat-dm-grant.ts`'s own row.
+    const foreignCaller = where.platform !== refusal.platform;
+    await appendAudit({
+      org: where.org,
+      platform: refusal.platform,
+      workspace: foreignCaller ? "unknown" : where.workspace,
+      ...(where.surface === undefined ? {} : { surface: foreignCaller ? "unknown" : where.surface }),
+      ...(attributedTo ? { principalId: attributedTo } : {}),
+      action: DM_REFUSED_ACTION,
+      detail: {
+        target: refusal.recipientId,
+        boundary: refusal.boundary,
+        // WHICH PLANE WAS REFUSED. Without it a reader cannot tell the grant card's refusal from a
+        // `dm_person` one, and "the stop reached every plane" is exactly the claim this row proves.
+        plane: refusal.plane,
+        grant: refusal.address,
+      },
+    });
+  } catch (err) {
+    console.warn(`[open-everywhere:audit] ${DM_REFUSED_ACTION} row was not written: ${String(err)}`);
+  }
+}
+
+/**
+ * SEND one proactive DM, record it, and audit it — the ONE path EVERY plane takes. It exists because the planes must not DRIFT: the carded first delivery, the flowing later ones and the credential-grant cards are different code paths by necessity, but they must obey the SAME stop, append the SAME footer, write the SAME delivery record and file the SAME audit shape.
+ * 🔴 THE STOP IS READ HERE, CLOSEST TO THE SEND, AND IT OUTRANKS THE PLANE (OPE-1855). A caller's own earlier fence is not enough: a person can stop between a card being proposed and a human approving it, and a plane that reads no stop at all is the defect this road closes. A refusal THROWS {@link ProactiveDmRefusedError}; a caller that owes its own answer catches it.
+ * ORDER IS LOAD-BEARING, and each step fails in its own direction. The GATE runs before anything is sent. The SEND throws when it did not land, because the DM IS the work. The RECORD comes after it, since writing it first would flow the NEXT message even if this one never landed, and a lost write only cards once more. The AUDIT is best-effort, because losing the row must not report a delivered message as a failure.
+ */
+export async function deliverProactiveDm(input: {
+  readonly where: DmDeliveryWhere;
+  /** WHICH PLANE asks. Declared in `proactive-dm-manifest.ts`, and named on every audit row. */
+  readonly plane: ProactiveDmPlane;
+  readonly platform: string;
+  /** The RECIPIENT's bare platform member id. */
+  readonly recipientId: string;
+  /** The grant's ARN-like address — the row's "which config line allowed this", and the record key. */
+  readonly address: string;
+  /** The model's message. */
+  readonly text: string;
+  /** The host-authored footer, appended to what the recipient sees. */
+  readonly footer: string;
+  /** Who asked for the message. */
+  readonly requestedBy: string;
+  /** Who the row is attributed to — the APPROVER on the carded path, the ASKER on the flowing one. */
+  readonly attributedTo: string;
+  /** TRUE on the carded first delivery. The fact a reviewer reads to tell the `chat.dm` plane's two paths apart, and meaningless on a plane with no such split — those omit it and the row reads false. */
+  readonly first?: boolean;
+  /** Tappable shortcuts. An arm with no component plane ignores them, so the text still stands alone. */
+  readonly actions?: readonly DirectMessageAction[];
+  readonly tainted?: boolean;
+}): Promise<DirectMessageDelivery> {
+  const plane = proactiveDmPlaneRow(input.plane);
+  await assertProactiveDmAllowed({
+    where: input.where,
+    plane: input.plane,
+    platform: input.platform,
+    recipientId: input.recipientId,
+    address: input.address,
+    attributedTo: input.attributedTo,
+  });
+  const delivery = await dispatchDirectMessage(input.platform, {
+    principalId: input.recipientId,
+    text: `${input.text}${input.footer}`,
+    ...(input.actions === undefined ? {} : { actions: input.actions }),
+  });
+  // ONLY THE PLANE THAT OWNS THE RECORD WRITES IT — see `recordsDelivery`'s own doc. A grant card
+  // that stamped it would spend the chat plane's one approval card on a message nobody proposed
+  // there.
+  if (plane.recordsDelivery) await noteDmAudienceDelivery(input.where.org, input.address, new Date().toISOString());
+  await appendAudit({
+    org: input.where.org,
+    platform: input.where.platform,
+    workspace: input.where.workspace,
+    ...(input.where.surface === undefined ? {} : { surface: input.where.surface }),
+    principalId: input.attributedTo,
+    action: DM_DELIVERY_ACTION,
+    // Ids only, NEVER the body or the footer. An audit log is a record that something happened, not
+    // a copy of what was said.
+    detail: {
+      platform: input.platform,
+      // WHICH PLANE SENT IT. The delivery row and the refusal row name the plane the same way, so a
+      // reader joins "what got through" to "what the stop turned away" on one field.
+      plane: input.plane,
+      recipient: input.recipientId,
+      grant: input.address,
+      surfaceId: delivery.surfaceId,
+      messageId: delivery.messageId,
+      requestedBy: input.requestedBy,
+      first: Boolean(input.first),
+      tainted: Boolean(input.tainted),
+    },
+  }).catch((err: unknown) => console.warn(`[open-everywhere:audit] ${DM_DELIVERY_ACTION} row was not written: ${String(err)}`));
+  return delivery;
+}
+
+/**
+ * The HOST-AUTHORED footer every proactive DM carries. The model authors none of it, the same rule as every other host signal, and it is appended by the delivery path rather than by the card.
+ * It says three things, each load-bearing for a person who did not ask for this message: WHO asked, WHERE the ask came from, and HOW to stop it. A stop the recipient cannot find is not a first-class stop, and this line is where they find it.
+ */
+export function dmDeliveryFooter(input: { readonly requestedBy: string; readonly fromContainer: string }): string {
+  return (
+    `\n\n_Sent by the agent on behalf of ${input.requestedBy}, from ${input.fromContainer}. ` +
+    `Reply here to ask me to stop and I will not start another DM with you._`
+  );
+}

package/agent/channels/dm-seat.ts

@@ -0,0 +1,138 @@
+// dm-seat — a DM is a FIRST-CLASS STANDING WINDOW on its own `oe-dm/<surfaceKey>` pseudo-domain, diverted onto the unified channel like every other standing seat. So a DM can be WOKEN by a worker's completion, a redrive or a self-dispatch hop, and it shares one rotation, spend, park and audit apparatus with every other seat. Every surface's DM and group-DM family mints through this one function.
+// The token is keyed on the SURFACE KEY, never the raw channel id: that is what the two admission gates match byte-for-byte to enforce the privacy fence, so a DM window is deliverable to ITS OWN DM and nowhere else. Defaults are deliberately CONSERVATIVE, because this reaches real prod DMs, and rotation resets only the in-flight context window — DM personal memory is domain- and user-anchored, never token-anchored, so it survives.
+
+import { getOperationalStore } from "../operational/provider.js";
+import type { ChannelSessionRow, OperationalStore } from "../operational/store.js";
+import { shouldRotate, rotationClockMsFromDays, supervisorRotateContextSize, type RotationThresholds } from "./turn-delivery.js";
+import { claimRuntimeRotation, stampMintedRuntime } from "./runtime-rotation.js";
+import { carryTailForward } from "./session-tail-record.js";
+import type { WakeMessageInput } from "./wake-envelope.js";
+import { dmWindowKey, formatWindowToken, saltSupervisorGeneration } from "./window-key.js";
+import { dmWindowRegistryKey } from "./unified-supervisor.js";
+
+/**
+ * EXPIRY — the PRIMARY DM rotation trigger, measured from the row's creation and reset at every rotation, on a LONGER clock than the unified window's.
+ * A channel window watches a room whose norms, owners and open asks turn over weekly, so a month-old generation there is confidently wrong; a DM is one person's own thread, holds far less stale, and its personal memory survives rotation regardless. `OE_DM_SEAT_ROTATE_EXPIRY_DAYS` overrides, `0` disables.
+ */
+export const DM_SEAT_ROTATE_EXPIRY_MS = rotationClockMsFromDays(process.env.OE_DM_SEAT_ROTATE_EXPIRY_DAYS, 30);
+
+/** TURN-budget rotation BACKSTOP for a DM seat (the observed latency creep is turn-count-driven).
+ *  Default 50 — under the ~85-turn workflow event wall the supervisor's 60 is also derived against
+ *  (turn-delivery.ts), and deliberately NOT the same number as the supervisor's. */
+export const DM_SEAT_ROTATE_TURN_BUDGET = Number(process.env.OE_DM_SEAT_ROTATE_TURN_BUDGET) || 50;
+
+/**
+ * INPUT-TOKEN rotation BACKSTOP for a DM seat, accumulated by the spend hook onto the row — a secondary bound under the turn budget above.
+ * Live-calibrated: every step re-counts its full context, so one substantial multi-step wake accumulates a large share of the budget and a blind low default would rotate a seat after every such wake. Kept ABOVE the supervisor's, so a DM — whose turn backstop is already the lower of the two — is not ALSO the first to trip the token one.
+ */
+export const DM_SEAT_ROTATE_TOKEN_BUDGET = Number(process.env.OE_DM_SEAT_ROTATE_TOKEN_BUDGET) || 5_000_000;
+
+/** QUIET-GAP rotation trigger for a DM seat, HOURS. Default 0 = DISABLED — idleness is not evidence
+ *  a DM's context went stale, and the freshness argument is carried by the expiry clock instead (see
+ *  the header). >0 rotates a seat idle that long on its next wake. */
+const DM_SEAT_ROTATE_QUIET_GAP_HOURS = Number(process.env.OE_DM_SEAT_ROTATE_QUIET_GAP_HOURS) || 0;
+
+/**
+ * The {@link shouldRotate} thresholds a DM seat actually passes, so these five numbers are the whole DM rotation policy. Quiet-gap 0h becomes `Number.POSITIVE_INFINITY`, the same spelling the expiry clock uses for "disabled".
+ * `runtimeChanged` is EXCLUDED on purpose: it is a per-wake verdict the caller resolves against the store, not a DM policy number, and a hard-coded value here would either rotate on every wake or never heal. The CONTEXT-SIZE rung takes the deployment-wide setting, because it is a property of the MODEL WINDOW that a DM seat and a channel seat share.
+ */
+export function dmSeatThresholds(): Required<Omit<RotationThresholds, "runtimeChanged">> {
+  const hours = DM_SEAT_ROTATE_QUIET_GAP_HOURS;
+  return {
+    quietGapMs: hours > 0 ? hours * 3_600_000 : Number.POSITIVE_INFINITY,
+    turnBudget: DM_SEAT_ROTATE_TURN_BUDGET,
+    tokenBudget: DM_SEAT_ROTATE_TOKEN_BUDGET,
+    expiryMs: DM_SEAT_ROTATE_EXPIRY_MS,
+    contextSizeTokens: supervisorRotateContextSize(),
+  };
+}
+
+/** A resolved DM seat for a wake: the continuation token eve should key the session on, plus the
+ *  recorded tail to seed a FRESH generation's first wake (empty unless `freshGeneration`). */
+export interface DmSeat {
+  /** The generation-bearing continuation token eve keys the session on — a DEGENERATE WINDOW token
+   *  (`oe-dom:oe-dm/<surfaceKey>:oe-sup:g<gen>[-<salt>]`) since OPE-351 stage 2. */
+  readonly token: string;
+  /** The current generation. */
+  readonly generation: number;
+  /** True on a first mint (adoption) OR a just-rotated generation — its first wake carries the tail. */
+  readonly freshGeneration: boolean;
+  /** The OUTGOING generation's recorded tail, oldest-first, for a fresh generation's first wake.
+   *  Empty on a resume, on a first mint, and on the one-time bootstrap of a generation that predates
+   *  the ring — every one of which falls back to the surface's own capped history fetch. */
+  readonly tail: readonly WakeMessageInput[];
+}
+
+/** Injected deps for {@link getOrCreateDmSeat} — the store, so the
+ *  policy is unit-testable without a live DB / Slack / model. */
+export interface DmSeatDeps {
+  readonly store?: OperationalStore;
+  readonly thresholds?: RotationThresholds;
+  /** The OPE-599 runtime-change claim (channels/runtime-rotation.ts). Injected so a test can drive
+   *  the heal — and its absence — without a live store. Live default: {@link claimRuntimeRotation}. */
+  readonly claimRuntimeRotation?: typeof claimRuntimeRotation;
+  /** The OPE-1821 mint stamp (channels/runtime-rotation.ts). Injected for the same reason the claim
+   *  is: a test drives the mint arm — and asserts the row is stamped — without a live store.
+   *  Live default: {@link stampMintedRuntime}. */
+  readonly stampMintedRuntime?: typeof stampMintedRuntime;
+}
+
+/** WHICH DM this seat belongs to. `surfaceKey` is the identity: the window token and the registry row are both keyed on it, and the admission gates match it byte-for-byte. */
+export interface DmSeatRef {
+  readonly surfaceKey: string;
+  /** The RAW platform channel id for this DM. {@link getOrCreateDmSeat} never reads it — it is here
+   *  for the caller's own history-fetch closure, which is built ONCE per process (it cannot see the
+   *  event) and needs the raw id for the fallback fetch on a seat with no recorded tail. */
+  readonly channelId?: string;
+}
+
+/**
+ * Resolve the DM seat for `(org, surfaceKey)` on a wake: ADOPT when there is no row, ROTATE when the row aged out or the running CODE fingerprint differs from the one the seat was last served with — carrying the OUTGOING generation's recorded tail — otherwise RESUME. (`EVE_RUNTIME_VERSION` is one half of that code fingerprint, so an eve bump moves it; a DM seat has no declared domain, so the domain half is the `no-domain` literal and never moves.) `freshGeneration` re-bases on `firstWakeAt`, so a mint or rotation whose first wake never landed re-carries context and heals an amnesiac generation.
+ * THE GENERATION IS THE STORE'S, never this function's: `rotateChannelSession` computes it atomically inside its own upsert, and the token must agree with the row it is stored in. The rotation SALT makes a re-used integer harmless by construction, which is why every standing seat mints through it.
+ */
+export async function getOrCreateDmSeat(org: string, dm: DmSeatRef, atIso: string, deps: DmSeatDeps = {}): Promise<DmSeat> {
+  const store = deps.store ?? getOperationalStore();
+  const key = dmWindowRegistryKey(dm.surfaceKey);
+  const thresholds = deps.thresholds ?? dmSeatThresholds();
+  // Salted at the mint call site, never inside formatWindowToken — the OPE-58 discipline every
+  // surface's `getOrCreateSession` rotate leg follows via unified-supervisor.ts's mintRotationToken.
+  const mint = (generation: number): string => saltSupervisorGeneration(formatWindowToken(dmWindowKey(dm.surfaceKey, generation)));
+  // BEFORE the row read, and unconditionally: the claim must be consumed on the ADOPT arm too, or the generation this call is about to mint would be rotated away by the very next wake.
+  // An INJECTED store owns the claim too, so a caller can never drive the seat against one store while the heal reads another.
+  const runtimeChanged = await (deps.claimRuntimeRotation ?? claimRuntimeRotation)(
+    { org, registryKey: key, surfaceKey: dm.surfaceKey, atIso },
+    deps.store ? { store: deps.store } : {},
+  );
+  const existing = await store.getChannelSession(org, key);
+  if (!existing) {
+    // ADOPT: a DM this deployment has never seated. No outgoing generation, so no recorded tail —
+    // the caller's first wake falls back to its own capped DM-history fetch.
+    const row = await store.rotateChannelSession(org, key, mint(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. It takes
+    // the INJECTED store for the same reason the claim above does.
+    await (deps.stampMintedRuntime ?? stampMintedRuntime)({ org, registryKey: key, surfaceKey: dm.surfaceKey, atIso }, deps.store ? { store: deps.store } : {});
+    return { token: row.token, generation: row.generation, freshGeneration: true, tail: [] };
+  }
+  if (shouldRotate(existing, atIso, { ...thresholds, runtimeChanged })) {
+    // ROTATE. `carryTailForward` is a store read that fail-softs to an empty tail: a rotation never waits on continuity, and never fails for the want of it.
+    // It takes the INJECTED store, not the process one — a tail read that quietly used a different store would report an empty tail on every injected run while looking correct.
+    const tail = await carryTailForward(org, key, existing.token, store);
+    const row = await store.rotateChannelSession(org, key, mint(existing.generation + 1), atIso);
+    return { token: row.token, generation: row.generation, freshGeneration: true, tail };
+  }
+  // RESUME. The tail is empty even when freshGeneration is true: it was carried forward and cleared
+  // at the rotation that minted this row, so a self-healing re-wake takes the history fallback.
+  return {
+    token: existing.token,
+    generation: existing.generation,
+    freshGeneration: existing.firstWakeAt == null,
+    tail: [],
+  };
+}
+
+/** Record one wake on the DM seat's current generation (lastWakeAt/turnCount; stamps first_wake_at).
+ *  Best-effort — the caller runs it off the wake's critical path. */
+export async function touchDmSeat(org: string, dmSurfaceKey: string, atIso: string, store: OperationalStore = getOperationalStore()): Promise<void> {
+  await store.touchChannelSession(org, dmWindowRegistryKey(dmSurfaceKey), atIso);
+}

package/agent/channels/domain-fingerprint.ts

@@ -0,0 +1,90 @@
+// domain-fingerprint — the PER-SEAT half of the runtime-rotation comparison
+// (channels/runtime-rotation.ts). One standing seat serves one domain, so hashing that domain's
+// declaration gives a value that moves when THAT domain changes and stays put when any other
+// domain does. It is why a config edit rotates the seats it touches and no others.
+//
+// THE HASH IS OVER THE DECLARATION THE SETTINGS MODULE LOADED, not over the file on disk: role
+// defaults and the agents overlay are applied by `loadDomains()`, and a seat is minted from the
+// resolved object, so the resolved object is what the seat must be compared against.
+//
+// The DOMAIN DECLARATION ONLY. Org-wide behaviour — `agent/settings/settings.ts`, the access
+// bundles and their machine-written overlays, the model policy — is covered by the CODE fingerprint
+// instead, which hashes those files with the per-domain declarations excluded. The split is what
+// makes a config edit surgical: this half moves for one domain, that half moves for everything else.
+// Neither half covers a dependency bump (`package.json` / `package-lock.json` are not hashed) or a
+// change under `docs/`. The code half DOES cover `patches/`, which rewrites the runtime bytes.
+
+import { createHash } from "node:crypto";
+import { getConfig } from "../access/config.js";
+import { domainForChannel, type Domain } from "../memory/domain.js";
+
+/** The fingerprint of a surface that belongs to NO domain — an undeclared channel, whose seat is minted from no declaration at all. A literal rather than a hash of `undefined`, so the stored value reads plainly in a row dump. */
+export const NO_DOMAIN_FINGERPRINT = "no-domain";
+
+/**
+ * Canonical JSON: object keys SORTED, so a declaration that only reordered its fields hashes the
+ * same and rotates nobody. Array order is PRESERVED, because order is meaningful in a declaration
+ * (`statusVerbs` extends in order, `windows` is matched most-specific-first).
+ * `undefined` members are dropped, which is what makes an explicitly-absent optional field
+ * indistinguishable from an omitted one — they mean the same thing to every reader of a Domain.
+ * 🔴 THROWS on a function or a symbol. A Domain is plain data today; a field that stopped being
+ * plain data would be silently invisible to the hash, so the seam refuses it rather than hashing
+ * around it. {@link domainFingerprintForSeat} turns the throw into "do not rotate".
+ */
+export function canonicalJson(value: unknown): string {
+  if (value === null) return "null";
+  const kind = typeof value;
+  if (kind === "function" || kind === "symbol" || kind === "bigint") {
+    throw new Error(`domain declaration holds a ${kind}, which no stable hash can cover`);
+  }
+  if (kind === "string" || kind === "number" || kind === "boolean") return JSON.stringify(value);
+  if (kind === "undefined") return "null";
+  if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, member]) => member !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries.map(([key, member]) => `${JSON.stringify(key)}:${canonicalJson(member)}`).join(",")}}`;
+}
+
+/**
+ * The stable 16-hex-character hash of ONE domain declaration, or {@link NO_DOMAIN_FINGERPRINT} when
+ * the surface belongs to no domain. Pure and total over the object, so a test can move one field
+ * and assert the fingerprint moved with it.
+ */
+export function domainFingerprint(domain: Domain | undefined): string {
+  if (!domain) return NO_DOMAIN_FINGERPRINT;
+  return createHash("sha256").update(canonicalJson(domain)).digest("hex").slice(0, 16);
+}
+
+/**
+ * The fingerprint of the domain THIS SEAT is grained by, resolved against the LIVE registered config.
+ *
+ * 🔴 `domainName` IS THE SEAT'S OWN GRAIN, AND IT IS NOT OPTIONAL DECORATION. A window seat serves
+ * MANY surfaces — a Discord thread and its parent channel share one registry row, and so does every
+ * channel of a cross-surface domain. Resolving the domain from the woken `surfaceKey` instead would
+ * hand one row two different fingerprints, and the two wakes would then rotate each other's
+ * generation away on every message, for ever. `SupervisorGrain.domainName` is present exactly when
+ * the registry key is the synthetic domain key, so passing it is what makes the value a property of
+ * the SEAT rather than of the wake. When it is absent the registry key IS the surface key, and
+ * resolving from the surface is then the same thing.
+ *
+ * UNDEFINED means "this process cannot resolve the seat's declaration" — an unregistered config in a
+ * unit process, a declaration the hash refuses, or a `domainName` no declaration carries. The caller
+ * must then rotate NOTHING: an unresolvable declaration proves no change, and treating it as a
+ * change would retire a healthy generation every wake until the config came back. That is the same
+ * fail-soft direction the store read takes.
+ */
+export function domainFingerprintForSeat(domainName: string | undefined, surfaceKey: string): string | undefined {
+  try {
+    const domains = getConfig().loadDomains();
+    if (domainName === undefined) return domainFingerprint(domainForChannel(surfaceKey, domains));
+    const named = domains.find((d) => d.name === domainName);
+    // A grain naming a domain the config does not carry is a config inconsistency, never evidence
+    // that the code changed. Fail soft rather than rotate the seat on every wake until it is fixed.
+    if (!named) throw new Error(`the seat is grained by domain "${domainName}", which the loaded config does not declare`);
+    return domainFingerprint(named);
+  } catch (err) {
+    console.warn(`[open-everywhere:runtime-rotation] domain fingerprint unavailable for ${domainName ?? surfaceKey}: ${String(err)} — resuming the current generation`);
+    return undefined;
+  }
+}

package/agent/channels/egress-spoof.ts

@@ -0,0 +1,35 @@
+// egress-spoof — the one exit every outbound room post passes through under `OE_EGRESS_SPOOF`, the local-eval flag that must swallow a vendor call before the transport. THE GATE SITS IN TWO LAYERS: the SPINES, where every post that owes its caller a usable answer gates itself and hands back a synthetic id or a `true`, so the caller's own bookkeeping reads as it would on a live surface; and the SLACK BRIDGE (channels/slack-bridge.ts), through which every OTHER core feature posts to Slack, and which gates its room-WRITE methods by allowlist and answers Slack's own success shape.
+// A new post site calls `swallowRoomPost` or `swallowRoomOp` BEFORE it resolves a transport or looks up a provider registry; there is no process-wide network interception, so a bundle that posts through neither seam is outside the flag.
+// 🔴 OPERATOR CAVEAT: `onVercel()` is the ONE refusal this module enforces, so keeping `OE_EGRESS_SPOOF=1` out of a self-host or `OE_PLATFORM`-labelled deploy is an operator responsibility. With the flag set on a non-Vercel deploy, every reply, card, notice and reaction that reaches one of the two layers above is swallowed behind a `console.warn` — a post hands back a synthetic id, an edit or reaction a bare `true` — and the audit rows read as normal.
+
+import { onVercel } from "../access/platform.js";
+
+/**
+ * True when the local-eval spoof is armed; THROWS on Vercel, where the flag is a deploy misconfiguration rather than a transport failure.
+ * Read at call time and never cached: the integration tier arms and disarms the flag around individual legs.
+ */
+function egressSpoofArmed(): boolean {
+  if (process.env.OE_EGRESS_SPOOF !== "1") return false;
+  if (onVercel()) throw new Error("OE_EGRESS_SPOOF is a local-eval flag — refusing on Vercel.");
+  return true;
+}
+
+/**
+ * Swallow one outbound room post and hand back a SYNTHETIC message id, or undefined when the spoof is not armed and the caller must reach the real transport.
+ * `what` and `idTag` are contract, not decoration: eval harnesses score off the log line and integration tests match the `spoof-<idTag>-…` id shape.
+ */
+export function swallowRoomPost(what: string, idTag: string): string | undefined {
+  if (!egressSpoofArmed()) return undefined;
+  console.warn(`[oe] OE_EGRESS_SPOOF: swallowed ${what}`);
+  return `spoof-${idTag}-${Date.now()}`;
+}
+
+/**
+ * Swallow one outbound room op that owes no message id — an edit, a reaction, a void notice. True when it was swallowed and the caller must not reach a transport.
+ * A swallowed op reports SUCCESS, so the caller's own bookkeeping reads exactly as it would on a live surface.
+ */
+export function swallowRoomOp(what: string): boolean {
+  if (!egressSpoofArmed()) return false;
+  console.warn(`[oe] OE_EGRESS_SPOOF: swallowed ${what}`);
+  return true;
+}