@open-everywhere/core 0.1.0

package/agent/control/read-route.ts

@@ -0,0 +1,841 @@
+// The DEPLOYMENT-MOUNTED read side of the control plane — a plain HTTPS GET the
+// deployment itself serves (channels/control-read.ts mounts it as an Eve route),
+// so a harness/CI can read priced usage back from the running instance with a
+// service token instead of a database URL. This is the "expose a tool, not a DB
+// URL" doctrine made real for the one read the e2e cost report needs
+// (scripts/e2e/cost.ts): before this route existed the harness held a raw
+// read-only Postgres URL; now the deployment answers through the SAME view the
+// control MCP's `usage_window` tool serves (views.ts usageWindowView).
+//
+// READ-ONLY IS STRUCTURAL, not a per-call gate: this module imports only the read
+// views — control/writes.ts (and server.ts, which registers it) are simply never
+// loaded here, and the channel mounts GET only. There is no write to reach,
+// mirroring how a service principal on the MCP mount gets the write tools
+// UNREGISTERED rather than refused (auth.ts AdminIdentity.readOnly).
+//
+// FAIL-CLOSED: with OE_CONTROL_READ_TOKENS unset/empty the route answers 404 to
+// everything — the mode is fully off and the endpoint effectively does not exist
+// (same posture as an unknown webhook id in channels/webhooks.ts). A configured
+// deployment still refuses any request without a matching bearer, through eve's own
+// route-auth walk over our credential (auth.ts serviceTokenAuth, verified by the same
+// constant-time compare the MCP mount uses — auth.ts verifyServiceToken). One door
+// serves every route here: {@link authorizeRead}.
+// Every authenticated call is audited (`control.service_call`, principal
+// `svc:<name>`), exactly like a service-token call on the MCP transport.
+
+import type { AttachSessionFn } from "eve/channels";
+import { routeAuth } from "eve/channels/auth";
+import { classifySessionId } from "../channels/window-key.js";
+import { parseServiceTokenEntries, serviceTokenAuth, type EveSessionAuth } from "./auth.js";
+import { auditView, usageWindowView, unifiedDomainAudit } from "./views.js";
+import { appendAudit } from "../audit/audit.js";
+import type { AuditFilter } from "../audit/audit.js";
+import { deploymentOrg } from "../identity/binding.js";
+import { credentialKeyArmed } from "../credentials/db-broker.js";
+import { getOperationalStore } from "../operational/provider.js";
+
+/** The mounted route path — GET ?since=<iso>&workspaces=<csv of platform/workspace>
+ *  [&sessionStartedAfter=<iso>] (OPE-402, optional). */
+export const CONTROL_READ_USAGE_PATH = "/control/v1/usage";
+/** The mounted audit-read path — GET ?since=<iso>[&platform&workspace&surface&actions&principalId&limit].
+ *  Same service-token + self-audit contract as the usage route; read-only, row-capped. */
+export const CONTROL_READ_AUDIT_PATH = "/control/v1/audit";
+/** The mounted unified cross-surface domain audit path — GET ?domain=<name>[&sinceDays]. Same
+ *  service-token + self-audit + fail-closed-404 contract as the audit route; read-only, row-capped
+ *  (via the composed auditView). The flagship detective control for the unified supervisor preview. */
+export const CONTROL_READ_UNIFIED_AUDIT_PATH = "/control/v1/unified-audit";
+/** The mounted session-transcript path — GET /control/v1/session/:sessionId/transcript
+ *  [?startIndex&limit&idleMs]. Same service-token + self-audit + fail-closed-404 contract as the
+ *  audit route; read-only (this module imports no write tool and the eve session API is read-only).
+ *  Replays the durable per-session event stream (handleSessionTranscriptRead). */
+export const CONTROL_READ_TRANSCRIPT_PATH = "/control/v1/session/:sessionId/transcript";
+/** The mounted runtime-signal path — GET, no query. Same service-token + self-audit +
+ *  fail-closed-404 contract as the siblings. OPE-658: the deploy-time half of the dynamic-tool-
+ *  roster-refresh contract — eve keys the refresh off `VERCEL_DEPLOYMENT_ID`
+ *  (window-gated-test.ts §6 pins the mechanism against the installed eve dist), and that env var
+ *  is a Vercel platform fact no offline tier can see. This route reports only whether THIS
+ *  process's env carries a non-empty value — presence, never the value itself, the same posture
+ *  the credential census already holds.
+ *
+ *  OPE-641 rides the same route: the response also carries `credentialBrokerArmed`, whether THIS
+ *  process's `OE_CREDENTIAL_ENCRYPTION_KEY` decodes to a valid AES-256 key
+ *  ({@link credentialKeyArmed}). Both fields answer the same question — "what does the deployed
+ *  function's own env carry, from outside the process" — so one route serves both rather than
+ *  duplicating the token-parse/audit boilerplate for a second GET. See
+ *  {@link handleRuntimeSignalRead}. */
+export const CONTROL_READ_RUNTIME_SIGNAL_PATH = "/control/v1/runtime-signal";
+/** The mounted model-call capture path — GET /control/v1/session/:sessionId/model-calls
+ *  [?turnId&limit&body]. Same service-token + self-audit + fail-closed-404 contract as the
+ *  transcript route, and the SAME sensitivity: a capture body is the whole composed prompt, so this
+ *  route is transcript-grade and is reachable only with an admin service token. Serves the soak
+ *  lane's prefix-replay harvest (OPE-846); empty on any deployment that never armed `soak.capture`. */
+export const CONTROL_READ_MODEL_CALLS_PATH = "/control/v1/session/:sessionId/model-calls";
+/** The mounted model-call capture SESSION LISTING path — GET /control/v1/model-calls/sessions
+ *  (OPE-857). Same service-token + self-audit + fail-closed-404 contract as its sibling, but
+ *  carries no body byte — it answers "which sessions hold captures", the read a retention operator
+ *  needs before they can name a session to the purge caller. See {@link handleModelCallSessionsRead}. */
+export const CONTROL_READ_MODEL_CALL_SESSIONS_PATH = "/control/v1/model-calls/sessions";
+/** Hard ceiling on the row cap so a caller can't ask for an unbounded scan.
+ *  🔴 EXPORTED BECAUSE THE RESPONSE NAMES IT (OPE-1886). A caller that reads `capped: true` has to
+ *  know WHICH number it hit before it can page or narrow, and hard-coding 1000 in every caller is
+ *  how a bumped ceiling silently stops meaning anything. The route reports it as `maxLimit`. */
+export const AUDIT_MAX_LIMIT = 1000;
+/** Hard ceiling on how many DISTINCT actions one `?actions=` CSV may name (OPE-1933). A
+ *  multi-action read runs ONE store scan per action, so this is the fan-out a single authenticated
+ *  request can buy. Well above any real query — the widest caller in this repository names seven. */
+const AUDIT_MAX_ACTIONS = 25;
+const AUDIT_DEFAULT_LIMIT = 200;
+/** Transcript paging/drain bounds. Channel sessions are long-lived, so the default page is larger
+ *  than the audit cap; `startIndex`+`limit` is the pager. `idleMs` is the parked-session stop
+ *  signal; `WALL_MS` is the hard invocation ceiling (never hold a serverless request open). */
+const TRANSCRIPT_DEFAULT_LIMIT = 2000;
+const TRANSCRIPT_MAX_LIMIT = 10000;
+const TRANSCRIPT_DEFAULT_IDLE_MS = 1500;
+const TRANSCRIPT_MAX_IDLE_MS = 10000;
+const TRANSCRIPT_WALL_MS = 30000;
+/** Budget for the EXISTENCE probe (OPE-333, {@link probeSessionExists}). Small: the probe is one
+ *  index read against a durable run, and a probe that has not answered in this long is treated as
+ *  INCONCLUSIVE (never as "missing"), so the ceiling only bounds the added latency. */
+const TRANSCRIPT_PROBE_MS = 3000;
+/** Model-call capture paging bounds. Far smaller than the transcript's when bodies are asked for:
+ *  one body can be hundreds of KB, so a wide page is a multi-hundred-MB response. The metadata read
+ *  (`body=0`) is cheap and takes the larger cap. */
+const MODEL_CALLS_DEFAULT_LIMIT = 200;
+const MODEL_CALLS_MAX_LIMIT = 1000;
+const MODEL_CALLS_MAX_LIMIT_WITH_BODY = 25;
+
+function json(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+}
+
+/**
+ * The ONE door every route on this mount passes (OPE-1613). Two rungs, in this order:
+ *
+ *  1. FAIL-CLOSED 404 when the READ family is unconfigured — the mode is off and the route does not
+ *     exist. This rung is OURS and stays ours: eve's walk answers 401, which would disclose that the
+ *     seam exists on a deployment that never armed it.
+ *  2. eve's route-auth walk over the READ family ({@link serviceTokenAuth}). It returns the verified
+ *     caller, or the framework's own 401 — `cache-control: no-store`, a `{ ok, code, error }` body,
+ *     and a `WWW-Authenticate: Bearer` challenge carrying `error="invalid_token"` when the caller
+ *     did present a bearer. Seven routes used to hand-roll that gate; the credential compare is
+ *     still ours (a constant-time digest compare over hashes the env holds), and nothing else is.
+ *
+ * The env is read PER REQUEST (not at module load) so a token rotation via env redeploy takes
+ * effect with no in-process cache to invalidate.
+ */
+async function authorizeRead(req: Request): Promise<EveSessionAuth | Response> {
+  const entries = parseServiceTokenEntries(process.env.OE_CONTROL_READ_TOKENS);
+  if (entries.length === 0) return new Response("not found", { status: 404 }); // mode off → the route does not exist
+  return routeAuth(req, serviceTokenAuth(entries));
+}
+
+/**
+ * Handle `GET /control/v1/usage?since=<iso>&workspaces=<csv>[&sessionStartedAfter=<iso>]` —
+ * the usage-window read (views.ts usageWindowView), returned as JSON. Transport-neutral over a
+ * WHATWG Request so the Eve channel wrapper stays one line and tests can call it
+ * directly. Statuses: 404 mode off (no tokens configured), 401 missing/bad bearer,
+ * 400 bad query (missing/invalid `since` or `workspaces`, or an unparseable
+ * `sessionStartedAfter`), 200 UsageWindowResult.
+ *
+ * `sessionStartedAfter` (OPE-402) is OPTIONAL — absent means today's behaviour, byte-identical:
+ * only `since` bounds the write ts, so a late-flushing turn from a session that started before
+ * the window still counts. A caller that wants that class excluded (the e2e driver, bounding a
+ * live run to sessions IT created) passes the same instant it used for `since`.
+ *
+ * A response to a query that CARRIED that bound also carries an `excluded` block (OPE-1622):
+ * the calls, dollars, surfaces and upper-bound session count the bound removed. It exists because
+ * the bound drops a session WHOLESALE, so a surface served by a standing seat otherwise reads
+ * $0.0000 for a run it really spent money in. Its absence means the query carried no bound.
+ */
+export async function handleUsageWindowRead(req: Request): Promise<Response> {
+  const identity = await authorizeRead(req);
+  if (identity instanceof Response) return identity;
+
+  const url = new URL(req.url);
+  const since = (url.searchParams.get("since") ?? "").trim();
+  const workspaces = (url.searchParams.get("workspaces") ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (!since || workspaces.length === 0) {
+    return json(400, { error: 'expected query params: since=<ISO-8601 timestamp> and workspaces=<comma-separated "platform/workspace" keys>' });
+  }
+  const sessionStartedAfter = (url.searchParams.get("sessionStartedAfter") ?? "").trim() || undefined;
+
+  // A machine credential leaves a per-request trail, same contract as the MCP mount
+  // (control/http.ts). Best-effort by appendAudit's own contract — never throws.
+  await appendAudit({
+    org: deploymentOrg(),
+    platform: "control",
+    workspace: "control",
+    principalId: identity.principalId, // "svc:<name>"
+    action: "control.service_call",
+    detail: { service: identity.principalId, view: "usage_window", since, workspaces: workspaces.join(","), ...(sessionStartedAfter ? { sessionStartedAfter } : {}) },
+  });
+
+  try {
+    return json(200, await usageWindowView({ sinceIso: since, workspaceKeys: workspaces, ...(sessionStartedAfter ? { sessionStartedAfter } : {}) }));
+  } catch (err) {
+    // usageWindowView throws only on input-shape problems (unparseable since/sessionStartedAfter,
+    // malformed workspace keys) — surface the message as a 400 so the caller can fix the query.
+    return json(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+/**
+ * Handle `GET /control/v1/audit?since=<iso>[&until&platform&workspace&surface&actions&principalId&limit]`
+ * — the audit-window read (views.ts auditView), returned as JSON. The uniform assertion channel
+ * for the ambient surfaces (plan §5.3 / driver-investigation §4.2): every `no_reply` (audited
+ * silence), `replied`, `dispatched`, `rejected` row is answerable over HTTP with the same
+ * service-token contract as the usage route — read-only (this module never imports the write
+ * tools), row-capped, and self-audited on every authenticated call.
+ *
+ * `since` is required (the natural lower bound; a bare audit scan is refused). `actions` is a
+ * CSV of action keys (e.g. `notion.no_reply,notion.replied`): one value narrows at the store, and
+ * several run one store-narrowed scan per action, merged newest-first. Statuses mirror the usage
+ * route: 404 mode off, 401 missing/bad bearer, 400 bad query, 200 AuditView.
+ *
+ * 🔴 `until` IS WHAT MAKES A PAST WINDOW READABLE AT ANY VOLUME (OPE-1886). Rows come back
+ * NEWEST-first and `limit` applies after that sort, so `since` alone answers "the newest N rows
+ * since then" — not "the rows in that window". Ship #214 asked for six legs that ran 19:21–19:56Z
+ * after the board had written well over 1000 further rows, and got none of them back; the report
+ * had to record that absence as no evidence either way. `until` (inclusive, like `since`) bounds
+ * the window at the top, so the window IS the page.
+ *
+ * The response always names the ceiling as `maxLimit` beside `capped`, so a caller that hit the
+ * cap can act without knowing the route's constants: narrow the window, or PAGE BACKWARDS by
+ * re-reading with `until` set to the OLDEST row it received. Both bounds are inclusive, so such a
+ * page re-reads the rows stamped exactly at that instant — de-duplicate them.
+ *
+ * 🔴 EVERY ROW CARRIES ITS STORAGE `seq`, AND THAT IS THE ONLY MONOTONIC LOCATOR HERE (OPE-1933).
+ * `since`/`until` are WALL-CLOCK bounds over a wall-clock column: `appendAudit` stamps `ts` with
+ * `new Date()` at append, so on a box whose clock steps BACKWARD a row written later can carry an
+ * earlier `ts` than a row written before it, and a `ts >= since` window drops it silently and
+ * forever. A caller that means "everything written after this point" therefore reads `seq` once to
+ * take a cursor, keeps the time window only as a coarse page bound, and selects `seq > cursor`.
+ * `seq` is the store's own insert order (sqlite AUTOINCREMENT / postgres IDENTITY) and never moves
+ * backwards. It is a LOCATOR, not a hash input: the chain's integrity still lives in `prevSha`
+ * (agent/audit/chain.ts), which this route does not serve.
+ *
+ * 🔴 EVERY ACTION GETS ITS OWN PAGE, AND A PAGE IS STILL `AUDIT_MAX_LIMIT` ROWS. Several actions
+ * are scanned ONE PER ACTION at the store and merged newest-first (OPE-1933), so a rare action can
+ * no longer be pushed off the page by a common one — including this route's own
+ * `control.service_call` self-audit row, which a polling caller writes on every call. What remains
+ * is the honest limit: an action with MORE than `AUDIT_MAX_LIMIT` rows of its own in the window
+ * still has a tail behind its page. The response then carries `capped: true` and
+ * `scanTruncated: true` — read them and narrow the window before you conclude "no such rows".
+ */
+export async function handleAuditWindowRead(req: Request): Promise<Response> {
+  const identity = await authorizeRead(req);
+  if (identity instanceof Response) return identity;
+
+  const url = new URL(req.url);
+  const p = (name: string): string | undefined => {
+    const v = (url.searchParams.get(name) ?? "").trim();
+    return v.length > 0 ? v : undefined;
+  };
+  const since = p("since");
+  if (!since) return json(400, { error: "expected query param: since=<ISO-8601 timestamp> (the audit-window lower bound)" });
+  if (Number.isNaN(Date.parse(since))) {
+    return json(400, { error: `since "${since}" is not a parseable ISO-8601 timestamp (e.g. "2026-07-10T12:00:00Z")` });
+  }
+  const until = p("until");
+  if (until !== undefined) {
+    if (Number.isNaN(Date.parse(until))) {
+      return json(400, { error: `until "${until}" is not a parseable ISO-8601 timestamp (e.g. "2026-07-10T12:00:00Z")` });
+    }
+    // An inverted window holds no row, and answering it with an empty list would read as "nothing
+    // happened" — the exact confusion this bound exists to remove. Refuse the query instead.
+    if (Date.parse(until) < Date.parse(since)) {
+      return json(400, { error: `until "${until}" is before since "${since}" — the window is empty (both bounds are inclusive)` });
+    }
+  }
+  // 🔴 NORMALISE BOTH BOUNDS, BECAUSE THE STORE COMPARES THEM AS TEXT. `ts` is a text column in both
+  // adapters and the predicates are `ts >= ?` / `ts <= ?`, so the bound only means what it says while
+  // it is canonical UTC ISO. `Date.parse` accepts more than that: an offset form (`…T19:56:00+01:00`)
+  // text-compares an hour off its own instant and silently widens the window, and a second-precision
+  // form (`…T19:21:00Z`) sorts AFTER every millisecond stamp in that second ("Z" > "."), so
+  // `since=…T19:21:00Z` drops the rows written at 19:21:00.500. One canonical spelling removes both.
+  const sinceIso = new Date(since).toISOString();
+  const untilIso = until === undefined ? undefined : new Date(until).toISOString();
+  const limitRaw = p("limit");
+  let limit = AUDIT_DEFAULT_LIMIT;
+  if (limitRaw !== undefined) {
+    const n = Number.parseInt(limitRaw, 10);
+    if (!Number.isInteger(n) || n <= 0) return json(400, { error: `limit "${limitRaw}" must be a positive integer` });
+    limit = Math.min(n, AUDIT_MAX_LIMIT);
+  }
+  // `actions` (CSV): 0 → no action filter; 1 → narrow at the store; >1 → one store-narrowed scan
+  // per action, merged below.
+  //
+  // 🔴 DE-DUPLICATED, BECAUSE EACH NAME NOW COSTS ITS OWN SCAN. `actions=a,a` used to be free — the
+  // in-process match ran over one page and a `Set` absorbed the repeat. Per-action scanning would
+  // instead run the same query twice and return every matching row twice, which is a wrong answer,
+  // not merely a slow one.
+  const actions = [
+    ...new Set(
+      (p("actions") ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean),
+    ),
+  ];
+  // 🔴 AND BOUNDED, because the fan-out is now the caller's to choose. One wide scan cost one query
+  // however many actions were named; one query per action means an unbounded CSV is an unbounded
+  // number of concurrent store reads off a single authenticated request. The ceiling is far above
+  // any real query — the widest caller in this repository names seven — so it refuses a shape nobody
+  // sends rather than narrowing one anybody uses.
+  if (actions.length > AUDIT_MAX_ACTIONS) {
+    return json(400, {
+      error: `actions names ${actions.length} distinct actions, more than the ${AUDIT_MAX_ACTIONS} this route scans in one request — ask for fewer, or drop the filter and match the rows yourself`,
+    });
+  }
+  const base: AuditFilter = {
+    // PIN to the deployment's own tenant (audit-wedge F10): a caller-supplied `?org=` must NOT
+    // widen the read to another tenant's audit rows. Every sibling control read already pins
+    // deploymentOrg() (the unified-domain + transcript routes); this one alone honoured the param.
+    // Multi-org control access, if it ever lands, must be a deliberate build, not an unguarded param.
+    org: deploymentOrg(),
+    since: sinceIso,
+    ...(untilIso !== undefined ? { until: untilIso } : {}),
+    ...(p("platform") ? { platform: p("platform") } : {}),
+    ...(p("workspace") ? { workspace: p("workspace") } : {}),
+    ...(p("surface") ? { surface: p("surface") } : {}),
+    ...(p("principalId") ? { principalId: p("principalId") } : {}),
+  };
+
+  await appendAudit({
+    org: deploymentOrg(),
+    platform: "control",
+    workspace: "control",
+    principalId: identity.principalId, // "svc:<name>"
+    action: "control.service_call",
+    // The NORMALISED bounds, so the control log records the window the store was actually asked for.
+    detail: { service: identity.principalId, view: "audit", since: sinceIso, until: untilIso ?? "", actions: actions.join(","), platform: base.platform ?? "", limit },
+  });
+
+  try {
+    if (actions.length <= 1) {
+      const view = await auditView({ ...base, ...(actions.length === 1 ? { action: actions[0] } : {}), limit });
+      return json(200, { ...view, maxLimit: AUDIT_MAX_LIMIT });
+    }
+    // Multi-action: ONE SCAN PER ACTION, each narrowed at the store, then merged newest-first and
+    // capped to `limit`.
+    //
+    // 🔴 WHY PER ACTION, AND NOT ONE WIDE SCAN (OPE-1933). This used to fetch the newest
+    // `AUDIT_MAX_LIMIT` rows of the window REGARDLESS of action and match in-process, so every row
+    // of every OTHER action competed for the same page — including this route's OWN
+    // `control.service_call` self-audit row, appended a few lines above on every call. A poll that
+    // cannot see past its own footprint is not an evidence surface.
+    //
+    // 🔴 STATED AS A CANDIDATE, NOT A REPRODUCED CAUSE. A long poll's own `control.service_call`
+    // rows compete for the same page and can push a wanted row off it. That is a candidate cause of
+    // the two OPE-1933 reds, never a measured one, and the arithmetic does not force it on its own:
+    // six minutes at 400 ms is only ~900 calls, BELOW this 1000-row page, and a wanted row is the
+    // newest row in the window at the instant it is written. Reaching the ceiling needs the poll's
+    // rows PLUS whatever else the window holds. The shape is real and is driven by
+    // `control-read-test.ts`; the attribution to those two reds is not.
+    //
+    // Narrowing at the store removes the competition outright: a wanted action's rows can now be
+    // pushed off the page only by 1000 rows OF THAT SAME ACTION. This is exactly the escape hatch
+    // the doc comment above already recommended ("ask for ONE action, which narrows at the store"),
+    // now applied on the caller's behalf instead of left as advice.
+    //
+    // 🔴 OPE-1065'S PROPERTY IS KEPT, NOT DROPPED. A truncated scan must never read as "these
+    // actions never happened": if ANY per-action scan comes back at the ceiling, that action's rows
+    // may still sit behind its page, so `scanTruncated` and `capped` are reported exactly as
+    // before. An action holding EXACTLY the ceiling reports truncation it did not suffer — still
+    // deliberate, for the reason that entry gave: over-warning costs one narrower re-read,
+    // under-warning costs a wrong conclusion drawn from an evidence surface.
+    //
+    // 🔴 AND THE SCAN IS NOT THE ANSWER. Per-action scanning stops one action from hiding another
+    // FROM THE SCAN; the merge below still cuts every action's rows to the caller's ONE `limit`, so
+    // a common action's newer rows can push a rare action's rows out of the RESPONSE even though
+    // both scans found them. That case reports `capped: true` and no `scanTruncated` — which is why
+    // `capped` is as load-bearing as `scanTruncated` here, and why the docs say to read both.
+    const views = await Promise.all(actions.map((action) => auditView({ ...base, action, limit: AUDIT_MAX_LIMIT })));
+    const scanTruncated = views.some((v) => v.entries.length >= AUDIT_MAX_LIMIT);
+    const scanned = views.reduce((n, v) => n + v.entries.length, 0);
+    // Newest-first across the merged actions — by `ts`, then by `seq` (OPE-1933). The store orders
+    // `ts DESC, seq DESC` within one action, and `seq` now rides the wire, so this merge reproduces
+    // that order across actions too: rows of DIFFERENT actions sharing a millisecond no longer come
+    // back in the order their actions happened to be named.
+    //
+    // 🔴 THE TEXT COMPARE IS NOT MADE SAFE BY THE BOUND NORMALISATION ABOVE. That canonicalises the
+    // QUERY BOUNDS (`since`/`until`); it never touches a row's stored `ts`, which is whatever
+    // `appendAudit` wrote — `entry.ts ?? new Date().toISOString()` (audit/audit.ts), so a CALLER may
+    // supply its own stamp. A text compare is the instant compare here because every current writer
+    // stamps canonical UTC ISO. A writer that passed an offset form or a second-precision stamp
+    // would sort wrongly in this merge, exactly as it already would in the store's own ORDER BY.
+    const merged = views
+      .flatMap((v) => v.entries)
+      .sort((a, b) => (a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : b.seq - a.seq))
+      .slice(0, limit);
+    return json(200, {
+      // Every per-action view carries the same chain root (one org, one store), so naming the first
+      // is not a pick — it is the only value there is.
+      root: views[0]!.root,
+      filter: { ...base, limit },
+      entries: merged,
+      capped: merged.length === limit || scanTruncated,
+      maxLimit: AUDIT_MAX_LIMIT,
+      ...(scanTruncated ? { scanTruncated: true, scanned } : {}),
+    });
+  } catch (err) {
+    return json(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+/**
+ * Handle `GET /control/v1/unified-audit?domain=<name>[&sinceDays=<n>]` — the unified cross-surface
+ * domain audit (views.ts unifiedDomainAudit), returned as JSON. Copies the `/control/v1/audit`
+ * contract EXACTLY: 404 when mode off (OE_CONTROL_READ_TOKENS unset), 401 on a missing/bad bearer,
+ * 400 on a bad/missing `domain` (or an unknown domain name), 200 UnifiedDomainAuditResult. Read-only
+ * (this module imports no write tool), self-audited on every authenticated call, and row-capped via
+ * the composed auditView. The org is the deployment org (a service token is a machine credential, not
+ * a scoped role) — the MCP tool is the org/domain-role-scoped surface for a human/agent caller.
+ */
+export async function handleUnifiedAuditRead(req: Request): Promise<Response> {
+  const identity = await authorizeRead(req);
+  if (identity instanceof Response) return identity;
+
+  const url = new URL(req.url);
+  const domain = (url.searchParams.get("domain") ?? "").trim();
+  if (!domain) return json(400, { error: "expected query param: domain=<domain name>" });
+  const sinceDaysRaw = (url.searchParams.get("sinceDays") ?? "").trim();
+  let sinceDays: number | undefined;
+  if (sinceDaysRaw.length > 0) {
+    const n = Number.parseInt(sinceDaysRaw, 10);
+    if (!Number.isInteger(n) || n <= 0 || n > 365) return json(400, { error: `sinceDays "${sinceDaysRaw}" must be a positive integer ≤ 365` });
+    sinceDays = n;
+  }
+
+  await appendAudit({
+    org: deploymentOrg(),
+    platform: "control",
+    workspace: "control",
+    principalId: identity.principalId, // "svc:<name>"
+    action: "control.service_call",
+    detail: { service: identity.principalId, view: "unified_domain_audit", domain, sinceDays: sinceDays ?? 30 },
+  });
+
+  try {
+    return json(200, await unifiedDomainAudit({ domain, org: deploymentOrg(), ...(sinceDays ? { sinceDays } : {}) }));
+  } catch (err) {
+    // unifiedDomainAudit throws only on an unknown domain name — a 400 so the caller can fix the query.
+    return json(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+/**
+ * Handle `GET /control/v1/runtime-signal` — no query, no body. Reports whether THIS process's
+ * env carries a non-empty `VERCEL_DEPLOYMENT_ID`, the fact eve's dynamic-tool-roster refresh
+ * (`refreshDynamicSessionToolsForRuntimeRevision`) keys off (OPE-658), AND whether THIS process's
+ * `OE_CREDENTIAL_ENCRYPTION_KEY` decodes to a valid AES-256 key (OPE-641). Copies the sibling
+ * routes' contract exactly: 404 mode off, 401 missing/bad bearer,
+ * 200 `{ hasDeploymentId: boolean; credentialBrokerArmed: boolean }`.
+ *
+ * PRESENCE, NEVER VALUE — the same posture the credential census already holds for stored
+ * secrets. Neither a deployment id nor a key-armed verdict is a secret, but a boolean is the
+ * smallest answer that proves the SIGNAL exists; printing the raw deployment id or any key
+ * material (a fingerprint, a length) buys nothing this route's one caller (`deploy:census`)
+ * needs, and {@link credentialKeyArmed} never returns or logs the key.
+ *
+ * WHAT NEITHER FIELD PROVES: `hasDeploymentId` does not prove any standing session actually
+ * consumed the revision on its next turn (OPE-658's own scope note). `credentialBrokerArmed`
+ * proves the key is valid IN THIS PROCESS, at the moment of the call — a key rotated or dropped
+ * a moment later is not observed until the next call.
+ */
+export async function handleRuntimeSignalRead(req: Request): Promise<Response> {
+  const identity = await authorizeRead(req);
+  if (identity instanceof Response) return identity;
+
+  const hasDeploymentId = (process.env.VERCEL_DEPLOYMENT_ID ?? "").trim().length > 0;
+  const credentialBrokerArmed = credentialKeyArmed();
+
+  await appendAudit({
+    org: deploymentOrg(),
+    platform: "control",
+    workspace: "control",
+    principalId: identity.principalId, // "svc:<name>"
+    action: "control.service_call",
+    detail: { service: identity.principalId, view: "runtime_signal", hasDeploymentId, credentialBrokerArmed },
+  });
+
+  return json(200, { hasDeploymentId, credentialBrokerArmed });
+}
+
+// --- session transcript read (session-transcript-access-investigation.md, Phase 1) ------------
+//
+// One normalized event on the wire. eve durably records every session event before a step
+// completes and replays the whole stream from `startIndex` (a public, documented authoring
+// primitive — `args.attachSession(id).getEventStream({ startIndex })`, eve/channels), so no capture,
+// storage, or fork is needed. The `type`/`data` payload is EVE'S OWN event shape at the
+// deployment's eve version (carries a wire version, pre-1.0) — NOT an OE-stable schema; treat it
+// as "eve's events". We add a stable OUTER envelope: `index` (0-based position in the durable
+// stream, for paging) and `at` (the event's `meta.at` write-time stamp, hoisted).
+export interface TranscriptEvent {
+  readonly index: number;
+  readonly at: string | null;
+  readonly type: string;
+  readonly data: unknown;
+}
+
+/** The minimal read shape this route consumes off eve's `MessageStreamEvent` — kept loose so
+ *  a pre-1.0 event-union change can't break the drain (we only read `type`/`data`/`meta.at`). */
+export interface SourceStreamEvent {
+  readonly type: string;
+  readonly data?: unknown;
+  readonly meta?: { readonly at?: string };
+}
+
+/** `?name` → non-negative integer, or `def` when absent/empty. Returns null on a malformed value. */
+function nonNegIntParam(raw: string | null, def: number): number | null {
+  const v = (raw ?? "").trim();
+  if (v.length === 0) return def;
+  const n = Number.parseInt(v, 10);
+  return Number.isInteger(n) && n >= 0 ? n : null;
+}
+
+/** `?name` → positive integer capped at `cap`, or `def` when absent/empty. Null on a malformed value. */
+function posIntCappedParam(raw: string | null, def: number, cap: number): number | null {
+  const v = (raw ?? "").trim();
+  if (v.length === 0) return def;
+  const n = Number.parseInt(v, 10);
+  if (!Number.isInteger(n) || n <= 0) return null;
+  return Math.min(n, cap);
+}
+
+/**
+ * Drain a session's durable event stream into a bounded, ordered array. The replay yields every
+ * recorded event fast, THEN — for a PARKED (idle-stopped) session — stays open waiting for the next
+ * turn (`session.waiting` recurs at every park and is NOT terminal). We therefore stop on the FIRST
+ * of: (a) a terminal `session.completed`/`session.failed` (complete=true), (b) the stream closing
+ * (done → complete=true), (c) `maxEvents` reached, (d) no event for `idleMs` (a parked session —
+ * return what's durably recorded, never hang), or (e) the hard wall-clock cap. The reader is always
+ * cancelled so the underlying stream is released.
+ */
+export async function drainSessionStream(
+  stream: ReadableStream<SourceStreamEvent>,
+  startIndex: number,
+  maxEvents: number,
+  idleMs: number,
+): Promise<{ events: TranscriptEvent[]; complete: boolean }> {
+  const reader = stream.getReader();
+  const events: TranscriptEvent[] = [];
+  let complete = false;
+  const deadline = Date.now() + TRANSCRIPT_WALL_MS;
+  try {
+    while (events.length < maxEvents) {
+      const budget = Math.min(idleMs, deadline - Date.now());
+      if (budget <= 0) break; // wall-clock cap — never hold a serverless invocation open
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const idle = new Promise<"idle">((resolve) => {
+        timer = setTimeout(() => resolve("idle"), budget);
+      });
+      const next = await Promise.race([reader.read(), idle]);
+      if (timer) clearTimeout(timer);
+      if (next === "idle") break; // parked/idle session — stop with what's recorded, don't block
+      if (next.done) {
+        complete = true; // stream closed (the session ended)
+        break;
+      }
+      const ev = next.value;
+      events.push({ index: startIndex + events.length, at: ev.meta?.at ?? null, type: ev.type, data: ev.data ?? null });
+      if (ev.type === "session.completed" || ev.type === "session.failed") {
+        complete = true;
+        break;
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+  return { events, complete };
+}
+
+// --- OPE-333: telling "no such session" apart from "a session with nothing to say" --------------
+//
+// THE BUG THIS FIXES, and it was never a 0.31 regression. The `sessionId` this route takes is EVE'S
+// DURABLE SESSION ID — a workflow run id (`wrun_…`), the thing every OE audit row stamps as
+// `detail.sessionId`. It always was: 0.27.11's `getSession` was `(sessionId) => Session` and 0.31's
+// `attachSession` is the same signature under a new name (the migration was a rename). What no
+// version ever accepted here is an OE CHANNEL CONTINUATION TOKEN (`oe-dom:<domain>:…:oe-sup:g<n>`,
+// or its eve-namespaced `unified:<raw>` form) — that is a channel ADDRESS, resolved by a different
+// API (`RouteHandlerArgs.resolveSession`, which is CHANNEL-SCOPED to the mounting channel and so
+// cannot resolve another channel's address from here anyway).
+//
+// Passing one was silently indistinguishable from success. `attachSession(unknownId)
+// .getEventStream()` resolves to a stream that NEVER yields and NEVER errors — eve's world opens a
+// poll against a run that does not exist — so the drain hit its idle stop and the route answered
+// `200 {count: 0, events: [], complete: false}`: byte-identical to a real session that has recorded
+// nothing. Reproduced against prod at `be5a1a72`: a real `wrun_…` returned events in 1.26s; a
+// garbage `wrun_…` and both spellings of a live window token each returned that empty 200 in ~1.7s
+// (= the 1500ms idle stop). The route did not fail; it lied, and the lie cost an investigation.
+//
+// SO: probe for existence FIRST, and answer 404 when the id resolves to nothing. This is NOT a
+// weakening of the non-enumeration posture — "unknown" and "expired" still give the identical
+// answer, which is the property that posture asks for. The hint the 404 carries is derived purely
+// from the CALLER'S OWN INPUT STRING (classifySessionId is a pure codec over the frozen token
+// grammar) and discloses nothing about server state: it fires on a well-formed OE token whether or
+// not any such window has ever existed.
+
+/** Whether a durable session id resolves to a real event stream. `unknown` is the honest third
+ *  answer — the probe API is absent or did not answer in budget — and is never treated as missing. */
+export type SessionExistence = "found" | "missing" | "unknown";
+
+/** The one method this route probes with. Structural, so the drain's own stub-friendly posture is
+ *  preserved and an eve rename shows up at the `AttachSessionFn` call site, not here. */
+export interface ProbeableSession {
+  getStreamTailIndex?: () => Promise<number>;
+}
+
+/**
+ * Does this session id name a real durable stream? Uses eve's `Session.getStreamTailIndex()`, whose
+ * documented contract is "index of the last known chunk, **-1 when no chunks have been written**"
+ * — and an eve session that has ever run has `session.started` at index 0, so `-1` (or a rejection)
+ * means the id resolved to nothing.
+ *
+ * Three arms, and the two conservative ones are deliberate:
+ *   • absent method (`typeof !== "function"`) ⇒ `unknown`, NOT `missing`. If a future eve drops or
+ *     renames the probe, this route must degrade to its old behaviour, never start 404-ing live
+ *     sessions. That is also why the field is optional on {@link ProbeableSession}.
+ *   • no answer within `budgetMs` ⇒ `unknown`. A slow world is not a missing session. The pending
+ *     promise already carries a rejection handler, so nothing is left unhandled when the race ends.
+ *   • a rejection, or a tail index below 0 ⇒ `missing`.
+ *
+ * TWO FRAGILE POINTS, both already covered by the arms above rather than by hope:
+ *   • eve's world might POLL for an unknown run here too (the same behaviour `getEventStream`
+ *     has) instead of answering `-1`. Then the probe times out to `unknown` and the drain backstop
+ *     in {@link handleSessionTranscriptRead} produces the same 404, just ~3s slower. Correctness
+ *     does not depend on which it does — only latency does.
+ *   • a session in the first instants of its life could in principle have no chunk yet and read as
+ *     `missing`. Accepted: `session.started` is written before the first step completes, and this
+ *     route is a forensic read of a run that has already happened, not a live tail.
+ */
+export async function probeSessionExists(session: ProbeableSession, budgetMs: number): Promise<SessionExistence> {
+  const probe = session.getStreamTailIndex;
+  if (typeof probe !== "function") return "unknown";
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const answered: Promise<SessionExistence> = Promise.resolve()
+      .then(async () => await probe.call(session))
+      .then(
+        (tail) => (typeof tail === "number" && tail >= 0 ? "found" : "missing"),
+        () => "missing",
+      );
+    const timedOut = new Promise<SessionExistence>((resolve) => {
+      timer = setTimeout(() => resolve("unknown"), budgetMs);
+    });
+    return await Promise.race([answered, timedOut]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * The 404 body for an id that resolved to nothing. JSON (the siblings' 4xx shape) rather than the
+ * old bare `not found` text, because the WHOLE point is that the caller can now tell what happened;
+ * the status is unchanged, so every existing consumer (scripts/e2e/transcript-read.ts throws on any
+ * non-2xx) behaves exactly as before, just with a legible reason.
+ *
+ * `hint` fires only when the supplied id is a well-formed OE continuation token — the exact mistake
+ * OPE-333 was filed for. It names the right lookup rather than describing the wrong one.
+ */
+function transcriptNotFound(sessionId: string): Response {
+  const classified = classifySessionId(sessionId);
+  const hint =
+    classified.kind === "native"
+      ? undefined
+      : `that looks like an OE channel continuation token (kind: ${classified.kind}), not a durable eve session id — ` +
+        `this route takes the id stamped on audit rows as detail.sessionId (GET /control/v1/audit), e.g. "wrun_…"`;
+  return json(404, { error: "no such session", found: false, sessionId, ...(hint ? { hint } : {}) });
+}
+
+/**
+ * Handle `GET /control/v1/session/:sessionId/transcript[?startIndex&limit&idleMs]` — replay one
+ * session's durable event stream as JSON (message.received/completed, reasoning.appended/completed,
+ * actions.requested + args, action.result + status, step.completed usage/costUsd/generationId,
+ * turn/session boundaries, subagent + HITL events), each with its `meta.at` timestamp, in order.
+ * Copies the `/control/v1/audit` contract EXACTLY: 404 when mode off (OE_CONTROL_READ_TOKENS unset),
+ * 401 on a missing/bad bearer, 400 on a malformed param, self-audited on every authenticated call
+ * (`control.service_call`, `view:"transcript"`), and read-only by construction — the eve session API
+ * exposes only a replay stream, and this module imports no write tool. An unknown/expired sessionId
+ * or an unreadable stream → 404 (same non-enumeration posture as an unknown webhook id) — and since
+ * OPE-333 that 404 is REACHED rather than merely intended: see the section above {@link
+ * probeSessionExists} for why an unknown id used to answer an empty 200 instead, and note that
+ * `sessionId` here is eve's DURABLE id (`wrun_…`, the `detail.sessionId` on every audit row), never
+ * a channel continuation token.
+ *
+ * EXPOSURE / REDACTION STANCE — serve raw, gate hard: a transcript is exactly as sensitive as the
+ * conversation itself (untrusted thread content + tool outputs, and possibly secrets in tool I/O).
+ * It is served ONLY to the admin service token — the same trust level as the audit log, which
+ * already carries message excerpts. There is deliberately NO redaction pass in v1 (the parent's
+ * spec): transcripts are IN SCOPE for the same GDPR/forget/at-rest-isolation story as audit rows.
+ * The gate is fail-safe: no token → the route does not exist.
+ *
+ * ⚠️ THIS ROUTE stays operator-only, but the blanket rule it used to carry — "transcript content
+ * must NEVER be fed back into model context by any OE code path" — was SUPERSEDED by OPE-153 and is
+ * removed rather than quietly left standing. What replaced it is narrower and enforced elsewhere:
+ * a model may read a transcript only through control/transcript-relay.ts, only for a routine fire
+ * that ran in ITS OWN channel, and only through the untrusted fence (the laundering argument is in
+ * that module's header). The old rule was written when the only reader was a human; keeping it as
+ * absolute prose while a tool did the opposite would have made this comment the lie a future agent
+ * reasons from. NOTHING about THIS route changed: the service-token family, the fail-closed 404 and
+ * the raw JSON body are exactly as they were, and no tool reaches this handler.
+ *
+ * Paging/drain: `startIndex` (default 0, full replay) + `limit` (default 2000, cap 10000) is the
+ * pager; `nextIndex` = startIndex + returned count. `idleMs` (default 1500, cap 10000) is the
+ * parked-session stop signal; the hard wall-clock cap bounds the invocation regardless.
+ */
+export async function handleSessionTranscriptRead(
+  req: Request,
+  attachSession: AttachSessionFn,
+  params: Readonly<Record<string, string>>,
+): Promise<Response> {
+  const identity = await authorizeRead(req);
+  if (identity instanceof Response) return identity;
+
+  const sessionId = (params["sessionId"] ?? "").trim();
+  if (!sessionId) return json(400, { error: "expected path param: sessionId" });
+
+  const url = new URL(req.url);
+  const startIndex = nonNegIntParam(url.searchParams.get("startIndex"), 0);
+  if (startIndex === null) return json(400, { error: "startIndex must be a non-negative integer" });
+  const limit = posIntCappedParam(url.searchParams.get("limit"), TRANSCRIPT_DEFAULT_LIMIT, TRANSCRIPT_MAX_LIMIT);
+  if (limit === null) return json(400, { error: `limit must be a positive integer (≤ ${TRANSCRIPT_MAX_LIMIT})` });
+  const idleMs = posIntCappedParam(url.searchParams.get("idleMs"), TRANSCRIPT_DEFAULT_IDLE_MS, TRANSCRIPT_MAX_IDLE_MS);
+  if (idleMs === null) return json(400, { error: `idleMs must be a positive integer (≤ ${TRANSCRIPT_MAX_IDLE_MS})` });
+
+  // A machine credential leaves a per-request trail (same contract as the sibling reads). The
+  // sessionId is stamped so a transcript read is itself join-able back to the audit log.
+  await appendAudit({
+    org: deploymentOrg(),
+    platform: "control",
+    workspace: "control",
+    principalId: identity.principalId, // "svc:<name>"
+    action: "control.service_call",
+    detail: { service: identity.principalId, view: "transcript", sessionId, startIndex, limit },
+  });
+
+  const session = attachSession(sessionId);
+
+  // OPE-333 — existence BEFORE replay. A missing id used to reach the drain and idle out to an
+  // empty 200; now it is a 404 in probe time, and a live session pays one index read.
+  const existence = await probeSessionExists(session as ProbeableSession, TRANSCRIPT_PROBE_MS);
+  if (existence === "missing") return transcriptNotFound(sessionId);
+
+  let stream: ReadableStream<SourceStreamEvent>;
+  try {
+    stream = (await session.getEventStream({ startIndex })) as unknown as ReadableStream<SourceStreamEvent>;
+  } catch {
+    // Unknown/expired sessionId or an unreadable stream → 404 (do not distinguish "never existed"
+    // from "expired" — same non-enumeration posture as an unknown webhook id).
+    return transcriptNotFound(sessionId);
+  }
+
+  try {
+    const { events, complete } = await drainSessionStream(stream, startIndex, limit, idleMs);
+    // The INCONCLUSIVE-probe backstop, and it encodes the same invariant the probe does: a durable
+    // eve session records `session.started` at index 0, so a full replay (`startIndex === 0`) that
+    // yields nothing is an id that resolved to nothing. Deliberately narrow — at a non-zero
+    // startIndex an empty page is a legitimate "no new events since your cursor", which is exactly
+    // the paging arm the probe exists to keep answering 200.
+    if (existence === "unknown" && events.length === 0 && startIndex === 0) return transcriptNotFound(sessionId);
+    return json(200, { sessionId, found: true, startIndex, nextIndex: startIndex + events.length, complete, count: events.length, events });
+  } catch (err) {
+    return json(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+/**
+ * Handle `GET /control/v1/session/<sessionId>/model-calls[?turnId&limit&body]` — one session's
+ * captured model-call bodies (`model_call_capture`, OPE-846), oldest first, as JSON.
+ *
+ * 🔴 THIS IS THE MOST SENSITIVE READ ON THIS MOUNT. A capture body is the whole composed request:
+ * the system prompt, every rendered member message, every tool result — verbatim, unredacted. It is
+ * strictly MORE than the transcript route returns, because it is the transcript as the model saw it
+ * plus the harness's own edits. So it takes the identical, non-negotiable gate: fail-closed 404 with
+ * no service tokens configured, 401 on a missing or non-matching bearer (the same constant-time hash
+ * compare), and one `control.service_call` audit row per authenticated call. No agent tool reaches
+ * this route and none may be given one.
+ *
+ * `body=0` returns metadata only — seq, turn/step, model, sha256, byte counts. That is the read for
+ * counting, for the capture-vs-step cross-check, and for choosing a cut point; it never moves prompt
+ * bytes. `body=1` (the default) returns `bodyGzipB64` and is capped hard, because one body can be
+ * hundreds of KB.
+ *
+ * Statuses: 404 mode off, 401 missing/bad bearer, 400 bad param, 200 with `count` + `captures`.
+ * An unknown session id returns `200 {count: 0}` and NOT a 404 — unlike the transcript route, this
+ * one asks the operational store, which cannot distinguish "no such session" from "capture was
+ * never armed for that session". Answering 404 would assert the former; both are honestly "nothing
+ * recorded here".
+ */
+export async function handleSessionModelCallsRead(req: Request, params: Readonly<Record<string, string>>): Promise<Response> {
+  const identity = await authorizeRead(req);
+  if (identity instanceof Response) return identity;
+
+  const sessionId = (params["sessionId"] ?? "").trim();
+  if (!sessionId) return json(400, { error: "expected path param: sessionId" });
+
+  const url = new URL(req.url);
+  const rawBody = (url.searchParams.get("body") ?? "").trim();
+  const includeBody = rawBody === "" ? true : rawBody === "1" || rawBody.toLowerCase() === "true";
+  const cap = includeBody ? MODEL_CALLS_MAX_LIMIT_WITH_BODY : MODEL_CALLS_MAX_LIMIT;
+  const limit = posIntCappedParam(url.searchParams.get("limit"), Math.min(MODEL_CALLS_DEFAULT_LIMIT, cap), cap);
+  if (limit === null) return json(400, { error: `limit must be a positive integer (≤ ${cap} for this body mode)` });
+  const turnId = (url.searchParams.get("turnId") ?? "").trim() || undefined;
+
+  // A machine credential leaves a per-request trail, same contract as every sibling read. The
+  // counts and ids are recorded; no body byte ever reaches an audit row.
+  await appendAudit({
+    org: deploymentOrg(),
+    platform: "control",
+    workspace: "control",
+    principalId: identity.principalId, // "svc:<name>"
+    action: "control.service_call",
+    detail: { service: identity.principalId, view: "model_calls", sessionId, limit, includeBody, ...(turnId ? { turnId } : {}) },
+  });
+
+  try {
+    const captures = await getOperationalStore().modelCallCapturesForSession(deploymentOrg(), sessionId, { includeBody, limit, ...(turnId ? { turnId } : {}) });
+    return json(200, { sessionId, count: captures.length, includeBody, captures });
+  } catch (err) {
+    return json(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+/**
+ * Handle `GET /control/v1/model-calls/sessions` — every session with at least one
+ * `model_call_capture` row for this deployment's org, most-recently-active first (OPE-857).
+ *
+ * This is the retention operator's discovery read: an operator who armed `soak.capture`, ran a
+ * soak, and does not remember which sessions it produced has no other supported way to enumerate
+ * them (the sibling `model-calls` route needs a session id up front). No body byte is ever in this
+ * response — `sessionId`, first/last capture timestamp, row count, total uncompressed bytes.
+ *
+ * Same gate as {@link handleSessionModelCallsRead}: fail-closed 404 with no service tokens
+ * configured, 401 on a missing or non-matching bearer, one `control.service_call` audit row per
+ * authenticated call. This route never deletes anything — purge is a separate operator script over
+ * a direct store connection (`scripts/soak/soak-capture-purge.ts`), because this mount is
+ * READ-ONLY BY CONSTRUCTION (see the file header).
+ */
+export async function handleModelCallSessionsRead(req: Request): Promise<Response> {
+  const identity = await authorizeRead(req);
+  if (identity instanceof Response) return identity;
+
+  await appendAudit({
+    org: deploymentOrg(),
+    platform: "control",
+    workspace: "control",
+    principalId: identity.principalId, // "svc:<name>"
+    action: "control.service_call",
+    detail: { service: identity.principalId, view: "model_call_sessions" },
+  });
+
+  try {
+    const sessions = await getOperationalStore().modelCallCaptureSessions(deploymentOrg());
+    return json(200, { count: sessions.length, sessions });
+  } catch (err) {
+    return json(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}