@open-everywhere/core 0.1.0

package/agent/access/background-tasks.ts

@@ -0,0 +1,364 @@
+// This is the only module that parses eve's background-task shapes; no second reader of them may exist. The taint handler these shapes serve is unconditional — nothing here reads a setting, so the defence has no off switch.
+
+/** eve's background-task lifecycle tools. This list is a UNION across eve versions — a name eve no longer mounts is inert, a name eve still mounts is mandatory for the subtractions that read it — so delete a name only in the commit that bumps the pinned eve past the release which removed it. `task_update` left in the commit that pinned eve 0.54.3: 0.54.1 removed the tool outright and offers no replacement verb, so no seat can be offered it and nothing can subtract it. */
+export const TASK_TOOL_NAMES: readonly string[] = ["task_peek", "task_cancel", "task_sleep"];
+
+/** The three task tools eve offers a PARENT, measured against eve 0.51.0's shouldHideTool rather than inferred. The narrowing is a per-tool availability declaration, and access/untrusted-projection.ts keys on the same seat verdict. */
+export const TASK_PARENT_TOOL_NAMES: readonly string[] = ["task_peek", "task_cancel", "task_sleep"];
+
+/** eve 0.40.0 DELETES task_peek, so nothing may depend on a result of it ever arriving; settlement keys on terminalTaskNotification instead. The name survives because eve 0.39.3 still mounts the tool, and a view it returns must still seed the taint plane. */
+const TASK_PEEK_TOOL = "task_peek";
+/** task_cancel also returns task views, and a cancel of an already-terminal task returns lastOutput — the child's prose. Reading only the peek left that second output path taint-blind, so both view-bearing tools are accepted. */
+const TASK_CANCEL_TOOL = "task_cancel";
+const TASK_VIEW_TOOLS: ReadonlySet<string> = new Set([TASK_PEEK_TOOL, TASK_CANCEL_TOOL]);
+
+/** eve produces this receipt in TWO envelopes and the reader takes both: the runtime-action receipt (kind subagent-result, carrying a backgroundTask envelope) and the background-tool receipt (kind tool-result, output {agentId, status "working", taskId}). The output half is identical in both, and that strict schema is the second envelope's whole discriminator. */
+export type TaskReceipt = {
+  readonly taskId: string;
+  readonly callId: string;
+  /** eve's persistent-session handle, spelled ag_<subagent-name>:<12 hex>, or null when unreadable. It is life-stable across continuations, and both envelopes build it byte-identically. */
+  readonly agentId: string | null;
+  /** eve's own name for the delegation the seat called — subagentName on arm A, toolName on arm B, and empty when the envelope carries neither. It is NOT sliced out of agentId: that handle's spelling is eve's to change, so the audit row's tool name must not be a hostage to an id format. */
+  readonly tool: string;
+};
+
+/** eve's task-id namespace stamp. Both readers keep an arbitrary word out of a store key with it. */
+const TASK_ID_PREFIX = "task_";
+
+/** Two arms, disjoint by kind, each a POSITIVE test for a parked background task. Arm B keys on eve's receipt output schema and deliberately not on toolName === "agent" — a name allow-list would answer null for a named subagent and take the taint adoption fail-OPEN; never throws, because a hook edge may not fail on an unpredicted shape. */
+export function readTaskReceipt(result: unknown): TaskReceipt | null {
+  try {
+    const r = result as
+      | { kind?: unknown; callId?: unknown; backgroundTask?: { taskId?: unknown }; output?: unknown; subagentName?: unknown; toolName?: unknown }
+      | null;
+    if (r === null || typeof r !== "object") return null;
+    const callId = r.callId;
+    if (typeof callId !== "string" || callId.length === 0) return null;
+    const agentId = (r.output as { agentId?: unknown } | null | undefined)?.agentId;
+    const handle = typeof agentId === "string" && agentId.length > 0 ? agentId : null;
+
+    if (r.kind === "subagent-result") {
+      const taskId = r.backgroundTask?.taskId;
+      if (typeof taskId !== "string" || taskId.length === 0) return null;
+      return { taskId, callId, agentId: handle, tool: typeof r.subagentName === "string" ? r.subagentName : "" };
+    }
+
+    if (r.kind === "tool-result") {
+      const output = r.output as { status?: unknown; taskId?: unknown } | null | undefined;
+      if (output === null || typeof output !== "object") return null;
+      if (output.status !== "working") return null;
+      const taskId = output.taskId;
+      if (typeof taskId !== "string" || !taskId.startsWith(TASK_ID_PREFIX) || taskId.length <= TASK_ID_PREFIX.length) return null;
+      if (handle === null) return null;
+      // Arm B spells the same name under eve's generic tool key, so both envelopes still read to one
+      // shape — the property OPE-943 pinned and this field must not break.
+      return { taskId, callId, agentId: handle, tool: typeof r.toolName === "string" ? r.toolName : "" };
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// The discriminator for a delegation failure is isError, never the error code: eve declares eight codes and picks between them, so a code list would answer "not a failure" the day it adds a ninth — fail-SILENT on a row that exists to make a death visible. The code is carried, never matched on.
+
+export type DelegationFailure = {
+  readonly callId: string;
+  /** eve's own error class (`SUBAGENT_EXECUTION_FAILED` and its siblings), or `""` when the result
+   *  carries none. Never matched on — see the header above. */
+  readonly errorClass: string;
+  /** eve's own error message — the sentence that says what went wrong — or empty when the result carries none. It is upstream-authored and attacker-influenceable, so it is scrubbed and truncated wherever it lands: a diagnostic, never an instruction. */
+  readonly errorText: string;
+  readonly tool: string;
+  /**
+   * eve's own STATUS word: `failed` for a worker that died, `cancelled` for an invocation eve
+   * cancelled. Kept apart because they are different events for an operator.
+   *
+   * 🔴 IT IS NOT THE AUDIT ROW'S `outcome` FIELD, AND THE RENAME IS THE FIX (OPE-1737, round 2).
+   * That field used to carry this word on both edges, with `"failed"` as the fallback here when the
+   * outcome kind was unreadable — so ship #201's rows could not even say WHICH edge wrote them.
+   * `delegation.task_failed` now spends `outcome` on the edge name and carries this word as
+   * `status`.
+   */
+  readonly status: string;
+};
+
+/** A positive test needing all three parts: a subagent-result kind, a non-empty callId, and eve's own isError. Never throws, because a hook edge may not fail because a payload had a shape nobody predicted. */
+export function readDelegationFailure(result: unknown): DelegationFailure | null {
+  try {
+    const r = result as
+      | {
+          kind?: unknown;
+          callId?: unknown;
+          isError?: unknown;
+          subagentName?: unknown;
+          outcome?: { result?: { kind?: unknown; error?: { message?: unknown } } };
+          output?: unknown;
+        }
+      | null;
+    if (r === null || typeof r !== "object") return null;
+    if (r.kind !== "subagent-result") return null;
+    if (r.isError !== true) return null;
+    const callId = r.callId;
+    if (typeof callId !== "string" || callId.length === 0) return null;
+    const out = r.output as { code?: unknown; message?: unknown } | null | undefined;
+    const code = out?.code;
+    const outcome = r.outcome?.result?.kind;
+    // The message sits in BOTH halves of eve's envelope. output.message is read first because eve stamps it on every arm; the nested one is the fallback, so a future arm that fills only the structured half still diagnoses.
+    const nested = r.outcome?.result?.error?.message;
+    const message = typeof out?.message === "string" && out.message.length > 0 ? out.message : nested;
+    return {
+      callId,
+      errorClass: typeof code === "string" && code.length > 0 ? code : "",
+      errorText: typeof message === "string" ? message : "",
+      tool: typeof r.subagentName === "string" ? r.subagentName : "",
+      status: typeof outcome === "string" && outcome.length > 0 ? outcome : "failed",
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** eve's own terminal set. input_required is NOT terminal — a child parked on a question can still read untrusted content and answer — while failed and cancelled ARE terminal and DO adopt taint: terminal means the marker can no longer change, never that the child succeeded. */
+export const TERMINAL_TASK_STATUSES: readonly string[] = ["completed", "failed", "cancelled"];
+
+/** The IDS OE reads off one task view — deliberately NOT called `TaskView`, because eve owns that
+ *  name for a wider shape. This is a projection: `lastOutput` (the child's prose) and
+ *  `inputRequests` are dropped here and are never read by the taint plane. */
+export type TaskSummary = {
+  readonly taskId: string;
+  readonly status: string;
+  /** eve's agent-handle id for the worker, or null. It is NOT a session id and cannot address the worker — eve strips the real child session id before OE ever sees a view — so no ONE named worker can be retired; retiring the parent seat generation still reaps them in bulk. */
+  readonly agentId: string | null;
+};
+
+/** TWO tools bear views, not one: a cancel of an already-terminal task returns the full view too, so a peek-only read left that second output path taint-blind. Views are read for their IDS ONLY — lastOutput holds the child's prose and is never touched here. */
+export function taskViewsOf(result: unknown): readonly TaskSummary[] {
+  try {
+    const r = result as { kind?: unknown; toolName?: unknown; output?: { tasks?: unknown } } | null;
+    if (r === null || typeof r !== "object") return [];
+    if (r.kind !== "tool-result" || typeof r.toolName !== "string" || !TASK_VIEW_TOOLS.has(r.toolName)) return [];
+    const tasks = r.output?.tasks;
+    if (!Array.isArray(tasks)) return [];
+    const out: TaskSummary[] = [];
+    for (const raw of tasks) {
+      const t = raw as { taskId?: unknown; status?: unknown; metadata?: { agentId?: unknown } } | null;
+      if (t === null || typeof t !== "object") continue;
+      if (typeof t.taskId !== "string" || t.taskId.length === 0) continue;
+      if (typeof t.status !== "string" || t.status.length === 0) continue;
+      const agentId = t.metadata?.agentId;
+      out.push({ taskId: t.taskId, status: t.status, agentId: typeof agentId === "string" && agentId.length > 0 ? agentId : null });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+/** The views whose status can never change again — the one edge where a parent may read a background child's taint marker and be sure of the answer. Split out so a test can assert both halves of the filter. */
+export function terminalTaskViewsOf(result: unknown): readonly TaskSummary[] {
+  return taskViewsOf(result).filter((v) => TERMINAL_TASK_STATUSES.includes(v.status));
+}
+
+// eve's notification TEXT is the only settlement signal that reaches authored code, and this is its one reader: the structured half is consumed into harness session state a hook cannot see. The parse is a SELECTOR, never a fact — every consequence is keyed on OE's own dispatch rows, so a drifted or forged line finds no row and is inert.
+
+export type TaskNotification = {
+  readonly taskId: string;
+  /** eve's own status word (`completed`, `failed`, `cancelled`, `working`), or `"input_required"`
+   *  for the `needs input.` spelling. Callers filter with {@link TERMINAL_TASK_STATUSES}. */
+  readonly status: string;
+};
+
+/** The "is" is optional because eve renders the FAILED arm without it; a grammar that required it would match completed and cancelled and silently miss every failure, which is fail-OPEN on taint adoption. The progress notification is deliberately not matched — it ends in a colon, not a full stop. */
+const TASK_NOTIFICATION_RE =
+  /^Background task (\S+) \([^)]*\) (?:needs input\.|(?:is )?([a-z_]+)\.)/m;
+const TASK_NOTIFICATION_START_RE =
+  /^Background task (\S+) \([^)]*\) (?:needs input\.|(?:is )?([a-z_]+)\.)/;
+const TASK_NOTIFICATION_GLOBAL_RE =
+  /^Background task (\S+) \([^)]*\) (?:needs input\.|(?:is )?([a-z_]+)\.)/gm;
+
+/** Deliberately wider than eve's own minting: this check exists to keep an arbitrary word out of a store key, not to re-implement how eve mints a task id. */
+const TASK_ID_RE = /^task_[A-Za-z0-9_-]{8,}$/;
+
+/** Anchored at the start of a LINE, not of the message, because eve folds a task COMPLETION COHORT — caller-less deliveries whose `taskDeliveryId` ends `:ready:completed` — into one turn and joins their text. That arm is LIVE on the pinned 0.54.3, unlike the auth-carrying merge (OPE-2042), so a settlement really can arrive mid-message: a message-anchored match would miss it, and missing it fails OPEN on the taint plane. A member can therefore put this sentence in their own message; every consequence was checked against that, and none of them is a way in. */
+export function readTaskNotification(message: unknown): TaskNotification | null {
+  try {
+    if (typeof message !== "string" || message.length === 0) return null;
+    const m = TASK_NOTIFICATION_RE.exec(message.trimStart());
+    if (m === null) return null;
+    const taskId = m[1] ?? "";
+    if (!TASK_ID_RE.test(taskId)) return null;
+    // Arm 2 of the grammar (`needs input.`) carries no status word; eve's own status for it is
+    // `input_required`, which is NON-terminal, so naming it here keeps the caller's terminal filter
+    // the single place that decides what settles.
+    const status = m[2] ?? "input_required";
+    return { taskId, status };
+  } catch {
+    return null;
+  }
+}
+
+/** Every valid notification line in one host-rendered message, in delivery order. */
+export function readTaskNotifications(message: unknown): readonly TaskNotification[] {
+  try {
+    if (typeof message !== "string" || message.length === 0) return [];
+    const out: TaskNotification[] = [];
+    // The regexp is module-scoped for one reviewed grammar. Reset lastIndex because the global
+    // cursor is mutable and this reader can run more than once in one process.
+    TASK_NOTIFICATION_GLOBAL_RE.lastIndex = 0;
+    for (const match of message.trimStart().matchAll(TASK_NOTIFICATION_GLOBAL_RE)) {
+      const taskId = match[1] ?? "";
+      if (!TASK_ID_RE.test(taskId)) continue;
+      out.push({ taskId, status: match[2] ?? "input_required" });
+    }
+    TASK_NOTIFICATION_GLOBAL_RE.lastIndex = 0;
+    return out;
+  } catch {
+    TASK_NOTIFICATION_GLOBAL_RE.lastIndex = 0;
+    return [];
+  }
+}
+
+/**
+ * Does the first trimmed line carry a terminal header? Eve's public hook flattens task-delivery
+ * provenance, so this is a conservative redispatch discriminator, not proof of authorship. It
+ * rejects an arbitrary task update that embeds a terminal-looking line after its own prefix.
+ */
+export function taskNotificationStartsWithTerminal(message: unknown): boolean {
+  try {
+    if (typeof message !== "string" || message.length === 0) return false;
+    const match = TASK_NOTIFICATION_START_RE.exec(message.trimStart());
+    if (match === null || !TASK_ID_RE.test(match[1] ?? "")) return false;
+    return TERMINAL_TASK_STATUSES.includes(match[2] ?? "input_required");
+  } catch {
+    return false;
+  }
+}
+
+/** The label eve writes before a failed task's error payload.
+ *
+ *  MEASURED on the PINNED eve 0.54.3 dist, `execution/tasks/child/steps.js`:
+ *  `` `${t} failed.\n\nError:\n${formatTaskOutput(e.lastOutput.data)}` `` — byte-identical to the
+ *  0.44.0 spelling this reader was written against. `packages/core/scripts/task-notification-test.ts`
+ *  P1b reads the same bytes and reds the day they move. */
+const TASK_FAILURE_ERROR_LABEL = "\n\nError:\n";
+
+/** How far a RAW notification fallback is carried. It bounds what {@link taskNotificationFailure}
+ *  hands its caller; the audit sink then applies the repo's own, tighter error cap
+ *  (`audit/tool-action.ts` `auditErrorDetail`, 300 characters) on top of it. */
+const RAW_NOTIFICATION_MAX_CHARS = 600;
+
+/** What a FAILED settlement notification says about the death.
+ *
+ * 🔴 `errorText` IS NEVER EMPTY WHEN `parse` IS NOT `"none"` (OPE-1737, round 2). Ship #201 wrote
+ * three `delegation.task_failed` rows whose `error` was `""`, and an empty field says nothing at all
+ * — not even whether the reader looked. So a text that IS a failed settlement always yields
+ * something: eve's own message when the payload reads, and the bounded notification paragraph itself
+ * when it does not. `parse` names which of the two happened, so an operator never has to guess. */
+export type TaskNotificationFailure = {
+  readonly errorClass: string;
+  readonly errorText: string;
+  /**
+   * WHICH READER ANSWERED, and it is an audit field in its own right:
+   *   • `"json"` — eve's `{code, message}` payload, split into {@link errorText} and
+   *     {@link errorClass}. The healthy shape for a delegation;
+   *   • `"text"` — a payload that is not that object, OR one with no readable `message` half,
+   *     carried whole as the message. eve's pass-through arm sends that second shape, so it is a
+   *     live arm and not a courtesy;
+   *   • `"raw"` — no readable payload at all, so the notification's own paragraph is carried instead.
+   *     A row with this value says eve's format moved, or eve sent a failure with no `Error:`
+   *     paragraph;
+   *   • `"none"` — the text is not a failed settlement notification. The only arm with an empty
+   *     {@link errorText}.
+   */
+  readonly parse: "json" | "text" | "raw" | "none";
+};
+
+const NO_NOTIFICATION_FAILURE: TaskNotificationFailure = { errorClass: "", errorText: "", parse: "none" };
+
+/** The message STOPS AT THE FIRST BLANK LINE, and that bound is the privacy fence: eve joins a turn's coalesced deliveries with a blank line, so reading further would put a member's own message into an audit row. Nothing keys on the result — both fields reach audit detail alone, scrubbed and truncated — and the class from this edge is forgeable where the failure-result edge's is not. */
+export function taskNotificationFailure(message: unknown): TaskNotificationFailure {
+  try {
+    if (typeof message !== "string" || message.length === 0) return NO_NOTIFICATION_FAILURE;
+    const text = message.trimStart();
+    const m = TASK_NOTIFICATION_RE.exec(text);
+    if (m === null) return NO_NOTIFICATION_FAILURE;
+    // The FAILED arm only. `completed` carries a `Result:` payload — the child's own prose, which no
+    // audit row may hold — and `cancelled`/`needs input.` carry nothing at all.
+    if (m[2] !== "failed") return NO_NOTIFICATION_FAILURE;
+    if (!TASK_ID_RE.test(m[1] ?? "")) return NO_NOTIFICATION_FAILURE;
+    // 🔴 READ BEFORE THE PAYLOAD, so every arm below has a non-empty answer to fall back to.
+    const raw = rawFailureNotification(text, m.index);
+    const tail = text.slice(m.index + m[0].length);
+    if (!tail.startsWith(TASK_FAILURE_ERROR_LABEL)) return raw;
+    const body = tail.slice(TASK_FAILURE_ERROR_LABEL.length);
+    const end = body.indexOf("\n\n");
+    const payload = end < 0 ? body : body.slice(0, end);
+    if (payload.length === 0) return raw;
+    return splitFailurePayload(payload);
+  } catch {
+    return NO_NOTIFICATION_FAILURE;
+  }
+}
+
+/**
+ * The notification's OWN first paragraph, bounded — the answer when no payload reads (OPE-1737,
+ * round 2).
+ *
+ * 🔴 IT KEEPS THE SAME PRIVACY FENCE THE PAYLOAD READER HAS, and that is why it stops at the first
+ * blank line rather than carrying "the rest of the text". eve joins a turn's coalesced deliveries
+ * with `\n\n` (`harness/messages.js` `appendUserContent`), so the bytes after the first blank line
+ * can be a MEMBER'S OWN MESSAGE. Reading past it to make the field richer would put that message in
+ * an audit row — the exact fence §14e pins. What survives the bound is eve's own sentence, which
+ * names the task, the worker and the status word, and the fact that nothing labelled `Error:`
+ * followed it. That is a diagnosis; an empty field is not.
+ *
+ * Never empty: the slice starts at the matched sentence, which is non-empty by construction.
+ */
+function rawFailureNotification(text: string, at: number): TaskNotificationFailure {
+  const rest = text.slice(at);
+  const end = rest.indexOf("\n\n");
+  const bounded = (end < 0 ? rest : rest.slice(0, end)).trimEnd();
+  const capped = bounded.length <= RAW_NOTIFICATION_MAX_CHARS ? bounded : `${bounded.slice(0, RAW_NOTIFICATION_MAX_CHARS)}…`;
+  return { errorClass: "", errorText: capped, parse: "raw" };
+}
+
+/** eve's `{code, message}` object as its two fields, or the whole payload as the message when it is
+ *  anything else. A parse failure is not an error here — it is the plain-string arm. */
+function splitFailurePayload(payload: string): TaskNotificationFailure {
+  const whole: TaskNotificationFailure = { errorClass: "", errorText: payload, parse: "text" };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    return whole;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return whole;
+  const o = parsed as { code?: unknown; message?: unknown };
+  // `code` is what `subagentFailureOutput` guarantees; `message` is what it fills beside it. An
+  // object carrying neither is carried whole, so nothing a future eve sends is silently dropped.
+  const errorClass = typeof o.code === "string" ? o.code : "";
+  const errorText = typeof o.message === "string" ? o.message : "";
+  // 🔴 THE MESSAGE HALF DECIDES, NOT THE PAIR. `subagentFailureOutput`'s PASS-THROUGH arm guarantees
+  // a `code` and nothing else (`execution/tools/workflow/owner-inbox.js`; the `"text"` arm of
+  // {@link TaskNotificationFailure.parse} says the same, and
+  // `packages/core/scripts/task-notification-test.ts` P1d pins it), so an object with a class and no message is a live
+  // shape — and answering `{errorClass, errorText: ""}` there would print exactly the empty `error`
+  // this round exists to remove, under a `parse` claiming the payload read cleanly. The class is
+  // kept and the whole payload becomes the message instead.
+  if (errorText.length === 0) return { ...whole, errorClass };
+  return { errorClass, errorText, parse: "json" };
+}
+
+/** The projection the settlement edge consumes, so the notification path and the task-view path hand their callers one shape. agentId is null here: eve's notification text does not carry it, and the caller recovers it from OE's own dispatch row. */
+export function terminalTaskNotification(message: unknown): TaskSummary | null {
+  return terminalTaskNotifications(message)[0] ?? null;
+}
+
+/** Every terminal task notification in one coalesced host message. */
+export function terminalTaskNotifications(message: unknown): readonly TaskSummary[] {
+  return readTaskNotifications(message)
+    .filter((note) => TERMINAL_TASK_STATUSES.includes(note.status))
+    .map((note) => ({ taskId: note.taskId, status: note.status, agentId: null }));
+}

package/agent/access/browser-hosts.ts

@@ -0,0 +1,151 @@
+// The operator's browser host declaration — the ONE browser reach list, read by both agent-browser's inner wall and the sandbox egress firewall. It is config-as-code, and it is FAIL-CLOSED whole-list: any invalid row invalidates the declaration and the capability does not arm.
+
+import { processRegistrySlot } from "../lib/process-registry.js";
+import { getSettings } from "../settings/settings.js";
+import { egressHostsOverlap, normaliseEgressHost, type HttpMethod } from "./bundle.js";
+import { GIT_BROKER_HOSTS, RESERVED_BROKER_HOST_REASON } from "./reserved-hosts.js";
+
+/** Mirrors `HttpMethod` (access/bundle.ts) so a browser host row and a bundle connection row are narrowed by one vocabulary. */
+const HTTP_METHODS: ReadonlySet<string> = new Set<HttpMethod>(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
+
+export interface BrowserHostDeclaration {
+  /** Bare lowercase hostname. No wildcards, schemes, ports, paths, credentials or literal IPs;
+   *  loopback names and 127.0.0.0/8 are the one accepted non-DNS shape (the in-sandbox dev server). */
+  readonly host: string;
+  /** The HTTP verbs the sandbox firewall admits for this host — required, and non-empty. The row is the control and raises no per-call card: declaring `["GET", "HEAD"]` is what makes a host read-only, and the firewall enforces it. */
+  readonly methods: readonly HttpMethod[];
+  /** The egress connection whose credential the FIREWALL stamps: the browser never holds the secret, and this field is the credential's identity, never its value. Fail-closed if the session does not reach the connection, and a credentialed row also gives `bash` that authenticated reach under `methods`. */
+  readonly credential?: string;
+  /** Arm `browser_evaluate` (model-written JavaScript, run in the page) for this host. Default FALSE, and the default is the ruling: arbitrary page scripting is re-added only by an operator's per-host declaration. */
+  readonly evaluate?: boolean;
+  /** Why THIS deployment declares this host, in one line. Required, and it is not decoration: the
+   *  row is a reviewed security decision, and a reviewer who cannot see the reason cannot review it.
+   *  Same discipline `agent/settings/settings.ts` asks of every override entry. */
+  readonly why: string;
+}
+
+// One label: alnum with interior hyphens; a dotted name needs ≥2 labels and an alphabetic TLD. The
+// alphabetic TLD is what structurally rejects every literal IP — the cloud metadata endpoint
+// (169.254.169.254) included, the same P0-2 posture as the host-egress SSRF guard.
+const DNS_NAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*\.[a-z]{2,}$/;
+
+/** Loopback browse targets ride the INNER wall only: they never leave the sandbox VM, so they never cross the egress firewall and no credential can be injected on them. */
+export function isLoopbackBrowseHost(host: string): boolean {
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  if (host === "::1" || host === "[::1]") return true;
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  return m !== null && Number(m[1]) === 127;
+}
+
+/** Every way a declaration can be wrong, named; pure and total, and `defineBrowserHosts` turns a non-empty result into a boot failure. A host the git read-broker reserves is refused because `mergeGitReadBroker` replaces those hosts' rules wholesale mid-turn, so a reviewed row there is silently displaced. */
+export function browserHostProblems(rows: readonly BrowserHostDeclaration[]): readonly string[] {
+  const problems: string[] = [];
+  const seen = new Set<string>();
+  if (rows.length === 0) {
+    problems.push("the browser host declaration is empty — the capability requires at least one declared host (fail closed)");
+  }
+  for (const row of rows) {
+    const host = row.host;
+    const at = `"${host}"`;
+    if (typeof host !== "string" || host.trim() !== host || host.toLowerCase() !== host || host.length === 0) {
+      problems.push(`${at}: a host is a bare lowercase hostname with no surrounding whitespace`);
+      continue;
+    }
+    // Loopback is tested first, and the order is load-bearing: `::1` is a legitimate loopback spelling and also contains the `:` the punctuation rule below rejects.
+    if (isLoopbackBrowseHost(host)) {
+      // accepted as-is
+    } else if (host.includes("*")) {
+      problems.push(`${at}: wildcards are not supported — the egress firewall matches exact hosts, so a wildcard would open nothing on the outer wall; declare each hostname`);
+    } else if (/[/:@\s]/.test(host)) {
+      problems.push(`${at}: bare hostname only — no scheme, port, path, or credentials`);
+    } else if (/^(\d{1,3}\.){3}\d{1,3}$/.test(host)) {
+      problems.push(`${at}: literal IPs are refused (metadata/private-range hazard) — declare a DNS name, or a loopback address for an in-sandbox server`);
+    } else if (!DNS_NAME.test(host)) {
+      problems.push(`${at}: not a valid hostname (lowercase DNS labels, alphabetic TLD)`);
+    }
+    if (seen.has(host)) {
+      problems.push(`${at}: declared twice — one row per host, so the verbs and the credential a host is reached with are unambiguous`);
+    }
+    seen.add(host);
+
+    // Overlap, not equality — the same question lint 7 asks — because a row spelling `*.github.com` claims `codeload.github.com` without ever writing it.
+    const claimed = normaliseEgressHost(host);
+    const reserved = GIT_BROKER_HOSTS.find((r) => egressHostsOverlap(claimed, r));
+    if (reserved !== undefined) {
+      problems.push(`${at}: ${claimed === reserved ? "" : `overlaps ${reserved}, and `}${RESERVED_BROKER_HOST_REASON}`);
+    }
+
+    if (!Array.isArray(row.methods)) {
+      problems.push(`${at}: declare the HTTP verbs the firewall admits, as an array`);
+      continue;
+    }
+    if (row.methods.length === 0) {
+      problems.push(`${at}: declare the HTTP verbs the firewall admits — a browser host is a host+method row, and an empty list would admit nothing`);
+    }
+    for (const method of row.methods) {
+      if (!HTTP_METHODS.has(method)) problems.push(`${at}: "${method}" is not an HTTP verb this plane admits`);
+    }
+    if (row.credential !== undefined) {
+      if (row.credential.trim().length === 0) {
+        problems.push(`${at}: "credential" names an egress connection id — an empty string names nothing`);
+      }
+      if (isLoopbackBrowseHost(host)) {
+        problems.push(
+          `${at}: a loopback host carries no credential — loopback traffic never crosses the egress firewall, so there is no boundary at which to inject one`,
+        );
+      }
+    }
+    if (typeof row.why !== "string" || row.why.trim().length === 0) {
+      problems.push(`${at}: declare WHY this deployment reaches this host — the row is a reviewed security decision`);
+    }
+  }
+  return problems;
+}
+
+// No read-only/write predicate lives here, deliberately: `openWriteHosts` (access/egress.ts) already answers that against the COMPILED policy, and a second spelling over the declaration would be a second answer.
+
+// Process-global rather than module-private: the two halves can load different copies of core, and a split registry would be SILENT — the reader would just see an unarmed capability.
+const SLOT = processRegistrySlot<readonly BrowserHostDeclaration[]>("browser-hosts.v1");
+
+/** Validate a deployment's declaration and freeze it. Called at MODULE LOAD, so a bad row fails the boot rather than silently arming a browser with reach nobody wrote. */
+export function defineBrowserHosts(rows: readonly BrowserHostDeclaration[]): readonly BrowserHostDeclaration[] {
+  const problems = browserHostProblems(rows);
+  if (problems.length > 0) {
+    throw new Error(`browser host declaration is unusable — NOT arming (fail closed):\n${problems.map((p) => `  - ${p}`).join("\n")}`);
+  }
+  return Object.freeze(rows.map((r) => Object.freeze({ ...r })));
+}
+
+/** Register the deployment's declaration (app boot). A later call REPLACES the previous one — the
+ *  whole-record convention `registerSurfaces`/`registerDeploymentIdentity` use, so a partial second
+ *  call cannot leave half of one declaration standing beside half of another. */
+export function registerBrowserHosts(rows: readonly BrowserHostDeclaration[]): void {
+  SLOT.set(defineBrowserHosts(rows));
+}
+
+/** What the operator DECLARED, whatever `browser.enabled` says — not the armed reach. Every consumer that turns a row into REACH must go through {@link browserEgressHosts} or {@link browserEvaluateHosts}, which apply the master flag. */
+export function browserHostDeclarations(): readonly BrowserHostDeclaration[] {
+  return SLOT.get() ?? [];
+}
+
+/** The declared hosts that cross the egress firewall: non-loopback rows only, and only while the master flag is armed. Without that check a deployment with `browser.enabled: false` would still open every declared host and still stamp its third-party secret on requests `bash` could make. */
+export function browserEgressHosts(): readonly BrowserHostDeclaration[] {
+  if (!getSettings().browser.enabled) return [];
+  return browserHostDeclarations().filter((r) => !isLoopbackBrowseHost(r.host));
+}
+
+/** The hosts the operator armed `browser_evaluate` on, or empty while the master flag is off. Empty
+ *  is also the default and the ruling: with an empty set the tool does not mount at all
+ *  (access/browser-toolkit.ts). */
+export function browserEvaluateHosts(): ReadonlySet<string> {
+  if (!getSettings().browser.enabled) return new Set();
+  return new Set(browserHostDeclarations().filter((r) => r.evaluate === true).map((r) => r.host));
+}
+
+export function _setBrowserHostsForTest(rows: readonly BrowserHostDeclaration[]): void {
+  SLOT.set(Object.freeze(rows.map((r) => Object.freeze({ ...r }))));
+}
+
+export function resetBrowserHostsForTest(): void {
+  SLOT.set(null);
+}