@oar-sh/oar 0.9.6 → 0.9.7

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

@@ -10,10 +10,19 @@
 //   { listRelays, selfNames, inboundEnabled, recordUnlock, describeRelay, repository }
 // Every helper treats a missing one as "feature absent": nothing is remote,
 // nothing unlocks, and the routes behave exactly as before.
+//
+// An agent of THIS relay reaches the same routes through the in-process
+// loopback (remote-relay-loopback.mjs), which marks its requests here. Such a
+// request is an agent's like any other relay's (provenance is stored, approval
+// cards stay hidden, nothing unlocks), with two differences: the inbound
+// switch does not apply to it (the local target has its own setting, which the
+// dispatcher checks), and only it may store an origin with `local: true`.
 
 import {
   REMOTE_RELAY_ERROR_CODES,
   REMOTE_RELAY_HEADERS,
+  REMOTE_RELAY_LOCAL_ALIAS,
+  REMOTE_RELAY_LOCAL_ID,
   REMOTE_RELAY_TOOL_NAME,
   normalizeRemoteRelayOrigin,
   stripRemotePromptHeader,
@@ -25,6 +34,19 @@ export const REMOTE_INBOUND_DISABLED_RESPONSE = Object.freeze({
   code: REMOTE_RELAY_ERROR_CODES.inboundDisabled,
 });
 
+// Requests the loopback built. Membership cannot be claimed over HTTP.
+const loopbackRequests = new WeakSet();
+
+/** Marks a request object as built in-process for an agent of this relay. */
+export function markRemoteRelayLoopbackRequest(req) {
+  if (req && typeof req === 'object') loopbackRequests.add(req);
+  return req;
+}
+
+export function isRemoteRelayLoopbackRequest(req) {
+  return !!req && typeof req === 'object' && loopbackRequests.has(req);
+}
+
 function headerValue(req, name) {
   const value = req?.headers?.[name];
   return String((Array.isArray(value) ? value[0] : value) ?? '').trim();
@@ -44,8 +66,21 @@ function headerHops(req) {
  * built from the header (its value is the sender's relay id), so a turn an
  * agent started is always recognisable as one. The hop count is the larger of
  * the body's and the X-OAR-Remote-Hops header's.
+ * `local` is true for a request of this relay's own agent (the loopback);
+ * an origin's `local` flag is kept for those alone.
  */
 export function readRemoteRelayRequest(req, inbound, { body = req?.body } = {}) {
+  const facts = readRemoteRelayRequestFacts(req, inbound, body);
+  if (!facts.remote) return facts;
+  const local = isRemoteRelayLoopbackRequest(req);
+  if (facts.origin?.local && !local) {
+    const { local: _claimed, ...origin } = facts.origin;
+    return { remote: true, origin };
+  }
+  return local ? { ...facts, local: true } : facts;
+}
+
+function readRemoteRelayRequestFacts(req, inbound, body) {
   if (!inbound) return { remote: false, origin: null };
   const rawOrigin = body && typeof body === 'object' ? body.origin : undefined;
   const senderRelayId = headerValue(req, REMOTE_RELAY_HEADERS.origin);
@@ -78,7 +113,9 @@ export function remoteRelayInboundEnabled(inbound) {
  */
 export function admitRemoteRelayRequest(req, res, inbound) {
   const request = readRemoteRelayRequest(req, inbound);
-  if (!request.remote || remoteRelayInboundEnabled(inbound)) return request;
+  // The switch is about OTHER relays' agents; this relay's own are let in by
+  // the agent-sessions setting, before the loopback is ever reached.
+  if (!request.remote || request.local || remoteRelayInboundEnabled(inbound)) return request;
   res.status(403).json({ ...REMOTE_INBOUND_DISABLED_RESPONSE });
   return null;
 }
@@ -164,9 +201,13 @@ export function formatRemoteRelayMentionHint(relays = []) {
 /**
  * The paired relay a remote prompt came from: `{ relayId, name }` (`relayId`
  * is the local registry id), or null when the sender is not paired here or
- * names no relay id.
+ * names no relay id. For a prompt from an agent of this relay itself:
+ * `{ relayId, name, local: true }` with the local target's id.
  */
 export function findOriginRemoteRelay(inbound, origin) {
+  if (inbound && origin?.local === true) {
+    return { relayId: REMOTE_RELAY_LOCAL_ID, name: String(origin.relayName || '').trim() || REMOTE_RELAY_LOCAL_ALIAS, local: true };
+  }
   const instance = String(origin?.relayId || '').trim();
   if (!inbound || typeof inbound.listRelays !== 'function' || !instance) return null;
   try {
@@ -188,6 +229,12 @@ export function findOriginRemoteRelay(inbound, origin) {
 export function formatRemoteRelayOriginHint(relay, origin) {
   const name = hintText(relay?.name);
   if (!name) return '';
+  if (relay?.local === true) {
+    const title = hintText(origin?.conversationTitle, 80);
+    return `<system_reminder>This prompt came from an agent in another session on this relay${title ? ` ("${title}")` : ''}, which started or prompted this session for a part of its own task. `
+      + 'Your reply to it is handed back to that agent by itself, so end with the result it needs. '
+      + 'You see nothing of its conversation: work from the prompt alone.</system_reminder>';
+  }
   const session = hintText(origin?.conversationId, 80);
   const where = session ? `relay "${name}", session "${session}"` : `relay "${name}"`;
   return `<system_reminder>This prompt came from an agent on the paired OAR relay "${name}". `

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

@@ -0,0 +1,245 @@
+'use strict';
+
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { Duplex } from 'node:stream';
+
+import {
+  REMOTE_RELAY_ERROR_CODES,
+  REMOTE_RELAY_HEADERS,
+  REMOTE_RELAY_LIMITS,
+} from '../../shared/remote-relay-contract.mjs';
+import { RemoteRelayError, remoteRelayHttpError } from './remote-relay-client.mjs';
+import { markRemoteRelayLoopbackRequest } from './remote-relay-inbound.mjs';
+
+// The client for the local target: this relay as a relay its own agents work
+// on. It has the outbound client's `request(relay, method, path, options)`,
+// but instead of opening a connection it hands the request to the relay's own
+// HTTP handler in-process. So a session an agent creates here goes through the
+// very routes a paired relay's request reaches (bootstrap, message,
+// conversation, questions, cancel-turn, archive) with their validation, their
+// provenance and their events, and there is no second implementation of what a
+// created session is or how reading, stopping and answering work.
+//
+// The request carries what the outbound client sends: the bearer token (the
+// routes sit behind `auth`), Accept, and the two x-oar-remote-* headers, so the
+// routes treat it as an agent's request (approval cards stay hidden, nothing
+// unlocks, the composer draft is left alone). It is also marked as built here
+// (markRemoteRelayLoopbackRequest), which is what lets it past the inbound
+// switch and lets its origin say `local: true`; nothing sent over HTTP can
+// claim that.
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function relayLabel(relay) {
+  const name = toText(relay?.name);
+  return name ? `Relay "${name}"` : 'This relay';
+}
+
+function buildUrl(path, query) {
+  const route = String(path || '');
+  if (!route.startsWith('/') || route.startsWith('//')) {
+    throw new RemoteRelayError(REMOTE_RELAY_ERROR_CODES.invalidInput, `Invalid path: ${route.slice(0, 80)}`);
+  }
+  const params = new URLSearchParams();
+  if (isPlainObject(query)) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === null) continue;
+      params.set(key, String(value));
+    }
+  }
+  const search = params.toString();
+  return search ? `${route}?${search}` : route;
+}
+
+/** A socket that goes nowhere: the response's bytes are read off the response itself. */
+function createNullSocket() {
+  const socket = new Duplex({
+    read() {},
+    write(_chunk, _encoding, callback) { callback(); },
+  });
+  socket.remoteAddress = '127.0.0.1';
+  socket.setTimeout = () => socket;
+  socket.setNoDelay = () => socket;
+  socket.setKeepAlive = () => socket;
+  return socket;
+}
+
+function toBuffer(chunk, encoding) {
+  if (chunk === undefined || chunk === null || typeof chunk === 'function') return null;
+  if (Buffer.isBuffer(chunk)) return chunk;
+  if (chunk instanceof Uint8Array) return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+  return Buffer.from(String(chunk), typeof encoding === 'string' ? encoding : 'utf8');
+}
+
+export function createRemoteRelayLoopbackClient({
+  // The relay's own request handler: `(req, res) => void` (the Express app).
+  handle,
+  getOwnRelayId = () => '',
+  getOwnToken = () => '',
+  timeoutMs: defaultTimeoutMs = REMOTE_RELAY_LIMITS.requestTimeoutMs,
+  maxBytes = REMOTE_RELAY_LIMITS.responseMaxBytes,
+  setTimeoutImpl = setTimeout,
+  clearTimeoutImpl = clearTimeout,
+} = {}) {
+  /** Runs one request through the handler. Resolves `{ status, text }`. */
+  function inject({ method, url, headers, body, hasBody, timeoutMs }) {
+    return new Promise((resolve, reject) => {
+      const socket = createNullSocket();
+      const req = new IncomingMessage(socket);
+      req.method = method;
+      req.url = url;
+      req.headers = headers;
+      req.rawHeaders = Object.entries(headers).flat();
+      req.httpVersionMajor = 1;
+      req.httpVersionMinor = 1;
+      req.httpVersion = '1.1';
+      if (hasBody) {
+        // What the wire would deliver: JSON, parsed. `_body` tells the JSON
+        // body parser the body is already there.
+        req.body = JSON.parse(JSON.stringify(body));
+        req._body = true;
+      }
+      req.complete = true;
+      req.push(null);
+      markRemoteRelayLoopbackRequest(req);
+
+      const res = new ServerResponse(req);
+      res.assignSocket(socket);
+      // An HTTP server forwards its socket's drain to the response; a handler
+      // that streams its answer waits for it.
+      socket.on('drain', () => res.emit('drain'));
+      const chunks = [];
+      let total = 0;
+      let settled = false;
+      let timer = null;
+      const finish = (error, value) => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeoutImpl(timer);
+        try { res.detachSocket(socket); } catch {}
+        try { socket.destroy(); } catch {}
+        if (error) reject(error);
+        else resolve(value);
+      };
+      const collect = (chunk, encoding) => {
+        const buffer = toBuffer(chunk, encoding);
+        if (!buffer || !buffer.length) return;
+        total += buffer.length;
+        if (total <= maxBytes) chunks.push(buffer);
+      };
+      const write = res.write;
+      const end = res.end;
+      res.write = function writeCollected(chunk, encoding, callback) {
+        collect(chunk, encoding);
+        return write.call(this, chunk, encoding, callback);
+      };
+      res.end = function endCollected(chunk, encoding, callback) {
+        collect(chunk, encoding);
+        return end.call(this, chunk, encoding, callback);
+      };
+      res.once('finish', () => {
+        if (total > maxBytes) {
+          finish(new RemoteRelayError(
+            REMOTE_RELAY_ERROR_CODES.unsupported,
+            `This relay's answer is larger than ${maxBytes} bytes`,
+            { detail: 'response too large' },
+          ));
+          return;
+        }
+        finish(null, { status: res.statusCode, text: Buffer.concat(chunks).toString('utf8') });
+      });
+      res.once('error', (error) => finish(error));
+
+      if (timeoutMs > 0) {
+        timer = setTimeoutImpl(() => finish(new RemoteRelayError(
+          REMOTE_RELAY_ERROR_CODES.offline,
+          `This relay did not answer its own request within ${Math.round(timeoutMs / 100) / 10} s`,
+          { detail: 'loopback timeout' },
+        )), timeoutMs);
+        timer?.unref?.();
+      }
+
+      try {
+        handle(req, res);
+      } catch (error) {
+        finish(error);
+      }
+    });
+  }
+
+  /**
+   * One call to this relay's own API. `relay` is the dispatcher's local target
+   * (only its name is used, for messages). Resolves to the parsed JSON body
+   * (null when empty); rejects with a RemoteRelayError, like the outbound
+   * client's request.
+   */
+  async function request(relay, method, path, { body, query, hops = 0, timeoutMs } = {}) {
+    if (typeof handle !== 'function') {
+      throw new RemoteRelayError(REMOTE_RELAY_ERROR_CODES.unsupported, 'This relay cannot call its own API', { detail: 'no handler' });
+    }
+    const token = toText(getOwnToken?.());
+    if (!token) {
+      throw new RemoteRelayError(REMOTE_RELAY_ERROR_CODES.unauthorized, 'This relay has no token configured');
+    }
+    const hopCount = Number.isInteger(Number(hops)) && Number(hops) >= 0 ? Number(hops) : 0;
+    const hasBody = body !== undefined;
+    const headers = {
+      authorization: `Bearer ${token}`,
+      accept: 'application/json',
+      host: 'localhost',
+      [REMOTE_RELAY_HEADERS.origin]: toText(getOwnRelayId?.()) || 'self',
+      [REMOTE_RELAY_HEADERS.hops]: String(hopCount),
+      ...(hasBody ? { 'content-type': 'application/json' } : {}),
+    };
+    const effectiveTimeoutMs = Number.isFinite(Number(timeoutMs)) && Number(timeoutMs) > 0
+      ? Number(timeoutMs)
+      : defaultTimeoutMs;
+
+    let answer;
+    try {
+      answer = await inject({
+        method: String(method || 'GET').toUpperCase(),
+        url: buildUrl(path, query),
+        headers,
+        body,
+        hasBody,
+        timeoutMs: effectiveTimeoutMs,
+      });
+    } catch (error) {
+      if (error instanceof RemoteRelayError) throw error;
+      throw new RemoteRelayError(
+        REMOTE_RELAY_ERROR_CODES.internal,
+        `${relayLabel(relay)} failed on its own request: ${toText(error?.message || error).slice(0, 200)}`,
+        { detail: 'loopback failure' },
+      );
+    }
+
+    const status = Number(answer.status) || 0;
+    let parsed = null;
+    let json = true;
+    if (answer.text.trim()) {
+      try {
+        parsed = JSON.parse(answer.text);
+      } catch {
+        json = false;
+      }
+    }
+    if (status < 200 || status >= 300) throw remoteRelayHttpError(relay, status, parsed);
+    if (!json) {
+      throw new RemoteRelayError(
+        REMOTE_RELAY_ERROR_CODES.unsupported,
+        `${relayLabel(relay)} did not answer its own request with JSON`,
+        { status, detail: 'not json' },
+      );
+    }
+    return parsed;
+  }
+
+  return { request };
+}

package/server/services/remote-relay-registry-service.mjs

@@ -3,6 +3,7 @@
 import { randomUUID as nodeRandomUUID } from 'crypto';
 
 import {
+  AGENT_SESSIONS_SOCKET_EVENT,
   REMOTE_RELAY_LIMITS,
   REMOTE_RELAY_PERMISSIONS,
   REMOTE_RELAY_PROTOCOL,
@@ -11,6 +12,7 @@ import {
   REMOTE_RELAY_ERROR_CODES,
   checkRemoteRelayUrlPolicy,
   normalizeRemoteRelayLink,
+  normalizeRemoteRelayMaxWaitSeconds,
   normalizeRemoteRelayPermission,
 } from '../../shared/remote-relay-contract.mjs';
 import { remoteRelayAliases } from '../../shared/remote-relay-mentions.mjs';
@@ -23,6 +25,9 @@ import { remoteRelayAliases } from '../../shared/remote-relay-mentions.mjs';
 //   remote_relays                the entries, tokens included
 //   relay_public_url             how other relays reach this one
 //   remote_relay_inbound_enabled accept prompts from other relays' agents
+//   agent_sessions_enabled       this relay's own agents may start and use
+//                                sessions on it (the local target; off by default)
+//   remote_relay_max_wait_seconds the longest wait of one remote_relay call
 //
 // Tokens never leave through listPublic(), the socket event or any route; only
 // the outbound client reads them (list()/get()/resolve() are server-internal).
@@ -260,6 +265,51 @@ export function createRemoteRelayRegistry({
     return { ok: true, ...getSelfSettings() };
   }
 
+  // ─── Agent sessions ────────────────────────────────────────────────────────
+
+  /** The payload of GET /api/settings/agent-sessions and of the socket event. */
+  function getAgentSessionsSettings() {
+    const enabled = readJsonSetting(REMOTE_RELAY_SETTING_KEYS.agentSessionsEnabled);
+    return {
+      enabled: enabled === true || enabled === 1 || ['true', '1', 'on'].includes(toText(enabled).toLowerCase()),
+      maxWaitSeconds: normalizeRemoteRelayMaxWaitSeconds(readJsonSetting(REMOTE_RELAY_SETTING_KEYS.maxWaitSeconds)),
+      limits: {
+        minWaitSeconds: REMOTE_RELAY_LIMITS.waitMaxFloorSeconds,
+        maxWaitSeconds: REMOTE_RELAY_LIMITS.waitMaxCeilingSeconds,
+        stepSeconds: REMOTE_RELAY_LIMITS.waitMaxStepSeconds,
+      },
+      maxActiveSessions: REMOTE_RELAY_LIMITS.localActiveSessions,
+    };
+  }
+
+  /**
+   * `{ enabled?, maxWaitSeconds? }`. Nothing is rounded or clamped here: a
+   * value outside the range, or off the slider's step, is refused, so what the
+   * settings page shows is what was stored.
+   */
+  function setAgentSessionsSettings(patch = {}) {
+    const input = patch && typeof patch === 'object' && !Array.isArray(patch) ? patch : {};
+    if (input.enabled !== undefined && typeof input.enabled !== 'boolean') {
+      return invalid('enabled must be true or false');
+    }
+    if (input.maxWaitSeconds !== undefined) {
+      const { waitMaxFloorSeconds: min, waitMaxCeilingSeconds: max, waitMaxStepSeconds: step } = REMOTE_RELAY_LIMITS;
+      const seconds = input.maxWaitSeconds;
+      if (typeof seconds !== 'number' || !Number.isInteger(seconds) || seconds < min || seconds > max || seconds % step !== 0) {
+        return invalid(`maxWaitSeconds must be a whole number of seconds from ${min} to ${max}, in steps of ${step}`);
+      }
+    }
+    if (input.enabled !== undefined) writeJsonSetting(REMOTE_RELAY_SETTING_KEYS.agentSessionsEnabled, input.enabled);
+    if (input.maxWaitSeconds !== undefined) writeJsonSetting(REMOTE_RELAY_SETTING_KEYS.maxWaitSeconds, input.maxWaitSeconds);
+    const settings = getAgentSessionsSettings();
+    try {
+      emit(AGENT_SESSIONS_SOCKET_EVENT, settings);
+    } catch (error) {
+      logger?.warn?.(`[remote-relays] agent sessions event failed: ${error?.message || error}`);
+    }
+    return { ok: true, ...settings };
+  }
+
   // ─── Remote relays ─────────────────────────────────────────────────────────
 
   function list() {
@@ -562,6 +612,8 @@ export function createRemoteRelayRegistry({
     selfIdentity,
     getSelfSettings,
     setSelfSettings,
+    getAgentSessionsSettings,
+    setAgentSessionsSettings,
     list,
     listPublic,
     get,

package/server/services/session-worker-launch-service.mjs

@@ -160,6 +160,23 @@ export function applyGrokProviderEnvironment(env = {}, {
   return next;
 }
 
+export function applyClaudeCloudProviderEnvironment(env = {}, {
+  enabled = false,
+  model = '',
+} = {}) {
+  const next = { ...env };
+  if (resolveWorkerKind(next) === 'claude-cloud') delete next.COPILOT_WEB_RELAY_WORKER_KIND;
+  delete next.CLAUDE_CLOUD_RELAY_MODEL;
+  if (!enabled) return next;
+  // No credential is added here: the worker reads the Claude CLI's login
+  // itself. A relay that runs on CLAUDE_CODE_OAUTH_TOKEN instead has it in its
+  // own environment; workerSecretEnvVarsFor hands that to the cloud worker.
+  next.COPILOT_WEB_RELAY_WORKER_KIND = 'claude-cloud';
+  const normalizedModel = normalizeText(model);
+  if (normalizedModel) next.CLAUDE_CLOUD_RELAY_MODEL = normalizedModel;
+  return next;
+}
+
 /**
  * The Copilot SDK engine: the same `github`/`openai` providers the extension
  * serves, run as a plain Node worker against the CLI's headless runtime.
@@ -245,6 +262,10 @@ export function isGrokWorkerEnvironment(env = {}) {
   return resolveWorkerKind(env) === 'grok';
 }
 
+export function isClaudeCloudWorkerEnvironment(env = {}) {
+  return resolveWorkerKind(env) === 'claude-cloud';
+}
+
 export function isCopilotSdkWorkerEnvironment(env = {}) {
   return resolveWorkerKind(env) === 'copilot-sdk';
 }
@@ -279,6 +300,16 @@ export function resolveGrokWorkerScriptPath(env = {}) {
   return path.join(process.cwd(), 'server', 'grok-worker', 'grok-session-worker.mjs');
 }
 
+export function resolveClaudeCloudWorkerScriptPath(env = {}) {
+  const explicit = normalizeText(env?.COPILOT_WEB_RELAY_CLAUDE_CLOUD_WORKER_PATH);
+  if (explicit) return explicit;
+  const repoRoot = normalizeText(env?.COPILOT_WEB_RELAY_ROOT);
+  if (repoRoot) return path.join(repoRoot, 'server', 'claude-cloud-worker', 'claude-cloud-session-worker.mjs');
+  const serverDir = normalizeText(env?.COPILOT_WEB_RELAY_SERVER_DIR);
+  if (serverDir) return path.join(serverDir, 'claude-cloud-worker', 'claude-cloud-session-worker.mjs');
+  return path.join(process.cwd(), 'server', 'claude-cloud-worker', 'claude-cloud-session-worker.mjs');
+}
+
 export function resolveCopilotSdkWorkerScriptPath(env = {}) {
   const explicit = normalizeText(env?.COPILOT_WEB_RELAY_COPILOT_SDK_WORKER_PATH);
   if (explicit) return explicit;
@@ -293,11 +324,16 @@ export function resolveCopilotSdkWorkerScriptPath(env = {}) {
 // `copilot` kind is intentionally absent: that is the extension engine, whose
 // launch path (the real TUI under a `script` pseudo-TTY) must stay exactly
 // as-is. `copilot-sdk` is the SAME provider on the headless SDK engine, and it
-// belongs here with Claude/Cursor/Grok.
+// belongs here with Claude/Cursor/Grok. `claude-cloud` is a provider of its
+// own: its worker follows a session in Anthropic's cloud and runs no CLI.
 const NODE_WORKER_DESCRIPTORS = Object.freeze({
   claude: Object.freeze({ resolveScriptPath: resolveClaudeWorkerScriptPath, windowsTitle: 'Claude Worker' }),
   cursor: Object.freeze({ resolveScriptPath: resolveCursorWorkerScriptPath, windowsTitle: 'Cursor Worker' }),
   grok: Object.freeze({ resolveScriptPath: resolveGrokWorkerScriptPath, windowsTitle: 'Grok Worker' }),
+  'claude-cloud': Object.freeze({
+    resolveScriptPath: resolveClaudeCloudWorkerScriptPath,
+    windowsTitle: 'Claude Cloud Worker',
+  }),
   'copilot-sdk': Object.freeze({
     resolveScriptPath: resolveCopilotSdkWorkerScriptPath,
     windowsTitle: 'Copilot SDK Worker',
@@ -472,14 +508,38 @@ export function getTmuxPanePid(sessionName, {
   }
 }
 
-export const WORKER_SECRET_ENV_VARS = Object.freeze(['COPILOT_PROVIDER_API_KEY', 'CURSOR_API_KEY']);
+export const WORKER_SECRET_ENV_VARS = Object.freeze(['COPILOT_PROVIDER_API_KEY', 'CURSOR_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN']);
+
+// Secrets that are not every worker's. The two API keys are put into the
+// launch environment by their own provider's applier and cleared for every
+// other one, so they need no entry. The Claude login token is different: it
+// sits in the relay's own environment (a relay run on CLAUDE_CODE_OAUTH_TOKEN
+// instead of the CLI's credentials file), so it would otherwise travel with
+// every launch. Only the Claude Cloud worker gets it: its cloud client reads
+// the login from there exactly as the relay's does (credentials.mjs).
+const WORKER_SECRET_ENV_VAR_KINDS = Object.freeze({
+  CLAUDE_CODE_OAUTH_TOKEN: Object.freeze(['claude-cloud']),
+});
+
+/**
+ * The secret variables the worker of this launch environment is handed, and
+ * only through the secret env file: never as a tmux `export`, never in the
+ * environment tmux itself is started with.
+ */
+export function workerSecretEnvVarsFor(env = {}) {
+  const kind = resolveWorkerKind(env);
+  return WORKER_SECRET_ENV_VARS.filter((key) => {
+    const kinds = WORKER_SECRET_ENV_VAR_KINDS[key];
+    return !kinds || kinds.includes(kind);
+  });
+}
 
 export function createWorkerSecretEnvFile(env = {}, {
   fsImpl = fs,
   tempRoot = os.tmpdir(),
 } = {}) {
   const secretLines = [];
-  for (const key of WORKER_SECRET_ENV_VARS) {
+  for (const key of workerSecretEnvVarsFor(env)) {
     const value = String(env?.[key] || '').trim();
     if (!value) continue;
     secretLines.push(`export ${key}=${shellQuote(value)}\n`);
@@ -555,7 +615,7 @@ export function buildTmuxWorkerShellCommand(targetSessionId, env = {}, {
     ...env,
     SESSION_ID: String(targetSessionId || '').trim() || String(env?.SESSION_ID || '').trim(),
   };
-  const hasSecretEnvValue = WORKER_SECRET_ENV_VARS
+  const hasSecretEnvValue = workerSecretEnvVarsFor(launchEnv)
     .some((key) => String(launchEnv[key] || '').trim());
   const normalizedSecretEnvFilePath = String(secretEnvFilePath || '').trim();
   if (hasSecretEnvValue && !normalizedSecretEnvFilePath) {
@@ -602,6 +662,16 @@ export function buildTmuxWorkerShellCommand(targetSessionId, env = {}, {
     // counterpart, has always been on this list.
     'CLAUDE_CODE_EXECUTABLE',
     'CLAUDE_RELAY_MODEL',
+    // The Claude Cloud worker's model. Its login is not listed here: the
+    // worker reads the CLI's credentials file (CLAUDE_CONFIG_DIR above tells
+    // it where), and a relay-level CLAUDE_CODE_OAUTH_TOKEN is a secret
+    // (workerSecretEnvVarsFor), so it comes through the secret file.
+    'CLAUDE_CLOUD_RELAY_MODEL',
+    // Tests point the relay's cloud client at a fake API on this machine;
+    // the worker's client has to follow, or the relay would talk to the fake
+    // and its worker to the real API. Not a secret, and harmless as a value:
+    // shared/claude-cloud/base-url.mjs ignores everything but a loopback URL.
+    'OAR_CLAUDE_CLOUD_API_BASE_URL',
     'CURSOR_RELAY_MODEL',
     'CURSOR_AGENT_STORE_DIR',
     'GROK_RELAY_MODEL',
@@ -688,10 +758,30 @@ export async function launchSessionCli({
   // Windows console launch: resolves (and rotates) the worker log the worker
   // then writes itself; returns its path or null.
   prepareWorkerLogFileImpl = prepareWorkerLogFile,
+  // Told when the process list could not be read (the error); the launch
+  // goes on without it.
+  onProcessListError = null,
 } = {}) {
   const target = String(targetSessionId || '').trim();
   if (!target) throw new Error('missing-target-session-id');
 
+  // On win32 the process list comes from PowerShell and can be unreadable for
+  // a reason that has nothing to do with this session (2026-10-01: a control
+  // byte in another process's command line, for an hour). A launch is not
+  // stopped by that: an unreadable list counts as "no process found".
+  // The asynchronous finder reads the list off the relay's thread (shared
+  // between concurrent callers, cached for a moment); `fresh` is for the poll
+  // that waits for the process this launch just started.
+  const findLiveProcess = async ({ fresh = false } = {}) => {
+    if (typeof processInspector?.findProcessForSessionAsync !== 'function') return null;
+    try {
+      return (await processInspector.findProcessForSessionAsync(target, { fresh })) || null;
+    } catch (error) {
+      try { onProcessListError?.(error); } catch {}
+      return null;
+    }
+  };
+
   // Kill switch for test/e2e servers: a relay started with this env var must
   // never spawn real session workers (Copilot CLI clients or Claude workers).
   if (String(env?.COPILOT_WEB_RELAY_DISABLE_CLI_SPAWN || '').trim()) {
@@ -699,9 +789,7 @@ export async function launchSessionCli({
   }
 
   if (allowProcessReuse) {
-    const liveProcess = typeof processInspector?.findProcessForSession === 'function'
-      ? processInspector.findProcessForSession(target)
-      : null;
+    const liveProcess = await findLiveProcess();
     const liveProcessPid = parsePositiveInt(liveProcess?.processId);
     if (liveProcessPid && isPidAlive(liveProcessPid)) {
       return {
@@ -741,8 +829,9 @@ export async function launchSessionCli({
     const tmuxEnv = { ...launchSessionEnv };
     delete tmuxEnv.TMUX;
     delete tmuxEnv.TMUX_PANE;
-    delete tmuxEnv.COPILOT_PROVIDER_API_KEY;
-    delete tmuxEnv.CURSOR_API_KEY;
+    // What the secret file carries is in no environment tmux is started with
+    // (a tmux server started by this call would keep it as its global one).
+    for (const key of workerSecretEnvVarsFor(launchSessionEnv)) delete tmuxEnv[key];
     if (allowProcessReuse) {
       const existingPanePid = getTmuxPanePid(sessionName, { execFileSyncImpl });
       if (existingPanePid && isPidAlive(existingPanePid)) {
@@ -785,9 +874,7 @@ export async function launchSessionCli({
     const attempts = Math.max(1, Number(tmuxPollAttempts) || 1);
     for (let index = 0; index < attempts; index += 1) {
       await sleep(Math.max(50, Number(tmuxPollDelayMs) || 200));
-      const processMatch = typeof processInspector?.findProcessForSession === 'function'
-        ? processInspector.findProcessForSession(target)
-        : null;
+      const processMatch = await findLiveProcess({ fresh: true });
       if (processMatch?.processId) {
         return {
           pid: Number(processMatch.processId),
@@ -886,9 +973,7 @@ export async function launchSessionCli({
     const attempts = Math.max(1, Number(detachedPollAttempts) || 1);
     for (let index = 0; index < attempts; index += 1) {
       await sleep(Math.max(50, Number(detachedPollDelayMs) || 200));
-      const processMatch = typeof processInspector?.findProcessForSession === 'function'
-        ? processInspector.findProcessForSession(target)
-        : null;
+      const processMatch = await findLiveProcess({ fresh: true });
       const processPid = parsePositiveInt(processMatch?.processId);
       if (processPid && isPidAlive(processPid)) {
         return {