@open-everywhere/core 0.1.0

package/agent/control/views.ts

@@ -0,0 +1,1289 @@
+// Control-plane VIEWS — the read models behind the management surface, as pure
+// JSON-serialisable data (no console, no transport). The MCP control server
+// (server.ts) wraps these; a future remote HTTP/OAuth transport and any thin CLI
+// reuse the SAME functions, so "what you can inspect" is defined once.
+//
+// These mirror the existing inspection scripts (scripts/spend.ts, routines.ts,
+// audit.ts, access-preview.ts) but return structured data instead of printing —
+// agents and dashboards consume JSON, humans got the scripts. All read-only; no
+// secret VALUES ever leave (only secretRef *names*, which are env-var labels).
+
+import { spendRollup, spendRoot } from "../spend/store.js";
+import { type Caps } from "../spend/spend.js";
+import { resolveCaps, applyCapOverrides, activeSpendLimitsForOrg, domainNameForScope, resolveUserCaps, userCapInventory, type UserCapRow } from "../spend/caps.js";
+import { parseScopeKey } from "../access/scope-key.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { listAllRoutines, routinesRoot } from "../routines/store.js";
+import { isDue } from "../routines/schedule.js";
+import { describeTrigger } from "../routines/routine.js";
+import { describeBound } from "../routines/bound.js";
+import { describeStall } from "../routines/stall.js";
+import { readAudit, auditRoot, type AuditFilter, type AuditReadRow } from "../audit/audit.js";
+import { getConfig } from "../access/config.js";
+import { windowedSupervisorEnabled, windowIdFor, windowModeFor, resolveDomainForChannel, domainRoster } from "../memory/domain.js";
+import { principalSurfaces } from "../identity/principals.js";
+import { unionPrincipals } from "../identity/link-resolve.js";
+import { confirmedLinkSetPrincipals } from "../identity/link-store.js";
+import { resolveAccess, type ResolveRequest, type SessionMode } from "../access/resolver.js";
+import { usageSummary } from "../spend/usage-events.js";
+import type { CapLevel, UsageSummaryRow } from "../operational/store.js";
+import { resolveAssumedModel, rowCostUsd, pricingMix, pricingNote, filterToDomain, buildRoutinePredictions, type RoutinePredictionRow } from "../spend/reporting.js";
+import { modelPricing, estimateCostUsd } from "../spend/pricing.js";
+import { deploymentOrg } from "../identity/binding.js";
+import { listDomainSkills, listDomainSkillRevisions } from "../skills/domain-skills.js";
+import type { DomainSkillRow, DomainSkillRevisionRow } from "../operational/store.js";
+import { providerById, type MemoryAccess } from "../memory/provider.js";
+import { siloAccess } from "../memory/resolve.js";
+import { siloTier } from "../memory/store.js";
+import { controlPartition } from "../memory/partition.js";
+import { sourceLabel } from "../memory/listing.js";
+import { siloCoveringDomains, roleCoversScope } from "./auth.js";
+import type { MemorySilo } from "../memory/silo.js";
+import { actionKind, summarizeFrozenRow } from "../approvals/actions.js";
+import type { ApproverPolicy } from "../approvals/types.js";
+
+const currentPeriod = (): string => new Date().toISOString().slice(0, 7);
+
+// --- spend ------------------------------------------------------------------
+// item 16 closeout: caps shown here are EFFECTIVE (config-as-code overlaid with any
+// active admin override, via activeSpendLimitsForOrg + applyCapOverrides — the same
+// pure overlay effectiveCaps uses, just batched once per org instead of once per
+// scope) so this control-plane view agrees with the spend gate (spend/check.ts's
+// scopeOverBudget). USD is the ledger's write-time-priced `usd_micros` (OPE-265 —
+// sandbox runtime included, OPE-266), the SAME sums the gate reads, so the figure
+// shown for a period equals what the gate enforces for that period.
+export interface SpendSurfaceRow {
+  readonly org: string;
+  readonly surfaceKey: string;
+  readonly tokens: number;
+  readonly tokenCap: number | null;
+  readonly tokenOver: boolean;
+  readonly usd: number;
+  readonly usdCap: number | null;
+  readonly usdOver: boolean;
+  readonly over: boolean;
+}
+export interface SpendWorkspaceRow {
+  readonly key: string; // org/platform/workspace
+  readonly tokens: number;
+  readonly tokenCap: number | null;
+  readonly tokenOver: boolean;
+  readonly usd: number;
+  readonly usdCap: number | null;
+  readonly usdOver: boolean;
+  readonly over: boolean;
+}
+export interface SpendView {
+  readonly root: string;
+  readonly period: string;
+  readonly surfaces: readonly SpendSurfaceRow[];
+  readonly workspaces: readonly SpendWorkspaceRow[];
+  /**
+   * PER-PERSON allowances (OPE-274), config-sourced AND override-sourced — see
+   * spend/caps.ts's {@link UserCapRow}. Deliberately a SEPARATE list rather than rows in
+   * `surfaces`: the person axis is not a place, and folding an allowance into a surface row
+   * would suggest it replaced that surface's cap, which is precisely what checkCap refuses to
+   * let it do. Keyed by org (`byOrg`) — a shape from when this view spanned every org's ledgers
+   * at once. Since OPE-1446 it holds exactly one key, the deployment's own org; the map survives
+   * because it says WHOSE allowances these are rather than leaving the reader to assume it.
+   *
+   * NO SPEND FIGURES HERE, on purpose: this answers "what allowances exist" — the question that
+   * had no read at all before, and the reason an admin could not explain a per-user refusal.
+   * "What has this person spent" is `usage_report`/`usageSummaryView`'s question, and it is
+   * DM-shaped data (anti-doxxing, reporting.ts's `(dms)` bucket) rather than governance config.
+   */
+  readonly userCaps: Readonly<Record<string, readonly UserCapRow[]>>;
+}
+
+export async function spendView(period: string = currentPeriod()): Promise<SpendView> {
+  // OPE-265: both denominations come from the ONE spend-ledger rollup — tokens AND usd
+  // (write-time-priced, sandbox runtime included) — so this view agrees with the gate
+  // by construction rather than by two reads happening to align.
+  // 🔴 THE ROLLUP IS PINNED TO THE DEPLOYMENT'S OWN ORG (OPE-1446), and the pin is the store
+  // filter rather than a filter over the answer — a foreign tenant's rows never enter the process.
+  // This read used to call `spendRollup()` bare, which rolls up every org's ledger, so a read-only
+  // service token (control/auth.ts mints one with roles ["admin"]) received every tenant's surface
+  // keys with their token and USD totals, and `userCaps` named every tenant's per-person
+  // allowances. The org is a property of the deployment, never a caller argument: `spend_report`
+  // advertises no `org` and this view accepts none, the same shape `audit_query` has (the argument
+  // is in control/auth.ts's `foreignOrgDenial`).
+  // The PERIOD is a store filter too (OPE-1653), for cost rather than for disclosure: this read
+  // used to load the org's whole ledger history and keep one month of it, so an old deployment
+  // paid for every month it ever wrote to render the current one. The `r.period` conjunct below
+  // is kept as the second belt, exactly as the `l.org` conjunct is kept in `spend_report`.
+  const org = deploymentOrg();
+  const rollup = (await spendRollup(org, { period })).filter((r) => r.period === period);
+
+  // Overrides are fetched ONCE for the org, not once per surface. The org is fetched even with no
+  // ledger rows this period (OPE-274): a deployment can have declared a per-user allowance and
+  // spent nothing yet, and "no spend" must not read as "no allowance" in the one view that answers
+  // what allowances exist.
+  const limits = await activeSpendLimitsForOrg(org);
+  const effCapsFor = (workspaceKey: string, surfaceKey: string): Caps => {
+    // Batch view over raw ledger surfaceKeys — no live session mode/trust to classify
+    // from, so this resolves the EXPLICIT-domain half of the perDomain layer only
+    // (domainNameForScope with mode/trust omitted); the dm/public criteria layer is
+    // covered wherever a live binding is available (the enforcement gate, /oe budget
+    // status, the propose tools).
+    // The SAME domain name reaches both halves: the config resolution's perDomain layer AND the
+    // runtime override overlay's domain-level bridge. Dropping it from the second half made an
+    // active level:"domain" override invisible in this view while the gate enforced it (OPE-1804),
+    // which is the "agrees with the gate by construction" claim above failing.
+    const domainName = domainNameForScope(surfaceKey);
+    const config = resolveCaps(workspaceKey, surfaceKey, domainName);
+    return limits.length ? applyCapOverrides(config, limits, workspaceKey, surfaceKey, domainName) : config;
+  };
+
+  const surfaces: SpendSurfaceRow[] = [];
+  const byWorkspace = new Map<string, { tokens: number; usd: number }>();
+  // Each row carries its OWN `org` rather than the pinned one. The store filter above already
+  // narrowed the read, so the two agree — and a row that somehow did not match would surface as
+  // itself instead of being relabelled as ours, which is the failure a reader can still see.
+  for (const { org: rowOrg, surfaceKey, tokens, usd } of rollup) {
+    const workspaceKey = surfaceKey.split("/").slice(0, 2).join("/");
+    const caps = effCapsFor(workspaceKey, surfaceKey);
+    const tokenCap = caps.surfaceMonthlyTokens ?? null;
+    const tokenOver = tokenCap != null && tokens >= tokenCap;
+    const usdCap = caps.surfaceMonthlyUsd ?? null;
+    const usdOver = usdCap != null && usd >= usdCap;
+    surfaces.push({ org: rowOrg, surfaceKey, tokens, tokenCap, tokenOver, usd, usdCap, usdOver, over: tokenOver || usdOver });
+    const wk = `${rowOrg}/${workspaceKey}`;
+    const acc = byWorkspace.get(wk) ?? { tokens: 0, usd: 0 };
+    byWorkspace.set(wk, { tokens: acc.tokens + tokens, usd: acc.usd + usd });
+  }
+  const workspaces: SpendWorkspaceRow[] = [...byWorkspace].map(([key, { tokens, usd }]) => {
+    // key is "org/platform/workspace"; caps are keyed by the workspaceKey (sans org leg).
+    const workspaceKey = key.slice(key.indexOf("/") + 1);
+    const caps = effCapsFor(workspaceKey, "");
+    const tokenCap = caps.workspaceMonthlyTokens ?? null;
+    const tokenOver = tokenCap != null && tokens >= tokenCap;
+    const usdCap = caps.workspaceMonthlyUsd ?? null;
+    const usdOver = usdCap != null && usd >= usdCap;
+    return { key, tokens, tokenCap, tokenOver, usd, usdCap, usdOver, over: tokenOver || usdOver };
+  });
+  // The deployment's own org only, from the SAME already-fetched override list the cap overlay
+  // used — no extra store read. A deployment with no allowance declared anywhere yields an empty
+  // array under its own key rather than an empty map, so "there are no per-user caps here" is a
+  // readable answer rather than an absence a reader has to interpret.
+  const userCaps = { [org]: userCapInventory(limits) };
+  return { root: spendRoot(), period, surfaces, workspaces, userCaps };
+}
+
+// --- routines ---------------------------------------------------------------
+export interface RoutineRow {
+  readonly id: string;
+  readonly org: string;
+  readonly surfaceKey: string;
+  readonly status: string;
+  readonly trigger: string;
+  readonly nextRunAt: string | null;
+  readonly prompt: string;
+  readonly lastOutcome?: string;
+  readonly consecutiveFailures?: number;
+  readonly disabledReason?: string;
+  /** OPE-184, `event` subscriptions only: when this routine's filter FIRST matched a delivery and
+   *  when it last did. `nextRunAt` is structurally null for an event trigger, so these are the only
+   *  liveness signals it has — and they are stamped on MATCH, before the grant/target/cap checks,
+   *  so a lastMatchAt with no fires says the filter works and something downstream does not.
+   *  Present-only, exactly like the fields above: absent means "never matched". */
+  readonly firstMatchAt?: string;
+  readonly lastMatchAt?: string;
+  /**
+   * OPE-248 / OPE-253 — the two things this view could not answer about a durable job: how much of
+   * its ceiling is left, and whether it is BLOCKED rather than working. Both present-only, exactly
+   * like the fields above.
+   *
+   * `ceiling` shipped to `list_routines` (the room) in OPE-248 and was not carried here; the argument
+   * for it — a limit nobody can enumerate is not governable — applies at least as strongly to the
+   * OPERATOR's read, which is where someone goes after "why did this job stop?". `stalled` is the
+   * reading that used to have no surface at all: "waiting on a human click" and "running fine" were
+   * the same row.
+   */
+  readonly ceiling?: string;
+  readonly stalled?: string;
+}
+export interface RoutinesView {
+  readonly root: string;
+  readonly total: number;
+  readonly dueCount?: number;
+  readonly routines: readonly RoutineRow[];
+}
+
+/**
+ * Every routine the caller's scope covers.
+ *
+ * SCOPING IS MANDATORY-BY-DEFAULT (OPE-146 / audit §S8). `listAllRoutines()` is literally
+ * every routine in every org, prompt included, and this view used to return it verbatim —
+ * so any principal who could reach `routines_list` read the whole fleet's standing
+ * instructions across tenants. `org` now filters at the view, and control/server.ts gates
+ * the ask with `scopeDenial` (org-wide ⇒ "admin"; a `surfaceKey` ⇒ a covering
+ * `domain:<name>` role is enough). The org filter lives HERE, not only at the tool, so a
+ * future caller of the view cannot re-open the leak by forgetting the gate — the widest
+ * thing an unfiltered call can now do is default to the deployment's own org.
+ */
+export async function routinesView(opts: { onlyDue?: boolean; org?: string; surfaceKey?: string } = {}): Promise<RoutinesView> {
+  const now = new Date();
+  const org = opts.org ?? deploymentOrg();
+  const all = (await listAllRoutines()).filter((r) => r.org === org && (opts.surfaceKey === undefined || r.surfaceKey === opts.surfaceKey));
+  const dueCount = all.filter((r) => r.status === "active" && isDue(r.nextRunAt, now)).length;
+  const rows = opts.onlyDue ? all.filter((r) => r.status === "active" && isDue(r.nextRunAt, now)) : all;
+  return {
+    root: routinesRoot(),
+    total: all.length,
+    ...(opts.onlyDue ? { dueCount } : {}),
+    routines: rows.map((r) => ({
+      id: r.id,
+      org: r.org,
+      surfaceKey: r.surfaceKey,
+      status: r.status,
+      trigger: describeTrigger(r.trigger, r.report),
+      nextRunAt: r.nextRunAt ?? null,
+      prompt: r.prompt,
+      ...(r.lastOutcome ? { lastOutcome: r.lastOutcome } : {}),
+      ...(r.consecutiveFailures ? { consecutiveFailures: r.consecutiveFailures } : {}),
+      ...(r.disabledReason ? { disabledReason: r.disabledReason } : {}),
+      ...(r.firstMatchAt ? { firstMatchAt: r.firstMatchAt } : {}),
+      ...(r.lastMatchAt ? { lastMatchAt: r.lastMatchAt } : {}),
+      ...(describeBound(r) !== null ? { ceiling: describeBound(r)! } : {}),
+      ...(describeStall(r) !== null ? { stalled: describeStall(r)! } : {}),
+    })),
+  };
+}
+
+// --- audit ------------------------------------------------------------------
+export interface AuditView {
+  readonly root: string;
+  readonly filter: AuditFilter;
+  readonly capped: boolean;
+  /** Newest-first. Each row carries its storage `seq` (OPE-1933) — the log's only monotonic
+   *  order key, and what a reader anchors on when the box's wall clock steps backward. */
+  readonly entries: readonly AuditReadRow[];
+}
+
+/** The audit window, row-capped. `filter.org` is REQUIRED (OPE-1812) — this view composes
+ *  `readAudit`, which refuses a read that names no org, and every control caller pins
+ *  `deploymentOrg()`. */
+export async function auditView(filter: AuditFilter): Promise<AuditView> {
+  const limit = filter.limit ?? 200;
+  const f: AuditFilter = { ...filter, limit };
+  const entries = await readAudit(f);
+  return { root: auditRoot(), filter: f, capped: entries.length === limit, entries };
+}
+
+// --- overrides drift view ("what's overlaying config, and does it need reconciling?") ---
+// Overrides are TEMPORARY BRIDGES (docs/control-plane.md). This is the reconcile
+// worklist: every live override, who set it and why, whether it's expired (spend only),
+// and whether it diverges from the git config baseline. Spend overrides should be PR'd
+// into the budgets registry (agent/spend/budgets.ts) or cleared; connector revokes are
+// sticky (no auto-expiry) and cleared deliberately or removed from bundles.ts.
+export interface SpendOverrideDriftRow {
+  readonly scopeKey: string;
+  readonly level: CapLevel;
+  /** The override's components — ≥1 present (an override sets tokens, USD, or both). */
+  readonly monthlyTokens?: number;
+  readonly monthlyUsd?: number;
+  /** Config-as-code baselines for the same scope+level (null = uncapped in config).
+   *  `configCap` = the token baseline; the name predates USD caps and is kept so
+   *  existing consumers keep reading the field they always did. */
+  readonly configCap: number | null;
+  readonly configCapUsd: number | null;
+  readonly divergesFromConfig: boolean;
+  readonly expiresAt?: number;
+  readonly expired: boolean;
+  readonly reason?: string;
+  readonly setBy?: string;
+}
+export interface ConnectorOverrideDriftRow {
+  readonly scopeKey: string;
+  readonly connector: string;
+  readonly granted: boolean; // false = revoke (the only kind that can exist — narrow-only)
+  readonly sticky: true; // no auto-expiry: clearing would re-open access
+  readonly reason?: string;
+  readonly setBy?: string;
+}
+export interface HaltOverrideDriftRow {
+  readonly orgWide: boolean;
+  readonly level?: CapLevel;
+  readonly scopeKey?: string;
+  readonly setAt: string;
+  readonly setBy?: string;
+  readonly setRef?: string;
+}
+export interface OverridesView {
+  readonly org: string;
+  readonly now: number;
+  readonly spend: readonly SpendOverrideDriftRow[];
+  readonly connectors: readonly ConnectorOverrideDriftRow[];
+  readonly halts: readonly HaltOverrideDriftRow[];
+  readonly note: string;
+}
+
+export async function overridesView(org: string, now: number = Date.now()): Promise<OverridesView> {
+  const store = getOperationalStore();
+  const [limits, connectors, halts] = await Promise.all([store.spendLimits(org), store.allConnectorOverrides(org), store.activeHalts(org)]);
+  const spend: SpendOverrideDriftRow[] = limits.map((l) => {
+    // "domain" reads the config baseline the same way "surface" does — the SURFACE-shaped
+    // fields, just resolved via a domain-name match (l.scopeKey IS the domain's name for
+    // this level) rather than a real surfaceKey. No real workspaceKey/surfaceKey exists for
+    // a domain scope, so both are passed empty (never matches perSurface/perWorkspace).
+    //
+    // "user" (OPE-274) leaves the place ladder entirely: the baseline is the config-as-code
+    // `perUser` resolution for the person the scope key names, read through the SAME function
+    // the gate uses (spend/caps.ts's resolveUserCaps, qualified-key form) so `divergesFromConfig`
+    // compares like with like. Resolving it through resolveCaps would compare a person's
+    // override against a place's cap and report every user row as diverging from "uncapped".
+    const parsedUser = l.level === "user" ? parseScopeKey(l.scopeKey) : undefined;
+    const config: Caps =
+      l.level === "user"
+        ? parsedUser?.kind === "principal"
+          ? resolveUserCaps(parsedUser.id, parsedUser.platform, parsedUser.tenant)
+          : {}
+        : l.level === "workspace"
+          ? resolveCaps(l.scopeKey, "")
+          : l.level === "domain"
+            ? resolveCaps("", "", l.scopeKey)
+            : resolveCaps(l.scopeKey.split("/").slice(0, 2).join("/"), l.scopeKey, domainNameForScope(l.scopeKey));
+    const configCap = (l.level === "workspace" ? config.workspaceMonthlyTokens : config.surfaceMonthlyTokens) ?? null;
+    const configCapUsd = (l.level === "workspace" ? config.workspaceMonthlyUsd : config.surfaceMonthlyUsd) ?? null;
+    return {
+      scopeKey: l.scopeKey,
+      level: l.level,
+      ...(l.monthlyTokens != null ? { monthlyTokens: l.monthlyTokens } : {}),
+      ...(l.monthlyUsd != null ? { monthlyUsd: l.monthlyUsd } : {}),
+      configCap,
+      configCapUsd,
+      // Component-wise: an override diverges when a component it CARRIES differs from
+      // the config baseline for that component. A component the override doesn't carry
+      // isn't overriding anything, so it can't diverge.
+      divergesFromConfig: (l.monthlyTokens != null && l.monthlyTokens !== configCap) || (l.monthlyUsd != null && l.monthlyUsd !== configCapUsd),
+      ...(l.expiresAt != null ? { expiresAt: l.expiresAt } : {}),
+      expired: l.expiresAt != null && l.expiresAt <= now,
+      ...(l.reason ? { reason: l.reason } : {}),
+      ...(l.setBy ? { setBy: l.setBy } : {}),
+    };
+  });
+  const connectorRows: ConnectorOverrideDriftRow[] = connectors.map((c) => ({
+    scopeKey: c.scopeKey,
+    connector: c.connector,
+    granted: c.granted,
+    sticky: true,
+    ...(c.reason ? { reason: c.reason } : {}),
+    ...(c.setBy ? { setBy: c.setBy } : {}),
+  }));
+  return {
+    org,
+    now,
+    spend,
+    connectors: connectorRows,
+    halts: halts.map((h) => ({
+      orgWide: h.address.orgWide,
+      ...(!h.address.orgWide ? { level: h.address.level, scopeKey: h.address.scopeKey } : {}),
+      setAt: h.setAt,
+      ...(h.setBy ? { setBy: h.setBy } : {}),
+      ...(h.setRef ? { setRef: h.setRef } : {}),
+    })),
+    note: 'Overrides are temporary bridges — reconcile each into config (PR) or clear it. Spend rows with divergesFromConfig=true need a spend-budgets PR (agent/spend/budgets.ts, or clear_spend_limit); expired=true rows are no longer applied and should be cleared. A level:"user" row reconciles into perUser.overrides keyed on the same person — drop the "user:" marker ("user:slack/U1" -> "slack/U1"). Connector revokes are sticky (no auto-expiry — clearing re-opens access); clear deliberately or remove the grant from bundles.ts. Active halts have no expiry and stay until an operator resumes their exact address.',
+  };
+}
+
+// --- usage summary (control-plane view of Batch A3's usage_events + B1's $ estimate) ---
+// Scope-gating (org-wide vs one domain vs one surfaceKey) happens at the CALL SITE
+// (control/server.ts's scopeDenial, same pattern as overridesView) — this is pure data
+// shaping, like every other view in this file.
+export interface UsageSummaryQuery {
+  readonly org: string;
+  /** Bucket to one memory domain (spend/reporting.ts's domainOfUsageRow) — mutually
+   *  exclusive in intent with surfaceKey (domain takes precedence if both are set). */
+  readonly domain?: string;
+  /** Bucket to one surface (prefix-matched, same convention as UsageSummaryFilter). */
+  readonly surfaceKey?: string;
+  readonly sinceDays?: number;
+  readonly assumedModelId?: string;
+}
+export interface UsageSummaryViewRow extends UsageSummaryRow {
+  readonly costUsd?: number;
+}
+export interface UsageSummaryViewResult {
+  readonly org: string;
+  readonly domain?: string;
+  readonly surfaceKey?: string;
+  readonly sinceDays: number;
+  readonly since: string;
+  readonly rows: readonly UsageSummaryViewRow[];
+  readonly pricedModel?: string;
+  /** Routine-fired cost projection (spend/reporting.ts's buildRoutinePredictions), same
+   *  estimate the spend_report agent tool surfaces — always an estimate, never a bill. */
+  readonly routinePredictions: readonly RoutinePredictionRow[];
+  readonly note: string;
+}
+
+export async function usageSummaryView(q: UsageSummaryQuery): Promise<UsageSummaryViewResult> {
+  const sinceDays = q.sinceDays ?? 30;
+  const since = new Date(Date.now() - sinceDays * 24 * 60 * 60 * 1000).toISOString();
+  const all = await usageSummary(q.org, { sinceTs: since, ...(q.surfaceKey && !q.domain ? { surfaceKeyPrefix: q.surfaceKey } : {}) });
+  const rows = q.domain ? filterToDomain(all, q.domain, getConfig().loadDomains()) : all;
+  // Pricing needs no readiness await (OPE-1148): every rate is code — the deployer table plus
+  // core's BUILT_IN — so `modelPricing` is synchronous and always fully resolved. The await this
+  // read used to carry existed only for a live catalog source's fire-and-forget first fetch,
+  // which could render a real price as unpriced on a fresh instance. That source is gone.
+  const assumed = resolveAssumedModel(q.assumedModelId);
+  // Per-row exact pricing (item 17): a row carrying its own stamped model (model/
+  // model-stamp.ts, via hooks/spend.ts) prices at THAT model's rate; only a stampless
+  // row falls back to the assumed model — same rule as the agent-facing report tools
+  // (spend/reporting.ts's rowCostUsd).
+  const priced: UsageSummaryViewRow[] = rows.map((r) => {
+    // 🔴 "aggregate": these are store-side rollups — `UsageSummaryRow.events` counts the model calls
+    // folded into each — so `r.inputTokens` is a sum with no prompt size in it. Pricing it as one
+    // call would charge the long-context tier to any group whose WINDOW crossed 272,001 input
+    // tokens and report roughly double the ledger figure shown beside it (OPE-2055).
+    const costUsd = rowCostUsd(r, assumed, "aggregate");
+    return costUsd !== undefined ? { ...r, costUsd } : r;
+  });
+  const routineRows = rows.filter((r) => r.kind === "routine");
+  const routinePredictions = await buildRoutinePredictions(q.org, routineRows, assumed.pricing);
+  return {
+    org: q.org,
+    ...(q.domain ? { domain: q.domain } : {}),
+    ...(q.surfaceKey ? { surfaceKey: q.surfaceKey } : {}),
+    sinceDays,
+    since,
+    rows: priced,
+    ...(assumed.model ? { pricedModel: assumed.model } : {}),
+    routinePredictions,
+    note: pricingNote(pricingMix(rows, assumed), assumed),
+  };
+}
+
+// --- usage window (priced, per surface × model — the harness/CI cost probe) ----------
+// "What did this deployment spend since <t> across these workspaces?" — the read the
+// e2e driver needs to price a live run (previously a raw read-only Postgres query;
+// per doctrine it belongs on the control plane instead). Reuses the SAME store read
+// as usage_summary (usageSummary — no new SQL): those rows group by (surfaceKey,
+// principalId, kind, routineId, surfaceMode, model), and sums/counts re-aggregate EXACTLY to (surfaceKey,
+// model) — unlike `sessions` (a distinct count), which is why this view doesn't
+// report one. Pricing is per-row EXACT (spend/pricing.ts's modelPricing on the row's
+// own stamped model — every model call is stamped since item 17): DELIBERATELY no
+// assumed-model fallback for stampless rows here, unlike usage_summary — this view
+// exists to price a run precisely, so an unstamped or unpriced row shows tokens with
+// estimatedUsd omitted (and its model under unpricedModels), never a guessed number.
+
+export interface UsageWindowQuery {
+  /** Window start — any Date.parse-able ISO-8601 timestamp (normalised before filtering). */
+  readonly sinceIso: string;
+  /** Workspace scopes, each exactly "platform/workspace" (e.g. "slack/T0EXAMPLE02"). */
+  readonly workspaceKeys: readonly string[];
+  /** Defaults to the deployment's declared org (else "default") — the value usage rows are stamped with. */
+  readonly org?: string;
+  /**
+   * OPE-402: additionally exclude a row whose owning session had any recorded usage event
+   * before this bound (UsageSummaryFilter's sessionStartedAfter, same normalisation as
+   * `sinceIso`). Closes the leak `sinceIso` alone cannot: a session that STARTED before the
+   * run but flushes a write mid-run is otherwise unexcludable, because `sinceIso` only bounds
+   * the write's own ts, not the session's. Optional — absent means today's behaviour
+   * (byte-identical).
+   */
+  readonly sessionStartedAfter?: string;
+}
+export interface UsageWindowRow {
+  readonly surfaceKey: string;
+  /** Absent for rows written with no stamped model (they price only via unpricedModels honesty, i.e. not at all). */
+  readonly model?: string;
+  /** Usage-event row count in this group (≈ model-call count — an exact sum). */
+  readonly calls: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly cacheReadTokens: number;
+  readonly cacheWriteTokens: number;
+  /** Exact per-row estimate at the stamped model's configured rate; ABSENT when the
+   *  model is unpriced or the row is unstamped — never a guessed figure. */
+  readonly estimatedUsd?: number;
+}
+export interface UsageWindowResult {
+  readonly org: string;
+  /** The normalised ISO actually used for the ts >= filter. */
+  readonly since: string;
+  readonly workspaceKeys: readonly string[];
+  readonly rows: readonly UsageWindowRow[];
+  /** Sum of the priced rows only — an HONEST PARTIAL when unpricedModels is non-empty. */
+  readonly totalUsd: number;
+  /** Model ids (or "(unstamped)") whose rows carry tokens but no $ — priced nowhere. */
+  readonly unpricedModels: readonly string[];
+  /** The normalised ISO actually used for the session-start filter — present only when the
+   *  query carried one (OPE-402). Echoed for the same reason `since` is: so a caller can
+   *  confirm what was actually applied, not just what it asked for. */
+  readonly sessionStartedAfter?: string;
+  /** What the session bound REMOVED from the figures above — present exactly when
+   *  `sessionStartedAfter` is (OPE-1622). See {@link UsageWindowExcluded}. */
+  readonly excluded?: UsageWindowExcluded;
+}
+
+/**
+ * THE SPEND THE SESSION BOUND TOOK OUT OF THIS READ (OPE-1622).
+ *
+ * 🔴 WHY A READ MUST REPORT THIS. `sessionStartedAfter` excludes a session WHOLESALE when the store
+ * holds any earlier usage row for it — not just that session's pre-window rows (see
+ * `UsageSummaryFilter.sessionStartedAfter`). A STANDING SEAT is a session that outlives a run: the
+ * Teams and Slack front doors resume a `channel_session` row and rotate it, never re-mint one per
+ * run, so its earliest row predates every later run and the bound drops ALL of its spend. A surface
+ * served by a seat therefore reads $0.0000 for a run in which it really spent money, with no defect
+ * anywhere in the write path — which is exactly how ship #183's Teams $0 was first read as a missing
+ * spend hook (OPE-1607, disproved).
+ *
+ * So the bound stays as it is — loosening it reopens the leak OPE-402 closed — and the read says
+ * what it dropped instead of hiding it. A zero here is a real answer: the bound applied and excluded
+ * nothing.
+ *
+ * COST: computing it costs one SECOND `usageSummary` per workspace key, unbounded. That read only
+ * happens when the query carries a bound, so a plain window read is unchanged.
+ */
+export interface UsageWindowExcluded {
+  /** The surfaces that LOST rows to the bound, sorted. This is the field that answers the question
+   *  the ticket was filed on — "which surface's $0.0000 is not really zero". */
+  readonly surfaceKeys: readonly string[];
+  /** Usage-event rows excluded. EXACT: a row count is additive, so the difference of two counts is
+   *  a count. */
+  readonly calls: number;
+  /** The excluded rows' $, priced per row exactly as `totalUsd` is — and, like `totalUsd`, an
+   *  HONEST PARTIAL when `unpricedModels` below is non-empty. */
+  readonly estimatedUsd: number;
+  /** Model ids (or "(unstamped)") among the EXCLUDED rows that carry tokens but no $ — the same
+   *  honesty `UsageWindowResult.unpricedModels` gives for the included ones. */
+  readonly unpricedModels: readonly string[];
+  /**
+   * Distinct excluded sessions, as an UPPER BOUND — never lower than the truth.
+   *
+   * 🔴 IT IS A BOUND AND NOT A COUNT, and the name says so rather than a comment nobody reads. The
+   * store's rollup grain is (surfaceKey, principalId, kind, routineId, surfaceMode, model) and `sessions` is a
+   * distinct count WITHIN a group, so a session whose rows span two models is counted twice here. An
+   * exact distinct count is not derivable from this grain and would need its own store read. Erring
+   * high is the correct direction for an honesty signal: it can overstate how much was hidden, never
+   * understate it.
+   */
+  readonly sessionsUpperBound: number;
+}
+
+const WORKSPACE_KEY_SHAPE = /^[^/\s]+\/[^/\s]+$/;
+
+/** The never-in-a-key group separator, the same convention spendView uses. */
+const USAGE_SEP = "\u0000";
+
+export async function usageWindowView(q: UsageWindowQuery): Promise<UsageWindowResult> {
+  const parsedSince = Date.parse(q.sinceIso);
+  if (Number.isNaN(parsedSince)) {
+    throw new Error(`sinceIso "${q.sinceIso}" is not a parseable ISO-8601 timestamp (e.g. "2026-07-07T12:00:00Z").`);
+  }
+  // Normalise before filtering: the stores compare ts LEXICOGRAPHICALLY against stamped
+  // ISO strings, so a parseable-but-non-ISO input must not reach the query raw.
+  const since = new Date(parsedSince).toISOString();
+  if (!Array.isArray(q.workspaceKeys) || q.workspaceKeys.length === 0) {
+    throw new Error('workspaceKeys must be a non-empty array of "platform/workspace" keys.');
+  }
+  for (const wk of q.workspaceKeys) {
+    if (typeof wk !== "string" || !WORKSPACE_KEY_SHAPE.test(wk)) {
+      throw new Error(`workspaceKeys entry "${String(wk)}" must be exactly "platform/workspace" (two segments, e.g. "slack/T1") — not a surface key or a bare platform.`);
+    }
+  }
+  // OPE-402: same shape of validation + normalisation as `sinceIso` above — a parseable-but-
+  // non-ISO input must not reach the store raw, since sessionStartedAfter compares
+  // LEXICOGRAPHICALLY against stamped ISO strings exactly like sinceTs does.
+  let sessionStartedAfter: string | undefined;
+  if (q.sessionStartedAfter !== undefined) {
+    const parsedSessionStartedAfter = Date.parse(q.sessionStartedAfter);
+    if (Number.isNaN(parsedSessionStartedAfter)) {
+      throw new Error(`sessionStartedAfter "${q.sessionStartedAfter}" is not a parseable ISO-8601 timestamp (e.g. "2026-07-07T12:00:00Z").`);
+    }
+    sessionStartedAfter = new Date(parsedSessionStartedAfter).toISOString();
+  }
+  const org = q.org ?? deploymentOrg();
+  const keys = [...new Set(q.workspaceKeys)];
+  // The trailing "/" makes the prefix exact at the workspace boundary ("slack/T1" must
+  // not also sweep up "slack/T1X/…"). Keys are deduped above, so no surface can be
+  // counted through two prefixes.
+  const grouped = await Promise.all(
+    keys.map((wk) => usageSummary(org, { sinceTs: since, surfaceKeyPrefix: `${wk}/`, ...(sessionStartedAfter !== undefined ? { sessionStartedAfter } : {}) })),
+  );
+
+  const { rows, totalUsd, unpricedModels } = priceGroups(grouped);
+  if (sessionStartedAfter === undefined) return { org, since, workspaceKeys: keys, rows, totalUsd, unpricedModels };
+
+  // OPE-1622 — the SAME window with no session bound, so the read can say what the bound REMOVED
+  // instead of reporting a silent $0.0000 for a surface served by a standing seat. Only reached when
+  // the query carries a bound, so a plain window read pays nothing for it.
+  const unbounded = await Promise.all(keys.map((wk) => usageSummary(org, { sinceTs: since, surfaceKeyPrefix: `${wk}/` })));
+  return {
+    org,
+    since,
+    workspaceKeys: keys,
+    rows,
+    totalUsd,
+    unpricedModels,
+    sessionStartedAfter,
+    excluded: excludedByBound(grouped, unbounded),
+  };
+}
+
+/** Collapse the store's rollup rows to the (surfaceKey, model) grain this view reports, and price
+ *  each one. Shared by the included figures and the OPE-1622 excluded slice, so the two can never
+ *  disagree about how a row is summed or priced. */
+function priceGroups(grouped: readonly (readonly UsageSummaryRow[])[]): { rows: UsageWindowRow[]; totalUsd: number; unpricedModels: string[] } {
+  const acc = new Map<string, { surfaceKey: string; model?: string; calls: number; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number }>();
+  for (const rows of grouped) {
+    for (const r of rows) {
+      const key = `${r.surfaceKey}${USAGE_SEP}${r.model ?? ""}`;
+      const a = acc.get(key) ?? { surfaceKey: r.surfaceKey, ...(r.model ? { model: r.model } : {}), calls: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
+      a.calls += r.events;
+      a.inputTokens += r.inputTokens;
+      a.outputTokens += r.outputTokens;
+      a.cacheReadTokens += r.cacheReadTokens;
+      a.cacheWriteTokens += r.cacheWriteTokens;
+      acc.set(key, a);
+    }
+  }
+
+  const unpriced = new Set<string>();
+  let totalUsd = 0;
+  const rows: UsageWindowRow[] = [...acc.values()]
+    .sort((a, b) => a.surfaceKey.localeCompare(b.surfaceKey) || (a.model ?? "").localeCompare(b.model ?? ""))
+    .map((r) => {
+      // 🔴 "aggregate": `acc` sums the rollup rows above across workspace keys, so this is a sum of
+      // sums — further still from any one call's prompt size. The tier must not fire (OPE-2055).
+      const usd = r.model ? estimateCostUsd(r, modelPricing(r.model), "aggregate") : undefined;
+      if (usd === undefined) unpriced.add(r.model ?? "(unstamped)");
+      else totalUsd += usd;
+      return { ...r, ...(usd !== undefined ? { estimatedUsd: usd } : {}) };
+    });
+  return { rows, totalUsd, unpricedModels: [...unpriced].sort() };
+}
+
+/**
+ * What the session bound removed: the UNBOUNDED read minus the BOUNDED one (OPE-1622).
+ *
+ * 🔴 THE DIFFERENCE IS TAKEN ON THE STORE'S OWN ROLLUP GRAIN, not on the collapsed rows this view
+ * returns. That is the only grain where the two reads are comparable row for row, and it is the
+ * grain `sessions` is a distinct count within — which is what makes `sessionsUpperBound` computable
+ * at all. The bounded read is a SUBSET of the unbounded one (the bound only ever removes sessions),
+ * so every difference is at or above zero; the `Math.max(0, …)` guards are belt-and-braces against a
+ * store that took a write between the two reads, never an expected case.
+ *
+ * The excluded slice is then priced by {@link priceGroups} — the same function that prices the
+ * included rows, so an excluded dollar and an included dollar are the same kind of number.
+ */
+function excludedByBound(
+  bounded: readonly (readonly UsageSummaryRow[])[],
+  unbounded: readonly (readonly UsageSummaryRow[])[],
+): UsageWindowExcluded {
+  const grainKey = (r: UsageSummaryRow): string =>
+    [r.surfaceKey, r.principalId ?? "", r.kind ?? "", r.routineId ?? "", r.model ?? ""].join(USAGE_SEP);
+  const boundedByGrain = new Map<string, UsageSummaryRow>();
+  for (const rows of bounded) for (const r of rows) boundedByGrain.set(grainKey(r), r);
+
+  const diffs: UsageSummaryRow[] = [];
+  const surfaceKeys = new Set<string>();
+  let calls = 0;
+  let sessionsUpperBound = 0;
+  for (const rows of unbounded) {
+    for (const u of rows) {
+      const b = boundedByGrain.get(grainKey(u));
+      const events = Math.max(0, u.events - (b?.events ?? 0));
+      sessionsUpperBound += Math.max(0, u.sessions - (b?.sessions ?? 0));
+      if (events === 0) continue;
+      calls += events;
+      surfaceKeys.add(u.surfaceKey);
+      diffs.push({
+        ...u,
+        events,
+        sessions: Math.max(0, u.sessions - (b?.sessions ?? 0)),
+        inputTokens: Math.max(0, u.inputTokens - (b?.inputTokens ?? 0)),
+        outputTokens: Math.max(0, u.outputTokens - (b?.outputTokens ?? 0)),
+        cacheReadTokens: Math.max(0, u.cacheReadTokens - (b?.cacheReadTokens ?? 0)),
+        cacheWriteTokens: Math.max(0, u.cacheWriteTokens - (b?.cacheWriteTokens ?? 0)),
+      });
+    }
+  }
+
+  const priced = priceGroups([diffs]);
+  return { surfaceKeys: [...surfaceKeys].sort(), calls, estimatedUsd: priced.totalUsd, unpricedModels: priced.unpricedModels, sessionsUpperBound };
+}
+
+// --- domain skills listing (control-plane mirror of the list_skills agent tool) -----
+export interface SkillsListQuery {
+  readonly org: string;
+  readonly domain: string;
+}
+export interface SkillsListResult {
+  readonly org: string;
+  readonly domain: string;
+  readonly skills: readonly DomainSkillRow[];
+}
+
+export async function skillsListView(q: SkillsListQuery): Promise<SkillsListResult> {
+  const skills = await listDomainSkills(q.org, q.domain);
+  return { org: q.org, domain: q.domain, skills };
+}
+
+// --- domain skill revision history (OPE-243 — the control-plane reader for OPE-237's
+// append-only body log). A domain skill is an approval-gated instruction package; without
+// this the only way to answer "what body did the approver actually agree to?" is a database
+// connection. DISCLOSURE: this is the SAME content class, at the SAME gate, as skillsListView
+// just above — a live skill's full body is already returned by `skills_list` to any
+// `domain:<name>` role covering it (no admin-only carve-out there), so a history of that
+// same skill's PAST bodies doesn't earn a tighter tier of its own; the server.ts call site
+// applies the identical scopeDenial(roles, {org, domain}) check skillsListView uses. (This
+// deliberately does NOT mirror memory_list/memory_read's split-by-sensitivity shape — that
+// split exists because memory_read can reach an admin-only silo skills_list has no analogue
+// of; every domain skill body is already at the skills_list tier, so splitting metadata from
+// content here would just be an extra round trip for no narrower disclosure.)
+//
+// `name` is REQUIRED — unlike the store port's optional "sweep the whole domain" (kept for
+// tests/migrations) — because the log is unbounded in principle and bodies run up to 32KB
+// each (MAX_DOMAIN_SKILL_BYTES): the control-plane surface only ever answers "this skill's
+// history", never "dump every skill's history in the domain", narrow by construction rather
+// than by a row limit alone. `limit` additionally bounds the ROWS for that one skill.
+export const DEFAULT_SKILL_REVISIONS_LIMIT = 20;
+export const MAX_SKILL_REVISIONS_LIMIT = 100;
+
+export interface SkillRevisionsQuery {
+  readonly org: string;
+  readonly domain: string;
+  readonly name: string;
+  readonly limit?: number;
+}
+export interface SkillRevisionsResult {
+  readonly org: string;
+  readonly domain: string;
+  readonly name: string;
+  /** Newest first — the store returns oldest-first by insertion `seq` (append-only order);
+   *  this view reverses it, since "what did the LAST approver read" is the usual question. */
+  readonly revisions: readonly DomainSkillRevisionRow[];
+  /** True when the skill has more revisions than fit `limit` — the row count was truncated.
+   *  No offset/cursor param yet: per-skill history is small by construction (a row is only
+   *  ever created by a human clicking an approval card — see domain_skill_revisions' comment
+   *  in operational/store.ts), so this flag existing at all is a defensive bound, not an
+   *  expected-common case. */
+  readonly capped: boolean;
+}
+
+/** One skill's approved-body history, newest first, clamped to `limit` (default
+ *  DEFAULT_SKILL_REVISIONS_LIMIT, hard-capped at MAX_SKILL_REVISIONS_LIMIT even if a caller
+ *  reaching this view directly — bypassing the zod-validated MCP tool's own max — asks for
+ *  more). Gating is the CALLER'S job (server.ts), exactly like skillsListView/memoryReadView. */
+export async function skillRevisionsView(q: SkillRevisionsQuery): Promise<SkillRevisionsResult> {
+  const limit = Math.min(Math.max(1, Math.trunc(q.limit ?? DEFAULT_SKILL_REVISIONS_LIMIT)), MAX_SKILL_REVISIONS_LIMIT);
+  const oldestFirst = await listDomainSkillRevisions(q.org, q.domain, q.name);
+  const newestFirst = [...oldestFirst].reverse();
+  return {
+    org: q.org,
+    domain: q.domain,
+    name: q.name,
+    revisions: newestFirst.slice(0, limit),
+    capped: oldestFirst.length > limit,
+  };
+}
+
+// --- memory-admin: inspect the DB-backed org brain without SQL (item 14) -----------
+// Tiers are enumerated FROM CONFIG (the domains registry → the silos they reference),
+// not by scanning the store — there is no provider "list every silo" API, and config is
+// the source of truth for what SHOULD exist (a silo nobody references is dead config,
+// not a tier to surface). DM/personal and workspace-tier memory are EXCLUDED ENTIRELY:
+// personal memory is never an admin browsing surface (fail-closed privacy — revisit only
+// with an explicit erasure/GDPR flow), and the workspace tier is retired from resolution
+// (memory/store.ts) with no config registry of "which workspaces exist" to enumerate
+// from — so both are simply never in the silo set this view walks. Row-level scope
+// gating: memory_list FILTERS to the silos the caller's roles cover (siloScopeDenial in
+// auth.ts — never an all-or-nothing denial, since a domain-scoped caller reasonably
+// expects "show me what I can see"); memory_read gates the ONE requested silo at the
+// server.ts call site instead (a single target either is or isn't covered).
+export interface MemoryFileRow {
+  readonly path: string;
+  readonly bytes: number;
+}
+export interface MemoryTierRow {
+  readonly silo: string;
+  /** Explicit domains referencing this silo (siloCoveringDomains) — empty means
+   *  admin-only (the org-brain / an orphaned silo / public|dm-referenced only). */
+  readonly domains: readonly string[];
+  readonly provider: string;
+  readonly backing: string;
+  readonly readOnly: boolean;
+  readonly files: readonly MemoryFileRow[];
+  readonly totalBytes: number;
+}
+export interface MemoryListResult {
+  readonly org: string;
+  readonly tiers: readonly MemoryTierRow[];
+}
+
+function byteSize(content: string): number {
+  return Buffer.byteLength(content, "utf-8");
+}
+
+async function memoryTierRow(org: string, silo: MemorySilo, domains: string[], access: MemoryAccess): Promise<MemoryTierRow> {
+  const provider = providerById(silo.provider);
+  const files = await provider.readTier(controlPartition(org), siloTier(silo.name), silo, access);
+  const rows: MemoryFileRow[] = Object.entries(files)
+    .map(([path, content]) => ({ path, bytes: byteSize(content) }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  return {
+    silo: silo.name,
+    domains,
+    provider: silo.provider,
+    backing: sourceLabel(silo),
+    readOnly: silo.readOnly === true,
+    files: rows,
+    totalBytes: rows.reduce((sum, f) => sum + f.bytes, 0),
+  };
+}
+
+/** Every memory silo the caller's roles cover, with its files + sizes. `roles` filters
+ *  row-by-row (siloCoveringDomains / "admin") — never a blanket denial. */
+export async function memoryListView(org: string, roles: readonly string[]): Promise<MemoryListResult> {
+  const cfg = getConfig();
+  const domains = cfg.loadDomains();
+  const isAdmin = roles.includes("admin");
+  const domainRoles = new Set(roles.filter((r) => r.startsWith("domain:")).map((r) => r.slice("domain:".length)));
+
+  const tiers: MemoryTierRow[] = [];
+  for (const silo of cfg.loadSilos()) {
+    const covering = siloCoveringDomains(silo.name, domains);
+    if (!isAdmin && !covering.some((d) => domainRoles.has(d))) continue;
+    tiers.push(await memoryTierRow(org, silo, covering, siloAccess(silo.name, domains)));
+  }
+  return { org, tiers: tiers.sort((a, b) => a.silo.localeCompare(b.silo)) };
+}
+
+/** A relPath is safe to read/write within a tier: relative posix, no `..`/empty segment. */
+export function assertSafeRelPath(relPath: string): void {
+  if (!relPath || relPath.trim().length === 0) throw new Error("relPath is required");
+  if (relPath.startsWith("/") || relPath.includes("\\")) throw new Error(`relPath must be a relative posix path (got "${relPath}")`);
+  const segments = relPath.split("/");
+  if (segments.some((s) => s === "" || s === "." || s === "..")) {
+    throw new Error(`relPath must not contain ".." or empty segments (got "${relPath}")`);
+  }
+}
+
+export interface MemoryReadQuery {
+  readonly org: string;
+  readonly silo: string;
+  readonly relPath: string;
+}
+export interface MemoryReadResult {
+  readonly org: string;
+  readonly silo: string;
+  readonly relPath: string;
+  readonly content: string;
+  readonly bytes: number;
+}
+
+/** Read one file out of one silo. Fails loud on an unknown silo, or a relPath that
+ *  isn't (validly, and actually) in the tier's file set — never a partial/guessed read. */
+export async function memoryReadView(q: MemoryReadQuery): Promise<MemoryReadResult> {
+  assertSafeRelPath(q.relPath);
+  const silo = getConfig()
+    .loadSilos()
+    .find((s) => s.name === q.silo);
+  if (!silo) throw new Error(`no memory silo named "${q.silo}" (memory_list for the configured silos).`);
+  const provider = providerById(silo.provider);
+  const files = await provider.readTier(controlPartition(q.org), siloTier(silo.name), silo, siloAccess(silo.name, getConfig().loadDomains()));
+  const content = files[q.relPath];
+  if (content === undefined) {
+    const have = Object.keys(files).sort().join(", ") || "(none)";
+    throw new Error(`"${q.relPath}" is not a file in silo "${q.silo}" (have: ${have}).`);
+  }
+  return { org: q.org, silo: q.silo, relPath: q.relPath, content, bytes: byteSize(content) };
+}
+
+// --- pending actions (the approvals decide-queue, without a Slack/Discord card) -----
+// The control-plane read model for agent/approvals: what's awaiting an admin decision
+// right now, so a consumer can inspect the queue before calling decide_pending_action.
+// REDACTION: we surface the SAME deterministic, code-rendered `summarize()` lines the
+// approval card shows (summarizeFrozenRow) — NEVER the raw frozen argsJson. That blob is
+// the model-proposed input; the summary is the reviewed display surface (approvals/types.ts
+// doctrine), so this matches access_preview's "no raw secret values, only the safe view"
+// discipline. Row-filtered by role (roleCoversScope), like memory_list — a domain:<name>
+// caller sees only pendings whose frozen scope resolves to their domain; "admin" sees all.
+// Never mutates (a read): a row past its TTL but not yet swept shows status "pending" with
+// expired:true, rather than being lazily decided here.
+export interface PendingActionListRow {
+  readonly id: string;
+  readonly kind: string;
+  /** Who may decide this kind — "admin" (org/domain admin) or "member". */
+  readonly policy: ApproverPolicy;
+  readonly domain: string | null;
+  readonly scopeKey: string;
+  /** Code-rendered summary of the FROZEN args (summarizeFrozenRow) — never the raw blob. */
+  readonly summary: readonly string[];
+  readonly requestedBy: string;
+  readonly requestedAt: string; // ISO (createdAt)
+  readonly expiresAt: string; // ISO
+  /** Age of the pending in whole seconds at `now`. */
+  readonly ageSeconds: number;
+  /** True once past its TTL (a decide would expire it) — shown, not swept, by this read. */
+  readonly expired: boolean;
+}
+export interface PendingActionsView {
+  readonly org: string;
+  readonly now: string;
+  readonly pending: readonly PendingActionListRow[];
+}
+
+/** Every still-pending action for `org` the caller's `roles` cover, oldest first. Row-
+ *  filtered (never an all-or-nothing denial) exactly like memoryListView. */
+export async function pendingActionsView(org: string, roles: readonly string[], now: number = Date.now()): Promise<PendingActionsView> {
+  const rows = await getOperationalStore().listPendingActions(org);
+  const domains = getConfig().loadDomains();
+  const isAdmin = roles.includes("admin");
+  const pending: PendingActionListRow[] = [];
+  for (const row of rows) {
+    if (!isAdmin && !roleCoversScope(roles, { org, surfaceKey: row.scopeKey, domain: row.domain ?? undefined }, domains)) continue;
+    pending.push({
+      id: row.id,
+      kind: row.kind,
+      policy: actionKind(row.kind)?.policy ?? "admin",
+      domain: row.domain,
+      scopeKey: row.scopeKey,
+      summary: summarizeFrozenRow(row),
+      requestedBy: row.requestedBy,
+      requestedAt: row.createdAt,
+      expiresAt: row.expiresAt,
+      ageSeconds: Math.max(0, Math.round((now - Date.parse(row.createdAt)) / 1000)),
+      expired: Date.parse(row.expiresAt) <= now,
+    });
+  }
+  return { org, now: new Date(now).toISOString(), pending };
+}
+
+// --- unified cross-surface domain audit (D1 — "who and what can see across all surfaces") -----
+// The flagship detective control for the unified cross-surface supervisor (research preview,
+// a design note D1). A PURE-READ composition over views that
+// already ship — it restricts the agent by exactly NOTHING, and answers a question ONLY the unified
+// feature makes askable: "which surfaces are in this one mind, what can the agent reach across all of
+// them, and which humans can read across which surfaces?". Composed from:
+//   1. the domain's exact reach entries (Domain.reach — exclusivity-guaranteed membership) + whether the
+//      domain actually unifies (both gates on);
+//   2. the agent's own reach per container via the EXISTING accessView(), unioned, FLAGGING any
+//      container that widens the set (e.g. "only payments-api grants the deploy connector");
+//   3. the participating humans via the principals map (identity/principals.ts) — for each mapped
+//      human, which of the domain's surface PLATFORMS they hold an account on, and which they do NOT
+//      (the T4 read-across exposure map). Unresolved accounts are the runtime half (per-container
+//      membership needs a live API call) — flagged as a note, never silently merged;
+//   4. the controllers (Domain.admins);
+//   5. the behavioural record (auditView filtered to the domain's surfaces) — the audited
+//      reply/silence history that proves the restraint was judged, not scripted.
+
+export interface UnifiedContainerRow {
+  readonly surfaceKey: string;
+  readonly platform: string;
+  readonly reachableHosts: readonly string[];
+  readonly connectors: readonly string[];
+  readonly repos: readonly string[];
+  readonly skills: readonly string[];
+  readonly subagents: readonly string[];
+  /** Reach items (host/connector/repo/skill/subagent, prefixed by kind) that ONLY this container
+   *  grants across the whole domain — the "this surface widens the agent's hands" flag. */
+  readonly widens: readonly string[];
+  readonly warnings: readonly string[];
+}
+export interface UnifiedHumanRow {
+  readonly name: string;
+  readonly handle?: string;
+  /** Domain-surface platforms this human HAS an account on (principal ids ∩ domain platforms). */
+  readonly surfacesInDomain: readonly string[];
+  /** Domain-surface platforms this human is NOT on — where answering could disclose to a non-member. */
+  readonly surfacesNotIn: readonly string[];
+}
+/** ONE standing window inside the domain (OPE-1167) — see {@link UnifiedDomainAuditResult.windows}. */
+export interface UnifiedWindowRow {
+  /** The window id the live grain keys this window by: a group name, the domain name, or a surfaceKey. */
+  readonly windowId: string;
+  /** Which of the three shapes produced it — a named `windows` group, the `mode: "unified"` residue,
+   *  or the `mode: "solo"` residue (one window per channel). */
+  readonly kind: "group" | "domain" | "solo";
+  /** The domain roster channels that share this window. */
+  readonly members: readonly string[];
+  /** The distinct surface platforms inside this ONE window — the real "which surfaces share a mind". */
+  readonly platforms: readonly string[];
+}
+export interface UnifiedDomainAuditResult {
+  readonly org: string;
+  readonly domain: string;
+  /** True iff the domain actually WINDOWS right now (WINDOW_TOPOLOGY_ENABLED on + the domain is an
+   *  ambient-supervisor explicit domain). */
+  readonly unified: boolean;
+  /** True iff this domain runs the CROSS-SURFACE window over its whole roster: the `mode: "unified"`
+   *  residue AND no named {@link Domain.windows} group carving part of the domain into a window of
+   *  its own. The J-UNI-X live run keys its shared-context expectations off this bit.
+   *  It is NOT the general "do all these surfaces share one mind" question — a domain whose every
+   *  channel sits in ONE named group reads `false` here, because its topology is the group's, not
+   *  the cross-surface residue's. Read {@link windows} for that question, and mind its known limit. */
+  readonly singleWindow: boolean;
+  /** The standing windows this domain hosts, with their members — the per-window answer that
+   *  {@link singleWindow} compresses to one bit. Empty when the domain does not window.
+   *  🔴 KNOWN LIMIT, the same one the config-load vouch gate states: membership is read from the
+   *  EXACT `reach` entries only. A window that exists solely for surfaces a {@link Domain.reach}
+   *  claim admits at runtime cannot be enumerated without I/O, so it is absent from this array —
+   *  and {@link singleWindow} cannot see it either. Say so rather than imply a coverage this read
+   *  cannot have. */
+  readonly windows: readonly UnifiedWindowRow[];
+  /** The distinct surface platforms the domain spans (the "which surfaces are in this one mind"). */
+  readonly platforms: readonly string[];
+  readonly containers: readonly UnifiedContainerRow[];
+  /** The agent's own reach UNIONED across every container — the domain-grain answer no per-container
+   *  access_preview can give. */
+  readonly agentReach: {
+    readonly reachableHosts: readonly string[];
+    readonly connectors: readonly string[];
+    readonly repos: readonly string[];
+    readonly skills: readonly string[];
+    readonly subagents: readonly string[];
+  };
+  /** Humans from the principals map that touch this domain's platforms, with their read-across map. */
+  readonly humans: readonly UnifiedHumanRow[];
+  /** Domain admins (Domain.admins) — the controllers who can read/write its memory + pull overrides. */
+  readonly controllers: readonly string[];
+  /** The audited reply/silence/demotion record across the domain's surfaces (row-capped). */
+  readonly behaviour: AuditView;
+  /** Honesty notes — the read-only half's boundaries (runtime trust/membership confirmed at delivery,
+   *  privacy ordinal not yet enforced, etc.). */
+  readonly notes: readonly string[];
+}
+
+export interface UnifiedDomainAuditQuery {
+  readonly domain: string;
+  readonly org?: string;
+  readonly sinceDays?: number;
+}
+
+/** Split a fully-qualified surfaceKey (`platform/workspace/surface…`) into accessView args. */
+function surfaceKeyParts(surfaceKey: string): { platform: string; workspace: string; channel: string } {
+  const parts = surfaceKey.split("/");
+  return { platform: parts[0] ?? "", workspace: parts[1] ?? "", channel: parts.slice(2).join("/") };
+}
+
+export async function unifiedDomainAudit(q: UnifiedDomainAuditQuery): Promise<UnifiedDomainAuditResult> {
+  const org = q.org ?? deploymentOrg();
+  const cfg = getConfig();
+  const domains = cfg.loadDomains();
+  const domain = domains.find((d) => d.name === q.domain);
+  if (!domain) {
+    const have = domains.map((d) => d.name).join(", ") || "(none)";
+    throw new Error(`no domain named "${q.domain}" (configured domains: ${have}).`);
+  }
+  const channels = domainRoster(domain);
+  const unified = channels.length > 0 && windowedSupervisorEnabled(channels[0], domains);
+  // PER WINDOW, NOT PER DOMAIN (OPE-1167). A domain can now host N named windows plus the `mode`
+  // residue, so `channels[0]` no longer speaks for the whole domain: elect EVERY channel to its own
+  // window, exactly as channels/unified-supervisor.ts does at wake time, and report the result.
+  // The residue is read once from the domain itself — `mode` does not inherit, so every channel of
+  // this domain resolves the same residue.
+  const residueUnified = unified && windowModeFor(channels[0] ?? "", domains) === "unified";
+  const byWindow = new Map<string, { kind: UnifiedWindowRow["kind"]; members: string[] }>();
+  if (unified) {
+    for (const ch of channels) {
+      const grouped = windowIdFor(ch, domains);
+      const windowId = grouped ?? (residueUnified ? domain.name : ch);
+      const kind: UnifiedWindowRow["kind"] = grouped !== undefined ? "group" : residueUnified ? "domain" : "solo";
+      const row = byWindow.get(windowId);
+      if (row) row.members.push(ch);
+      else byWindow.set(windowId, { kind, members: [ch] });
+    }
+  }
+  const windows: UnifiedWindowRow[] = [...byWindow].map(([windowId, row]) => ({
+    windowId,
+    kind: row.kind,
+    members: row.members,
+    platforms: [...new Set(row.members.map((ch) => surfaceKeyParts(ch).platform))].sort(),
+  }));
+  // The CROSS-SURFACE claim is now a question about the WINDOWS, not about `mode` alone: a
+  // `mode: "unified"` domain that also declares a group holds two windows, and the shared-context
+  // claim is then false for part of it. With no group declared this is exactly the old expression.
+  // Deliberately NOT `unified && windows.length === 1`: that would flip every single-channel
+  // `mode: "solo"` domain from false to true and change what an existing consumer reads.
+  const singleWindow = residueUnified && windows.length === 1;
+
+  // Fan accessView across every container, then union + flag wideners.
+  const perContainer = await Promise.all(
+    channels.map(async (surfaceKey) => {
+      const { platform, workspace, channel } = surfaceKeyParts(surfaceKey);
+      const a = await accessView({ platform, workspace, channel, mode: "channel" });
+      return { surfaceKey, platform, access: a };
+    }),
+  );
+
+  // Count how many containers grant each kind-prefixed reach item, so "widens" = granted by exactly one.
+  const reachCount = new Map<string, number>();
+  const tag = (kind: string, v: string): string => `${kind}:${v}`;
+  const itemsOf = (a: Awaited<ReturnType<typeof accessView>>): string[] => [
+    ...a.reachableHosts.map((h) => tag("host", h.host)),
+    ...a.connectors.map((c) => tag("connector", c)),
+    ...a.repos.map((r) => tag("repo", r)),
+    ...a.skills.map((s) => tag("skill", s)),
+    ...a.subagents.map((s) => tag("subagent", s)),
+  ];
+  for (const c of perContainer) for (const it of new Set(itemsOf(c.access))) reachCount.set(it, (reachCount.get(it) ?? 0) + 1);
+
+  const containers: UnifiedContainerRow[] = perContainer.map((c) => {
+    const items = new Set(itemsOf(c.access));
+    const widens = [...items].filter((it) => reachCount.get(it) === 1).sort();
+    return {
+      surfaceKey: c.surfaceKey,
+      platform: c.platform,
+      reachableHosts: c.access.reachableHosts.map((h) => h.host),
+      connectors: c.access.connectors,
+      repos: c.access.repos,
+      skills: c.access.skills,
+      subagents: c.access.subagents,
+      widens,
+      warnings: c.access.warnings,
+    };
+  });
+
+  const union = (pick: (r: UnifiedContainerRow) => readonly string[]): string[] => [...new Set(containers.flatMap((r) => [...pick(r)]))].sort();
+  const platforms = [...new Set(channels.map((ch) => surfaceKeyParts(ch).platform))].sort();
+
+  // Humans: the read-across exposure map at platform granularity (per-container membership is the
+  // runtime half — noted below). For each mapped human, which domain platforms they're on / not on.
+  //
+  // THE ROSTER IS THE UNION of the reviewed config map and the CONFIRMED DB link-sets (P1.5). The
+  // DB read happens HERE, at the caller's edge, and the resolution rule stays a pure function of
+  // two lists (identity/link-resolve.ts) — the same shape principals have always been loaded in.
+  // A (platform, id) both sides claim for DIFFERENT people is NOT merged and produces a loud
+  // warning, appended to `notes` below rather than swallowed.
+  const principalUnion = unionPrincipals(cfg.loadPrincipals?.() ?? [], await confirmedLinkSetPrincipals(org));
+  const principals = principalUnion.principals;
+  const humans: UnifiedHumanRow[] = principals
+    .map((p) => {
+      const surfaces = principalSurfaces(p);
+      const inDomain = platforms.filter((pl) => surfaces.includes(pl));
+      const notIn = platforms.filter((pl) => !surfaces.includes(pl));
+      return { name: p.name, ...(p.handle ? { handle: p.handle } : {}), surfacesInDomain: inDomain, surfacesNotIn: notIn };
+    })
+    .filter((h) => h.surfacesInDomain.length > 0);
+
+  // Behavioural record: audit rows across the domain's surfaces (one surface filter at the store;
+  // multi-surface is matched in-process). Newest-first, row-capped by auditView. SCOPE: exact
+  // container match only, plus workspace-LEVEL rows (no surface) for a workspace the domain has a
+  // container in — never another surface's rows just because it shares a workspace (a domain:<name>
+  // role must not read audit beyond its domain's containers).
+  const since = new Date(Date.now() - (q.sinceDays ?? 30) * 24 * 60 * 60 * 1000).toISOString();
+  const surfaceSet = new Set(channels);
+  const behaviourAll = await auditView({ org, since, limit: 200 });
+  const behaviour: AuditView = {
+    ...behaviourAll,
+    entries: behaviourAll.entries.filter((e) => {
+      const key = `${e.platform}/${e.workspace}/${e.surface ?? ""}`.replace(/\/$/, "");
+      if (surfaceSet.has(key)) return true;
+      return !e.surface && [...surfaceSet].some((ch) => ch.startsWith(`${e.platform}/${e.workspace}/`));
+    }),
+  };
+
+  const notes = [
+    "Pure-read: this view restricts the agent by nothing — it is only answerable because the domain unifies the surfaces.",
+    "Per-container INTERNAL/EXTERNAL trust and per-account membership are confirmed FAIL-CLOSED at delivery time (each surface's confirmInternal); a container that fails is dropped and audited (*.trust_demotion). This read reflects config-declared membership, not a live trust probe.",
+    "Unmapped accounts (present in a surface but not in the principals map) stay DISTINCT per-surface identities — never merged on name similarity; enumerate them from the live surface, not here.",
+    "Surface-privacy ORDINAL (P5 enforced form) is not yet built — TODO(unified-audit-privacy-ordinal); quote-across-surfaces is advisory (one sentence in the standing prompt) until it lands.",
+  ];
+  if (!unified) notes.unshift(`NOTE: domain "${q.domain}" is not currently windowed (WINDOW_TOPOLOGY_ENABLED off and/or the domain is not an ambient supervisor) — this shows what unification WOULD expose.`);
+  // An identity conflict is an operator worklist item, so it goes at the TOP of the notes rather
+  // than into a log nobody reads. Empty in the ordinary case ⇒ the notes are byte-identical.
+  for (const w of principalUnion.warnings) notes.unshift(`⚠ ${w.message}`);
+
+  return {
+    org,
+    domain: q.domain,
+    unified,
+    singleWindow,
+    windows,
+    platforms,
+    containers,
+    agentReach: {
+      reachableHosts: union((r) => r.reachableHosts),
+      connectors: union((r) => r.connectors),
+      repos: union((r) => r.repos),
+      skills: union((r) => r.skills),
+      subagents: union((r) => r.subagents),
+    },
+    humans,
+    controllers: [...(domain.admins ?? [])],
+    behaviour,
+    notes,
+  };
+}
+
+// --- access ("what can this surface reach?") --------------------------------
+export interface AccessQuery {
+  readonly platform?: string;
+  readonly workspace?: string;
+  readonly channel?: string;
+  readonly mode?: SessionMode;
+  readonly principalId?: string;
+}
+
+/**
+ * The container triple an {@link AccessQuery} names — each omitted segment filled with the default
+ * {@link accessView} applies. Exported because the ROLE GATE and the VIEW must resolve the SAME
+ * triple (OPE-1802): `control/server.ts` builds `access_preview`'s `surfaceKey` from this, so a
+ * caller who omits a segment is gated on the surface the answer really comes from. A second copy of
+ * these defaults at the gate would let the two drift, and a gate that names a different surface from
+ * the answer is not a gate.
+ *
+ * 🔴 IT IS THE ANSWER'S SCOPE ONLY OUTSIDE DM MODE. A `mode: "dm"` query is resolved from
+ * `principalId` alone (access/resolver.ts applies no `surface`-level binding there) and the answer
+ * is stamped `dm:<principalId>`, so this triple describes nothing about it. `control/server.ts`
+ * gates a `dm` ask as org-wide instead of calling this.
+ */
+export function accessQueryScope(q: AccessQuery = {}): { platform: string; workspace: string; channel: string } {
+  return { platform: q.platform ?? "local", workspace: q.workspace ?? "dev", channel: q.channel ?? "default" };
+}
+
+// The resolved access already contains NO secret values — connections carry only
+// `secretRef` (an env-var name) and the websites they may reach. We return it as
+// data; the firewall the egress layer compiles is derivable from this.
+export async function accessView(q: AccessQuery = {}) {
+  const cfg = getConfig();
+  const { platform, workspace, channel } = accessQueryScope(q);
+  const req: ResolveRequest = {
+    mode: q.mode ?? "channel",
+    platform,
+    workspace,
+    channel,
+    domains: cfg.domainsForSurface({ workspaceKey: `${platform}/${workspace}`, surface: channel }),
+    principalId: q.principalId,
+  };
+  // 🔴 THE CREDENTIAL CATALOGUE IS THE FIFTH ARGUMENT, AND OMITTING IT EMPTIES `connectors`
+  // (OPE-1473). Without it `expandConnectorGrant` resolves EVERY bundle connector grant to `null`,
+  // so `access_preview` answered `connectors: []` for a surface that really does reach one, and an
+  // admin running an access review read that as "no connector here". This call site was the only
+  // one in the tree that omitted it — `scripts/access-preview.ts`, the CI-runnable config script
+  // this tool is meant to be the served twin of, has always passed it. It is CONFIG, not a live
+  // override: reading it does not give this view the operational store, and `access_preview` stays
+  // a config-only answer exactly as `docs/security/control-plane.md` now says.
+  const access = resolveAccess(req, cfg.loadBundles(), cfg.loadBindings(), cfg.pluginRegistry, cfg.loadConnectorCredentials?.() ?? []);
+  // WHICH domain, and VIA WHAT (OPE-205). `req.domains` above says only "payments"; it cannot
+  // distinguish "somebody named this room in payments.reach" from "payments reaches this whole
+  // tenant (or matched it with a `prefix*` glob — OPE-417 — and `via` names the exact entry) and
+  // swept the room in" from "a reach entry WOULD have matched, but an `exclude` entry carved it
+  // back out" from "nothing routes here at all" — and those are the difference between a deliberate
+  // grant, an inherited one, a deliberate carve-out, and a config gap. Answering it here
+  // means the control plane, the config previews and any create-time achievability check
+  // ("does this surface resolve to a domain at all?") all compute it one way.
+  const routing = resolveDomainForChannel(`${platform}/${workspace}/${channel}`, cfg.loadDomains());
+  return {
+    scopeKey: access.scopeKey,
+    mode: access.mode,
+    routing: { domain: routing.domain?.name ?? null, via: routing.via },
+    reachableHosts: access.reachableHosts,
+    connections: access.connections.map((c) => ({
+      id: c.id,
+      credentialType: c.credentialType,
+      secretRef: c.secretRef, // env-var NAME, not the secret
+      allowedWebsites: c.allowedWebsites,
+    })),
+    repos: access.repos,
+    plugins: access.plugins,
+    skills: access.skills,
+    subagents: access.subagents,
+    connectors: access.connectors,
+    instructionStack: access.instructionStack,
+    warnings: access.warnings,
+  };
+}