@open-everywhere/core 0.1.0

package/agent/access/roles.ts

@@ -0,0 +1,106 @@
+// Admin roles live in config-as-code (`Domain.admins`) as PLATFORM-QUALIFIED principal keys: the `org` pseudo-domain grants workspace-wide standing, an explicit domain grants it for that domain's channels only, and an org admin is a domain admin everywhere. FAIL-CLOSED: no verified principal, an unresolvable binding, or no configured domains all answer "not an admin".
+
+import { actingPrincipalId, bindFrom, type BindableContext, type SurfaceBinding } from "../identity/binding.js";
+import { adminStandingSubject } from "./admin-standing.js";
+import { rosterHasPrincipal, tryPrincipalKey } from "../identity/principal-key.js";
+import { domainForChannel, criteriaDomain, type Domain } from "../memory/domain.js";
+import { getConfig } from "./config.js";
+
+/** This turn's admin standing — never throws for "not an admin" (see resolveRole). */
+export interface Role {
+  /** The principal these bits were resolved FOR; absent means both bits are false. It is the binding's ACTING principal in roleForBinding and the admin SUBJECT in resolveRole — never the identity the turn's auth happens to carry. */
+  readonly principalId?: string;
+  readonly isOrgAdmin: boolean;
+  /** Listed on the resolved explicit domain's `admins`, OR isOrgAdmin (org admins are domain admins everywhere). */
+  readonly isDomainAdmin: boolean;
+  /** The explicit domain this channel resolved to (domainForChannel), if any — undefined on
+   *  an unassigned channel or a pseudo-domain (dm/public/mpim have no channel list to match). */
+  readonly domain?: string;
+  /** Set when standing could not be RESOLVED at all. Both bits are false, as they are for a plain member, but the refusal copy must not confuse "you are not an admin" with "the gate does not know whose ask this is". */
+  readonly unverified?: string;
+}
+
+const NO_ROLE: Role = { isOrgAdmin: false, isDomainAdmin: false };
+
+/** Pure, I/O-free core, so it is the matrix-tested primitive; resolveRole below is the ctx-taking wrapper every tool actually calls. */
+export function roleForBinding(binding: SurfaceBinding, domains: readonly Domain[]): Role {
+  // The ACTING principal, never the bound one. A triggered fire binds as its routine's attested creator, and giving it that creator's admin standing would hand every later fire the arming admin's whole toolset, unattended and forever.
+  const principalId = actingPrincipalId(binding);
+  if (!principalId) return NO_ROLE; // fail-closed: no verified sender, no admin bits
+
+  // Admin is EXACT-ID ONLY: a roster entry is `platform/<principal-id>` with the platform taken from the BINDING, and a `linkSet:<id>` reference is deliberately never an admin key. On a tenant-scoped platform the workspace must match too, or a foreign-workspace guest issued the same id would be admitted; an unnameable workspace fails closed.
+  const rosterAdmits = (roster: readonly string[] | undefined): boolean =>
+    rosterHasPrincipal(roster, binding.platform, binding.workspace, principalId);
+
+  const org = criteriaDomain("org", domains);
+  const isOrgAdmin = rosterAdmits(org?.admins);
+
+  // DOMAIN grain, not conversational grain: `domainSurface ?? surface`, so a Discord thread resolves through its PARENT channel and a domain admin keeps standing inside the domain's threads.
+  const channelKey = `${binding.platform}/${binding.workspace}/${binding.domainSurface ?? binding.surface}`;
+  const explicit = domainForChannel(channelKey, domains);
+  const isDomainAdmin = isOrgAdmin || rosterAdmits(explicit?.admins);
+
+  return { principalId, isOrgAdmin, isDomainAdmin, domain: explicit?.name };
+}
+
+/** Resolves this turn's admin standing from runtime context. It throws only when the app config is not registered, never to signal "not an admin" — callers that must enforce use requireOrgAdmin or requireDomainAdminOrOrg. */
+export function resolveRole(ctx: BindableContext): Role {
+  const binding = bindFrom(ctx);
+  const domains = getConfig().loadDomains();
+  // 🔴 THE SUBJECT IS THE PERSON WHO ASKED, NOT THE TURN'S AUTH (OPE-673 — access/admin-standing.ts
+  // carries the measured reason). `roleForBinding` stays PURE and unchanged: it is handed a binding
+  // whose principal IS the subject, so the matrix tests keep driving it directly.
+  const subject = adminStandingSubject(binding, ctx);
+  if (!subject.ok) return { ...NO_ROLE, unverified: subject.message };
+  return roleForBinding({ ...binding, principalId: subject.principalId }, domains);
+}
+
+/** Gates a tool's execute() to org admins only. Call it as the FIRST line of the tool. */
+export function requireOrgAdmin(ctx: BindableContext): Role {
+  const role = resolveRole(ctx);
+  if (role.unverified !== undefined) throw new Error(role.unverified);
+  if (!role.isOrgAdmin) {
+    throw new Error(
+      `this action requires an org admin.${
+        role.principalId ? ` Your id ("${role.principalId}") isn't listed.` : " No verified sender id on this turn."
+      } Add the QUALIFIED principal key ("<platform>/<id>", or "<platform>/<tenant-id>/<id>" on Slack) to the "org" pseudo-domain's admins (Domain.admins, agent/memory/config/domains.ts) to grant org-admin.`,
+    );
+  }
+  return role;
+}
+
+/** Gates a tool's execute() to this channel's domain admins; org admins pass too. Call it as the FIRST line of the tool. */
+export function requireDomainAdminOrOrg(ctx: BindableContext): Role {
+  const role = resolveRole(ctx);
+  if (role.unverified !== undefined) throw new Error(role.unverified);
+  if (!role.isDomainAdmin) {
+    const hint = role.principalId ? `Your id ("${role.principalId}") isn't listed.` : "No verified sender id on this turn.";
+    const fix = role.domain
+      ? `Add the QUALIFIED principal key ("<platform>/<id>", or "<platform>/<tenant-id>/<id>" on Slack) to domain "${role.domain}"'s admins (Domain.admins, agent/memory/config/domains.ts).`
+      : `This channel isn't in an explicit domain, so only an org admin can do this — add the QUALIFIED principal key ("<platform>/<id>", or "<platform>/<tenant-id>/<id>" on Slack) to the "org" pseudo-domain's admins.`;
+    throw new Error(`this action requires a domain admin (or an org admin). ${hint} ${fix}`);
+  }
+  return role;
+}
+
+/** Every control-plane role ("admin" | "domain:<name>") this principal holds across EVERY configured domain, not only the one their current channel resolves to. Only EXPLICIT domains yield a `domain:<name>` role; `platform` and `tenant` are both required because together they namespace the roster key, and no principal or no platform answers [] rather than "admin". */
+export function adminControlRoles(
+  principalId: string | undefined,
+  domains: readonly Domain[],
+  platform: string | undefined,
+  tenant: string | undefined,
+): string[] {
+  if (!principalId || !platform) return [];
+  // Fail-CLOSED on an unnameable workspace, matching every other roster gate: no key composes ⇒ no
+  // roster can admit ⇒ no roles. Never a partial answer built from the platform alone.
+  const key = tryPrincipalKey(platform, tenant, principalId);
+  if (key === undefined) return [];
+  // 🔴 ADMIN IS EXACT-ID ONLY. Each domain's admins list admits this caller by their exact
+  // `platform/<id>` key — never a `linkSet:<id>` reference (config load rejects those on admin
+  // rosters; admin standing stays static/diff-auditable with no runtime link-set read on this gate).
+  const admits = (roster: readonly string[] | undefined): boolean =>
+    roster?.includes(key) === true;
+  if (admits(criteriaDomain("org", domains)?.admins)) return ["admin"];
+  // `match === undefined` is the test for "an explicit domain", and it still holds where a domain's reach is a whole tenant with no channel list.
+  return domains.filter((d) => d.match === undefined && admits(d.admins)).map((d) => `domain:${d.name}`);
+}

package/agent/access/scope-key.ts

@@ -0,0 +1,50 @@
+// The ONE reader of the `scopeKey` STRING GRAMMAR — the textual form of an OE-SURFACE address, never the EVENT scope vocabulary (ScopeStep / ScopeKind / event-model), and that fence is a security property rather than tidiness. The grammar has four shapes: `<platform>/<tenant-id>`, `<platform>/<tenant-id>/<container-id>`, a BARE domain name, and `user:<principal-key>`. A hand-rolled split("/") misreads the domain shape and cannot tell a principal key from a tenant or surface key, which is why the `user:` marker exists and why the grammar is read in one place.
+
+import { parsePrincipalKey, principalKey } from "../identity/principal-key.js";
+
+/** `malformed` is a VALUE, never a throw: every consumer of this grammar is fail-open, and a parser that threw inside a card render or an audit append would turn a cosmetic problem into an outage. */
+export type ScopeKeyShape =
+  /** A bare domain NAME — no platform, no tenant. `name` may be empty for a `""` key;
+   *  every consumer fails open on that (no domain is named `""`). */
+  | { readonly kind: "domain"; readonly name: string }
+  | { readonly kind: "tenant"; readonly platform: string; readonly workspace: string }
+  | { readonly kind: "surface"; readonly platform: string; readonly workspace: string; readonly surface: string }
+  /** A PERSON — `user:<principal-key>` (OPE-274). The parts are identity/principal-key.ts's, with
+   *  the marker stripped; `tenant` is present exactly when the platform is tenant-scoped
+   *  (OPE-309). */
+  | { readonly kind: "principal"; readonly platform: string; readonly tenant?: string; readonly id: string }
+  /** Two or more segments, at least one of them empty, or more than three segments — or a
+   *  `user:`-marked key whose remainder is not a well-formed principal key.
+   *  `parts` is carried so a fail-open consumer can still salvage what it can. */
+  | { readonly kind: "malformed"; readonly raw: string; readonly parts: readonly string[] };
+
+/** Exported so the one minter and any reader testing for the shape without parsing share the literal. */
+export const USER_SCOPE_PREFIX = "user:";
+
+/** Composes the `user:<principal-key>` scope key, and is the ONE place the marker is written. The remainder must come from the principal-key module, never a local `platform/id` join, or the two spellings of one person stop comparing equal when that grammar gains a rung. */
+export function userScopeKey(platform: string, tenant: string | undefined | null, id: string): string {
+  return `${USER_SCOPE_PREFIX}${principalKey(platform, tenant, id)}`;
+}
+
+/** Never throws. The `user:` marker is tested FIRST, before any segment counting, and a marked key whose remainder is not a well-formed principal key is MALFORMED rather than salvaged as another shape; otherwise a single segment is always a domain name. */
+export function parseScopeKey(scopeKey: string): ScopeKeyShape {
+  if (scopeKey.startsWith(USER_SCOPE_PREFIX)) {
+    const rest = scopeKey.slice(USER_SCOPE_PREFIX.length);
+    const principal = parsePrincipalKey(rest);
+    if (principal) return { kind: "principal", ...principal };
+    return { kind: "malformed", raw: scopeKey, parts: rest.split("/") };
+  }
+  const parts = scopeKey.split("/");
+  if (parts.length === 1) return { kind: "domain", name: parts[0] };
+  if (parts.some((p) => p.length === 0)) return { kind: "malformed", raw: scopeKey, parts };
+  if (parts.length === 2) return { kind: "tenant", platform: parts[0], workspace: parts[1] };
+  if (parts.length === 3) return { kind: "surface", platform: parts[0], workspace: parts[1], surface: parts[2] };
+  return { kind: "malformed", raw: scopeKey, parts };
+}
+
+/** The platform this key names, or `undefined` for a bare DOMAIN name or a malformed key. That `undefined` is the point: split("/")[0] returns a domain name wearing a platform's clothes, and the caller is usually about to qualify a principal id with it. */
+export function platformOfScopeKey(scopeKey: string | undefined | null): string | undefined {
+  if (!scopeKey) return undefined;
+  const parsed = parseScopeKey(scopeKey);
+  return parsed.kind === "tenant" || parsed.kind === "surface" || parsed.kind === "principal" ? parsed.platform : undefined;
+}

package/agent/access/seat-read-budget.ts

@@ -0,0 +1,57 @@
+// Bounds a LEAN standing seat's recovery reads to a count PER TURN, so a seat asked a second question is never punished for the first one's reads. The refusal is instructive by design, because a budget cannot be enforced by deletion the way the lean roster is. FAIL-SOFT AND FAIL-OPEN: outside an eve session context nothing is ever refused, and only a positively-resolved `lean` wake is bounded — a worker, a fire and any unclassifiable wake read unbounded.
+
+import { defineState } from "eve/context";
+import { currentLeanSeatPosture } from "./lean-seat-state.js";
+
+/** How many read calls a LEAN conversational wake may make in ONE turn. Four is a judgement, not a measurement — raise it only with a measurement that says a recovery failed for want of a call. */
+export const SEAT_RECOVERY_READ_BUDGET = 4;
+
+/** The refusal for the Nth read of a turn, or null while the budget holds. PURE. `used` is the running count INCLUDING this call, so the first call passes 1, and a `used` of 0 can never exceed the budget. */
+export function seatReadBudgetRefusal(toolName: string, used: number): string | null {
+  if (used <= SEAT_RECOVERY_READ_BUDGET) return null;
+  return (
+    `\`${toolName}\` is refused: you have used your ${SEAT_RECOVERY_READ_BUDGET} recovery reads on this turn. ` +
+    `Reading is how you recover a message somebody referred to that you cannot see — it is not how you work ` +
+    `through a room. Do one of three things now. Answer from what you have already read. Or say plainly what ` +
+    `you looked at and that you could not find it, which is a good answer. Or delegate a worker to dig ` +
+    `further on its work surfaces and report back. Do not guess the content you could not find.`
+  );
+}
+
+/** Thrown by a read verb when the per-turn budget is spent. A distinct class so a caller can tell a
+ *  budget stop from a scope refusal or a surface error. */
+export class SeatReadBudgetError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SeatReadBudgetError";
+  }
+}
+
+const slot = defineState<number>("open-everywhere.seat-read-budget", () => 0);
+
+/** Count one read on this turn and return the running total. Returns 0 outside an eve session context, which {@link seatReadBudgetRefusal} treats as "never refuse". */
+export function noteSeatRead(): number {
+  try {
+    const next = slot.get() + 1;
+    slot.update(() => next);
+    return next;
+  } catch {
+    return 0; // no session context (unit test, render path, sessionless eval) — no counting, no refusal
+  }
+}
+
+/** Clear the per-turn counter — called by hooks/loop-breaker.ts on `turn.started`, the repo's one
+ *  per-turn reset hook. Fail-soft outside a session context. */
+export function resetSeatReadBudget(): void {
+  try {
+    slot.update(() => 0);
+  } catch {
+  }
+}
+
+/** THE GUARD a read verb calls FIRST, before it resolves anything; throws {@link SeatReadBudgetError} once the lean seat's budget is spent. ORDER MATTERS: it runs before the scope gates, so a spent seat gets the instructive message rather than a scope refusal, and a refused call still costs a read. */
+export function assertSeatReadBudget(toolName: string): void {
+  if (currentLeanSeatPosture() !== "lean") return; // workers, fires and unclassifiable wakes read unbounded
+  const refusal = seatReadBudgetRefusal(toolName, noteSeatRead());
+  if (refusal !== null) throw new SeatReadBudgetError(refusal);
+}

package/agent/access/self-host-egress.ts

@@ -0,0 +1,103 @@
+// Off Vercel there is no server-side firewall to call, so the compiled policy is PUSHED to a local egress proxy instead of `sandbox.setNetworkPolicy`. FAIL-CLOSED: pushEgressPolicy THROWS on any push failure and its callers abort the session, unless the deployment declares `egress: { allowUnenforced: true }`.
+
+import type { SandboxNetworkPolicy } from "eve/sandbox";
+
+import { getSettings } from "../settings/settings.js";
+
+import { onVercel } from "./platform.js";
+export { onVercel };
+
+export function egressProxyUrl(): string | undefined {
+  const raw = process.env.OE_EGRESS_PROXY_URL?.trim();
+  return raw ? raw : undefined;
+}
+
+/** True only OFF Vercel and with a proxy URL configured; every other case uses the legacy setNetworkPolicy path unchanged. */
+export function useSelfHostEgress(): boolean {
+  return !onVercel() && egressProxyUrl() !== undefined;
+}
+
+export interface EgressBootLog {
+  /** A loud, unmissable warning — present ONLY when the deployment will run without an enforced firewall. */
+  readonly warn?: string;
+  readonly info: string;
+}
+
+/** Resolves the self-host egress posture for a one-shot BOOT log, so an operator meets the choice at boot rather than at the first silently aborting session. The no-proxy warning says "any session that resolves a HOST ALLOW-LIST will abort", NOT "every session": docker accepts the coarse "deny-all" a no-reach compile produces, so that session boots with no network at all. */
+export function selfHostEgressBootLog(env: NodeJS.ProcessEnv = process.env): EgressBootLog {
+  const proxy = (env.OE_EGRESS_PROXY_URL ?? "").trim();
+  const allowUnenforced = getSettings().egress.allowUnenforced;
+  if (proxy) {
+    return {
+      info: "[open-everywhere:egress] self-host egress ENFORCED via proxy sidecar (OE_EGRESS_PROXY_URL set) — the compiled policy is pushed to the proxy natively; `egress.allowUnenforced` is not needed.",
+    };
+  }
+  if (allowUnenforced) {
+    return {
+      warn:
+        "[open-everywhere:egress] ⚠ UNENFORCED egress — no OE_EGRESS_PROXY_URL and `egress.allowUnenforced: true` in agent/settings.ts: the agent runs WITHOUT a network firewall " +
+        "(default-deny egress + at-boundary credential injection are OFF). Dev/testing ONLY — wire the egress-proxy sidecar (docker-compose.yml) for real deployments.",
+      info: "[open-everywhere:egress] self-host egress posture = unenforced (egress.allowUnenforced)",
+    };
+  }
+  return {
+    warn:
+      "[open-everywhere:egress] ⚠ egress NOT enforceable — no OE_EGRESS_PROXY_URL configured and `egress.allowUnenforced` is off: any session that resolves a HOST ALLOW-LIST will ABORT at session.started (fail-closed). " +
+      "Neither wired backend applies a fine-grained policy: justbash rejects every setNetworkPolicy, and docker accepts only the coarse \"allow-all\"/\"deny-all\" strings. A session that reaches nothing compiles to \"deny-all\", which docker DOES apply — that session boots, with no network at all. " +
+      "Wire the egress-proxy sidecar (docker-compose.yml / docs/deploy/platforms/self-host-egress.md), or declare `egress: { allowUnenforced: true }` in agent/settings.ts to run unenforced in dev.",
+    info: "[open-everywhere:egress] self-host egress posture = none (a session needing any host fails closed until a proxy is wired or egress.allowUnenforced is declared)",
+  };
+}
+
+export interface PushPolicyBody {
+  readonly policy: SandboxNetworkPolicy;
+  /** Explicit source-IP key. Omit to let the control service key by the POST's remote addr. */
+  readonly sourceIp?: string;
+  /** Optional session id — audit-only on the control side; not load-bearing for matching. */
+  readonly sessionId?: string;
+}
+
+export type FetchLike = (
+  url: string,
+  init: { method: string; headers: Record<string, string>; body: string },
+) => Promise<{ ok: boolean; status: number; text: () => Promise<string> }>;
+
+/** POSTs the policy to `${proxyUrl}/policy` and THROWS on a network error or a non-2xx response. Fail-closed: a caller that cannot confirm the proxy accepted the policy must abort rather than run unenforced. */
+export async function postPolicy(
+  fetchImpl: FetchLike,
+  proxyUrl: string,
+  token: string | undefined,
+  body: PushPolicyBody,
+): Promise<void> {
+  const url = `${proxyUrl.replace(/\/+$/, "")}/policy`;
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (token) headers.authorization = `Bearer ${token}`;
+  let res: Awaited<ReturnType<FetchLike>>;
+  try {
+    res = await fetchImpl(url, { method: "POST", headers, body: JSON.stringify(body) });
+  } catch (err) {
+    throw new Error(`egress-proxy push failed (network): ${String(err)}`);
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`egress-proxy push rejected (HTTP ${res.status})${detail ? `: ${detail.slice(0, 300)}` : ""}`);
+  }
+}
+
+/** Reads OE_EGRESS_PROXY_URL, throwing when it is unset, and OE_EGRESS_PROXY_TOKEN. An unset token still fails closed: no header, the proxy rejects, postPolicy throws and the session aborts. */
+export async function pushEgressPolicy(
+  policy: SandboxNetworkPolicy,
+  opts?: { sourceIp?: string; sessionId?: string },
+): Promise<void> {
+  const proxyUrl = egressProxyUrl();
+  if (!proxyUrl) {
+    throw new Error("pushEgressPolicy called with no OE_EGRESS_PROXY_URL set (self-host egress not configured)");
+  }
+  const token = process.env.OE_EGRESS_PROXY_TOKEN?.trim() || undefined;
+  await postPolicy(
+    globalThis.fetch as unknown as FetchLike,
+    proxyUrl,
+    token,
+    { policy, sourceIp: opts?.sourceIp ?? (process.env.OE_EGRESS_SOURCE_IP?.trim() || undefined), sessionId: opts?.sessionId },
+  );
+}

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

@@ -0,0 +1,96 @@
+// A settlement turn carries no rendered wake envelope, but the host has already installed the
+// settled task's own wake. This turn-scoped slot carries the matching frozen dispatch authority to
+// a second delegation. It accepts one settled task only. Two different tasks in one turn are
+// ambiguous, even when they happen to resolve to the same surface.
+
+import { defineState } from "eve/context";
+import { isRequesterVerdict, type RequesterVerdict } from "./requester-identity.js";
+
+export interface SettlementDispatchAuthority {
+  readonly wakeId: string;
+  readonly requester: RequesterVerdict;
+  readonly nonMemberWake: boolean;
+}
+
+interface SettlementDispatchState {
+  readonly turn?: string;
+  readonly taskId?: string;
+  readonly authority?: SettlementDispatchAuthority;
+  readonly blocked?: boolean;
+}
+
+const slot = defineState<SettlementDispatchState>("open-everywhere.settlement-dispatch-authority", () => ({}));
+
+function validAuthority(value: unknown): value is SettlementDispatchAuthority {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const authority = value as Record<string, unknown>;
+  return (
+    typeof authority.wakeId === "string" &&
+    authority.wakeId.length > 0 &&
+    isRequesterVerdict(authority.requester) &&
+    typeof authority.nonMemberWake === "boolean"
+  );
+}
+
+function readState(value: unknown): SettlementDispatchState {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return {};
+  const state = value as Record<string, unknown>;
+  if (typeof state.turn !== "string" || state.turn.length === 0) return {};
+  const taskId = typeof state.taskId === "string" && state.taskId.length > 0 ? state.taskId : undefined;
+  const authority = validAuthority(state.authority) ? state.authority : undefined;
+  return {
+    turn: state.turn,
+    ...(taskId !== undefined ? { taskId } : {}),
+    ...(authority !== undefined ? { authority } : {}),
+    ...(state.blocked === true ? { blocked: true } : {}),
+  };
+}
+
+/**
+ * Record one host-installed settled task. Missing authority blocks this turn instead of allowing a
+ * later task to supply it. A duplicate observation of the same task and authority is idempotent.
+ */
+export function noteSettlementDispatchAuthority(
+  turnId: string | undefined,
+  taskId: string,
+  authority: SettlementDispatchAuthority | undefined,
+): void {
+  if (turnId === undefined || turnId.length === 0 || taskId.length === 0) return;
+  try {
+    slot.update((current) => {
+      const state = readState(current);
+      if (state.turn !== turnId) {
+        return authority === undefined
+          ? { turn: turnId, taskId, blocked: true }
+          : { turn: turnId, taskId, authority };
+      }
+      if (state.blocked === true) return state;
+      if (state.taskId !== taskId || state.authority === undefined || authority === undefined) {
+        return { turn: turnId, blocked: true };
+      }
+      return JSON.stringify(state.authority) === JSON.stringify(authority)
+        ? state
+        : { turn: turnId, blocked: true };
+    });
+  } catch {
+    /* no eve context or unreadable state means no authority; actions.requested then refuses */
+  }
+}
+
+/** Exact frozen authority for a single host-installed settlement on this turn. */
+export type SettlementDispatchResolution =
+  | { readonly kind: "none" }
+  | { readonly kind: "blocked" }
+  | { readonly kind: "single"; readonly authority: SettlementDispatchAuthority };
+
+export function settlementDispatchAuthorityThisTurn(turnId: string | undefined): SettlementDispatchResolution {
+  if (turnId === undefined || turnId.length === 0) return { kind: "none" };
+  try {
+    const state = readState(slot.get());
+    if (state.turn !== turnId) return { kind: "none" };
+    if (state.blocked === true || state.authority === undefined) return { kind: "blocked" };
+    return { kind: "single", authority: state.authority };
+  } catch {
+    return { kind: "blocked" };
+  }
+}

package/agent/access/skill-taint-envelope.ts

@@ -0,0 +1,94 @@
+// The ONE source of the sandbox-to-host taint delimiter contract, emitted by `oe wrap-untrusted` and parsed by the host. It can only ever ADD taint: there is no trusted variant, a forged OPEN taints more, a forged CLOSE fails on a nonce minted after the content was already in hand, and omitting the envelope leaves today's untainted behaviour.
+
+import { randomBytes } from "node:crypto";
+
+/** The literal marker constants — the SINGLE source of truth for both emitter and parser. The OPEN
+ *  marker is `${OPEN_PREFIX}<nonce> source=<label>${MARKER_END}`; the CLOSE is
+ *  `${CLOSE_PREFIX}<nonce>${MARKER_END}`. The trailing space on each prefix is load-bearing. */
+export const SKILL_ENVELOPE_OPEN_PREFIX = "<<<OE-UNTRUSTED ";
+export const SKILL_ENVELOPE_CLOSE_PREFIX = "<<<END-OE-UNTRUSTED ";
+export const SKILL_ENVELOPE_MARKER_END = ">>>";
+
+/** A fully-formed open marker matched against the slice up to its own first `${MARKER_END}`. The
+ *  nonce is lowercase hex, ≥16 chars (≥64 bits — the util mints 128). The label is any run of
+ *  non-`>` chars, so the FIRST `>>>` after `source=` terminates the marker unambiguously. */
+const OPEN_MARKER_RE = /^<<<OE-UNTRUSTED ([0-9a-f]{16,}) source=([^>]*)>>>$/;
+
+/** Mint a fresh envelope nonce: 128 bits of randomness as 32 lowercase hex chars. Minted by the
+ *  util AT WRAP TIME — i.e. AFTER the content was fetched and is immutable — so pre-authored
+ *  content can never contain the close marker (§3 of the header). */
+export function mintSkillEnvelopeNonce(): string {
+  return randomBytes(16).toString("hex");
+}
+
+/** Reduces a caller-supplied provenance label to a bounded, delimiter-safe NAME: it can never contain `>` or a control byte, so it can never break the OPEN marker. BOTH ends call it, and the host re-sanitizes the extracted label before it reaches an audit row. */
+export function sanitizeSkillEnvelopeSource(label: string | undefined): string {
+  const cleaned = (label ?? "").trim().replace(/[^A-Za-z0-9._:-]/g, "-").slice(0, 64);
+  return cleaned.length > 0 ? cleaned : "external";
+}
+
+/** Emits one envelope, and is the single place the wire format is composed. It mints the nonce over content already in hand — the immutability the forged-close defence depends on — unless a caller passes one for a deterministic golden test. */
+export function formatSkillEnvelope(content: string, opts: { source?: string; nonce?: string } = {}): string {
+  const nonce = opts.nonce ?? mintSkillEnvelopeNonce();
+  const label = sanitizeSkillEnvelopeSource(opts.source);
+  return (
+    `${SKILL_ENVELOPE_OPEN_PREFIX}${nonce} source=${label}${SKILL_ENVELOPE_MARKER_END}\n` +
+    `${content}\n` +
+    `${SKILL_ENVELOPE_CLOSE_PREFIX}${nonce}${SKILL_ENVELOPE_MARKER_END}`
+  );
+}
+
+/** One parsed segment of stdout: either VERBATIM text (left untouched, the common case) or a
+ *  declared UNTRUSTED span the host must fence + taint. `source` is the raw captured label; the
+ *  host sanitizes it via {@link sanitizeSkillEnvelopeSource} before use. */
+export type SkillEnvelopeSegment =
+  | { readonly untrusted: false; readonly text: string }
+  | { readonly untrusted: true; readonly source: string; readonly content: string };
+
+/** Parses stdout left-to-right, FLAT and fail-closed: a malformed marker stays verbatim, a CLOSE with any other nonce is inert, and an UNCLOSED open runs to EOF. Stdout with no valid envelope yields one verbatim segment, which is the byte-identical no-envelope path. */
+export function extractSkillEnvelopes(stdout: string): SkillEnvelopeSegment[] {
+  const segments: SkillEnvelopeSegment[] = [];
+  const pushText = (text: string) => {
+    if (text.length === 0) return;
+    const last = segments[segments.length - 1];
+    if (last && last.untrusted === false) {
+      segments[segments.length - 1] = { untrusted: false, text: last.text + text };
+    } else {
+      segments.push({ untrusted: false, text });
+    }
+  };
+
+  let pos = 0;
+  while (pos < stdout.length) {
+    const openIdx = stdout.indexOf(SKILL_ENVELOPE_OPEN_PREFIX, pos);
+    if (openIdx === -1) {
+      pushText(stdout.slice(pos));
+      break;
+    }
+    const termIdx = stdout.indexOf(SKILL_ENVELOPE_MARKER_END, openIdx);
+    const marker = termIdx === -1 ? null : OPEN_MARKER_RE.exec(stdout.slice(openIdx, termIdx + SKILL_ENVELOPE_MARKER_END.length));
+    if (marker === null) {
+      // Not a valid open marker — emit through the end of the sentinel prefix verbatim and re-scan
+      // past it (a valid open may still start further along).
+      const skipTo = openIdx + SKILL_ENVELOPE_OPEN_PREFIX.length;
+      pushText(stdout.slice(pos, skipTo));
+      pos = skipTo;
+      continue;
+    }
+    if (openIdx > pos) pushText(stdout.slice(pos, openIdx));
+    const nonce = marker[1];
+    const source = marker[2];
+    const contentStart = termIdx + SKILL_ENVELOPE_MARKER_END.length;
+    const closeMarker = `${SKILL_ENVELOPE_CLOSE_PREFIX}${nonce}${SKILL_ENVELOPE_MARKER_END}`;
+    const closeIdx = stdout.indexOf(closeMarker, contentStart);
+    if (closeIdx === -1) {
+      // Unclosed ⇒ taint to EOF.
+      segments.push({ untrusted: true, source, content: stdout.slice(contentStart) });
+      break;
+    }
+    segments.push({ untrusted: true, source, content: stdout.slice(contentStart, closeIdx) });
+    pos = closeIdx + closeMarker.length;
+  }
+
+  return segments;
+}