@open-everywhere/core 0.1.0

package/agent/channels/window-key.ts

@@ -0,0 +1,439 @@
+// window-key — the identity of a standing cross-surface session, decoupled from the domain: `(domain, windowId, generation)`, carried entirely in the raw continuation token this module parses and formats. The `windowId` discriminator is what lets a domain host MORE THAN ONE window without a new eve channel, a new store table or a memory re-anchor, and the domain stays IN the token so memory, access and audit anchoring is token-derivable with no async lookup.
+// BACKWARD COMPATIBILITY IS THE LOAD-BEARING INVARIANT: a token WITHOUT a `:win:` segment parses as `windowId === domain`, and that degenerate form is byte-identical to the pre-window token, so every live session token keeps resolving unchanged. The optional trailing `-<sha>` is a rotation SALT, and every regex still captures the digits alone, so each existing numeric-generation consumer reads the SAME integer whether or not a salt is present. The domain capture is greedy, because a domain may contain colons, so the explicit form is tried FIRST — a greedy degenerate match would otherwise swallow `<domain>:win:<id>` into the domain group. The one unsupported edge is a domain name that literally contains the segment `:win:<something>:`, which misparses under the explicit form; domain names are config-controlled slugs, so that is a documented constraint rather than a live risk.
+
+import { randomBytes } from "node:crypto";
+
+/** The identity of a standing window session, recovered from / minted into a continuation token. */
+export interface WindowKey {
+  /** The memory/access/trust anchor — always parseable from the token (§W-memory: memory is
+   *  DOMAIN-anchored, never window-anchored, so the domain must survive the key change). */
+  readonly domain: string;
+  /** The window discriminator. Defaults to `domain` (the degenerate id-equals-domain form) — a
+   *  domain hosts multiple windows only when this differs from `domain`. */
+  readonly windowId: string;
+  /** The rotation generation (eve opens a fresh session per never-before-seen token). */
+  readonly generation: number;
+}
+
+/**
+ * Explicit-window token. Tried FIRST, because a greedy degenerate match would swallow the `:win:<id>` segment into the domain group.
+ * The domain is greedy so a colon-bearing domain still parses, and the windowId is colon-free. The optional trailing salt is non-capturing, so the generation group still captures ONLY the number.
+ */
+const EXPLICIT_WINDOW_TOKEN_RE = /^oe-dom:(.+):win:([^:]+):oe-sup:g(\d+)(?:-[0-9a-f]+)?$/;
+
+/**
+ * DEGENERATE (id-equals-domain) token, where `windowId === domain`. This form is LIVE, not historical — {@link formatWindowToken} MINTS it for every degenerate key, which is every standing domain seat today.
+ * The greedy domain backtracks to the LAST `:oe-sup:g`, and the optional salt tail is additive and never required.
+ */
+const DEGENERATE_WINDOW_TOKEN_RE = /^oe-dom:(.+):oe-sup:g(\d+)(?:-[0-9a-f]+)?$/;
+
+/**
+ * Serialize a window key to its continuation token: a degenerate key emits the degenerate shape, so today's tokens are reproduced byte for byte, and a distinct windowId emits the explicit `:win:` form. This is the ONE place a window token is minted, and every surface's mint funnels here.
+ * DELIBERATELY UNSALTED: it stays a PURE function of `key`, so it is goldenable and round-trippable. The salt is applied by the CALLER, once, at the actual mint-for-rotation call site — never inside this formatter.
+ */
+export function formatWindowToken(key: WindowKey): string {
+  if (key.windowId === key.domain) {
+    // Degenerate (id-equals-domain) form. A colon-bearing DOMAIN is legal here (the greedy-domain
+    // parse recovers it) and is existing, tested behaviour — do NOT guard this branch.
+    return `oe-dom:${key.domain}:oe-sup:g${key.generation}`;
+  }
+  // Explicit `:win:<windowId>:` form: the windowId is `[^:]+` in EXPLICIT_WINDOW_TOKEN_RE, so a
+  // colon-bearing windowId would misparse. Reject it at the mint (mirrors taskWindowId/threadSeatWindowId).
+  if (key.windowId.includes(":")) {
+    throw new Error(
+      `formatWindowToken: a windowId is colon-free ([^:]+) — got windowId="${key.windowId}" (domain="${key.domain}"); sanitise colons before minting the explicit :win: form`,
+    );
+  }
+  return `oe-dom:${key.domain}:win:${key.windowId}:oe-sup:g${key.generation}`;
+}
+
+/**
+ * Parse a continuation token into a {@link WindowKey}, or `undefined` when it is not a window token — a per-container token, a thread token or a non-string all fail-soft.
+ * A degenerate token, with no `:win:` segment, resolves to `windowId === domain`, the invariant every consumer relies on. The explicit form is matched first.
+ */
+export function parseWindowToken(token: unknown): WindowKey | undefined {
+  if (typeof token !== "string") return undefined;
+  const explicit = EXPLICIT_WINDOW_TOKEN_RE.exec(token);
+  if (explicit) return { domain: explicit[1], windowId: explicit[2], generation: Number(explicit[3]) };
+  const degenerate = DEGENERATE_WINDOW_TOKEN_RE.exec(token);
+  if (degenerate) return { domain: degenerate[1], windowId: degenerate[1], generation: Number(degenerate[2]) };
+  return undefined;
+}
+
+/** Is this a window (domain-keyed supervisor) token? Fail-soft on any odd shape. */
+export function isWindowToken(token: unknown): token is string {
+  return parseWindowToken(token) !== undefined;
+}
+
+/** The DEGENERATE window key for a domain — `windowId === domain`, the id-equals-domain default that
+ *  STEP 1 mints exclusively. The seam a later step swaps for a distinct windowId. */
+export function windowKeyForDomain(domain: string, generation: number): WindowKey {
+  return { domain, windowId: domain, generation };
+}
+
+// TASK (thread-grain) windows: an async spawn mints a fresh window at THREAD grain, a session that owns ONE thread, distinct from a standing seat's domain or solo window. It is the SAME window primitive with a reserved `t/<channelKey>/<threadTs>` windowId, slash-separated so the whole id stays colon-free.
+// The `t/` prefix is the grain MARKER: any other windowId classifies standing. Identity is the token — the id is a pure function of its inputs, so a later message in the same thread re-derives the SAME token and resumes the SAME session, needing no identity store.
+
+/** Marks a TASK (thread-grain) windowId — the grain the spawn-ownership routing (and the later
+ *  toolset gate) keys on. A task windowId begins `t/`; a domain/solo-channel windowId never does. */
+const TASK_WINDOW_ID_RE = /^t\//;
+
+/**
+ * Mint a TASK window's `windowId` from the thread it owns. The 2-arg form is DETERMINISTIC per thread, so a later message in that thread resumes the same session; the 3-arg form is UNIQUE per call, for the one-shot delegation model, so two calls never collide and the task owns nothing.
+ * It THROWS on an empty component, or a colon in any component: a windowId is colon-free, so the caller must sanitise first. The `/` separators are legal inside that class, so the composite parses as one windowId and the grain marker survives the extra segment.
+ */
+export function taskWindowId(channelKey: string, threadTs: string, nonce?: string): string {
+  if (channelKey.length === 0 || threadTs.length === 0) {
+    throw new Error("taskWindowId: channelKey and threadTs must both be non-empty");
+  }
+  const parts = [channelKey, threadTs, ...(nonce !== undefined ? [nonce] : [])];
+  for (const p of parts) {
+    if (p.length === 0) throw new Error("taskWindowId: nonce must be non-empty when supplied");
+    if (p.includes(":")) {
+      throw new Error(
+        `taskWindowId: a windowId is colon-free ([^:]+) — got a colon-bearing component in ["${channelKey}","${threadTs}"${nonce !== undefined ? `,"${nonce}"` : ""}] (sanitise colons before minting)`,
+      );
+    }
+  }
+  return `t/${parts.join("/")}`;
+}
+
+/**
+ * The session-approval MEMO key for a continuation token: a TASK-grain window token collapses to its PARENT domain window token, so an "approve for session" grant survives across wakes of the SAME conversation window; any other token keys as itself.
+ * String surgery rather than a parse-and-reformat round trip, so the generation — INCLUDING its rotation salt — is preserved verbatim and a rotation still drops every grant held under the old token.
+ */
+export function sessionGrantKeyFromToken(token: string): string {
+  const m = /^(oe-dom:[^:]+):win:t\/[^:]+(:oe-sup:g[^:]*)$/.exec(token);
+  return m ? `${m[1]}${m[2]}` : token;
+}
+
+/** Is this `windowId` a TASK (thread-grain) window id, as opposed to a domain / solo-channel one? */
+export function isTaskWindowId(windowId: string): boolean {
+  return TASK_WINDOW_ID_RE.test(windowId);
+}
+
+/** Is this continuation token a TASK window token — a window token whose `windowId` is task-grain?
+ *  Fail-soft on any non-window / odd shape (parse yields undefined ⇒ false). The grain classifier
+ *  the spawn recursion-guard + ownership routing read; a standing/degenerate token classifies false. */
+export function isTaskWindowToken(token: unknown): boolean {
+  const key = parseWindowToken(token);
+  return key !== undefined && isTaskWindowId(key.windowId);
+}
+
+// THREAD-SEAT windows: a spawned thread session mints a long-lived CONVERSATIONAL seat that owns ONE thread — a persistent presence with NARROW hands, distinct from a task worker's full-hands leaf. Same window primitive, reserved `s/<channelKey>/<threadTs>` windowId.
+// The `s/` marker is DISTINCT from task's `t/` for a FAIL-CLOSED reason: if the host grain stamp is ever lost, the classifier falls back to the token SHAPE, and `s/` classifies thread — narrow — never task, which is wide. Reusing `t/` would fail OPEN to wide hands on a dropped stamp.
+
+/** Marks a THREAD-SEAT (conversational thread-grain) windowId — begins `s/`; a task windowId (`t/`),
+ *  a domain/solo-channel windowId never does. The fail-closed grain marker (see the block above). */
+const THREAD_SEAT_WINDOW_ID_RE = /^s\//;
+
+/**
+ * Mint a THREAD-SEAT window's `windowId` from the thread it owns. Pure and deterministic: the same inputs give the same id and so the same seat.
+ * Same colon-free constraint as {@link taskWindowId}: it THROWS on an empty or colon-bearing component.
+ */
+export function threadSeatWindowId(channelKey: string, threadTs: string): string {
+  if (channelKey.length === 0 || threadTs.length === 0) {
+    throw new Error("threadSeatWindowId: channelKey and threadTs must both be non-empty");
+  }
+  if (channelKey.includes(":") || threadTs.includes(":")) {
+    throw new Error(
+      `threadSeatWindowId: a windowId is colon-free ([^:]+) — got channelKey="${channelKey}", threadTs="${threadTs}" (sanitise colons before minting)`,
+    );
+  }
+  return `s/${channelKey}/${threadTs}`;
+}
+
+/** Is this `windowId` a THREAD-SEAT (conversational thread-grain) window id? */
+export function isThreadSeatWindowId(windowId: string): boolean {
+  return THREAD_SEAT_WINDOW_ID_RE.test(windowId);
+}
+
+/** Is this continuation token a THREAD-SEAT window token — a window token whose `windowId` is
+ *  thread-seat-grain? Fail-soft on any non-window / odd shape. The fail-closed backstop the grain
+ *  classifier reads when the host `oe_grain:"thread"` stamp is absent. */
+export function isThreadSeatWindowToken(token: unknown): boolean {
+  const key = parseWindowToken(token);
+  return key !== undefined && isThreadSeatWindowId(key.windowId);
+}
+
+// DM-SEAT windows: eve keys a native DM session by a token with NO generation, so a long-lived DM is one ever-growing session whose reply latency creeps as the backscroll grows. A DM seat token carries a rotatable generation in the SAME registry the channel supervisor uses, so a generation bump means a fresh session with the outgoing generation's recorded tail.
+// The `:oe-dm:g` infix is DISTINCT from the supervisor's, so it is INERT to every supervisor detector: model routing keeps a DM on the primary model, the supervisor spend counter skips it, and the reply path stays eve-native. Its codec grain is `native`, because a DM seat has exactly the hands a plain native DM has.
+
+/** DM-seat token: `<dmChannelId>:oe-dm:g<gen>`. Greedy channel part (colon-tolerant), numeric gen. */
+const DM_SEAT_TOKEN_RE = /^(.+):oe-dm:g(\d+)$/;
+
+/** Mint a DM seat's continuation token for a channel at a generation. THROWS on an empty channelId
+ *  (a token must address a real DM channel). The `:oe-dm:g` infix keeps it INERT to `:oe-sup:g`. */
+export function formatDmSeatToken(dmChannelId: string, generation: number): string {
+  if (dmChannelId.length === 0) throw new Error("formatDmSeatToken: dmChannelId must be non-empty");
+  return `${dmChannelId}:oe-dm:g${generation}`;
+}
+
+/** Parse a DM-seat token into `{ channelId, generation }`, or undefined if it isn't one. Strips eve's
+ *  `unified:` send-prefix first (defensive; a DM seat is never window-namespaced in practice). */
+export function parseDmSeatToken(token: unknown): { channelId: string; generation: number } | undefined {
+  if (typeof token !== "string") return undefined;
+  const raw = token.startsWith("unified:") ? token.slice("unified:".length) : token;
+  const m = DM_SEAT_TOKEN_RE.exec(raw);
+  return m ? { channelId: m[1], generation: Number(m[2]) } : undefined;
+}
+
+/** Is this continuation token a DM-seat token? Fail-soft on any odd shape. */
+export function isDmSeatToken(token: unknown): token is string {
+  return parseDmSeatToken(token) !== undefined;
+}
+
+/** The synthetic channel_session registry surfaceKey for a DM seat: `oe-dm-seat::<dmChannelId>`.
+ *  Slack channel ids never contain `::`, and a real surface key is `platform/workspace/surface`, so
+ *  this can never collide with a per-container or window row. Token-recoverable: the spend hook derives
+ *  it from the DM-seat token's channelId, the front route from the inbound DM event — one stable key. */
+export function dmSeatRegistryKey(dmChannelId: string): string {
+  return `oe-dm-seat::${dmChannelId}`;
+}
+
+// THE DM DELEGATION ANCHOR. Delegation mints a worker into the CALLER's `(domain, generation)`, read off a WINDOW token — and a DM root has none, so the spawn wall refused and a DM seat could talk and nothing else. The ruling is that a triggered worker always carries the same domain as its parent seat: the DM's OWN `platform/workspace/surface` key, verbatim, as a reserved PSEUDO-DOMAIN inside the existing free-form domain field.
+// That is not a grammar change but the same reserved-namespace move the grain markers already made, and it is safe for the same two reasons: a real config domain may not start with the prefix, enforced fail-loud at config load, so a pseudo-domain can never be confused for or shadowed by a real one; and every consumer that maps a domain to CONFIG goes through one seam that recognises it, so an unrecognised consumer sees a name matching no config row and fails CLOSED.
+
+/** The RESERVED domain-name namespace for a DM delegation anchor. A real config domain may not start
+ *  with it (fail-loud at config load) — that exclusivity is what lets a pseudo-domain share the
+ *  `<domain>` field with real names. Slash-separated on purpose: a surface key already is. */
+export const DM_ANCHOR_DOMAIN_PREFIX = "oe-dm/";
+
+/** The generation every DM-anchor token carries. CONSTANT `0` — a DM anchor never rotates, and 0 is
+ *  unreachable by `rotateChannelSession` (which mints ≥ 1), so it can never collide. See the section
+ *  header for the full rotation story. */
+export const DM_ANCHOR_GENERATION = 0;
+
+/**
+ * The pseudo-domain for a DM or group-DM surface key.
+ * It THROWS on an empty key, or one containing a colon: the domain segment sits before `:win:` in the explicit token form, so a colon-bearing domain would misparse. Partition keys are sanitised, so this never fires in practice — it is the mint-side assertion that keeps that true.
+ */
+export function dmAnchorDomain(dmSurfaceKey: string): string {
+  if (dmSurfaceKey.length === 0) throw new Error("dmAnchorDomain: dmSurfaceKey must be non-empty");
+  if (dmSurfaceKey.includes(":")) {
+    throw new Error(`dmAnchorDomain: a DM anchor's surface key must be colon-free (it becomes the token's <domain> segment) — got "${dmSurfaceKey}"`);
+  }
+  return `${DM_ANCHOR_DOMAIN_PREFIX}${dmSurfaceKey}`;
+}
+
+/** Is this token `<domain>` segment a DM delegation anchor rather than a real config domain? */
+export function isDmAnchorDomain(domain: unknown): domain is string {
+  return typeof domain === "string" && domain.startsWith(DM_ANCHOR_DOMAIN_PREFIX) && domain.length > DM_ANCHOR_DOMAIN_PREFIX.length;
+}
+
+/** The DM surface key a pseudo-domain was derived from, or undefined when it is a real domain name.
+ *  The inverse of {@link dmAnchorDomain} — the seam every config hop uses to recover the ONE surface
+ *  a DM-anchored worker may be dispatched to. */
+export function dmSurfaceKeyFromAnchorDomain(domain: unknown): string | undefined {
+  return isDmAnchorDomain(domain) ? domain.slice(DM_ANCHOR_DOMAIN_PREFIX.length) : undefined;
+}
+
+/**
+ * The DEGENERATE window key for a DM ANCHOR, at the constant generation — what a DM root hands the spawn primitive in place of the window key it does not have.
+ * The spawn replaces `windowId` with a task windowId, so the `(domain, generation)` pair is the whole contribution, which is exactly what delegation needs from a caller.
+ */
+export function dmAnchorWindowKey(dmSurfaceKey: string): WindowKey {
+  const domain = dmAnchorDomain(dmSurfaceKey);
+  return { domain, windowId: domain, generation: DM_ANCHOR_GENERATION };
+}
+
+/** Is this continuation token a DM-ANCHORED task window token — a worker minted off a DM root?
+ *  Fail-soft on any odd shape. The TASK-grain half of the anchor family; the admission gates read the
+ *  grain-agnostic {@link dmAnchorSurfaceForToken} instead, so this stays the narrow grain predicate. */
+export function isDmAnchoredTaskToken(token: unknown): boolean {
+  const key = parseWindowToken(stripUnifiedPrefix(token));
+  return key !== undefined && isTaskWindowId(key.windowId) && isDmAnchorDomain(key.domain);
+}
+
+// THE DM SEAT AS A FIRST-CLASS WINDOW. The seat becomes a DEGENERATE window on the same `oe-dm/` pseudo-domain its workers already use, so a DM gets the whole standing-window apparatus — a rotatable generation, a registry row, the unified channel's wake and redrive path — with no new session KIND and no grammar change. It is an ordinary window token whose domain happens to sit in the reserved namespace.
+// Unlike the anchor's constant generation, a DM WINDOW rotates like any other standing seat, from the registry row. That is the whole point, and it is exactly why the anchor's constant is justified on the rotation ARITHMETIC rather than on "a DM has no row".
+
+/**
+ * The DEGENERATE window key for a DM SEAT at a generation — the same pseudo-domain the worker anchor uses, so a DM's seat and its workers share ONE memory, access and audit anchor. It THROWS on an empty or colon-bearing surface key.
+ * NOT the anchor key: that one pins the unreachable constant generation and addresses no session, where this addresses the seat's REAL rotatable session.
+ */
+export function dmWindowKey(dmSurfaceKey: string, generation: number): WindowKey {
+  const domain = dmAnchorDomain(dmSurfaceKey);
+  return { domain, windowId: domain, generation };
+}
+
+/**
+ * Is this token a DM WINDOW token — a STANDING window on a DM pseudo-domain? True only when it parses as a window token, its domain is a DM anchor, AND its windowId is standing-grain, neither task nor thread-seat.
+ * The grain exclusion is what keeps it DISJOINT from the DM-anchored TASK predicate: a DM's worker must never be mistaken for its seat, in either direction.
+ */
+export function isDmAnchorWindowToken(token: unknown): boolean {
+  const key = parseWindowToken(stripUnifiedPrefix(token));
+  return key !== undefined && isDmAnchorDomain(key.domain) && !isTaskWindowId(key.windowId) && !isThreadSeatWindowId(key.windowId);
+}
+
+/**
+ * The DM surface a window token is anchored to, or `undefined` when it is not on a DM pseudo-domain. GRAIN-AGNOSTIC on purpose: a DM seat window, a DM-anchored worker and any future DM-anchored thread seat all answer with the SAME surface key.
+ * THIS IS THE ONE ADMISSION SEAM. Both dispatch gates admit a DM-anchored delivery by SELF-CONSISTENCY — the surface delivered to must equal this, byte for byte — rather than by a config read, because a DM surface is in no configured domain by definition. Those gates once carried hand-rolled copies of the derivation and diverged, so they now share this function.
+ */
+export function dmAnchorSurfaceForToken(token: unknown): string | undefined {
+  const key = parseWindowToken(stripUnifiedPrefix(token));
+  return key ? dmSurfaceKeyFromAnchorDomain(key.domain) : undefined;
+}
+
+// DECLARED-SUBAGENT sessions: eve mints that session's continuation token and OE never does. This shape is READ-ONLY — recognising it adds no field to any OE-minted string, and there is deliberately NO formatter here, because minting one would be forging eve's identity.
+// The grain is deliberately `native`, NOT `task`: task is a WIDE-HANDS grain, so promoting a delegated child to it would widen what its tool gate grants. Keeping the grain the codec already returned is the fail-closed choice, and the supervisor-shape allowlist excludes the arm automatically, so model routing, the spend counter and the rotation machinery all stay inert to a subagent token.
+
+/** eve's delegated-child token: `subagent:<parentSessionId>:<callId>`. Greedy parent part (a session
+ *  id is colon-free today, but stay robust), colon-free callId — so the split is at the LAST colon. */
+const SUBAGENT_TOKEN_RE = /^subagent:(.+):([^:]+)$/;
+
+/** Parse eve's delegated-subagent token into `{ parentSessionId, callId }`, or undefined if it isn't
+ *  one. Strips eve's `unified:` send-prefix first (defensive — a child session is never window-
+ *  namespaced in practice). READ-ONLY: there is deliberately no formatter, eve owns this mint. */
+export function parseSubagentToken(token: unknown): { parentSessionId: string; callId: string } | undefined {
+  if (typeof token !== "string") return undefined;
+  const raw = token.startsWith(UNIFIED_SEND_PREFIX) ? token.slice(UNIFIED_SEND_PREFIX.length) : token;
+  const m = SUBAGENT_TOKEN_RE.exec(raw);
+  return m ? { parentSessionId: m[1], callId: m[2] } : undefined;
+}
+
+/** Is this continuation token an eve delegated-subagent session token? Fail-soft on any odd shape. */
+export function isSubagentSessionToken(token: unknown): token is string {
+  return parseSubagentToken(token) !== undefined;
+}
+
+// THE SESSION-ID CODEC — the ONE typed classifier the scattered per-consumer regexes converge on. It resolves the ordering hazards once: eve's send prefix is stripped here, explicit-before-degenerate and the grain-marker-before-standing precedence live here, and every per-consumer copy dies. PURE, TOTAL and FAIL-SOFT: any non-string, blank or unrecognised input classifies `native`, and only where that is already the documented posture of the classifier it replaces.
+// GRAMMAR FROZEN: the continuation-token wire format is feature-complete, and NO new field is ever added to the string. New per-session metadata rides where it already rides — a per-delivery host-stamped auth attribute, or a durable fact in the operational registry row. The only change that ever touches this grammar is a genuinely-NEW session KIND, and it lands as ONE new union arm plus ONE new case, after which the exhaustiveness checker propagates it to every consumer.
+
+/**
+ * The standing/supervisor suffix — the ONE marker shared by BOTH window tokens and the per-container supervisor tokens. Anchored at the tail, with an alternative that lets a bare form with no leading colon match too.
+ * The optional salt tail is additive, and the generation group still captures ONLY the number. This is byte-identical, modulo that widening, to the anchored detectors that now route here.
+ */
+const SUPERVISOR_SUFFIX_RE = /(?:^|:)oe-sup:g(\d+)(?:-[0-9a-f]+)?$/;
+
+/** eve namespaces a window-channel send as `unified:<raw>`; consumers strip it before classifying. */
+const UNIFIED_SEND_PREFIX = "unified:";
+
+/** Strip eve's `unified:` send-prefix once, fail-soft — a non-string passes through untouched (every
+ *  caller feeds the result to a parse that fail-softs on it). Hoisted `function` on purpose: the DM
+ *  anchor predicates above sit earlier in the file than the const, and only read it at CALL time. */
+function stripUnifiedPrefix(token: unknown): unknown {
+  return typeof token === "string" && token.startsWith(UNIFIED_SEND_PREFIX) ? token.slice(UNIFIED_SEND_PREFIX.length) : token;
+}
+
+// THE ROTATION SALT. The monotonic integer generation is minted as "current plus one" with one row per surface and no history, so if the registry row is ever cleared the counter falls back to its first value — and eve resumes a session by EXACT token match, so a reused bare generation risks resuming a STALE snapshot under what should be a brand-new conversation.
+// The fix is to mint a UNIQUE token on every rotation by appending a short random hex salt, so even a counter that resets twice mints two DIFFERENT tokens. It is additive: every consumer keeps reading bare tokens unchanged, and only FRESH mints carry the salt.
+
+/** Short random hex suffix minted fresh on every rotation (OPE-58) — 6 hex chars (~16.7M values,
+ *  collision-negligible for a per-rotation salt; this is a uniqueness aid, not a security boundary,
+ *  so `Math.random`-backed `randomBytes` is plenty). */
+export function mintGenerationSalt(): string {
+  return randomBytes(3).toString("hex");
+}
+
+/**
+ * Append a fresh rotation salt to a JUST-MINTED supervisor-suffixed token. Every shape this module mints ends in exactly that suffix, so a plain string append at the tail is correct whichever shape the token is.
+ * Call it ONCE, at the actual rotation-mint call site — never on an already-salted or store-round-tripped token, which would double-append a fresh, unrelated salt.
+ */
+export function saltSupervisorGeneration(token: string): string {
+  return `${token}-${mintGenerationSalt()}`;
+}
+
+/**
+ * The typed classification of a continuation token — the discriminated union that replaces the scattered regex verdicts.
+ * `grain` mirrors the window grain the tool gate keys on, so reading it off this classification is a drop-in for the old per-consumer classifier.
+ */
+export type SessionId =
+  | { kind: "window"; grain: "standing"; key: WindowKey } // domain / solo window
+  | { kind: "task"; grain: "task"; key: WindowKey; nonce?: string } // one-shot / async worker leaf
+  | { kind: "thread-seat"; grain: "thread"; key: WindowKey } // persistent conversational seat
+  | { kind: "container-supervisor"; grain: "standing"; containerKey: string; generation: number }
+  | { kind: "dm-seat"; grain: "native"; channelId: string; generation: number } // per-user Slack DM seat (OPE-90)
+  | { kind: "subagent"; grain: "native"; parentSessionId: string; callId: string } // eve-minted declared-subagent child (OPE-45)
+  | { kind: "native"; grain: "native" }; // cse_… / blank / unknown / absent
+
+/**
+ * Classify a continuation token into a {@link SessionId}. PURE, TOTAL and FAIL-SOFT — it never throws, and any non-string, blank or unrecognised token classifies `native`. It is the single ORDERING AUTHORITY: strip the send prefix, then the window parse (explicit before degenerate) whose grain comes from the windowId prefix, then the anchored supervisor suffix as a per-container supervisor, then eve's own subagent shape — LAST on purpose, so every arm above keeps its exact prior truth table — and finally native.
+ * The optional `nonce` is left `undefined` rather than populated with a knowingly-wrong segment: a task windowId's channelKey is itself slash-bearing, so a nonce is not structurally recoverable by segment position, and the mint inputs are its only reliable carrier.
+ */
+export function classifySessionId(token: unknown): SessionId {
+  if (typeof token !== "string") return { kind: "native", grain: "native" };
+  const raw = token.startsWith(UNIFIED_SEND_PREFIX) ? token.slice(UNIFIED_SEND_PREFIX.length) : token;
+  const key = parseWindowToken(raw);
+  if (key) {
+    if (isTaskWindowId(key.windowId)) return { kind: "task", grain: "task", key };
+    if (isThreadSeatWindowId(key.windowId)) return { kind: "thread-seat", grain: "thread", key };
+    return { kind: "window", grain: "standing", key };
+  }
+  // DM seat (OPE-90): `<dmChannelId>:oe-dm:g<gen>`. Checked BEFORE the `:oe-sup:g` suffix — the two
+  // infixes are mutually exclusive, so order is only for clarity. grain "native": a DM seat has the
+  // SAME hands/model/label posture as a plain native DM token (the generation is the only difference,
+  // and it is inert to every supervisor detector).
+  const dm = parseDmSeatToken(raw);
+  if (dm) return { kind: "dm-seat", grain: "native", channelId: dm.channelId, generation: dm.generation };
+  const sup = SUPERVISOR_SUFFIX_RE.exec(raw);
+  if (sup) {
+    // Container-supervisor label split — byte-identical to access/window-gated.ts domainLabelOf:
+    // `suffix > 0 ? token.slice(0, suffix) : "unknown"`. Here the empty containerKey stands in for
+    // that "unknown" (the caller maps a blank containerKey back to "unknown").
+    const idx = raw.lastIndexOf(":oe-sup:g");
+    return {
+      kind: "container-supervisor",
+      grain: "standing",
+      containerKey: idx > 0 ? raw.slice(0, idx) : "",
+      generation: Number(sup[1]),
+    };
+  }
+  // Declared-subagent child (OPE-45), checked LAST so every arm above keeps its exact pre-OPE-45
+  // precedence: eve's `subagent:` namespace is disjoint from every OE shape, so position is free and
+  // last is the position that PROVES nothing else moved. Grain stays "native" (see the section note).
+  const sub = parseSubagentToken(raw);
+  if (sub) return { kind: "subagent", grain: "native", parentSessionId: sub.parentSessionId, callId: sub.callId };
+  return { kind: "native", grain: "native" };
+}
+
+/**
+ * Recover the BARE OE-minted token from a hook-context token. eve reports the continuation token NAMESPACED with the channel-definition name, while every registry row stores the BARE token OE minted — so any consumer doing an EXACT match against a stored token must strip that namespace first, or its guard silently never matches.
+ * Parse-VERIFIED, at most ONE leading segment, and fail-soft: an anchored structural parse of the input as-is wins; else one segment is stripped and returned only if the remainder itself parses; else the input is returned unchanged when it carries the per-container suffix, whose keys may legitimately contain colons; else undefined. A bare colon-bearing container token passed directly is indistinguishable from its namespaced form, and the strip wins, because this helper is for EVE-CONTEXT tokens, which are always namespaced.
+ */
+export function bareTokenFromEveContext(token: unknown): string | undefined {
+  if (typeof token !== "string" || token.length === 0) return undefined;
+  const anchored = (t: string): boolean => {
+    if (parseWindowToken(t)) return true;
+    // eve's declared-subagent token (OPE-45) is structurally anchored on its own `subagent:` head, so
+    // it needs no namespace strip at rule 1 and strips correctly at rule 2 when eve namespaces it.
+    // Tested against the RAW regex (not parseSubagentToken, which also eats a `unified:` prefix) so
+    // this predicate stays a pure structural test, matching parseWindowToken's shape.
+    if (SUBAGENT_TOKEN_RE.test(t)) return true;
+    const dm = parseDmSeatToken(t);
+    return dm !== undefined && !dm.channelId.includes(":");
+  };
+  if (anchored(token)) return token;
+  const i = token.indexOf(":");
+  const stripped = i > 0 ? token.slice(i + 1) : undefined;
+  if (stripped && (anchored(stripped) || SUPERVISOR_SUFFIX_RE.test(stripped))) return stripped;
+  if (SUPERVISOR_SUFFIX_RE.test(token)) return token;
+  return undefined;
+}
+
+/**
+ * The ONE platform a window token is pinned to, or `undefined` when it addresses no single surface. A pure read of the token — no config, no delivery, no store — so a caller that renders it into a byte-stable standing block stays byte-stable.
+ * Three shapes answer, each because the token itself names one surface: a SOLO window, whose windowId IS a surface key; a TASK or THREAD-SEAT window, whose channelKey sits AFTER the grain marker, so the platform is segment ONE — reading segment zero would answer with the marker itself, which is why this is a function and not a split at a call site; and a DM window, whose domain carries the DM's own surface key. A DEGENERATE domain window answers `undefined`, because its windowId is a config domain NAME that names no surface and may span several.
+ */
+export function windowTokenPlatform(token: unknown): string | undefined {
+  const sid = classifySessionId(token);
+  if (sid.kind === "task" || sid.kind === "thread-seat") {
+    return sid.key.windowId.split("/")[1] || undefined;
+  }
+  if (sid.kind !== "window") return undefined;
+  if (sid.key.windowId !== sid.key.domain) return sid.key.windowId.split("/")[0] || undefined;
+  return dmSurfaceKeyFromAnchorDomain(sid.key.domain)?.split("/")[0] || undefined;
+}
+
+/**
+ * Is this token SUPERVISOR-SHAPED — any OE-structured standing, task, thread or window token, as opposed to a native one? It is exactly the set the anchored supervisor suffix denotes, and byte-identical to the regex it replaces over every real and malformed shape.
+ * Fail-soft: a non-string or blank token answers false.
+ */
+export function isSupervisorShapedToken(token: unknown): boolean {
+  // Explicit allowlist (NOT `kind !== "native"`) so the OPE-90 `dm-seat` arm is EXCLUDED — a DM seat
+  // must route to the PRIMARY model exactly like a native DM token, never the cheap supervisor model.
+  // Byte-identical to the old `kind !== "native"` for every pre-dm-seat token (those are the only
+  // other kinds), which scripts/session-id-codec-test.ts pins against the original anchored regex.
+  const k = classifySessionId(token).kind;
+  return k === "window" || k === "task" || k === "thread-seat" || k === "container-supervisor";
+}

package/agent/channels/window-sources.ts

@@ -0,0 +1,88 @@
+// window-sources — the SOURCES vector: which surface PLATFORMS legitimately fan wakes into a given window. A per-surface tool for platform X mounts only when X is in the vector.
+// DERIVED, NOT CONFIGURED: it is a pure function of the window's `(windowId, domain)` identity and the domain's EXISTING membership config, so there is no sources field and no migration. This module imports only window-key.ts and the Domain type — no store, no session, no eve, no surface SDK.
+
+import { dmSurfaceKeyFromAnchorDomain, isTaskWindowId } from "./window-key.js";
+import { domainRoster, type Domain } from "../memory/domain.js";
+
+/** The platform prefix of a fully-qualified surface key (`platform/workspace/surface` → `platform`),
+ *  or `""` when there is no prefix. */
+function platformOf(surfaceKey: string): string {
+  return surfaceKey.split("/", 1)[0] ?? "";
+}
+
+/** The DISTINCT platform prefixes of a channel list, insertion-order preserved (dedupe). */
+function distinctPlatforms(channels: readonly string[]): readonly string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const ch of channels) {
+    const p = platformOf(ch);
+    if (p.length > 0 && !seen.has(p)) {
+      seen.add(p);
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * Derive the `sources` vector for a window from its identity and the domain config. PURE — a function of (windowId, domain, domains) only — so it is mint-and-assert testable without a store or an eve runtime.
+ * An EMPTY vector means the identity could not be resolved; the CARRIAGE layer fails that empty result closed to the single origin platform, never to a wider set.
+ */
+export function sourcesForWindow(windowId: string, domain: string, domains: readonly Domain[]): readonly string[] {
+  // Task / thread child (windowId `t/<channelKey>/<threadTs>`): the single parent-origin platform,
+  // read off the task windowId's channelKey. Checked FIRST — a task windowId never equals a domain
+  // slug, and this branch needs no config at all.
+  if (isTaskWindowId(windowId)) {
+    const p = platformOf(windowId.slice("t/".length)); // strip the "t/" grain marker → channelKey's platform
+    return p.length > 0 ? [p] : [];
+  }
+  // DM ANCHOR window: the domain is the reserved `oe-dm/<surfaceKey>` pseudo-domain, which is in NO config roster, so the vector derives from the identity alone and no `loadDomains()` is paid per DM wake.
+  // Placed AFTER the task arm, so a DM-anchored WORKER keeps deriving its platform from its own task windowId.
+  const dmSurface = dmSurfaceKeyFromAnchorDomain(domain);
+  if (dmSurface !== undefined) {
+    const p = platformOf(dmSurface);
+    return p.length > 0 ? [p] : [];
+  }
+  // Cross-surface (multi-source) window: the degenerate id-equals-domain form — the distinct
+  // platforms of the domain's configured channels.
+  if (windowId === domain) {
+    const d = domains.find((dm) => dm.name === domain);
+    return distinctPlatforms(d ? domainRoster(d) : []);
+  }
+  // NAMED WINDOW GROUP: the windowId is a group NAME. This arm must sit BEFORE the solo fallback, whose `platformOf(windowId)` would turn a slash-free id into a PHANTOM platform nobody configured; an unknown slash-free id yields the EMPTY vector instead, which the carriage fails closed.
+  // It reads the EXACT keys of the group's `reach` and only those, never its containers, because the config-load vouch gate enumerates the same membership: reading a container here would stamp a platform into `oe_sources` that no operator vouched. A container-only group therefore resolves EMPTY, which is narrower and never wider.
+  if (!windowId.includes("/")) {
+    const d = domains.find((dm) => dm.name === domain);
+    const group = d?.windows?.find((g) => g.name === windowId);
+    if (group === undefined) return [];
+    return distinctPlatforms(domainRoster(group));
+  }
+  // Solo channel window: windowId is a fully-qualified surface key — its single platform.
+  const p = platformOf(windowId);
+  return p.length > 0 ? [p] : [];
+}
+
+/**
+ * Does {@link sourcesForWindow} need the DOMAIN CONFIG for this window, or is the identity self-describing? A producer asks before paying a `loadDomains()` per wake, and MUST ask here rather than keep a private copy of which shapes need config.
+ * The drift is silent and wrong: an empty roster passed for a window that DID need config answers EMPTY, the carriage fails closed to one platform, and a cross-platform window leaves its other members' tools unmounted. TRUE for exactly the two config-derived shapes — the id-equals-domain window and a named group.
+ */
+export function windowSourcesNeedConfig(windowId: string, domain: string): boolean {
+  if (isTaskWindowId(windowId)) return false;
+  if (dmSurfaceKeyFromAnchorDomain(domain) !== undefined) return false;
+  return windowId === domain || !windowId.includes("/");
+}
+
+/** Serialise a `sources` vector to its `oe_sources` auth-attribute form (comma-joined). */
+export function encodeSources(sources: readonly string[]): string {
+  return sources.join(",");
+}
+
+/** Parse an `oe_sources` auth-attribute value back to a `sources` vector. Fail-soft: a non-string /
+ *  empty value yields an empty vector; blank segments are dropped. */
+export function decodeSources(raw: unknown): readonly string[] {
+  if (typeof raw !== "string" || raw.length === 0) return [];
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}

package/agent/channels/work-destinations.ts

@@ -0,0 +1,48 @@
+// work-destinations — the one answer both work-item registries ask: a session may address exactly the connectors its DOMAIN holds a work grant on. Chat presence is never a precondition for a tool, and never a source of one either.
+// This set decides which platform NAMES are admissible; each adapter's own `checkAccess` fence is the capability statement, so narrowing here can never close a hole that was open. It fails closed and silently — an identity-less ctx yields an empty set and every dispatch refuses.
+
+import type { BindableContext } from "../identity/binding.js";
+import { callerWorkDomain, hasGithubWorkGrant, hasWorkGrant, workRoleFor, GITHUB_CONNECTOR } from "../access/work-grant.js";
+import { registeredWorkPlatforms, registeredWorkRole } from "./work-registry.js";
+import { resolveAccessFor } from "../access/request.js";
+import type { Domain } from "../memory/domain.js";
+
+/**
+ * The registered work platforms this caller's DOMAIN holds the grant for, sorted — derived from what the deployment registered rather than tabulated.
+ * `callerWorkDomain` is the one caller resolution every work-grant consumer runs, so this gate and each provider's mount predicate can never disagree about the caller's domain; no domain means no grant, never a default.
+ */
+function grantedWorkPlatforms(ctx: BindableContext, domains: readonly Domain[]): readonly string[] {
+  const domain = callerWorkDomain(ctx, () => domains);
+  if (!domain) return [];
+  return registeredWorkPlatforms().filter((platform) => {
+    const role = registeredWorkRole(platform) ?? workRoleFor(platform);
+    return role !== undefined && hasWorkGrant(domain, platform, role);
+  });
+}
+
+/**
+ * This session's resolved REPO GRANT — GitHub's work declaration, read for the calling scope. Empty on an unreadable config or an identity-less ctx, which is a refusal here and never a default.
+ * The MOUNT predicate (scm/github-work.ts) fails the other way on purpose: this set decides a NAME's admissibility, and admitting an ungranted name only moves the refusal from the fence to the gate.
+ */
+function grantedRepos(ctx: BindableContext): readonly string[] {
+  try {
+    return resolveAccessFor(ctx).repos;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The platforms this session may name as a work DESTINATION or a work ENTITY — exactly the connectors its domain holds a work grant on.
+ * Sorted by connector name, which is stable across calls: the "exactly one work surface" inference in ticket-create.ts is the one consumer that reads the order.
+ */
+export function workDestinationPlatforms(ctx: BindableContext, domains: readonly Domain[]): readonly string[] {
+  const granted = [...grantedWorkPlatforms(ctx, domains)];
+  // GitHub's grant is the access bundle's `repos:` list, not a `Domain.credentials` row (OPE-940),
+  // so it is admitted here rather than by the role lookup above. Only when an adapter for it is
+  // actually registered — the same rule every other platform takes.
+  if (hasGithubWorkGrant(grantedRepos(ctx)) && registeredWorkPlatforms().includes(GITHUB_CONNECTOR) && !granted.includes(GITHUB_CONNECTOR)) {
+    granted.push(GITHUB_CONNECTOR);
+  }
+  return granted.sort();
+}

package/agent/channels/work-registry.ts

@@ -0,0 +1,26 @@
+// work-registry — which platforms ACCEPT a work item in this deployment, derived from the adapters a provider bundle actually registered rather than from a hard-coded table.
+// It GRANTS nothing: whether THIS caller may send one is `hasWorkGrant` against the role recorded here, and then the adapter's own `checkAccess` fence.
+
+const WORK_PLATFORM_ROLES: Record<string, string | undefined> = Object.create(null);
+
+/**
+ * Record that `platform` accepts work items. Called by {@link registerTicketCreateAdapter} and {@link registerEntityActionAdapter}, never directly by a provider.
+ * Idempotent and ADDITIVE on the role: the first non-undefined role wins and a later registration never clears it, so registration ORDER cannot change which grant is read.
+ */
+export function registerWorkPlatform(platform: string, workRole?: string): void {
+  const existing = WORK_PLATFORM_ROLES[platform];
+  WORK_PLATFORM_ROLES[platform] = existing ?? workRole;
+}
+
+/** Every registered work platform, sorted. The universe `workDestinationPlatforms` narrows by grant. */
+export function registeredWorkPlatforms(): readonly string[] {
+  return Object.keys(WORK_PLATFORM_ROLES).sort();
+}
+
+/**
+ * The work role registered for `platform`, or `undefined`. Undefined means either that the provider declares the role in `WORK_ROLES`, so the pair is spelled once and the two cannot drift, or that its grant is not a `Domain.credentials` row at all — GitHub's grant is the access bundle's repo list.
+ * A platform named in neither place holds no declarable grant and is never a destination.
+ */
+export function registeredWorkRole(platform: string): string | undefined {
+  return WORK_PLATFORM_ROLES[platform];
+}