@open-everywhere/core 0.1.0

package/agent/routines/watch.ts

@@ -0,0 +1,328 @@
+// The WATCH protocol — what makes a `watch` routine post-on-diff rather than a
+// plain interval. The state a watch observes is defined in natural language
+// ("watch the status page"), so only the fired SESSION can observe it — but the
+// diff verdict must not be left to the model's memory. Split accordingly:
+//
+//   - the dispatcher wraps the routine's prompt with the protocol instruction
+//     (renderWatchMessage): observe, call `record_watch_state`, end with the
+//     silence sentinel when nothing changed;
+//   - the `record_watch_state` tool (tools/record_watch_state.ts) does the
+//     HOST-SIDE half (applyWatchObservation): hash the observation, compare to
+//     the routine's stored `lastStateHash`, persist the new hash, and record a
+//     `skipped` outcome when unchanged. The hash comparison is authoritative;
+//     staying silent is instruction-followed (same contract as judged
+//     thread-follow replies — see channels/slack-events.ts).
+//
+// The module also holds the invariant host blocks EVERY fire carries, whatever its trigger kind —
+// the silent block, the health block and the reach block. They live here because the watch protocol
+// already did, and job.ts and events.ts import them from here rather than growing copies.
+//
+// 🔴 THERE ARE FOUR RENDER PATHS, NOT ONE, AND EACH KEEPS ITS OWN COPY OF THE BLOCK ORDER:
+// `fireMessage` below (which renderScheduledMessage uses), renderWatchMessage below, job.ts
+// renderJobMessage, and events.ts eventPrompt. A new block must be added to ALL FOUR — adding it to
+// the shared joiner reaches one of them. scripts/routine-fire-reach-test.ts §2 is what reds when a
+// path is missed; it is the only thing that does.
+//
+// Framework-free (no eve imports), matching routine.ts/lifecycle.ts, so the
+// dispatcher, the tool, and the tests share it without pulling the runtime.
+
+import { isSilentRoutine, type Routine } from "./routine.js";
+import { hashState, MAX_CONSECUTIVE_FAILURES, shouldPostOnDiff } from "./lifecycle.js";
+import { renderPolicyBlock } from "./policy.js";
+import { renderCollectedBlock, type CollectedInput } from "./collector.js";
+import { renderFollowUpsBlock } from "./follow-ups.js";
+
+// The turn-final silence sentinel. MUST equal NO_REPLY_SENTINEL in
+// channels/slack-events.ts (the channel's message.completed override is what
+// swallows it) — pinned by an equality assertion in scripts/dispatch-test.ts;
+// duplicated here so this module stays framework-free.
+export const WATCH_SILENCE_SENTINEL = "NO_REPLY";
+
+/** The tool a watch turn must call — named here so prompt and tool can't drift. */
+export const WATCH_STATE_TOOL = "record_watch_state";
+
+/** The tool ANY fired turn calls to declare that the work didn't work (OPE-177) — named here, next
+ *  to the other protocol tool names, so prompt and tool can't drift. */
+export const RUN_FAILED_TOOL = "report_run_failed";
+
+/** The framework tool that FINDS a connector operation (OPE-2033) — named here, beside the other
+ *  protocol tool names, for the same anti-drift reason. It is eve's own slot, not one this package
+ *  defines, and eve declares it REQUIRED, so this app may not sentinel it away
+ *  (scripts/eve-framework-tools-test.ts). The pins that keep the name honest are the window-gate
+ *  manifest's `WINDOW_UNGATED_TOOLS` membership and its ABSENCE from `JOB_WAKE_TOOLS`, both
+ *  asserted in scripts/routine-fire-reach-test.ts. */
+export const CONNECTION_SEARCH_TOOL = "connection_search";
+
+/**
+ * The temporal header EVERY fired turn gets (interval/cron and watch alike). A fired
+ * session starts stateless, so "since my last run" work (new commits, what changed
+ * today) needs the previous run injected here: the dispatcher advances `lastRunAt`
+ * to NOW before dispatching (the double-fire guard), so by the time the turn could
+ * look its own routine up, the record already shows the current run. `r` must be the
+ * PRE-advance object (dispatch.ts renders from its in-memory copy). Times are ISO UTC.
+ */
+export function firePreamble(r: Pick<Routine, "id" | "createdAt" | "lastRunAt">): string {
+  const last = r.lastRunAt ? `previous run: ${r.lastRunAt}` : "previous run: none — this is the FIRST run";
+  return `[routine ${r.id}] Scheduled fire (routine created: ${r.createdAt}; ${last}).`;
+}
+
+/**
+ * The trusted SILENT block (OPE-149) — the instruction half of `postPolicy: "never"`, rendered
+ * immediately after {@link firePreamble} for a routine whose stored `report` is `{kind:"silent"}`.
+ * OURS, trusted, same posture as the `[watch]` protocol block right below it.
+ *
+ * SILENCE IS THE DEFAULT; FAILURE IS LOUD — that one clause is the whole answer to "how does a
+ * silent routine's failure ever surface". The routine's product is the WORK (a ticket updated,
+ * memory written), so the ordinary outcome is no message at all; the single carve-out is a problem
+ * the turn cannot resolve, which the model is told plainly WILL reach the humans. Naming both arms
+ * matters: without the exception a model that hits a wall either invents a reason to post anyway or
+ * swallows the failure, and the mechanical gate (routines/report.ts) would drop it either way.
+ *
+ * The escape hatch is a POSITIVE act — the `reply` tool posts mid-turn and is untouched by the
+ * gate — so the instruction points at it rather than at the terminal completion, which is dropped
+ * whatever it contains. Empty string for a non-silent routine, so a routine that posts normally
+ * contributes no silent block at all.
+ */
+export function renderSilentBlock(r: Pick<Routine, "report">): string {
+  if (!isSilentRoutine(r)) return "";
+  return (
+    `[silent] This routine reports NOTHING here — its product is the work itself, not a message, ` +
+    `so a post would be noise. Do the work, then end your turn with exactly ${WATCH_SILENCE_SENTINEL} ` +
+    `and nothing else. The ONE exception: if you hit a problem you cannot resolve, say so with the ` +
+    `\`reply\` tool — that message WILL post. Anything you write as your FINAL answer instead is ` +
+    `dropped before it reaches anyone, so never leave a problem in it.`
+  );
+}
+
+/**
+ * The HEALTH block (OPE-177) — the instruction half of the declared-failure seam, rendered on EVERY
+ * fire (scheduled, watch, job, event) because semantic failure is not a property of a trigger kind.
+ * OURS, trusted, same posture as the `[watch]` / `[job]` / `[silent]` blocks.
+ *
+ * WHY THE MODEL HAS TO BE TOLD, not merely handed the tool. The three-strike self-disable folds the
+ * SESSION outcome, and a run that hits a 500 and posts "I couldn't reach the API" completes CLEANLY
+ * — so the routine's health record says it succeeded and it fires forever on a broken thing. Only
+ * the turn knows the work didn't work. Mounting `report_run_failed` on the toolset makes the
+ * declaration POSSIBLE; naming it here, in the fire's own message, is what makes it HAPPEN — the
+ * same "necessary but not sufficient" split the watch protocol already respects by spelling out
+ * `record_watch_state` rather than trusting the toolset to advertise itself.
+ *
+ * THE SECOND CLAUSE IS AS LOAD-BEARING AS THE FIRST. A routine whose JOB is to report problems must
+ * not disable itself for doing that job correctly — that is precisely the failure mode
+ * a design note rejects a runtime "does this output look like a
+ * failure?" classifier over. The distinction the block draws is the only one that is checkable from
+ * inside the turn: did the WORK happen, not was the NEWS good.
+ */
+export function renderFailureBlock(): string {
+  return (
+    `[health] If the work this fire was asked to do DID NOT HAPPEN — the thing you needed was down, ` +
+    `a credential was rejected, the page never loaded — call the \`${RUN_FAILED_TOOL}\` tool with one ` +
+    `line saying why, before you finish. Saying it only in your answer is not enough: nothing reads ` +
+    `your prose, so a run that reports a problem and finishes cleanly is recorded as a SUCCESS and ` +
+    `this routine keeps firing at the same broken thing forever. ${MAX_CONSECUTIVE_FAILURES} declared ` +
+    `failures in a row and it stops itself. Do NOT call it when the work DID happen and the news was ` +
+    `merely bad — finding a problem is a routine doing its job, not failing at it. ` +
+    // OPE-2033 — the WORDING half. The line above already demanded a reason; it did not demand that
+    // the reason be EARNED. A fire that guesses at its own access writes a reason that reads exactly
+    // like a measured one, and the audit row then carries a false cause with a real timestamp.
+    `Say what you TRIED and what the system ANSWERED: the operation you called, the search you ran, ` +
+    `and the words that came back. A bare "not authorized" is a guess unless a call returned it.`
+  );
+}
+
+/**
+ * Which reach a fire actually has. `full` is every fire whose toolset is assembled normally;
+ * `job-restricted` is a stamped durable-job fire, which `access/job-posture.ts`
+ * `resolveJobWakePosture` narrows to the default-deny `JOB_WAKE_TOOLS` kit before the model
+ * ever sees the toolset. The two hold DIFFERENT connector reach, so they get different prose — see
+ * {@link renderReachBlock}. No default: a new render path must decide which one it is.
+ */
+export type FireReach = "full" | "job-restricted";
+
+/**
+ * The REACH block (OPE-2033) — the instruction half of "a capability you cannot see is not a
+ * capability you do not have". Rendered on EVERY fire, beside the health block and for the same
+ * reason: a fire that mis-reads its own reach is not a property of a trigger kind. OURS, trusted,
+ * same posture as the `[watch]` / `[job]` / `[silent]` / `[health]` blocks.
+ *
+ * WHAT THE `full` ARM ANSWERS. A connector operation is not a static tool. eve always mounts
+ * `connection_search` (it is a REQUIRED framework slot this app may not sentinel — see
+ * scripts/eve-framework-tools-test.ts), and it mounts the `<connection>__<op>` tools only once that
+ * search FINDS them. So the operation an instruction names is absent from the session's opening tool
+ * list by construction, and present one call later. A model that reads that opening list as the
+ * whole of its reach concludes the connector is unavailable and reports a refusal no gate issued.
+ *
+ * 🔴 WHY THE `job-restricted` ARM SAYS THE OPPOSITE, AND MUST. A stamped durable-job fire is
+ * narrowed to `JOB_WAKE_TOOLS`, which withholds `connection_search` by name and admits a connector
+ * op only at tier `read` (`allowedOnRestrictedJobWake`). On that wake ABSENCE IS THE CONTROL — the
+ * model never sees the tool, so no injected instruction has a refusal to argue with. Telling such a
+ * fire to go searching would instruct it to disbelieve the only enforcement its wake has, and the
+ * health block beside it would then push it to invent the attempt it cannot make. So the job arm
+ * states the narrowing plainly and points at `report_run_failed` instead.
+ *
+ * WHY A FIRE NEEDS EITHER ARM AND A LIVE SEAT NEEDS IT LESS. Nobody is watching a fire. A person who
+ * is told "I can't reach Notion" asks "did you look?"; a routine's report is read hours later, if at
+ * all, and a fire that auto-disables on the strike counter takes the false cause with it.
+ *
+ * 🔴 IT WIDENS NOTHING. The block changes what the turn ATTEMPTS, never what the turn may do. Every
+ * gate an attempt meets — the connector hard-gate, the unattended connector fence, the DM-only
+ * context wall, the egress firewall — decides exactly as it did before. What the fire then reports
+ * is whatever came back, which can be a refusal, an error, or an approval nobody is present to give.
+ */
+export function renderReachBlock(reach: FireReach): string {
+  if (reach === "job-restricted") {
+    return (
+      `[reach] This fire runs on a RESTRICTED job wake: it holds no \`${CONNECTION_SEARCH_TOOL}\`, and ` +
+      `no connector operation beyond a read. That is the design, not a fault — this job runs for weeks ` +
+      `with nobody attending it, so the consequential half of the kit is withheld until a human takes ` +
+      `the session over. Do NOT go looking for a connector here, and do not describe the narrowing as a ` +
+      `refusal: nothing refused you. If the work this fire was sent to do needs a tool you do not hold, ` +
+      `call \`${RUN_FAILED_TOOL}\` and name the tool you needed and the fact that this wake does not ` +
+      `carry it. That IS what the [health] block above asks of you here: a tool your kit does not hold ` +
+      `is a fact about the kit, not a guess, and no call has to sit behind it. Never invent one.`
+    );
+  }
+  return (
+    `[reach] A tool you cannot see is not a tool you do not have. A CONNECTOR operation — creating a ` +
+    `Notion page, reading a record in a connected workspace — is FOUND by search: it is not always ` +
+    `listed in this session, and the list you start with is not the whole of your reach. Call ` +
+    `\`${CONNECTION_SEARCH_TOOL}\` with a keyword for the thing you need, then call the operation it ` +
+    `names. Do that BEFORE you report that a connector is unavailable. Attempt the operation this ` +
+    `fire names, and report what came back. A refusal is what a call returned — never something you ` +
+    `concluded without making one.`
+  );
+}
+
+/**
+ * Join the fire preamble, the (possibly empty) silent block, the health block, the reach block, the
+ * (possibly empty) standing-rules block, the (possibly empty) follow-ups ledger, and the rest —
+ * dropping the blank paragraph an absent block would otherwise leave, so a routine with neither
+ * rules nor follow-ups renders without a hole where they would sit.
+ *
+ * BLOCK ORDER, and why `[rules]` sits LAST of the invariant host blocks: it is the one whose content
+ * a human wrote about THIS routine's work, so it belongs adjacent to the work — directly above the
+ * protocol instruction and the prompt it constrains. The preamble/silent/health/reach blocks above
+ * it are invariant host prose that says nothing about the task. `[follow-ups]` sits directly below the
+ * rules, for the same reason and one rung weaker: it is about this routine's work too, but it was
+ * written by a previous RUN rather than armed by a human, so it never sits above the doctrine that
+ * constrains it (routines/follow-ups.ts fences the entries a tainted run wrote).
+ *
+ * 🔴 `collected` IS LAST, BELOW THE PROMPT, AND THAT ORDERING IS THE SECURITY PROPERTY. It is the
+ * only region of the message that can carry an outside party's bytes (routines/collector.ts wraps
+ * them in an untrusted fence), so every trusted instruction — ours and the operator's prompt alike —
+ * sits strictly above it. Exactly the ordering routines/events.ts eventPrompt keeps for the event
+ * leg's payload.
+ */
+function fireMessage(
+  head: string,
+  silent: string,
+  rules: string,
+  followUps: string,
+  body: readonly string[],
+  collected: string,
+): string {
+  return [
+    head,
+    ...(silent.length > 0 ? ["", silent] : []),
+    "",
+    renderFailureBlock(),
+    "",
+    renderReachBlock("full"),
+    ...(rules.length > 0 ? ["", rules] : []),
+    ...(followUps.length > 0 ? ["", followUps] : []),
+    "",
+    ...body,
+    ...(collected.length > 0 ? ["", collected] : []),
+  ].join("\n");
+}
+
+/** The message a fired interval/cron turn receives: the temporal header, the silent block when the
+ *  routine posts nothing (OPE-149), the health block (OPE-177), the reach block (OPE-2033), the
+ *  routine's standing rules when it has any (OPE-141), the follow-ups its earlier runs left
+ *  (OPE-151), the prompt, and last of all the pre-run collection (OPE-151), fenced.
+ *
+ *  `collected` defaults to empty, so a routine that declares no collectors renders with no
+ *  collection block at all. */
+export function renderScheduledMessage(
+  r: Pick<Routine, "id" | "prompt" | "createdAt" | "lastRunAt" | "report" | "policy" | "followUps">,
+  collected: readonly CollectedInput[] = [],
+): string {
+  return fireMessage(
+    firePreamble(r),
+    renderSilentBlock(r),
+    renderPolicyBlock(r),
+    renderFollowUpsBlock(r),
+    [r.prompt],
+    renderCollectedBlock(collected),
+  );
+}
+
+/**
+ * The message a fired `watch` turn receives: the temporal header, the protocol
+ * instruction (OURS, trusted — same posture as the wake instruction), then the
+ * routine's prompt, then the pre-run collection.
+ */
+export function renderWatchMessage(
+  r: Pick<Routine, "id" | "prompt" | "lastStateHash" | "createdAt" | "lastRunAt" | "policy" | "followUps">,
+  collected: readonly CollectedInput[] = [],
+): string {
+  const baseline =
+    r.lastStateHash === undefined
+      ? "No baseline is recorded yet — this is the first check, so report what you observe as the baseline."
+      : "A baseline from the last check is recorded — the tool will tell you whether the state changed.";
+  // This path keeps its OWN copy of the block order (see the module header) — it does not go
+  // through `fireMessage`. A watch is never silent (assertReportConsistent refuses the pair), so it
+  // has no silent slot at all, and the standing-rules block lands in the same place it does on
+  // every other fire shape. Watch tuning ("ignore the fetched_at field when deciding whether the
+  // state changed") is one of the things policy is FOR, so this leg is not incidental.
+  const rules = renderPolicyBlock(r);
+  const followUps = renderFollowUpsBlock(r);
+  const collectedBlock = renderCollectedBlock(collected);
+  return [
+    firePreamble(r),
+    "",
+    renderFailureBlock(),
+    "",
+    renderReachBlock("full"),
+    ...(rules.length > 0 ? ["", rules] : []),
+    ...(followUps.length > 0 ? ["", followUps] : []),
+    "",
+    `[watch] This is a scheduled check of a WATCH routine — post ONLY if the watched state changed. ` +
+      `Protocol: do the check below, then call the \`${WATCH_STATE_TOOL}\` tool with a canonical text ` +
+      `representation of the watched state (stable ordering; leave out values that differ on every ` +
+      `look, like timestamps or "fetched at" counters). ${baseline} If the tool returns ` +
+      `\`changed: false\`, the state is unchanged: end your turn with exactly ${WATCH_SILENCE_SENTINEL} ` +
+      `and nothing else — nothing will be posted. If it returns \`changed: true\`, report what changed.`,
+    "",
+    r.prompt,
+    ...(collectedBlock.length > 0 ? ["", collectedBlock] : []),
+  ].join("\n");
+}
+
+/** Host-side verdict for one watch observation (see WatchObservation.patch). */
+export interface WatchObservation {
+  /** Did the state change since the last recorded observation? (No prior hash counts
+   *  as changed, so the baseline is reported once — see shouldPostOnDiff.) */
+  readonly changed: boolean;
+  /** True when no baseline existed — the turn should report what it sees, once. */
+  readonly firstObservation: boolean;
+  /** What to persist on the routine: always the new hash; an unchanged observation
+   *  also records `skipped` NOW, so the outcome hook can settle the session's
+   *  eventual "ok" back to `skipped` (lifecycle.ts settleOutcome). */
+  readonly patch: Partial<Routine>;
+}
+
+/**
+ * Fold one observed state into a watch routine's diff state. Pure: hashing +
+ * comparison here, persistence in the tool. The dispatcher clears `lastOutcome`
+ * on every fire, so a `skipped` present at session end was written by THIS run.
+ */
+export function applyWatchObservation(r: Pick<Routine, "lastStateHash">, state: string): WatchObservation {
+  const newHash = hashState(state);
+  const changed = shouldPostOnDiff(r.lastStateHash, newHash);
+  return {
+    changed,
+    firstObservation: r.lastStateHash === undefined,
+    patch: changed ? { lastStateHash: newHash } : { lastStateHash: newHash, lastOutcome: "skipped" },
+  };
+}

package/agent/sandbox/backend-select.ts

@@ -0,0 +1,58 @@
+// Off-Vercel sandbox backend selection — the PURE, side-effect-free decision logic behind
+// `agent/sandbox/sandbox.ts`'s selfHostBackend(). Kept in its own zero-import module so it is
+// unit-testable (scripts/sandbox-backend-test.ts) without pulling the whole app graph that
+// importing sandbox.ts would (defineSandbox default export + register-config + eve/sandbox
+// backends).
+//
+// TWO CONSUMERS, ONE ANSWER. The app re-exports this to build the backend; the turn-end stop
+// hook reads it through the adapter-api barrel to pick which backend OWNS the stop
+// (packages/adapters/agent/sandbox/backend-stop.ts). They must never disagree, so the parse
+// lives here rather than in either caller.
+//
+// DEFAULT = docker (OPE-106): the running agent must be CONTAINED to a limited, per-session
+// filesystem — its workspace — never the app process's fs or the host OS. justbash shares the
+// app process filesystem, so it is a DEV-ONLY opt-in guarded by a loud boot warning.
+
+export type SelfHostBackendKind = "docker" | "justbash";
+
+export const JUSTBASH_BOOT_WARNING =
+  "[open-everywhere:sandbox] ⚠ justbash backend: the agent's shell SHARES THE APP PROCESS FILESYSTEM " +
+  "(app files, container/OS). Dev + testing only — use docker() (default) or Vercel for any real deployment.";
+
+/**
+ * Resolve the off-Vercel backend kind from the environment.
+ *   unset / empty / "docker"  → docker  (the contained default)
+ *   "justbash"                → justbash (dev opt-in)
+ *   anything else             → THROW    (fail loud at boot; never silently fall back)
+ * Trims + lowercases so `OE_SANDBOX_BACKEND=" Docker "` still resolves.
+ */
+export function resolveSelfHostBackendKind(env: NodeJS.ProcessEnv = process.env): SelfHostBackendKind {
+  const raw = env.OE_SANDBOX_BACKEND;
+  const kind = (raw ?? "").trim().toLowerCase();
+  if (kind === "" || kind === "docker") return "docker";
+  if (kind === "justbash") return "justbash";
+  throw new Error(
+    `[open-everywhere:sandbox] unknown OE_SANDBOX_BACKEND=${JSON.stringify(raw)} — valid values: ` +
+      `docker (default) | justbash (dev only). Refusing to boot.`,
+  );
+}
+
+export interface BackendBootLog {
+  /** A loud, unmissable warning line — present ONLY for the dev-only justbash backend. */
+  warn?: string;
+  /** One info line naming the chosen backend (ids only, no values). Always present. */
+  info: string;
+}
+
+/** Pure boot-log plan for a resolved backend kind (emitted by selfHostBackend()). */
+export function selfHostBackendBootLog(kind: SelfHostBackendKind): BackendBootLog {
+  if (kind === "justbash") {
+    return {
+      warn: JUSTBASH_BOOT_WARNING,
+      info: "[open-everywhere:sandbox] off-Vercel sandbox backend = justbash (explicit OE_SANDBOX_BACKEND=justbash)",
+    };
+  }
+  return {
+    info: "[open-everywhere:sandbox] off-Vercel sandbox backend = docker (default; contained per-session fs, egress via proxy sidecar)",
+  };
+}

package/agent/sandbox/vercel-create.ts

@@ -0,0 +1,211 @@
+// What Open Everywhere hands eve for VERCEL SANDBOX CREATION — the pure, side-effect-free half of
+// `agent/sandbox/sandbox.ts`'s `vercel({ … })` argument. Kept in its own zero-import module so it is
+// unit-testable (scripts/sandbox-region-test.ts) without pulling the eve graph that importing
+// sandbox.ts would, exactly like the sibling `backend-select.ts`.
+//
+// ── THE RESIDENCY KNOB (OPE-1257, adopted at eve 0.52.2 under OPE-1532) ──
+// A deployment pins WHERE INFERENCE RUNS through the AI Gateway's `inferenceRegion`, and WHERE THE
+// SANDBOX RUNS through `sandbox.region` (docs/extending/models-and-gateway.md). Both legs work.
+//
+// The sandbox leg travels through eve, so it depends on facts about eve's own code:
+//
+//   1. eve mints every sandbox itself. Open Everywhere never calls `Sandbox.create` — it hands
+//      options to `vercel(opts)` (`eve/sandbox/vercel`) and eve creates the template and the
+//      session sandboxes.
+//   2. eve creates them through its OWN VENDORED copy of the SDK, a `#compiled/*` package-internal
+//      import: the root `@vercel/sandbox` float is NOT the module eve creates sandboxes with, so
+//      floating our own dependency forward changes nothing here.
+//      🔴 eve VENDORS SEVERAL COPIES AND HAS SWAPPED WHICH ONE CREATES. At 0.51.0 the create path
+//      loaded `#compiled/@vercel/sandbox`; at 0.52.2 it loads `#compiled/@vercel/sandbox-drives`,
+//      and `@vercel/sandbox` became the DELETE path. So no copy name is a durable fact. The
+//      binding's own two loaders are: `loadSandboxModule` ⇒ create, `loadDeleteSandboxModule` ⇒
+//      delete, and the guard below reads which copy the CREATE loader defaults to rather than
+//      naming one.
+//   3. That vendored copy TYPES `region` on `BaseCreateSandboxParams` and its `Sandbox.create`
+//      FORWARDS it to the API. Both halves are required and neither implies the other — see below.
+//
+// 🔴 TYPED-BUT-NOT-FORWARDED IS THE DANGEROUS SHAPE, and it is why this is a measured boolean
+// rather than a version comparison. The vendored `Sandbox.create` ENUMERATES the fields it posts. A
+// `region` that is typed but missing from that enumeration compiles, passes every typecheck, and is
+// DROPPED — the sandbox boots in the default region while the operator believes it boots in Paris.
+// So `SANDBOX_REGION_PASSTHROUGH_SUPPORTED` records both halves as one boolean, and
+// `scripts/sandbox-region-test.ts` re-derives it from eve's own files on every run — an eve bump
+// that REMOVES the passthrough fails the suite instead of leaving a stale constant behind. That
+// guard also pins the three things it depends on: the interface it reads, the create method it
+// reads, and — the one that bit — WHICH VENDORED COPY IT READS. It resolves that from the binding's
+// `loadSandboxModule` default on every run, so an eve that renames a symbol or moves creation to
+// another copy reds rather than passing by reading a file that no longer decides anything. The bare
+// specifier this used to pin was satisfied by eve 0.52.2's DELETE import, which is how the guard
+// briefly measured a module that mints nothing (found in cold review, OPE-1532).
+//
+// THE POSTURE STAYS FAIL-CLOSED, mirroring `inferenceRegion`, and the `refused` arm below stays for
+// it. 🔴 THE REFUSAL IS NOT AUTOMATIC, AND SAYING OTHERWISE OVERCLAIMS IT. Should a future eve
+// withdraw the passthrough, the automatic part is the SUITE GOING RED — that red is the signal.
+// `SANDBOX_REGION_PASSTHROUGH_SUPPORTED` is a hand-maintained boolean, so the boot keeps pinning the
+// region until a human flips it to `false`. The flip is what arms the `refused` arm: an operator who
+// set `sandbox.region` then gets a REFUSED BOOT naming the gap, instead of a sandbox in the default
+// region. A residency control that quietly does nothing is worse than no control: it is a claim the
+// deployment cannot honour. That is why the red must never be waved through.
+
+/** The regions Vercel Sandbox shipped with, for docs and error text. Not an allow-list — see
+ *  {@link sandboxRegionProblem}, which validates the SHAPE so a region Vercel adds later works
+ *  the day it ships. */
+export const KNOWN_SANDBOX_REGIONS = ["iad1", "sfo1", "cle1", "cdg1"] as const;
+
+/** Where a Vercel sandbox runs when no region is requested. */
+export const DEFAULT_SANDBOX_REGION = "iad1";
+
+/**
+ * Does the pinned eve forward a `region` to Vercel sandbox creation? `true` since eve 0.52.2, whose
+ * vendored `@vercel/sandbox` both types `region` on create and posts it. It is the default
+ * {@link resolveSandboxRegionPlan} uses, so this one constant decides whether a set region is a
+ * working pin or a refused boot.
+ *
+ * 🔴 Do not set it by hand from a changelog: `scripts/sandbox-region-test.ts` derives the same
+ * answer from `node_modules/eve` and fails when the two disagree, which is the signal to change it.
+ */
+export const SANDBOX_REGION_PASSTHROUGH_SUPPORTED = true;
+
+/** One sentence naming the gap the `refused` arm reports, reused by the refusal message and the
+ *  docs. It describes the CONDITION, not a release: the pinned eve satisfies the passthrough today,
+ *  and this text is what an operator would read if a future eve stopped doing so. */
+export const SANDBOX_REGION_GAP =
+  "the pinned eve creates every Vercel sandbox through its own vendored copy of the SDK, whose " +
+  "Sandbox.create enumerates the fields it forwards to the API — and this eve either does not type " +
+  "`region` on create or does not forward it, so a region set here would be DROPPED SILENTLY and " +
+  "the sandbox would run in the default region";
+
+/** A Vercel region id: three lowercase letters then one digit (`iad1`, `cdg1`, `lhr1`, …). */
+const REGION_SHAPE = /^[a-z]{3}[0-9]$/;
+
+/** Trim and lowercase a raw setting value. `""` means "not set". */
+export function normalizeSandboxRegion(raw: string): string {
+  return typeof raw === "string" ? raw.trim().toLowerCase() : "";
+}
+
+/**
+ * The `sandbox.region` settings validator: a problem string, or `undefined` when the value is
+ * acceptable. Empty (the shipped default) is acceptable — it means "do not pin".
+ */
+export function sandboxRegionProblem(raw: string): string | undefined {
+  if (typeof raw !== "string") return "must be a string";
+  const region = normalizeSandboxRegion(raw);
+  if (region === "") return undefined;
+  if (!REGION_SHAPE.test(region)) {
+    return (
+      `must be a Vercel region id — three lowercase letters then a digit, e.g. ` +
+      `${KNOWN_SANDBOX_REGIONS.join(", ")} — or "" to pin nothing`
+    );
+  }
+  return undefined;
+}
+
+/** What a resolved `sandbox.region` means for this boot. */
+export type SandboxRegionPlan =
+  /** Nothing pinned: sandboxes run wherever Vercel puts them. */
+  | { readonly kind: "unset" }
+  /** The value is not a region id. Fail the boot rather than guess. */
+  | { readonly kind: "invalid"; readonly error: string }
+  /** Off Vercel there is no Vercel sandbox to place — the operator's own host is the residency fact. */
+  | { readonly kind: "inert"; readonly warn: string }
+  /** A region was asked for and cannot be delivered. Fail the boot; never run in the default region. */
+  | { readonly kind: "refused"; readonly error: string }
+  /** A region was asked for and reaches sandbox creation. */
+  | { readonly kind: "pinned"; readonly region: string; readonly info: string };
+
+/**
+ * Decide what a `sandbox.region` value means for this boot. Pure — the caller raises the error,
+ * prints the log, and applies the region.
+ *
+ * `passthroughSupported` DEFAULTS to {@link SANDBOX_REGION_PASSTHROUGH_SUPPORTED} — the boot passes
+ * nothing, so that one constant decides between a pin and a refusal. It stays a parameter so BOTH
+ * arms are testable whichever way the constant currently reads.
+ */
+export function resolveSandboxRegionPlan(input: {
+  readonly region: string;
+  readonly onVercel: boolean;
+  readonly passthroughSupported?: boolean;
+}): SandboxRegionPlan {
+  const passthroughSupported = input.passthroughSupported ?? SANDBOX_REGION_PASSTHROUGH_SUPPORTED;
+  const region = normalizeSandboxRegion(input.region);
+  if (region === "") return { kind: "unset" };
+
+  const problem = sandboxRegionProblem(region);
+  if (problem !== undefined) {
+    return {
+      kind: "invalid",
+      error: `[open-everywhere:sandbox] sandbox.region=${JSON.stringify(input.region)} ${problem}. Refusing to boot.`,
+    };
+  }
+
+  // Off Vercel the sandbox is a container on hardware the operator already chose, so a region id
+  // has nothing to select. Say so loudly — silence would read as "pinned".
+  if (!input.onVercel) {
+    return {
+      kind: "inert",
+      warn:
+        `[open-everywhere:sandbox] ⚠ sandbox.region=${region} is a VERCEL-BACKEND knob and does nothing here. ` +
+        `The docker/justbash backend runs on the host you run it on — that host, not this setting, is where ` +
+        `sandbox compute happens.`,
+    };
+  }
+
+  if (!passthroughSupported) {
+    return {
+      kind: "refused",
+      error:
+        `[open-everywhere:sandbox] sandbox.region=${region} cannot be honoured: ${SANDBOX_REGION_GAP}. ` +
+        `Refusing to boot rather than run in ${DEFAULT_SANDBOX_REGION} under a residency pin. ` +
+        `Clear sandbox.region to boot without the pin (and drop the sandbox leg of any residency claim), ` +
+        `or stay on an eve whose CREATE path forwards the region.`,
+    };
+  }
+
+  return {
+    kind: "pinned",
+    region,
+    info: `[open-everywhere:sandbox] sandbox region = ${region} (pinned at sandbox CREATE; existing sandboxes keep theirs)`,
+  };
+}
+
+/**
+ * The options object handed to eve's `vercel(opts)`. Fields eve forwards to Vercel sandbox
+ * creation for every fresh sandbox it makes.
+ *
+ * 🔴 `failoverRegions` IS DELIBERATELY ABSENT and must stay absent. A cross-zone failover moves the
+ * workload out of the pinned region without telling anyone, which is the silent-fallback shape the
+ * residency posture refuses. A same-zone failover set can be argued for later; it needs its own
+ * decision, not a default.
+ */
+// 🔴 A `type`, NOT an `interface`, and that is load-bearing. eve's `vercel(opts)` parameter
+// intersects an index signature (`{ readonly [key: `__${string}`]: unknown }`) for its internal
+// options. TypeScript gives an object TYPE an implicit index signature and an INTERFACE none, so
+// an interface here is unassignable to that parameter — with an error that names four unrelated
+// missing properties and points nowhere near the cause.
+export type OeVercelCreateOptions = {
+  /** The per-session window (the backstop fuse), ms. */
+  readonly timeout: number;
+  /** Snapshot auto-GC age, ms. */
+  readonly snapshotExpiration: number;
+  /** Keep exactly the latest snapshot; delete evicted ones at once. */
+  readonly keepLastSnapshots: { readonly count: number; readonly deleteEvicted: boolean };
+  /** The pinned region — present ONLY for a `pinned` plan. */
+  readonly region?: string;
+};
+
+/**
+ * Compose the `vercel(opts)` argument. The region joins it only on a `pinned` plan, so the object
+ * an unpinned deployment hands eve is byte-identical to the pre-OPE-1257 one.
+ */
+export function vercelSandboxCreateOptions(input: {
+  readonly timeoutMs: number;
+  readonly snapshotExpirationMs: number;
+  readonly regionPlan: SandboxRegionPlan;
+}): OeVercelCreateOptions {
+  const base = {
+    timeout: input.timeoutMs,
+    snapshotExpiration: input.snapshotExpirationMs,
+    keepLastSnapshots: { count: 1, deleteEvicted: true },
+  } as const;
+  return input.regionPlan.kind === "pinned" ? { ...base, region: input.regionPlan.region } : base;
+}