@open-everywhere/core 0.1.0

package/agent/access/dispatch-origin-signal.ts

@@ -0,0 +1,133 @@
+// A background task's answer belongs to the conversation the turn ADDRESSED, not the delivery `currentWakeId` names — a turn that merged queued deliveries carries only the last delivery's auth. The FIRST addressed wake wins, once per turn, and re-points tasks dispatched earlier in the turn; outside an eve context every function no-ops or answers empty.
+// 🔴 THAT MERGE IS UNREACHABLE ON eve 0.54.3, AND THIS SIGNAL STAYS ANYWAY (OPE-2042). eve batches adjacent queued deliveries only when their full auth contexts match, and OE stamps a fresh per-delivery `oe_delivery_id` into `auth.attributes`, so two auth-carrying deliveries on one unified window never compare equal. Only the caller-less task COMPLETION COHORT still folds, and it carries no `auth` at all. But the turn's ctx names the wrong conversation WITHOUT any merge too: a turn woken by an INTERNAL wake — an approval decision, a completion — answers a conversation whose envelope is in the seat's shared context, through the reply fence's same-conversation and pending arms. Measured in production on 2026-08-15 (`docs/glossary.md`). So this is LOAD-BEARING, not defensive. `scripts/coalesced-delivery-merge-assumption-test.ts` pins the MERGE road alone.
+
+import { defineState } from "eve/context";
+import { wakeIdsFromEnvelope } from "../channels/wake-envelope.js";
+
+export interface DispatchedTaskWake {
+  readonly taskId: string;
+  readonly wakeId: string;
+}
+
+/** All of it is scoped to ONE eve turn: a record stamped for turn A is never answered for turn B, which removes the need for a reset hook on the durable slot. */
+interface DispatchOriginState {
+  readonly turn?: string;
+  readonly addressed?: string;
+  readonly tasks?: readonly DispatchedTaskWake[];
+  readonly deliveredWakes?: readonly string[];
+}
+
+const slot = defineState<DispatchOriginState>("open-everywhere.dispatch-origin", () => ({}));
+
+/** How many dispatched tasks one turn tracks. A real turn dispatches a handful; the cap only stops a
+ *  looping turn from growing the serialized container without bound. Past the cap the ledger stops
+ *  recording, so the extra tasks keep the pre-OPE-601 address — it never starts refusing. */
+const MAX_TASKS = 16;
+
+/** Read the durable value defensively — a resumed session can hand back anything a previous
+ *  deployment wrote. Anything unrecognised reads as "no record". */
+function readState(v: unknown): DispatchOriginState {
+  if (v === null || typeof v !== "object") return {};
+  const s = v as { turn?: unknown; addressed?: unknown; tasks?: unknown; deliveredWakes?: unknown };
+  if (typeof s.turn !== "string" || s.turn.length === 0) return {};
+  const tasks = Array.isArray(s.tasks)
+    ? s.tasks.filter(
+        (t): t is DispatchedTaskWake =>
+          typeof t === "object" &&
+          t !== null &&
+          typeof (t as DispatchedTaskWake).taskId === "string" &&
+          (t as DispatchedTaskWake).taskId.length > 0 &&
+          typeof (t as DispatchedTaskWake).wakeId === "string" &&
+          (t as DispatchedTaskWake).wakeId.length > 0,
+      )
+    : [];
+  return {
+    turn: s.turn,
+    ...(typeof s.addressed === "string" && s.addressed.length > 0 ? { addressed: s.addressed } : {}),
+    tasks,
+    deliveredWakes: Array.isArray(s.deliveredWakes)
+      ? [...new Set(s.deliveredWakes.filter((wake): wake is string => typeof wake === "string" && wake.length > 0))].slice(0, 2)
+      : [],
+  };
+}
+
+/** Capture the wake ids the host attributed to this turn's delivery. Human deliveries use the full
+ * rendered envelope; host-only routine fires use the same structured wake marker without inventing
+ * a trigger message. Two distinct ids are enough to make pre-reply delegation ambiguous, so the
+ * durable set is capped at two. */
+export function recordDeliveredWakes(turnId: string | undefined, message: string | undefined): void {
+  if (turnId === undefined || turnId.length === 0 || message === undefined) return;
+  const incoming = wakeIdsFromEnvelope(message);
+  if (incoming.length === 0) return;
+  try {
+    slot.update((cur) => {
+      const state = readState(cur);
+      const prior = state.turn === turnId ? (state.deliveredWakes ?? []) : [];
+      const deliveredWakes = [...new Set([...prior, ...incoming])].slice(0, 2);
+      return state.turn === turnId ? { ...state, deliveredWakes } : { turn: turnId, deliveredWakes, tasks: [] };
+    });
+  } catch {
+    /* no eve context means there is no dispatch to authorize */
+  }
+}
+
+/** Exact authority for a delegation before the turn has replied: one and only one delivered wake. */
+export function exactDispatchWakeThisTurn(turnId: string | undefined): string | undefined {
+  if (turnId === undefined || turnId.length === 0) return undefined;
+  try {
+    const state = readState(slot.get());
+    if (state.turn !== turnId || state.deliveredWakes?.length !== 1) return undefined;
+    return state.deliveredWakes[0];
+  } catch {
+    return undefined;
+  }
+}
+
+/** The wake this turn has addressed. `undefined` means the dispatch edge must use a positively
+ * singleton delivered wake or refuse; the mutable last-delivery auth is never an authority. */
+export function addressedWakeThisTurn(turnId: string | undefined): string | undefined {
+  if (turnId === undefined || turnId.length === 0) return undefined;
+  try {
+    const state = readState(slot.get());
+    return state.turn === turnId ? state.addressed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Records that this turn dispatched a task, so the first wake the turn addresses can re-point it. Records NOTHING once the turn has already addressed a wake, because such a dispatch read the addressed wake at the edge and is already right. */
+export function noteTaskDispatchedThisTurn(turnId: string | undefined, taskId: string, wakeId: string): void {
+  if (turnId === undefined || turnId.length === 0) return;
+  if (taskId.length === 0 || wakeId.length === 0) return;
+  try {
+    slot.update((cur) => {
+      const state = readState(cur);
+      if (state.turn !== turnId) return { turn: turnId, tasks: [{ taskId, wakeId }] };
+      if (state.addressed !== undefined) return state; // dispatched AFTER an address ⇒ already right
+      const tasks = state.tasks ?? [];
+      if (tasks.length >= MAX_TASKS || tasks.some((t) => t.taskId === taskId)) return state;
+      return { ...state, tasks: [...tasks, { taskId, wakeId }] };
+    });
+  } catch {
+    /* no eve context — nothing to record, and never a reason to disturb the turn */
+  }
+}
+
+/** Returns the tasks whose registered origin must now be re-pointed at the just-addressed wake, and empties the ledger in the same update so a second reply in the turn claims nothing. Returns an EMPTY list, while still recording the address, whenever there is nothing to move or anything is unreadable. */
+export function claimTasksForAddressedWake(turnId: string | undefined, wakeId: string): readonly DispatchedTaskWake[] {
+  if (turnId === undefined || turnId.length === 0) return [];
+  if (wakeId.length === 0) return [];
+  let claimed: readonly DispatchedTaskWake[] = [];
+  try {
+    slot.update((cur) => {
+      const state = readState(cur);
+      if (state.turn !== turnId) return { turn: turnId, addressed: wakeId, tasks: [] };
+      if (state.addressed !== undefined) return state; // FIRST addressed wake wins — see the header
+      claimed = state.tasks ?? [];
+      return { turn: turnId, addressed: wakeId, tasks: [] };
+    });
+  } catch {
+    return [];
+  }
+  return claimed;
+}

package/agent/access/domain-credentials.ts

@@ -0,0 +1,115 @@
+// A domain with NO binding falls back to the org default — absence is the ordinary state, not a misconfiguration. A binding that names a MISSING credential never falls back: it is refused at boot, because serving the org credential there would hand a bound domain the exact key it was bound away from.
+
+import type { Domain } from "../memory/domain.js";
+import type { ConnectorCredentials } from "./connector-credentials.js";
+
+/** One domain's override of one connector credential. It keys on the credential it REPLACES, not on the connector alone, so a vendor with several credential roles stays unambiguous. */
+export interface DomainCredentialOverride {
+  readonly connector: string;
+  /** The ORG-DEFAULT credential id this replaces, i.e. the ROLE (Notion: `"channel-key"`). */
+  readonly credential: string;
+  readonly use: string;
+  /** The operator-secret NAME holding this integration's INBOUND webhook signing key; absent means the deployment's default inbound secret. It is a name, never a credential — inbound signing keys are never resolvable as outbound credentials. */
+  readonly inboundSecret?: string;
+}
+
+export interface CredentialBoundDomain {
+  readonly name?: string;
+  readonly credentials?: readonly DomainCredentialOverride[];
+}
+
+/** Undefined means this domain has no override, which every caller reads as "use the org default". */
+export function credentialOverrideFor(
+  domain: CredentialBoundDomain | undefined,
+  connector: string,
+  credential: string,
+): DomainCredentialOverride | undefined {
+  return (domain?.credentials ?? []).find((c) => c.connector === connector && c.credential === credential);
+}
+
+/** The credential id this domain uses — the override's `use`, else `credential` itself — so every domain resolves to some id and an unbound one resolves to the org default. */
+export function domainCredentialId(domain: CredentialBoundDomain | undefined, connector: string, credential: string): string {
+  return credentialOverrideFor(domain, connector, credential)?.use ?? credential;
+}
+
+/** One integration this deployment can be reached by. A delivery is authenticated by trying each entry's inbound secret; the one that verifies IDENTIFIES the integration that sent it. */
+export interface ConnectorIntegration {
+  readonly credentialId: string;
+  readonly inboundSecret: string;
+  readonly domain?: string;
+}
+
+/** The org default is always present and always FIRST, which makes an unbound domain work with no config and keeps the trial order stable. Entries repeating a (credentialId, inboundSecret) pair are dropped, so the gate never verifies one key twice. */
+export function connectorIntegrations(
+  domains: readonly Domain[],
+  connector: string,
+  credential: string,
+  defaultInboundSecret: string,
+): readonly ConnectorIntegration[] {
+  const out: ConnectorIntegration[] = [{ credentialId: credential, inboundSecret: defaultInboundSecret }];
+  const seen = new Set<string>([`${credential}\u0000${defaultInboundSecret}`]);
+  for (const d of domains) {
+    const override = credentialOverrideFor(d, connector, credential);
+    if (!override) continue;
+    const inboundSecret = override.inboundSecret ?? defaultInboundSecret;
+    const key = `${override.use}\u0000${inboundSecret}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ credentialId: override.use, inboundSecret, domain: d.name });
+  }
+  return out;
+}
+
+/** The SHAPE half of validation, called from assertDomainsValid so a malformed binding fails at config load rather than at the first webhook. Whether the named credentials EXIST is a separate question, answered by assertDomainCredentialsResolvable at boot. */
+export function domainCredentialProblems(domain: CredentialBoundDomain): readonly string[] {
+  const bad: string[] = [];
+  const name = domain.name ?? "(unnamed)";
+  const seen = new Set<string>();
+  for (const c of domain.credentials ?? []) {
+    const where = `  "${name}" credential override ${JSON.stringify(`${c.connector ?? ""}/${c.credential ?? ""}`)}`;
+    for (const [field, value] of [["connector", c.connector], ["credential", c.credential], ["use", c.use]] as const) {
+      if (typeof value !== "string" || value.trim().length === 0) {
+        bad.push(`${where}: \`${field}\` must be a non-empty string`);
+      }
+    }
+    if (c.inboundSecret !== undefined && (typeof c.inboundSecret !== "string" || c.inboundSecret.trim().length === 0)) {
+      bad.push(`${where}: \`inboundSecret\` must be a non-empty operator-secret name when present (omit it to share the deployment default)`);
+    }
+    if (typeof c.connector !== "string" || typeof c.credential !== "string") continue;
+    const key = `${c.connector}\u0000${c.credential}`;
+    if (seen.has(key)) {
+      bad.push(`${where}: declared more than once — a domain overrides each (connector, credential) at most once, so two entries are a contradiction rather than a precedence question`);
+    }
+    seen.add(key);
+    if (typeof c.use === "string" && c.use === c.credential) {
+      bad.push(`${where}: \`use\` names the credential it replaces, so the override does nothing — delete it (an unbound domain already uses the org default)`);
+    }
+  }
+  return bad;
+}
+
+/** Fails LOUD at boot when an override names a credential no connector catalogue carries. This is what keeps the no-silent-fallback rule from ever being felt at runtime. */
+export function assertDomainCredentialsResolvable(domains: readonly Domain[], catalogues: readonly ConnectorCredentials[]): void {
+  const bad: string[] = [];
+  for (const d of domains) {
+    for (const c of d.credentials ?? []) {
+      const cfg = catalogues.find((p) => p.connector === c.connector);
+      if (!cfg) {
+        bad.push(`  "${d.name}" overrides credential "${c.credential}" on connector "${c.connector}", which has no credential catalogue (agent/access/connector-credentials.ts)`);
+        continue;
+      }
+      if (!cfg.credentials.some((pc) => pc.id === c.credential)) {
+        bad.push(`  "${d.name}" overrides credential "${c.credential}" on connector "${c.connector}", which declares no such credential — name the ORG-DEFAULT credential the override replaces (one of: ${cfg.credentials.map((pc) => pc.id).join(", ")})`);
+      }
+      if (!cfg.credentials.some((pc) => pc.id === c.use)) {
+        bad.push(`  "${d.name}" binds connector "${c.connector}" to credential "${c.use}", which that connector does not declare — add it to agent/access/connector-credentials.ts with its own secretRef + broker (one of the declared ids: ${cfg.credentials.map((pc) => pc.id).join(", ")})`);
+      }
+    }
+  }
+  if (bad.length > 0) {
+    throw new Error(
+      `invalid per-domain credential override(s):\n${bad.join("\n")}\n` +
+        `A bound domain NEVER falls back to the org credential — that would hand it the exact key it was bound away from — so an unresolvable binding is refused at boot.`,
+    );
+  }
+}

package/agent/access/egress-denial-log.ts

@@ -0,0 +1,111 @@
+// Reduces a Squid access log to HOSTS AND INTEGER COUNTS only: no method, URL, query string, client address or byte count may reach the append-only audit plane. A token that fails the strict host checks is DROPPED rather than passed through, and the module is pure — no I/O, no clock, no env.
+
+export interface DeniedHostCount {
+  readonly host: string;
+  readonly count: number;
+}
+
+/** The result of reducing one chunk of access log. Deliberately has nowhere to put a path. */
+export interface DenialScan {
+  /** Denied hosts, count-desc then host-asc — the same ordering every counted list in the
+   *  permission-evidence family uses, so a reader never has to ask how a list is sorted. */
+  readonly hosts: readonly DeniedHostCount[];
+  readonly linesRead: number;
+  readonly denials: number;
+  /** Denial lines whose host could not be reduced to something safe to record. Non-zero means this parser and this Squid build disagree about the log format. */
+  readonly unparsed: number;
+}
+
+/** Squid's `%Ss` result tag followed by `%03>Hs`, e.g. `TCP_DENIED/403` — the ONE field that is
+ *  present, in this exact shape, in both the conventional `squid` logformat and the minimal
+ *  `oe_deny` one this deployment writes. Anchoring on it is what lets one parser read both. */
+const RESULT_TAG = /^([A-Z][A-Z0-9_]*)\/(\d{3})$/u;
+
+/** A hostname (at least one dot — see {@link normaliseDenialHost} for why single labels are
+ *  dropped) or a bracketed IPv6 literal. Deliberately strict: this is the last thing standing
+ *  between an arbitrary log token and an append-only audit row. */
+const HOSTNAME = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+\.?$/u;
+const IPV6_LITERAL = /^\[[0-9a-f:.]+\]$/u;
+
+/** The ORDER of operations is the security property: the path, query and fragment are cut FIRST, then the `user:pass@` userinfo, before anything else interprets the value. Single-label tokens are dropped, so a stray log field can never be mistaken for a host. */
+export function normaliseDenialHost(token: string): string | undefined {
+  let v = token.trim();
+  if (v.length === 0 || v === "-") return undefined;
+  const scheme = v.indexOf("://");
+  if (scheme >= 0) v = v.slice(scheme + 3);
+  // 2. 🔴 PATH / QUERY / FRAGMENT — cut before anything else looks at the value.
+  for (const cut of ["/", "?", "#"]) {
+    const at = v.indexOf(cut);
+    if (at >= 0) v = v.slice(0, at);
+  }
+  // 3. 🔴 USERINFO — `user:pass@host` → `host`. A credential in a URL is a credential.
+  const at = v.lastIndexOf("@");
+  if (at >= 0) v = v.slice(at + 1);
+  // 4. Port. Bracketed IPv6 keeps its brackets; everything else splits on the LAST colon so a
+  //    bare (unbracketed) IPv6 literal fails the charset check below rather than being mangled.
+  if (v.startsWith("[")) {
+    const close = v.indexOf("]");
+    if (close >= 0) v = v.slice(0, close + 1);
+  } else {
+    const colon = v.lastIndexOf(":");
+    if (colon >= 0) v = v.slice(0, colon);
+  }
+  v = v.toLowerCase();
+  if (v.length === 0 || v.length > 253) return undefined;
+  if (IPV6_LITERAL.test(v)) return v;
+  return HOSTNAME.test(v) ? v : undefined;
+}
+
+/** Squid spells every refusal `*_DENIED*`, so matching the suffix still counts a build that spells it differently. Outage tags such as `TAG_NONE/503` and `TCP_MISS_ABORTED` carry no `_DENIED` and must never be read as evidence that a grant is too narrow. */
+export function isDenialTag(tag: string): boolean {
+  return tag.includes("_DENIED");
+}
+
+/** Reads both log formats by finding the result tag and taking the first later token that reduces to a valid host; positional indexing would silently read the WRONG field, which on this path means recording a URL. A line with no result tag is skipped silently. */
+export function reduceDenialLog(chunk: string): DenialScan {
+  const counts = new Map<string, number>();
+  let linesRead = 0;
+  let denials = 0;
+  let unparsed = 0;
+
+  for (const raw of chunk.split("\n")) {
+    const line = raw.trim();
+    if (line.length === 0) continue;
+    linesRead++;
+    const tokens = line.split(/\s+/u);
+    const tagAt = tokens.findIndex((t) => RESULT_TAG.test(t));
+    if (tagAt < 0) continue;
+    const tag = RESULT_TAG.exec(tokens[tagAt]!)![1]!;
+    if (!isDenialTag(tag)) continue;
+    denials++;
+    let host: string | undefined;
+    for (let i = tagAt + 1; i < tokens.length; i++) {
+      host = normaliseDenialHost(tokens[i]!);
+      if (host !== undefined) break;
+    }
+    if (host === undefined) {
+      unparsed++;
+      continue;
+    }
+    counts.set(host, (counts.get(host) ?? 0) + 1);
+  }
+
+  const hosts = [...counts.entries()]
+    .map(([host, count]) => ({ host, count }))
+    .sort((a, b) => b.count - a.count || a.host.localeCompare(b.host));
+
+  return { hosts, linesRead, denials, unparsed };
+}
+
+export interface TailPlan {
+  readonly from: number;
+  readonly to: number;
+  readonly rotated: boolean;
+}
+
+/** A COLD START seeks to the END, so denials logged while nothing was watching are lost rather than replayed on every restart. A file smaller than the last offset is a ROTATION and is re-read from 0. */
+export function planTailRead(size: number, lastOffset: number | undefined): TailPlan {
+  if (lastOffset === undefined) return { from: size, to: size, rotated: false };
+  if (size < lastOffset) return { from: 0, to: size, rotated: true };
+  return { from: lastOffset, to: size, rotated: false };
+}

package/agent/access/egress-denial-poller.ts

@@ -0,0 +1,239 @@
+// Tails the egress proxy's denial log and appends aggregated `egress.denied` audit rows; the reduction and the host-only invariant live in egress-denial-log.ts.
+// Fail-quiet by requirement: a missing, rotated, unreadable or truncated log degrades to doing nothing. Rows carry the scope of the MOST RECENT policy push, which is exact to org grain only while one process serves one org.
+
+import { open, stat } from "node:fs/promises";
+import { appendAudit, type AuditInput } from "../audit/audit.js";
+import { planTailRead, reduceDenialLog, type DenialScan } from "./egress-denial-log.js";
+
+const EGRESS_DENIED_ACTION = "egress.denied";
+
+export const DEFAULT_POLL_MS = 60_000;
+/** Floor, so a mistyped env cannot turn this into a spin loop against a shared volume. */
+export const MIN_POLL_MS = 5_000;
+
+/** Per-pass cap on the number of DISTINCT hosts that become rows. A worker enumerating hosts (a
+ *  scan, a crash-loop through a package registry's mirrors) must not be able to write an unbounded
+ *  number of audit rows per minute. The hosts are already sorted count-desc, so the cap keeps the
+ *  evidence that matters and drops the tail; the drop is recorded on the rows that do get written. */
+export const MAX_HOSTS_PER_PASS = 20;
+
+/** Ceiling on how many bytes one pass will read. A log that grew by more than this since the last
+ *  pass is read from its TAIL — the newest bytes are the ones worth having, and holding an
+ *  arbitrarily large file in memory is exactly the failure this plane must not cause. */
+const MAX_READ_BYTES = 4 * 1024 * 1024;
+
+export interface EgressAttribution {
+  readonly org: string;
+  readonly platform: string;
+  readonly workspace: string;
+  readonly surface?: string;
+  /** The fingerprint of the policy generation in force — the same value the `egress.policy` audit
+   *  row and `egress/STATUS.json` carry, so a denial and the policy that produced it name the same
+   *  generation. */
+  readonly policyFingerprint: string;
+}
+
+let attribution: EgressAttribution | undefined;
+
+/** Record the scope and policy generation a later denial is attributed to. Called only on a pass that ESTABLISHED what is in force, never on a skipped-unchanged turn and never on an apply that threw. */
+export function rememberEgressAttribution(next: EgressAttribution): void {
+  attribution = next;
+}
+
+/** The current attribution, or undefined if no policy has been applied in this process yet. */
+export function currentEgressAttribution(): EgressAttribution | undefined {
+  return attribution;
+}
+
+export function resetEgressAttribution(): void {
+  attribution = undefined;
+}
+
+/** Configured denial-log path, or undefined (⇒ the poller does not run). */
+export function egressDenialLogPath(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const raw = env.OE_EGRESS_DENIAL_LOG?.trim();
+  return raw ? raw : undefined;
+}
+
+export function egressDenialPollMs(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = Number(env.OE_EGRESS_DENIAL_POLL_MS ?? "");
+  if (!Number.isFinite(raw) || raw <= 0) return DEFAULT_POLL_MS;
+  return Math.max(MIN_POLL_MS, Math.trunc(raw));
+}
+
+export interface DenialPollDeps {
+  /** Byte size of the log, or undefined if it cannot be stated (missing, unreadable, not a file). */
+  readonly size: () => Promise<number | undefined>;
+  /** Read `[from, to)` as text. May throw; the caller degrades. */
+  readonly read: (from: number, to: number) => Promise<string>;
+  readonly attribution: () => EgressAttribution | undefined;
+  readonly audit: (entry: AuditInput) => Promise<void>;
+  /** Emit a diagnostic AT MOST ONCE per distinct reason, for the lifetime of the process. */
+  readonly warnOnce: (reason: string, message: string) => void;
+  /** Milliseconds this pass aggregates over — carried onto the row so a count is interpretable. */
+  readonly windowMs: number;
+}
+
+export interface DenialPollResult {
+  readonly offset: number | undefined;
+  readonly rowsWritten: number;
+  readonly scan?: DenialScan;
+  readonly skipped?: "no-file" | "no-growth" | "unreadable" | "no-attribution" | "no-denials";
+}
+
+/** One poll pass; it never throws. The aggregation contract is one row per (host, policy generation) per pass carrying a count, so a worker denied a thousand times a minute writes one row a minute. */
+export async function pollEgressDenials(deps: DenialPollDeps, lastOffset: number | undefined): Promise<DenialPollResult> {
+  let size: number | undefined;
+  try {
+    size = await deps.size();
+  } catch {
+    size = undefined;
+  }
+  if (size === undefined) {
+    // Missing or unreadable. This is the NORMAL state on a deployment whose proxy predates the
+    // denial log, and on every deployment for the first moments after boot — so it is a one-time
+    // note, not a recurring warning, and the offset is left untouched so a file that appears later
+    // is picked up from its end like any other cold start.
+    deps.warnOnce(
+      "no-file",
+      "[open-everywhere:egress] denial log not readable — egress denials will not reach the audit log (the plane stays as dark as it is on the Vercel tier). Check OE_EGRESS_DENIAL_LOG and the shared volume.",
+    );
+    return { offset: lastOffset, rowsWritten: 0, skipped: "no-file" };
+  }
+
+  const plan = planTailRead(size, lastOffset);
+  if (plan.rotated) {
+    deps.warnOnce("rotated", "[open-everywhere:egress] denial log rotated — resuming from the start of the new file.");
+  }
+  if (plan.to <= plan.from) return { offset: plan.to, rowsWritten: 0, skipped: "no-growth" };
+
+  // Bound the read. A gap larger than the cap keeps the NEWEST bytes: the first line will usually be
+  // a partial one, which the reducer drops on its own (no result tag, or a token that is not a host).
+  const from = plan.to - plan.from > MAX_READ_BYTES ? plan.to - MAX_READ_BYTES : plan.from;
+  let chunk: string;
+  try {
+    chunk = await deps.read(from, plan.to);
+  } catch (err) {
+    deps.warnOnce("unreadable", `[open-everywhere:egress] denial log read failed — egress denials are not being recorded: ${String(err)}`);
+    // Advance anyway: a read that fails repeatedly at the same offset would otherwise retry the same
+    // bytes forever, and the alternative to losing this chunk is never reading any later one.
+    return { offset: plan.to, rowsWritten: 0, skipped: "unreadable" };
+  }
+
+  const scan = reduceDenialLog(chunk);
+  if (scan.unparsed > 0) {
+    deps.warnOnce(
+      "unparsed",
+      `[open-everywhere:egress] ${scan.unparsed} denial line(s) did not yield a host — this parser and this Squid build disagree about the log format. No half-parsed value is ever recorded; see agent/access/egress-denial-log.ts.`,
+    );
+  }
+  if (scan.hosts.length === 0) return { offset: plan.to, rowsWritten: 0, scan, skipped: "no-denials" };
+
+  const scope = deps.attribution();
+  if (scope === undefined) {
+    // Denials before this process ever applied a policy. There is no org to stamp and none may be
+    // invented, so the rows are dropped and the offset still advances — replaying them after the
+    // first push would attribute them to a generation that provably was not in force when they
+    // happened.
+    deps.warnOnce(
+      "no-attribution",
+      "[open-everywhere:egress] egress denials observed before any policy was applied in this process — dropped, because nothing can say which org or policy generation they belong to.",
+    );
+    return { offset: plan.to, rowsWritten: 0, scan, skipped: "no-attribution" };
+  }
+
+  const kept = scan.hosts.slice(0, MAX_HOSTS_PER_PASS);
+  const dropped = scan.hosts.length - kept.length;
+  let rowsWritten = 0;
+  for (const { host, count } of kept) {
+    try {
+      await deps.audit({
+        org: scope.org,
+        platform: scope.platform,
+        workspace: scope.workspace,
+        ...(scope.surface !== undefined ? { surface: scope.surface } : {}),
+        action: EGRESS_DENIED_ACTION,
+        // 🔴 HOST + FINGERPRINT + COUNT. Nothing else may be added to this object — see the
+        // invariant in egress-denial-log.ts. `windowMs` makes the count interpretable and
+        // `distinctHostsDropped` keeps the per-pass cap honest rather than silent.
+        detail: {
+          host,
+          count,
+          policyFingerprint: scope.policyFingerprint,
+          windowMs: deps.windowMs,
+          ...(dropped > 0 ? { distinctHostsDropped: dropped } : {}),
+        },
+      });
+      rowsWritten++;
+    } catch {
+      // appendAudit is best-effort by contract and already swallows its own failures; this catch is
+      // for the injected seam, and it must not stop the remaining hosts being recorded.
+    }
+  }
+  return { offset: plan.to, rowsWritten, scan };
+}
+
+export interface DenialPoller {
+  stop(): void;
+}
+
+/** Starts the poller only when a denial log is configured, and returns undefined otherwise, which is every Vercel deployment and every self-host that has not mounted the volume. The timer is `unref`'d, because diagnostics must never keep the process alive. */
+export function startEgressDenialPoller(options?: { readonly env?: NodeJS.ProcessEnv }): DenialPoller | undefined {
+  const env = options?.env ?? process.env;
+  const path = egressDenialLogPath(env);
+  if (path === undefined) return undefined;
+  const intervalMs = egressDenialPollMs(env);
+
+  const warned = new Set<string>();
+  const warnOnce = (reason: string, message: string): void => {
+    if (warned.has(reason)) return;
+    warned.add(reason);
+    console.warn(message);
+  };
+
+  const deps: DenialPollDeps = {
+    size: async () => {
+      const s = await stat(path);
+      return s.isFile() ? s.size : undefined;
+    },
+    read: async (from, to) => {
+      const fh = await open(path, "r");
+      try {
+        const length = to - from;
+        const buf = Buffer.alloc(length);
+        const { bytesRead } = await fh.read(buf, 0, length, from);
+        return buf.subarray(0, bytesRead).toString("utf8");
+      } finally {
+        await fh.close();
+      }
+    },
+    attribution: currentEgressAttribution,
+    audit: appendAudit,
+    warnOnce,
+    windowMs: intervalMs,
+  };
+
+  let offset: number | undefined;
+  let running = false;
+  const tick = async (): Promise<void> => {
+    if (running) return; // a slow store must never let two passes overlap and double-count
+    running = true;
+    try {
+      const result = await pollEgressDenials(deps, offset);
+      offset = result.offset;
+    } catch (err) {
+      warnOnce("pass-threw", `[open-everywhere:egress] denial poll pass failed — continuing: ${String(err)}`);
+    } finally {
+      running = false;
+    }
+  };
+
+  const timer = setInterval(() => void tick(), intervalMs);
+  timer.unref?.();
+  console.info(
+    `[open-everywhere:egress] denial poller watching ${path} every ${Math.round(intervalMs / 1000)}s — TCP_DENIED lines become aggregated \`egress.denied\` audit rows (host + policy fingerprint + count, nothing else), which permission_fit_report reads as widening evidence.`,
+  );
+  return {
+    stop: () => clearInterval(timer),
+  };
+}