@oar-sh/oar 0.9.18 → 0.9.19

package/.github/extensions/web-relay/server-lifecycle/managed-server.mjs

@@ -1,3 +1,5 @@
+import { relayRuntimeNodeFlags, relayRuntimeNodeFlagsOrNone } from "../../../../server/relay-heap-guard.mjs";
+
 export function createManagedServerLifecycle({
   api,
   dbg,
@@ -16,6 +18,8 @@ export function createManagedServerLifecycle({
   relayPort = 3333,
   nodeBin,
   serverStartTimeoutMs,
+  // The heap limit and heap snapshot flags every relay runtime starts with.
+  nodeFlags = relayRuntimeNodeFlags,
 }) {
   let managedServerProc = null;
   let managedServerStdoutFd = null;
@@ -301,7 +305,15 @@ export function createManagedServerLifecycle({
         if (startupWorkspaceRoot) {
           serverEnv.COPILOT_WORKSPACE_ROOT = startupWorkspaceRoot;
         }
-        managedServerProc = spawn(nodeBin, serverArgs, {
+        // The runtime runs in this process (--supervised): its Node flags go here.
+        const { flags } = relayRuntimeNodeFlagsOrNone(nodeFlags, {
+          env: serverEnv,
+          execArgv: [],
+          serverDir,
+          fsImpl: fs,
+          logger: { log: (line) => dbg(line) },
+        });
+        managedServerProc = spawn(nodeBin, [...flags, ...serverArgs], {
           cwd: serverDir,
           env: serverEnv,
           stdio: ["ignore", managedServerStdoutFd, managedServerStderrFd],

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 All notable changes to OAR are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [0.9.19] — 2026-10-27
+
+Highlights: a relay that runs out of memory is restarted instead of staying
+down. Its runtime starts with a heap limit, set with `heapLimitMb` in
+`config.json`, and writes one heap snapshot when it nears that limit; a
+snapshot holds the relay's auth token and API keys, so never share one as it
+is. Agent sessions can use the providers a relay update added without a
+restart of their own, and Copilot refuses another provider's model id before
+it creates anything.
+
+### Fixed
+
+- **A relay that runs out of memory is restarted.** A relay runtime that ran
+  out of memory ended the relay for good. Its supervisor took the
+  out-of-memory abort for a clean stop and exited 0, which systemd does not
+  restart. The runtime is now relaunched like any crash. It starts with a heap
+  limit (60 % of RAM, 2048–8192 MB, set with `heapLimitMb` in `config.json`)
+  and writes one heap snapshot to `diagnostics` in the data directory when it
+  nears that limit. A heap snapshot holds the relay's auth token and API keys:
+  never share one as it is. The status log shows its memory every 10 minutes
+  and when the heap passes 80 % of the limit.
+- **`relay_tool` takes any provider id.** Agent sessions started before a
+  relay update refused the providers the update added (such as `deepseek` and
+  `claude-api`) in `relay_tool`'s `create_session` and `send`. The tool now
+  takes any provider id; the relay checks it against its current list and
+  names that list when it refuses one.
+- **Copilot refuses another provider's model id before creating anything.** A
+  Copilot session given another provider's model id (such as `claude-opus-5-5`
+  for Copilot's `claude-opus-5.5`) was created and then refused with
+  `CURSOR_MODEL_REQUIRES_NEW_CONVERSATION`. Copilot now refuses such an id
+  with `COPILOT_MODEL_UNAVAILABLE` and the close match before anything is
+  created, and a first prompt refused after `create_session` made the session
+  names that session.
+
+### Upgrade notes
+
+- **Agent sessions started before 0.9.19 keep their provider list:** their
+  workers keep running through the update, with the `relay_tool` they
+  started with. That list is the one 0.9.19 has, so nothing changes now; it
+  lacks the providers a later update adds until the session's worker
+  restarts, for example after **☠️ Kill session** in the `⋯` menu.
+
 ## [0.9.18] — 2026-10-26
 
 Highlights: Claude chats can run on a Claude Console API key. Claude API is

package/README.md

@@ -45,29 +45,29 @@ flowchart LR
 <table>
 <tr>
 <td width="42%" rowspan="4" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-mobile.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.18" alt="OAR on a phone: a finished agent turn in a conversation, with the composer below"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.19"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-mobile.light.png?v=0.9.19"><img src="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.19" alt="OAR on a phone: a finished agent turn in a conversation, with the composer below"></picture></a>
 <br><sub>On a phone: the same conversations, installable as an app.</sub>
 </td>
 <td width="58%" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-agents.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.18" alt="Background subagents running in parallel in the task panel, each with live token counts, elapsed time, and its own Stop button"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.19"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-agents.light.png?v=0.9.19"><img src="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.19" alt="Background subagents running in parallel in the task panel, each with live token counts, elapsed time, and its own Stop button"></picture></a>
 <br><sub>Agents working in parallel, each with live token counts and its own Stop.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-question.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.18" alt="A question card in the middle of a turn: the agent offers several choices and a free-text reply"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.19"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-question.light.png?v=0.9.19"><img src="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.19" alt="A question card in the middle of a turn: the agent offers several choices and a free-text reply"></picture></a>
 <br><sub>When the agent needs a decision, it asks, and waits for your answer.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pingcf-thoughts.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.18" alt="An expanded Thoughts block showing the agent's reasoning above its reply"></picture></a>
+<a href="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.19"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pingcf-thoughts.light.png?v=0.9.19"><img src="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.19" alt="An expanded Thoughts block showing the agent's reasoning above its reply"></picture></a>
 <br><sub>Read the reasoning, not just the answer.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-watching.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.18" alt="A session watching two other sessions: a finished reply arrives as a compact relay-event row, the watching 2 sessions list is open with Unsubscribe, and a request to also watch a session on a paired relay waits on an Allow / Deny card"></picture></a>
+<a href="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.19"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-watching.light.png?v=0.9.19"><img src="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.19" alt="A session watching two other sessions: a finished reply arrives as a compact relay-event row, the watching 2 sessions list is open with Unsubscribe, and a request to also watch a session on a paired relay waits on an Allow / Deny card"></picture></a>
 <br><sub>Agents that watch agents: woken by events, approving nothing.</sub>
 </td>
 </tr>
@@ -118,11 +118,11 @@ API keys are entered in **⚙️ Settings** and stay on the relay host. The Clau
 <table>
 <tr>
 <td width="62%" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-steering.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.18" alt="A running Claude turn with a message steered into it mid-turn, the reply streaming with its tool calls, and the Steer button in the composer"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.19"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-steering.light.png?v=0.9.19"><img src="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.19" alt="A running Claude turn with a message steered into it mid-turn, the reply streaming with its tool calls, and the Steer button in the composer"></picture></a>
 <br><sub>Send a message while the agent works, and it steers the running turn.</sub>
 </td>
 <td width="38%" valign="top">
-<a href="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/usage-copilot-compact.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.18" alt="The GitHub Copilot card in Check Usage: premium requests and plan quota with reset dates, and the cost of the last turn"></picture></a>
+<a href="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.19"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/usage-copilot-compact.light.png?v=0.9.19"><img src="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.19" alt="The GitHub Copilot card in Check Usage: premium requests and plan quota with reset dates, and the cost of the last turn"></picture></a>
 <br><sub>What each plan has left, in one place.</sub>
 </td>
 </tr>
@@ -139,7 +139,7 @@ API keys are entered in **⚙️ Settings** and stay on the relay host. The Clau
 - **Share** a conversation as a read-only link, hide single messages and the host's paths from it, and see when it was opened ([Sharing](docs/web-ui.md#sharing)).
 - **On your phone**: install OAR as an app and get push notifications ([Notifications and the app](docs/web-ui.md#notifications-and-the-app)).
 
-The full tour is in [Using the web UI](docs/web-ui.md); every setting and config key is in [Settings and configuration](docs/configuration.md). What changed in each release is in the [changelog](CHANGELOG.md), with [0.9.18](CHANGELOG.md#0918--2026-10-26) as the latest.
+The full tour is in [Using the web UI](docs/web-ui.md); every setting and config key is in [Settings and configuration](docs/configuration.md). What changed in each release is in the [changelog](CHANGELOG.md), with [0.9.19](CHANGELOG.md#0919--2026-10-27) as the latest.
 
 ## Remote access
 
@@ -190,7 +190,7 @@ flowchart LR
 
 You stay in charge: per paired relay you decide whether agents may only read, also prompt, or do everything, and in the `ask` and `plan` modes every write asks you first. A subscription only notifies; it approves nothing.
 
-<p><a href="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-cross-relay.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.18" alt="A session watching two sessions on a paired relay: a reply arrives as a relay-event row, and after a short outage the events the other relay kept arrive as one replayed row" width="720"></picture></a></p>
+<p><a href="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.19"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-cross-relay.light.png?v=0.9.19"><img src="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.19" alt="A session watching two sessions on a paired relay: a reply arrives as a relay-event row, and after a short outage the events the other relay kept arrive as one replayed row" width="720"></picture></a></p>
 
 How pairing, permissions and limits work is in [Agents working together](docs/agents-together.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oar-sh/oar",
-  "version": "0.9.18",
+  "version": "0.9.19",
   "type": "module",
   "description": "OAR — Open Agent Relay: drive your local coding agents from any browser",
   "license": "MIT",

package/server/claude-worker/claude-remote-relay-tool.mjs

@@ -11,7 +11,6 @@ import {
   REMOTE_RELAY_ACTIONS,
   REMOTE_RELAY_IF_BUSY,
   REMOTE_RELAY_MODES,
-  REMOTE_RELAY_PROVIDERS,
   REMOTE_RELAY_SESSION_SCOPES,
   REMOTE_RELAY_THINKING_DISPLAYS,
 } from '../../shared/remote-relay-contract.mjs';
@@ -61,7 +60,8 @@ export const REMOTE_RELAY_TOOL_ZOD_SHAPE = {
   before: text('before'),
   include_activity: z.boolean().optional().describe(FIELDS.include_activity.description),
   max_chars: number('max_chars'),
-  provider: choice('provider', REMOTE_RELAY_PROVIDERS),
+  // Free text: the worker outlives relay updates, the relay checks the id.
+  provider: text('provider'),
   model: text('model'),
   cwd: text('cwd'),
   repo: text('repo'),

package/server/relay-heap-guard.mjs

@@ -0,0 +1,338 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import v8 from 'v8';
+
+import { resolveDataDir } from './services/data-dir-resolution.mjs';
+
+// The config.json key an operator sets to pin the runtime's heap (MB). A key
+// and not an env var: a shell's NODE_OPTIONS is lost on the next relaunch by
+// systemd, an autostart launcher or the CLI extension; config.json is read by
+// every one of them.
+export const HEAP_LIMIT_CONFIG_KEY = 'heapLimitMb';
+export const MIN_HEAP_LIMIT_MB = 512;
+const DEFAULT_FLOOR_MB = 2048;
+const DEFAULT_CAP_MB = 8192;
+const DEFAULT_RAM_SHARE = 0.6;
+// v8's heap_size_limit is old space plus the young generation, while
+// --max-old-space-size sets old space only: compare like with like. Node 24
+// reserves 3 × 64 MB semi-spaces (old space 2048 → heap_size_limit 2240);
+// older Nodes reserve less, which only sets this floor a little low.
+const YOUNG_GENERATION_ALLOWANCE_MB = 192;
+const MB = 1024 * 1024;
+
+const HEAP_FLAG = /^--max[-_]old[-_]space[-_]size(?:=(.*))?$/;
+// Node 24.11+: the old space as a percentage of the memory Node sees.
+const HEAP_PERCENTAGE_FLAG = /^--max[-_]old[-_]space[-_]size[-_]percentage(?:=(.*))?$/;
+const SNAPSHOT_FLAG = /^--heapsnapshot[-_]near[-_]heap[-_]limit(?:=|$)/;
+const DIAGNOSTIC_DIR_FLAG = /^--diagnostic[-_]dir(?:=(.*))?$/;
+
+/**
+ * NODE_OPTIONS as Node splits it (ParseNodeOptionsEnvVar): on spaces, except
+ * inside double quotes, which are taken off; inside them a backslash escapes
+ * the next character. A single quote is an ordinary character.
+ */
+export function splitNodeOptions(value) {
+  const args = [];
+  let current = '';
+  let inString = false;
+  const text = String(value || '');
+  for (let index = 0; index < text.length; index += 1) {
+    let char = text[index];
+    if (char === '\\' && inString && index + 1 < text.length) {
+      index += 1;
+      char = text[index];
+    } else if (char === ' ' && !inString) {
+      if (current) args.push(current);
+      current = '';
+      continue;
+    } else if (char === '"') {
+      inString = !inString;
+      continue;
+    }
+    current += char;
+  }
+  if (current) args.push(current);
+  return args;
+}
+
+// The value the last `flag` in an arg list sets (`=V` or V as the next arg),
+// as in Node; undefined when none sets it.
+function lastFlagValue(args, flag) {
+  let found;
+  for (let index = 0; index < args.length; index += 1) {
+    const match = flag.exec(String(args[index]));
+    if (match) found = match[1] !== undefined ? match[1] : String(args[index + 1] ?? '');
+  }
+  return found;
+}
+
+function positiveNumber(value) {
+  const number = Number.parseFloat(String(value ?? ''));
+  return Number.isFinite(number) && number > 0 ? number : null;
+}
+
+/**
+ * The heap limit the operator set in execArgv or NODE_OPTIONS: `{ mb }` for
+ * --max-old-space-size, `{ percentage }` for --max-old-space-size-percentage,
+ * with its `source`; null when neither sets one. As in Node, a percentage
+ * wins over a size wherever each is set, and execArgv over NODE_OPTIONS.
+ */
+export function operatorHeapLimit({ execArgv = [], nodeOptions = '' } = {}) {
+  const sources = [['execArgv', Array.from(execArgv || [])], ['NODE_OPTIONS', splitNodeOptions(nodeOptions)]];
+  for (const [source, args] of sources) {
+    const percentage = positiveNumber(lastFlagValue(args, HEAP_PERCENTAGE_FLAG));
+    if (percentage) return { percentage, source };
+  }
+  for (const [source, args] of sources) {
+    const mb = positiveNumber(lastFlagValue(args, HEAP_FLAG));
+    if (mb) return { mb: Math.floor(mb), source };
+  }
+  return null;
+}
+
+/**
+ * The memory this host gives the relay: a container's or cgroup's limit
+ * (process.constrainedMemory) when it is set and under the RAM, else the RAM.
+ * Without a limit it reports 0, nothing, or a huge number: ignored.
+ */
+export function availableMemory({ totalMem = os.totalmem(), constrainedMem = process.constrainedMemory?.() } = {}) {
+  const total = Number(totalMem) || 0;
+  const constrained = Number(constrainedMem);
+  if (Number.isFinite(constrained) && constrained > 0 && constrained < total) {
+    return { bytes: constrained, label: 'memory limit' };
+  }
+  return { bytes: total, label: 'RAM' };
+}
+
+/**
+ * 60 % of RAM in whole 64 MB steps, between 2048 and 8192 MB, and never under
+ * Node's own default (`nodeDefaultMb`, old space only). 60 % leaves room for
+ * the CLI workers and for writing a heap snapshot: a heap that fills RAM ends
+ * in the kernel's OOM killer, which leaves neither a snapshot nor a log line.
+ */
+export function defaultHeapLimitMb({ totalMem = os.totalmem(), nodeDefaultMb = 0 } = {}) {
+  const share = Math.floor((Number(totalMem) || 0) * DEFAULT_RAM_SHARE / MB / 64) * 64;
+  const clamped = Math.min(DEFAULT_CAP_MB, Math.max(DEFAULT_FLOOR_MB, share));
+  return Math.max(clamped, Math.floor(Number(nodeDefaultMb) || 0));
+}
+
+/** Node's default old-space limit, from this process's v8 heap limit. */
+export function nodeDefaultOldSpaceMb(heapSizeLimit = v8.getHeapStatistics().heap_size_limit) {
+  return Math.max(0, Math.floor(Number(heapSizeLimit) / MB) - YOUNG_GENERATION_ALLOWANCE_MB);
+}
+
+function resolveConfigPath(env, serverDir) {
+  const fromEnv = String(env?.COPILOT_WEB_RELAY_CONFIG || '').trim();
+  return fromEnv ? path.resolve(fromEnv) : path.join(String(serverDir || ''), 'config.json');
+}
+
+/**
+ * config.json's heapLimitMb: `{ mb }`, `{ invalid }` for a value that is not a
+ * whole number of at least MIN_HEAP_LIMIT_MB, or null when it sets none. An
+ * unreadable config sets none: the runtime reports config problems itself.
+ */
+export function configuredHeapLimit({ configPath, fsImpl = fs } = {}) {
+  let parsed = null;
+  try { parsed = JSON.parse(fsImpl.readFileSync(configPath, 'utf8')); } catch { return null; }
+  const value = parsed?.[HEAP_LIMIT_CONFIG_KEY];
+  if (value === undefined || value === null || value === '') return null;
+  const mb = Number(value);
+  return Number.isInteger(mb) && mb >= MIN_HEAP_LIMIT_MB ? { mb } : { invalid: value };
+}
+
+function freeBytes(dir, fsImpl) {
+  try {
+    if (typeof fsImpl.statfsSync !== 'function') return null;
+    const stats = fsImpl.statfsSync(dir);
+    return Number(stats.bavail) * Number(stats.bsize);
+  } catch {
+    return null;
+  }
+}
+
+/** A path for the log: `~` for the home folder, so a log line names no user. */
+export function displayPath(target, homeDir = os.homedir()) {
+  const resolved = path.resolve(String(target || ''));
+  const home = String(homeDir || '').trim() ? path.resolve(String(homeDir)) : '';
+  if (!home) return resolved;
+  const relative = path.relative(home, resolved);
+  if (relative === '') return '~';
+  if (relative.startsWith('..') || path.isAbsolute(relative)) return resolved;
+  return `~${path.sep}${relative}`;
+}
+
+function countSnapshots(dir, fsImpl) {
+  try {
+    return fsImpl.readdirSync(dir).filter((name) => name.endsWith('.heapsnapshot')).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * The Node flags every relay runtime starts with: a known heap limit, and one
+ * heap snapshot near it, written to `<data dir>/diagnostics`.
+ *
+ * The heap limit comes from execArgv or NODE_OPTIONS when the operator set
+ * one there (nothing added), else config.json's heapLimitMb, else
+ * defaultHeapLimitMb; neither of the last two goes above the memory the host
+ * gives the relay (availableMemory). The diagnostics folder is made 0700 (a
+ * snapshot holds the auth token and provider keys); a --diagnostic-dir or
+ * --heapsnapshot-near-heap-limit the operator set is kept as it is. When the
+ * folder cannot be made, or its drive has less than twice the heap limit
+ * free (the database lives there too), no snapshot is asked for. Says what
+ * it chose on `logger`, with the home folder as `~`.
+ */
+export function relayRuntimeNodeFlags({
+  env = process.env,
+  execArgv = process.execArgv,
+  serverDir,
+  totalMem = os.totalmem(),
+  constrainedMem = process.constrainedMemory?.(),
+  heapSizeLimit = v8.getHeapStatistics().heap_size_limit,
+  fsImpl = fs,
+  platform = process.platform,
+  homeDir = os.homedir(),
+  logger = console,
+} = {}) {
+  const log = (line) => logger?.log?.(line);
+  const operatorArgs = [...Array.from(execArgv || []), ...splitNodeOptions(env?.NODE_OPTIONS)];
+  const memory = availableMemory({ totalMem, constrainedMem });
+  const memoryMb = Math.floor(memory.bytes / MB / 64) * 64;
+  const memoryText = `${(memory.bytes / 1024 ** 3).toFixed(1)} GB ${memory.label}`;
+  const flags = [];
+
+  let heapLimitMb;
+  let source;
+  const operator = operatorHeapLimit({ execArgv, nodeOptions: env?.NODE_OPTIONS });
+  if (operator?.mb) {
+    heapLimitMb = operator.mb;
+    source = `from ${operator.source}`;
+  } else if (operator?.percentage) {
+    heapLimitMb = Math.floor(memory.bytes * operator.percentage / 100 / MB);
+    source = `${operator.percentage}% of ${memoryText}, from ${operator.source}`;
+  } else {
+    const configured = configuredHeapLimit({ configPath: resolveConfigPath(env, serverDir), fsImpl });
+    if (configured?.invalid !== undefined) {
+      log(`[relay] config ${HEAP_LIMIT_CONFIG_KEY}=${JSON.stringify(configured.invalid)} ignored: expected a whole number of MB, at least ${MIN_HEAP_LIMIT_MB}`);
+    }
+    if (configured?.mb) {
+      heapLimitMb = configured.mb;
+      source = `from config ${HEAP_LIMIT_CONFIG_KEY}`;
+      if (memoryMb >= MIN_HEAP_LIMIT_MB && heapLimitMb > memoryMb) {
+        log(`[relay] config ${HEAP_LIMIT_CONFIG_KEY}=${heapLimitMb} is more than the ${memoryText}; using ${memoryMb} MB`);
+        heapLimitMb = memoryMb;
+      }
+    } else {
+      heapLimitMb = defaultHeapLimitMb({ totalMem: memory.bytes, nodeDefaultMb: nodeDefaultOldSpaceMb(heapSizeLimit) });
+      if (memoryMb >= MIN_HEAP_LIMIT_MB) heapLimitMb = Math.min(heapLimitMb, memoryMb);
+      source = `default: ${Math.round(DEFAULT_RAM_SHARE * 100)}% of ${memoryText}`;
+    }
+    flags.push(`--max-old-space-size=${heapLimitMb}`);
+  }
+  log(`[relay] heap limit ${heapLimitMb} MB (${source})`);
+
+  // The operator's --diagnostic-dir is theirs: checked, never made or changed.
+  const operatorDir = lastFlagValue(operatorArgs, DIAGNOSTIC_DIR_FLAG);
+  const diagnosticDir = operatorDir
+    ? path.resolve(operatorDir)
+    : path.join(resolveDataDir({ env, configPath: resolveConfigPath(env, serverDir), serverDir, fsImpl }), 'diagnostics');
+  const shownDir = displayPath(diagnosticDir, homeDir);
+  let snapshot = false;
+  try {
+    if (!operatorDir) {
+      fsImpl.mkdirSync(diagnosticDir, { recursive: true, mode: 0o700 });
+      // mkdir leaves a folder that was there as it was.
+      if (platform !== 'win32') fsImpl.chmodSync?.(diagnosticDir, 0o700);
+    }
+    const free = freeBytes(diagnosticDir, fsImpl);
+    if (operatorArgs.some((arg) => SNAPSHOT_FLAG.test(arg))) {
+      snapshot = true;
+    } else if (free !== null && free < 2 * heapLimitMb * MB) {
+      log(`[relay] no heap snapshot near the limit: ${shownDir} has ${Math.floor(free / MB)} MB free, under twice the heap limit`);
+    } else {
+      flags.push('--heapsnapshot-near-heap-limit=1');
+      snapshot = true;
+    }
+    if (!operatorDir) flags.push(`--diagnostic-dir=${diagnosticDir}`);
+    if (snapshot) {
+      log(`[relay] heap snapshots near the limit go to ${shownDir} (${countSnapshots(diagnosticDir, fsImpl)} already there)`);
+    }
+  } catch (error) {
+    log(`[relay] no heap snapshot near the limit: cannot prepare ${shownDir} (${error?.code || error?.message || error})`);
+  }
+
+  return { flags, heapLimitMb, source, diagnosticDir, snapshot };
+}
+
+/**
+ * relayRuntimeNodeFlags' flags, or none when it fails: a runtime must start
+ * even when its heap guard cannot be worked out.
+ */
+export function relayRuntimeNodeFlagsOrNone(nodeFlags, options = {}) {
+  try {
+    return nodeFlags(options);
+  } catch (error) {
+    options.logger?.log?.(`[relay] starting the runtime without heap flags: ${error?.message || error}`);
+    return { flags: [] };
+  }
+}
+
+function toMb(bytes) {
+  return Math.round((Number(bytes) || 0) / MB);
+}
+
+/** `[relay] memory rss=<MB> heapUsed=<MB> heapLimit=<MB>` */
+export function formatMemoryLine({ rss, heapUsed, heapLimit }) {
+  return `[relay] memory rss=${toMb(rss)} heapUsed=${toMb(heapUsed)} heapLimit=${toMb(heapLimit)}`;
+}
+
+/**
+ * Says once when heapUsed crosses `threshold` of the heap limit, and again
+ * only after it has been back under it. `check` returns whether it said so.
+ */
+export function createHeapWatch({ threshold = 0.8, logger = console } = {}) {
+  let above = false;
+  return {
+    check({ heapUsed, heapLimit }) {
+      const over = Number(heapLimit) > 0 && Number(heapUsed) >= threshold * Number(heapLimit);
+      const crossed = over && !above;
+      above = over;
+      if (crossed) {
+        logger?.log?.(`[relay] memory high: heapUsed=${toMb(heapUsed)} is over ${Math.round(threshold * 100)}% of heapLimit=${toMb(heapLimit)}`);
+      }
+      return crossed;
+    },
+  };
+}
+
+/**
+ * The runtime's memory in the status log: a line now and every 10 minutes,
+ * and a silent check every minute that says when heapUsed crosses 80 % of
+ * the limit. Both timers are unref'd; returns them for runtimeTimers.
+ */
+export function startRelayMemoryLog({
+  logger = console,
+  memoryUsage = () => process.memoryUsage(),
+  heapLimit = () => v8.getHeapStatistics().heap_size_limit,
+  logIntervalMs = 10 * 60 * 1000,
+  watchIntervalMs = 60 * 1000,
+} = {}) {
+  const watch = createHeapWatch({ logger });
+  const sample = () => {
+    const { rss, heapUsed } = memoryUsage();
+    return { rss, heapUsed, heapLimit: heapLimit() };
+  };
+  const logLine = () => {
+    const now = sample();
+    logger?.log?.(formatMemoryLine(now));
+    watch.check(now);
+  };
+  logLine();
+  const log = setInterval(logLine, logIntervalMs);
+  log.unref?.();
+  const check = setInterval(() => watch.check(sample()), watchIntervalMs);
+  check.unref?.();
+  return { log, check };
+}

package/server/relay-self-restart.mjs

@@ -1,6 +1,7 @@
 import { spawn } from 'child_process';
 import path from 'path';
 import { RELAY_RESTART_EXIT_CODE, RELAY_STOP_EXIT_CODE } from './relay-exit-codes.mjs';
+import { relayRuntimeNodeFlags, relayRuntimeNodeFlagsOrNone } from './relay-heap-guard.mjs';
 
 // Role selection travels on argv, never in the environment. The runtime's env is
 // inherited by tmux worker sessions and by the Copilot CLI it launches, and the
@@ -34,8 +35,11 @@ export function spawnRelayRuntime({
   detached = false,
   windowsHide = true,
   logger = console,
+  // The heap limit and heap snapshot flags (relay-heap-guard.mjs).
+  nodeFlags = relayRuntimeNodeFlags,
 } = {}) {
-  const child = spawnImpl(process.execPath, [...execArgv, scriptPath, RELAY_RUNTIME_FLAG, ...args], {
+  const { flags } = relayRuntimeNodeFlagsOrNone(nodeFlags, { env, execArgv, serverDir: path.dirname(String(scriptPath || '')), logger });
+  const child = spawnImpl(process.execPath, [...flags, ...execArgv, scriptPath, RELAY_RUNTIME_FLAG, ...args], {
     cwd,
     env,
     detached,
@@ -84,8 +88,14 @@ export async function runDirectRelaySupervisor({
   exitImpl = (code) => process.exit(code),
   logger = console,
   installSignalHandlers = true,
+  signals = process,
+  nodeFlags = relayRuntimeNodeFlags,
   restartDelayMs = 500,
   maxCrashRestarts = 3,
+  // A runtime that ran this long before it crashed starts the count afresh:
+  // crashes days apart are not a crash loop.
+  crashCountResetMs = 10 * 60 * 1000,
+  now = Date.now,
 } = {}) {
   let runtimeProc = null;
   let shuttingDown = false;
@@ -102,13 +112,20 @@ export async function runDirectRelaySupervisor({
   const handleSigTerm = () => requestShutdown('SIGTERM', 0);
 
   if (installSignalHandlers) {
-    process.on('SIGINT', handleSigInt);
-    process.on('SIGTERM', handleSigTerm);
+    signals.on('SIGINT', handleSigInt);
+    signals.on('SIGTERM', handleSigTerm);
   }
 
   try {
     let crashCount = 0;
     while (true) {
+      // A Ctrl-C reaches the runtime (same process group) before this
+      // supervisor's handler can run: the runtime's signal exit looks like a
+      // crash, and the shutdown arrives during the delay. Never relaunch then.
+      if (shuttingDown) {
+        return await exitImpl(shutdownExitCode);
+      }
+      const startedAt = now();
       runtimeProc = spawnRelayRuntime({
         env,
         cwd,
@@ -119,6 +136,7 @@ export async function runDirectRelaySupervisor({
         stdio,
         detached: false,
         logger,
+        nodeFlags,
       });
       if (runtimeProc.stdout?.on) {
         runtimeProc.stdout.on('data', (chunk) => process.stdout.write(chunk));
@@ -139,7 +157,13 @@ export async function runDirectRelaySupervisor({
         return await exitImpl(1);
       }
 
-      const exitCode = Number.isInteger(Number(result.code)) ? Number(result.code) : null;
+      // A runtime killed by a signal (an out-of-memory abort is SIGABRT, the
+      // kernel's OOM killer SIGKILL) exits with code null: a crash. Number(null)
+      // is 0, which once ended the supervisor as if the runtime stopped cleanly.
+      const exitCode = result.code !== null && result.code !== undefined && Number.isInteger(Number(result.code))
+        ? Number(result.code)
+        : null;
+      const signal = exitCode === null ? (result.signal || null) : null;
       if (exitCode === RELAY_RESTART_EXIT_CODE) {
         logger?.log?.(`[relay] runtime requested restart; relaunching ${path.basename(String(scriptPath || ''))}...`);
         crashCount = 0;
@@ -156,8 +180,10 @@ export async function runDirectRelaySupervisor({
         return await exitImpl(RELAY_STOP_EXIT_CODE);
       }
 
+      if (now() - startedAt >= crashCountResetMs) crashCount = 0;
       const attempt = crashCount + 1;
-      logger?.error?.(`[relay] runtime crashed with exit code ${exitCode ?? 'null'} (crash ${attempt}/${maxCrashRestarts}).`);
+      const how = signal ? `signal ${signal}` : `exit code ${exitCode ?? 'null'}`;
+      logger?.error?.(`[relay] runtime crashed with ${how} (crash ${attempt}/${maxCrashRestarts}).`);
       if (attempt >= maxCrashRestarts) {
         logger?.error?.('[relay] crash limit reached; supervisor stopping.');
         return await exitImpl(1);
@@ -168,8 +194,8 @@ export async function runDirectRelaySupervisor({
 
   } finally {
     if (installSignalHandlers) {
-      process.off('SIGINT', handleSigInt);
-      process.off('SIGTERM', handleSigTerm);
+      signals.off('SIGINT', handleSigInt);
+      signals.off('SIGTERM', handleSigTerm);
     }
   }
 }

package/server/relay-tools.md

@@ -39,12 +39,12 @@ A paired relay stays locked until the user mentions it in this conversation (`@n
 
 This relay itself is listed with "self": true when its owner switched agent sessions on, and is addressed by its name or as "this"; it needs no mention. Use it to hand parts of your task to other sessions:
 
-- `create_session` starts a session with any provider that `relay_info` lists: a local one in a folder ("cwd"), or provider "claude-cloud" with "repo" (a GitHub URL or owner/repo) and an optional "branch". At most 4 sessions you started may work at the same time; a fifth is refused until one finishes.
+- `create_session` starts a session with any provider that `relay_info` lists: a local one in a folder ("cwd"), or provider "claude-cloud" with "repo" (a GitHub URL or owner/repo) and an optional "branch". The provider ids are the target relay's, as `relay_info` shows them; an id it does not know is refused with the list it has. A session started before a relay update can use providers the update added, without a restart. At most 4 sessions you started may work at the same time; a fifth is refused until one finishes.
 - The first `create_session` on this relay shows the user an approval card, once per conversation. A session that an agent created cannot create sessions itself (one level only), unless the owner allowed it for that session: `list_sessions` and `read_session` then show "mayCreateSessions": true. Only the owner sets that.
 - Sessions you start here are grouped under this session in the user's sidebar. `list_sessions` lists in the sidebar's order (a group sorts by its newest session, head first) and shows the group as a "group" field (id, name, role); `read_session` adds the group's live members with their state. `create_session` takes "group" (a group id, or its name in any case, from `relay_info`'s "groups") to put the new session into an existing group instead, here or on a paired relay; an unknown group is refused with the groups listed and nothing is created, and the result carries the "group". Renaming and dissolving groups is the user's.
 - `update_session` ("session" plus any of "model", "effort", "mode", "auto_compact_window", "title", "group", "thinking_enabled", "thinking_display", "cwd") changes another session's settings for its next turns without prompting it, here or on a paired relay, and answers the settings and "changed"; a group name that does not exist makes one, "none" takes the session out (a group the user made stays, even empty; one update_session made goes once empty), a new "cwd" restarts its CLI there (refused while it works), "auto_compact_window" 0 is the model default. The model is checked as for `send`. A failed call still lists in "changed" what it wrote before the failing step. A mode set this way lasts until the next `send` that names another mode or comes from a caller in another mode: a `send` without "mode" passes the caller's own mode.
 - Only a session your conversation started may be updated freely; any other (the user's, another agent's, the one that started you) needs the user's approval card once per conversation and relay (refused: `REMOTE_RELAY_PERMISSION`); never your own conversation.
-- A "model" for `create_session` or `send` must be an id `relay_info` lists for the provider (Claude also takes "opus", "sonnet", "haiku"). An unknown id is refused with the close matches and the valid ids (`Unknown model 'gpt-5-4' for Copilot on relay "…"; did you mean 'gpt-5.4'? Valid ids: … Nothing was sent.`), and nothing is created or sent: pick from the list instead of guessing. If the answer has a "modelNote" saying the model could not be checked, the relay had no model list yet.
+- A "model" for `create_session` or `send` must be an id `relay_info` lists for the provider (Claude also takes "opus", "sonnet", "haiku"). An unknown id is refused with the close matches and the valid ids (`Unknown model 'gpt-5-4' for Copilot on relay "…"; did you mean 'gpt-5.4'? Valid ids: … Nothing was sent.`), and nothing is created or sent: pick from the list instead of guessing. Copilot ids use dots (`claude-opus-5.5`, not the Claude form `claude-opus-5-5`); a hyphen form is refused with the close match named, and a Copilot session never moves to another provider because of its model name. If the answer has a "modelNote" saying the model could not be checked, the relay had no model list yet.
 - A new session knows nothing of this conversation: write a self-contained prompt. A Claude Cloud session works on a fresh clone in a sandbox at Anthropic, so name the branch it should work on and push.
 - Follow each session with `wait` (the message id comes back from `create_session` and `send`) and `read_session`; "wait_seconds" is limited to the maximum set on the relay (default 600).
 - Sessions run on the relay owner's accounts and cost their usage: start only what the task needs.

package/server/routes/messages-routes.mjs

@@ -56,7 +56,11 @@ import { readBefore, readTail, shapeSnapshot, taskOutputSource } from '../servic
 import { taskKindOf } from '../services/session-activity-tracker.mjs';
 import { ANSWERED_ELSEWHERE_KIND, STEER_FOLDED_TEXT } from '../../shared/steer-settle-markers.mjs';
 import { isLiveResend } from '../services/steer-resend.mjs';
-import { resolveProviderModelSelection } from '../services/provider-model-selection.mjs';
+import {
+  checkRequestedProviderModel,
+  resolveProviderModelSelection,
+  unknownProviderModelText,
+} from '../services/provider-model-selection.mjs';
 import { stripRemotePromptHeader } from '../../shared/remote-relay-contract.mjs';
 import { stripModelTierSuffix } from '../../shared/claude-cloud/repo-url.mjs';
 import {
@@ -5019,6 +5023,13 @@ export function registerMessagesRoutes(app, deps) {
         code: 'OPENAI_MODEL_REQUIRES_NEW_CONVERSATION',
       });
     }
+    // A Copilot conversation is bound too, for the model-id guards below only:
+    // Copilot resells Claude and GPT models under ids of its own
+    // ("claude-opus-5.5"), so a Claude-form id another provider lists
+    // ("claude-opus-5-5") is a model Copilot lacks, answered by the Copilot
+    // check further down, never a switch to Cursor, Grok or DeepSeek. (It is
+    // not in runtimeBoundToExplicitProvider: that one also picks the catalog.)
+    const runtimeBoundForModelGuards = runtimeBoundToExplicitProvider || runtimeProviderType === 'github';
     // Cursor conversations are bootstrap-created only, so an existing
     // github/openai/claude conversation cannot cross to the Cursor provider
     // mid-conversation. Cursor settings are read lazily so the hot path stays
@@ -5028,7 +5039,7 @@ export function registerMessagesRoutes(app, deps) {
       let requestTargetsCursor = requestedProviderType === 'cursor';
       if (
         !requestTargetsCursor
-        && !runtimeBoundToExplicitProvider
+        && !runtimeBoundForModelGuards
         && requestedOpenAIModel
         && !requestedModelAvailableInGitHub
       ) {
@@ -5053,7 +5064,7 @@ export function registerMessagesRoutes(app, deps) {
       let requestTargetsGrok = requestedProviderType === 'grok';
       if (
         !requestTargetsGrok
-        && !runtimeBoundToExplicitProvider
+        && !runtimeBoundForModelGuards
         && requestedOpenAIModel
         && !requestedModelAvailableInGitHub
       ) {
@@ -5079,7 +5090,7 @@ export function registerMessagesRoutes(app, deps) {
       let requestTargetsDeepSeek = requestedProviderType === 'deepseek';
       if (
         !requestTargetsDeepSeek
-        && !runtimeBoundToExplicitProvider
+        && !runtimeBoundForModelGuards
         && requestedOpenAIModel
         && !requestedModelAvailableInGitHub
       ) {
@@ -5397,6 +5408,24 @@ export function registerMessagesRoutes(app, deps) {
                     error: deepseekModel ? null : 'DeepSeek model is not configured',
                   }
                 : githubModelResolution)))));
+    // A model Copilot does not list is named with its close matches, as the
+    // bootstrap names it: "claude-opus-5-5" (the Claude form) gets "did you
+    // mean 'claude-opus-5.5'?". Refused before anything is stored.
+    if (!modelResolution.ok && modelResolution === githubModelResolution && explicitModelGiven) {
+      const copilotCheck = checkRequestedProviderModel({
+        requestedModel: requestedOpenAIModel,
+        provider: 'github',
+        models: Array.isArray(githubModelResolution.available) ? githubModelResolution.available : [],
+      });
+      if (copilotCheck.status === 'unknown') {
+        return res.status(400).json({
+          error: unknownProviderModelText({ model: copilotCheck.model, provider: 'github', suggestions: copilotCheck.suggestions, models: copilotCheck.models }),
+          code: 'COPILOT_MODEL_UNAVAILABLE',
+          supportedModels: copilotCheck.models,
+          ...(copilotCheck.suggestions.length ? { suggestedModels: copilotCheck.suggestions } : {}),
+        });
+      }
+    }
     if (!modelResolution.ok) return res.status(400).json({ error: modelResolution.error, supportedModels: modelResolution.available || [] });
     const requestedModel = String(modelResolution.model || '').trim();
     const requestedAutoModel = requestedModel.toLowerCase() === AUTO_MODEL_SENTINEL;

package/server/routes/sessions-routes.mjs

@@ -501,15 +501,34 @@ export function parseGrokSettingsUpdateRequest(body = {}) {
   };
 }
 
-export function buildModelCatalogWithClaudeProvider(modelState = {}, claudeSettings = {}) {
-  const configured = claudeSettings?.enabled === true;
-  const model = String(claudeSettings?.model || '').trim();
-  if (!configured || !model) return { ...modelState };
-  const baseModels = new Set(
+/**
+ * The lower-cased ids Copilot itself lists in `modelState`: those an earlier
+ * provider layer did not add. A layer tags every id it adds, so an id with
+ * tags but none of them Copilot's is another provider's ("claude-opus-5-5"
+ * from the Claude layer), not one Copilot serves too.
+ */
+function copilotListedModelIds(modelState = {}) {
+  const providersByModel = modelState?.providersByModel && typeof modelState.providersByModel === 'object'
+    ? modelState.providersByModel
+    : {};
+  return new Set(
     (Array.isArray(modelState?.models) ? modelState.models : [])
+      .filter((value) => {
+        const id = String(value || '').trim();
+        const providers = providersByModel[id] || providersByModel[id.toLowerCase()];
+        return !Array.isArray(providers) || providers.length === 0
+          || providers.some((provider) => String(provider || '').trim().toLowerCase() === 'github-copilot');
+      })
       .map((value) => String(value || '').trim().toLowerCase())
       .filter((value) => value && value.toLowerCase() !== 'auto'),
   );
+}
+
+export function buildModelCatalogWithClaudeProvider(modelState = {}, claudeSettings = {}) {
+  const configured = claudeSettings?.enabled === true;
+  const model = String(claudeSettings?.model || '').trim();
+  if (!configured || !model) return { ...modelState };
+  const baseModels = copilotListedModelIds(modelState);
   const claudeModels = Array.isArray(claudeSettings?.models)
     ? claudeSettings.models.map((value) => String(value || '').trim()).filter(Boolean)
     : [];
@@ -605,11 +624,7 @@ export function buildModelCatalogWithOpenAIProvider(modelState = {}, openAISetti
   const configured = openAISettings?.enabled === true;
   const model = String(openAISettings?.model || '').trim();
   if (!configured || !model) return { ...modelState };
-  const baseModels = new Set(
-    (Array.isArray(modelState?.models) ? modelState.models : [])
-      .map((value) => String(value || '').trim().toLowerCase())
-      .filter((value) => value && value.toLowerCase() !== 'auto'),
-  );
+  const baseModels = copilotListedModelIds(modelState);
   const openAIModels = Array.isArray(openAISettings?.models)
     ? openAISettings.models.map((value) => String(value || '').trim()).filter(Boolean)
     : [];
@@ -659,11 +674,7 @@ export function buildModelCatalogWithCursorProvider(modelState = {}, cursorSetti
   const configured = cursorSettings?.enabled === true;
   const model = String(cursorSettings?.model || '').trim();
   if (!configured || !model) return { ...modelState };
-  const baseModels = new Set(
-    (Array.isArray(modelState?.models) ? modelState.models : [])
-      .map((value) => String(value || '').trim().toLowerCase())
-      .filter((value) => value && value.toLowerCase() !== 'auto'),
-  );
+  const baseModels = copilotListedModelIds(modelState);
   const cursorModelList = Array.isArray(cursorSettings?.models)
     ? cursorSettings.models.map((value) => String(value || '').trim()).filter(Boolean)
     : [];
@@ -748,11 +759,7 @@ export function buildModelCatalogWithGrokProvider(modelState = {}, grokSettings
   const configured = grokSettings?.enabled === true;
   const model = String(grokSettings?.model || '').trim();
   if (!configured || !model) return { ...modelState };
-  const baseModels = new Set(
-    (Array.isArray(modelState?.models) ? modelState.models : [])
-      .map((value) => String(value || '').trim().toLowerCase())
-      .filter((value) => value && value.toLowerCase() !== 'auto'),
-  );
+  const baseModels = copilotListedModelIds(modelState);
   const grokModelList = Array.isArray(grokSettings?.models)
     ? grokSettings.models.map((value) => String(value || '').trim()).filter(Boolean)
     : [];
@@ -6600,6 +6607,7 @@ export function registerSessionsRoutes(app, deps) {
     // lookup below knows exact base ids only and would fall back too.
     let copilotBoundModel = '';
     let copilotVariantEffort = '';
+    let copilotRefusal = null;
     if (
       remoteRequest.remote
       && !useClaudeCloudProvider && !useOpenAIProvider && !useClaudeProvider && !useCursorProvider && !useGrokProvider
@@ -6625,20 +6633,23 @@ export function registerSessionsRoutes(app, deps) {
         effortsFor: (base) => reasoningByModel[base] || reasoningByModel[String(base).toLowerCase()] || null,
       });
       // Another provider's model is answered by the checks below ("requires
-      // the Claude provider"), not as an unknown one.
+      // the Claude provider"), not as an unknown one. One that several other
+      // providers list ("claude-opus-5-5": Claude and Cursor) passes those
+      // checks and is refused as unknown after them.
       const otherProviders = mergedModels.some((modelId) => String(modelId || '').trim().toLowerCase() === requestedBootstrapModel.toLowerCase());
       if (copilotCheck.status === 'known' && copilotCheck.model && !isAutoModelId(copilotCheck.model)) {
         copilotBoundModel = copilotCheck.base || copilotCheck.model;
         copilotVariantEffort = copilotCheck.effort || '';
       }
-      if (copilotCheck.status === 'unknown' && !otherProviders) {
-        return res.status(400).json({
+      if (copilotCheck.status === 'unknown') {
+        copilotRefusal = {
           ok: false,
           error: unknownProviderModelText({ model: copilotCheck.model, provider: 'github', suggestions: copilotCheck.suggestions, models: copilotCheck.models }),
           code: 'COPILOT_MODEL_UNAVAILABLE',
           supportedModels: copilotCheck.models,
           ...(copilotCheck.suggestions.length ? { suggestedModels: copilotCheck.suggestions } : {}),
-        });
+        };
+        if (!otherProviders) return res.status(400).json(copilotRefusal);
       }
     }
     if (useOpenAIProvider && openAISettings?.configured !== true) {
@@ -6798,6 +6809,9 @@ export function registerSessionsRoutes(app, deps) {
         });
       }
     }
+    // No single other provider claims it: a Copilot session with a model
+    // Copilot does not list would be refused at its first send.
+    if (copilotRefusal) return res.status(400).json(copilotRefusal);
 
     const bootstrapProviderType = useClaudeCloudProvider
       ? 'claude-cloud'

package/server/server-runtime.mjs

@@ -141,6 +141,7 @@ import { createClaudeSessionRootResolver } from './services/claude-session-root-
 import { createCursorSessionRootResolver } from './services/cursor-session-root-service.mjs';
 import { createGitChangesService } from './services/git-changes-service.mjs';
 import { createRelaySingletonGuard } from './services/relay-singleton-guard.mjs';
+import { startRelayMemoryLog } from './relay-heap-guard.mjs';
 import { adoptEarlierDatabase, lostPackageDatabaseWarning, packageDatabaseEvidence } from './services/earlier-database-service.mjs';
 import { ensureDataDirs, resolveDataDir, resolveUploadDir, resolveUploadReadDirs, uploadPathInDirs } from './services/data-dir-resolution.mjs';
 import { mergeStrayMigratedUploads } from './services/oar-state-migration-service.mjs';
@@ -1949,6 +1950,8 @@ const runtimeTimers = {
   sharedViewerPrune: null,
   restoredTaskSettle: null,
   claudeApiCapClock: null,
+  memoryLog: null,
+  memoryWatch: null,
 };
 
 function normalizeRemotePath(value) {
@@ -7856,6 +7859,13 @@ runtimeTimers.questionExpiry = setInterval(expirePendingQuestions, 10_000);
 expirePendingQuestions();
 runtimeTimers.sharedViewerPrune = setInterval(pruneSharedViewerPresence, 5_000);
 if (typeof runtimeTimers.sharedViewerPrune.unref === 'function') runtimeTimers.sharedViewerPrune.unref();
+// Memory in the status log: now, every 10 minutes, and once per crossing of
+// 80 % of the heap limit (relay-heap-guard.mjs).
+{
+  const memoryTimers = startRelayMemoryLog({ logger: console });
+  runtimeTimers.memoryLog = memoryTimers.log;
+  runtimeTimers.memoryWatch = memoryTimers.check;
+}
 const sweptUploads = sweepUnreferencedUploadBlobs();
 if (sweptUploads > 0) {
   console.log(`${runtimeLogPrefix()}Reclaimed ${sweptUploads} unreferenced upload(s)`);

package/server/services/remote-relay-dispatcher.mjs

@@ -2386,10 +2386,29 @@ export function createRemoteRelayDispatcher({
       // From here the new session's queued turn counts toward the cap itself.
       ctx.onPromptQueued?.();
     } catch (error) {
-      if (!choice.effort || !isEffortRejection(error)) throw error;
       // The session exists by now: say so, or the agent starts a second one.
+      const remoteCode = toText(error?.remoteBody?.code);
+      if (!choice.effort || !isEffortRejection(error)) {
+        // The remote's own 4xx is passed on, anything else is a 502, as
+        // mapRemoteError answers them.
+        const code = toText(error?.code);
+        const remoteStatus = Number(error?.status) || 0;
+        const status = error instanceof DispatchFailure
+          ? error.status
+          : (code.startsWith(REMOTE_RELAY_ERROR_CODES.httpPrefix) && remoteStatus >= 400 && remoteStatus < 500 ? remoteStatus : 502);
+        const supportedModels = Array.isArray(error?.remoteBody?.supportedModels) ? error.remoteBody.supportedModels.slice(0, 50) : null;
+        throw new DispatchFailure(status, code || `${REMOTE_RELAY_ERROR_CODES.httpPrefix}${status}`,
+          `${toText(error?.message).replace(/[.\s]+$/, '') || `Relay "${ctx.relay.name}" refused the first prompt`}. The session ${session} was created, but the prompt was not queued.`,
+          {
+            ...(isPlainObject(error?.extra) ? error.extra : {}),
+            session,
+            ...(remoteCode ? { remoteCode } : {}),
+            ...(supportedModels ? { supportedModels } : {}),
+            openUrl: remoteConversationUrl(ctx.relay.url, session) || null,
+            note: 'Use send with this session (update_session to change its model); do not create another session.',
+          });
+      }
       const supported = supportedEffortsOf(error);
-      const remoteCode = toText(error.remoteBody?.code);
       throw new DispatchFailure(400, toText(error.code) || `${REMOTE_RELAY_ERROR_CODES.httpPrefix}400`,
         `${toText(error.message) || `Relay "${ctx.relay.name}" refused effort "${choice.effort}"`}. The session was created, but the prompt was not queued.`,
         {
@@ -3966,7 +3985,13 @@ export function createRemoteRelayDispatcher({
     // wait_seconds is cut to this relay's "longest wait" setting, for every
     // target: the waiting is done here, by polling the target.
     const { maxWaitSeconds } = agentSessions();
-    const validation = validateRemoteRelayToolInput({ ...(isPlainObject(args) ? args : {}), action }, { maxWaitSeconds });
+    // The server must always pass the provider lists: without them the
+    // contract checks a provider's shape only (the worker's path).
+    const validation = validateRemoteRelayToolInput({ ...(isPlainObject(args) ? args : {}), action }, {
+      maxWaitSeconds,
+      providers: REMOTE_RELAY_PROVIDERS,
+      sendProviders: REMOTE_RELAY_SEND_PROVIDERS,
+    });
     const result = await runValidated({ conversationId, req, signal }, validation);
     // The arguments the action does not take, named on the answer (a call
     // that came through a worker's tool had them named there already).

package/shared/remote-relay-contract.mjs

@@ -175,6 +175,17 @@ export const REMOTE_RELAY_IF_BUSY = Object.freeze(['queue', 'fail']);
 // xhigh, max, ultracode, ...), so the contract only checks the shape of the
 // value: the remote relay decides whether its model takes it.
 export const REMOTE_RELAY_EFFORT_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+// A worker can outlive a relay update, so its tool checks a provider's shape
+// only; the relay checks it against the list it has now.
+export const REMOTE_RELAY_PROVIDER_ID_PATTERN = REMOTE_RELAY_EFFORT_PATTERN;
+
+/** The provider field's description, with the lists a relay has. */
+export function remoteRelayProviderDescription(providers = REMOTE_RELAY_PROVIDERS, sendProviders = REMOTE_RELAY_SEND_PROVIDERS) {
+  return `create_session: provider, one of: ${providers.join(', ')} (relay_info lists what the target relay offers; `
+    + 'default: the same provider as this session). '
+    + `send to a Claude session: one of ${sendProviders.join(', ')} (the subscription or the API key) switches its billing from the next turn, `
+    + 'together with this message; the other billing must be set up there. Omit it to keep the session\'s billing.';
+}
 
 export const REMOTE_RELAY_RESULT_STATUSES = Object.freeze([
   'queued',
@@ -460,10 +471,7 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
     },
     provider: {
       type: 'string',
-      enum: [...REMOTE_RELAY_PROVIDERS],
-      description: 'create_session: provider (default: the same provider as this session). '
-        + 'send to a Claude session: "claude" (the subscription) or "claude-api" (the API key) switches its billing from the next turn, '
-        + 'together with this message; the other billing must be set up there. Omit it to keep the session\'s billing.',
+      description: remoteRelayProviderDescription(),
     },
     model: {
       type: 'string',
@@ -759,6 +767,10 @@ export function normalizeRemoteRelayRepo(value) {
  * does not know the setting) wait_seconds is clamped to the ceiling only.
  * `waitLimitedFrom` is set on the result when the relay's setting cut the wait.
  *
+ * `providers` / `sendProviders` are the relay's own lists. Without them (an
+ * adapter in a worker, which may be older than the relay) `provider` is
+ * checked for its shape only; the relay passes them and refuses an unknown one.
+ *
  * An argument the action does not take is never dropped in silence:
  * create_session and update_session refuse it (nothing is created or
  * changed), every other action lists it in `ignored` on the result, which the
@@ -777,7 +789,7 @@ export function validateRemoteRelayToolInput(input = {}, options = {}) {
   return notTaken.length ? { ...result, ignored: notTaken } : result;
 }
 
-function validateToolInput(input, { maxWaitSeconds, now } = {}) {
+function validateToolInput(input, { maxWaitSeconds, now, providers, sendProviders } = {}) {
   const action = toText(input?.action).toLowerCase();
   if (!REMOTE_RELAY_ACTIONS.includes(action)) {
     return invalid(`action must be one of: ${REMOTE_RELAY_ACTIONS.join(', ')}`);
@@ -823,6 +835,16 @@ function validateToolInput(input, { maxWaitSeconds, now } = {}) {
     args[key] = value;
     return { ok: true };
   };
+  const optionalProvider = (allowed, refusal) => {
+    const value = toText(input?.provider).toLowerCase();
+    if (!value) return { ok: true };
+    if (!REMOTE_RELAY_PROVIDER_ID_PATTERN.test(value)) {
+      return invalid('provider must be a provider id such as claude or openai (letters, digits and dashes, at most 32 characters)');
+    }
+    if (Array.isArray(allowed) && !allowed.includes(value)) return invalid(refusal(value, allowed.join(', ')));
+    args.provider = value;
+    return { ok: true };
+  };
   const optionalText = (key, max = 500) => {
     const value = toText(input?.[key]);
     if (value) args[key] = value.slice(0, max);
@@ -883,12 +905,12 @@ function validateToolInput(input, { maxWaitSeconds, now } = {}) {
       const busyCheck = optionalEnum('if_busy', REMOTE_RELAY_IF_BUSY);
       if (!busyCheck.ok) return busyCheck;
       args.if_busy = args.if_busy || 'queue';
-      const providerCheck = optionalEnum('provider', REMOTE_RELAY_SEND_PROVIDERS);
-      if (!providerCheck.ok) {
-        return invalid('send takes provider "claude" (the subscription) or "claude-api" (the API key), for a Claude session only');
-      }
+      const providerCheck = optionalProvider(sendProviders, (value, list) =>
+        `provider "${value}" can't be used with send; send takes one of: ${list} (the Claude session's subscription or API key)`);
+      if (!providerCheck.ok) return providerCheck;
     } else {
-      const providerCheck = optionalEnum('provider', REMOTE_RELAY_PROVIDERS);
+      const providerCheck = optionalProvider(providers, (value, list) =>
+        `provider "${value}" is not a provider here; this relay offers: ${list}`);
       if (!providerCheck.ok) return providerCheck;
       optionalText('cwd', 1000);
       optionalText('title', 200);