@oar-sh/oar 0.9.19 → 0.9.20

package/server/services/relay-restart-picture.mjs

@@ -18,13 +18,14 @@
  * detached process, a console window on Windows) and keeps its tasks when
  * the runtime exits. A restart (exit 75) is taken by the relay's own
  * supervisor or by the Copilot CLI extension, which start a new runtime;
- * the workers report back to it. A shutdown under a systemd service is
- * different: the service stops, and systemd stops every process of the
- * service, which takes the workers with it unless they live outside it (a
- * tmux session on a tmux server the user started elsewhere survives). The
- * relay cannot tell which, so they "may stop". A Claude Cloud session runs at
- * Anthropic and is never affected. `oar restart` and `oar stop` through
- * systemd do not come through here at all.
+ * the workers report back to it. Under a systemd user service the
+ * supervisor hands that restart to systemd, which stops and starts the
+ * whole service, and a shutdown stops it: systemd ends every process of the
+ * service then. The workers this relay starts there run in scopes of their
+ * own (worker-scope.mjs) and keep running; a worker on a tmux server or in a
+ * process started before 0.9.20, inside the service, may stop once. A Claude Cloud session runs at
+ * Anthropic and is never affected. `oar restart` and `oar stop` come through
+ * here too (they ask the relay); only their `--now` goes to systemd directly.
  */
 
 import fs from 'node:fs';
@@ -37,8 +38,10 @@ function toText(value) {
 
 /**
  * How this relay process is run, from its environment and argv: whether a
- * systemd service runs it, and whether an outer supervisor (the Copilot CLI
- * extension, `--supervised`) owns its restarts.
+ * systemd service runs it (`unit`: the service, `userManager`: a user's
+ * systemd runs it, not the system's), and whether an outer supervisor (the
+ * Copilot CLI extension, `--supervised`) owns its restarts. The supervisor
+ * and the runtime ask the same way.
  */
 export function detectRelayHosting({
   env = process.env,
@@ -47,20 +50,64 @@ export function detectRelayHosting({
   readCgroup = () => fs.readFileSync('/proc/self/cgroup', 'utf8'),
 } = {}) {
   // systemd sets INVOCATION_ID for the processes of a unit, and a service's
-  // cgroup ends in `.service` (a terminal's shell sits in a `.scope`).
+  // cgroup ends in `.service` (a terminal's shell sits in a `.scope`). Every
+  // process the service starts inherits INVOCATION_ID; one in a scope of its
+  // own (a session worker) is not the service.
   let systemd = false;
+  let unit = '';
+  let userManager = false;
   if (platform === 'linux' && toText(env?.INVOCATION_ID)) {
     let cgroup = '';
     try { cgroup = String(readCgroup() || ''); } catch {}
-    systemd = cgroup.split('\n').some((line) => /\.service\/?$/.test(line.trim()));
+    // The unified line (`0::/…`, the only one on cgroup v2) when it names a
+    // service, else v1's `name=systemd` hierarchy: on a hybrid host the
+    // unified line may be a bare `0::/` that says nothing. Controller lines
+    // (`10:memory:/…`) are not systemd's view: on a hybrid host they stop at
+    // `user@<uid>.service`.
+    const isService = (entry) => /\.service\/?$/.test(entry || '');
+    const lines = cgroup.split('\n').map((entry) => entry.trim());
+    const unified = lines.find((entry) => entry.startsWith('0::'));
+    const named = lines.find((entry) => /^\d+:name=systemd:/.test(entry));
+    const line = isService(unified) ? unified : isService(named) ? named : '';
+    if (line) {
+      systemd = true;
+      const cgroupPath = line.slice(line.indexOf(':', line.indexOf(':') + 1) + 1).replace(/\/$/, '');
+      unit = cgroupPath.split('/').pop();
+      userManager = /\/user@\d+\.service\//.test(cgroupPath);
+    }
   }
   const supervised = Array.isArray(argv) && argv.includes('--supervised');
-  return { systemd, supervised, platform };
+  return { systemd, supervised, platform, unit, userManager };
 }
 
-/** Whether the session workers outlive this action, and why, in one line each. */
+/**
+ * Whether the session workers outlive this action, and why, in one line each.
+ * `hosting.workerScopes`: whether this relay starts its workers in scopes of
+ * their own (worker-scope.mjs `inUse`); unset counts as no.
+ */
 export function describeRestartSurvival({ action = 'restart', hosting = {} } = {}) {
   const restart = action === 'restart';
+  // Under a user service a restart is handed to systemd, which restarts the
+  // whole service; elsewhere only the runtime is started anew.
+  const wholeService = hosting.systemd && (!restart || hosting.userManager);
+  if (wholeService && hosting.workerScopes !== true) {
+    return {
+      action: restart ? 'restart' : 'shutdown',
+      workersSurvive: false,
+      summary: `The relay runs as a systemd service: ${restart ? 'a restart restarts' : 'shutting it down stops'} the service and every process in it, `
+        + 'and this relay could not start its session workers outside it, so they and their background tasks may stop too '
+        + '(a worker in a tmux session the service did not start keeps running).',
+    };
+  }
+  if (wholeService) {
+    return {
+      action: restart ? 'restart' : 'shutdown',
+      workersSurvive: true,
+      summary: `The relay runs as a systemd service: ${restart ? 'a restart restarts' : 'shutting it down stops'} the service and every process in it. `
+        + 'Session workers this relay started run in scopes of their own and keep running, with their background tasks; '
+        + `they report back ${restart ? 'to the new relay within a minute' : 'when it starts again'}. A worker on a tmux server or in a process started before OAR 0.9.20, inside the service, may stop once.`,
+    };
+  }
   if (restart) {
     return {
       action: 'restart',
@@ -69,14 +116,6 @@ export function describeRestartSurvival({ action = 'restart', hosting = {} } = {
         + 'they report back to the new relay within a minute.',
     };
   }
-  if (hosting.systemd) {
-    return {
-      action: 'shutdown',
-      workersSurvive: false,
-      summary: 'The relay runs as a systemd service: shutting it down stops the service and every process in it, '
-        + 'so session workers and their background tasks may stop too (a worker in a tmux session the service did not start keeps running).',
-    };
-  }
   return {
     action: 'shutdown',
     workersSurvive: true,
@@ -185,6 +224,8 @@ export function createRestartPictureCollector({
   // () => [{ conversationId, description }]: tasks held since a restart.
   listHeldTasks = () => [],
   hosting = detectRelayHosting(),
+  // Whether the workers start in scopes of their own (worker-scope.mjs `inUse`).
+  workerScopes = () => false,
   providerOf = () => '',
   titleOf = undefined,
 } = {}) {
@@ -204,6 +245,10 @@ export function createRestartPictureCollector({
     try { backgroundBlockers = backgroundWorkView?.backgroundBlockers?.() || []; } catch {}
     let heldTasks = [];
     try { heldTasks = listHeldTasks() || []; } catch {}
-    return buildRestartPicture({ action, queueRows, backgroundBlockers, heldTasks, hosting, providerOf, ...(titleOf ? { titleOf } : {}) });
+    let scopes;
+    try { scopes = workerScopes(); } catch {}
+    return buildRestartPicture({
+      action, queueRows, backgroundBlockers, heldTasks, hosting: { ...hosting, workerScopes: scopes }, providerOf, ...(titleOf ? { titleOf } : {}),
+    });
   };
 }

package/server/services/remote-inbox-watch-service.mjs

@@ -0,0 +1,204 @@
+'use strict';
+
+// Paired relays' cards, watched from here: every ~20 s, even with no
+// browser open, this relay reads the Inbox of each paired relay
+// (GET /api/relay-asks/remote/inbox) and
+//
+// - tells its browsers when the set of pending remote items changed (the
+//   socket event `inbox_remote_changed`, no payload), so the sidebar badge is
+//   current without waiting for the Inbox's own poll;
+// - with a device that takes question pushes here, asks with `?push=1` and
+//   pushes a card a turn there waits on (an approval, a blocking ask_user)
+//   when that relay says this one claimed it just now (`notice: 'you'`,
+//   `claimed: 'now'`). One push per card: the card's relay pushes first,
+//   and only one paired relay ever holds the claim.
+//
+// A sweep with neither question subscribers nor a connected browser does
+// nothing. Everything here is in memory: after a restart, a card this relay
+// claimed before comes back `claimed: 'before'` and is not pushed again.
+
+import { INBOX_REMOTE_CHANGED_EVENT } from '../../shared/relay-asks.mjs';
+import { REMOTE_INBOX_CLAIMS, REMOTE_INBOX_NOTICES } from '../../shared/remote-relay-contract.mjs';
+import { RELAY_ASK_REMOTE_PATHS } from './relay-ask-link-service.mjs';
+import { PUSH_SEND_TIMEOUT_MS } from './push-dispatch-service.mjs';
+
+export const REMOTE_INBOX_CHANGED_EVENT = INBOX_REMOTE_CHANGED_EVENT;
+export const REMOTE_INBOX_WATCH_INTERVAL_MS = 20_000;
+export const REMOTE_INBOX_WATCH_JITTER_MS = 3_000;
+const REQUEST_TIMEOUT_MS = 5_000;
+const CONCURRENCY = 4;
+// Pushes per paired relay and sweep; the rest go on the next sweep.
+const PUSHES_PER_RELAY = 3;
+// Registry states that mean "do not even try" (as for the Inbox).
+const UNREACHABLE_STATES = new Set(['offline', 'unauthorized']);
+const PUSHED_KINDS = new Set(['approval', 'ask_user']);
+// A sweep waits this long for one push at most: a push that never settles
+// must not hold the sweep, and with it every later one (the next is
+// scheduled when a sweep ends). The send itself fails after its own timeout.
+const PUSH_WAIT_MS = PUSH_SEND_TIMEOUT_MS + 5_000;
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+/**
+ * @param {object} options
+ * @param {{ list: () => object[] }} options.registry the pairings
+ * @param {{ request: Function }} options.client calls a paired relay
+ * @param {{ hasQuestionSubscribers: () => boolean, notifyRemoteCard: Function }} options.push
+ * @param {() => boolean} options.hasSockets a browser is connected here
+ * @param {(event: string) => void} options.emit to every browser
+ */
+export function createRemoteInboxWatchService({
+  registry,
+  client,
+  push,
+  hasSockets = () => false,
+  emit = () => {},
+  logger = console,
+  intervalMs = REMOTE_INBOX_WATCH_INTERVAL_MS,
+  jitterMs = REMOTE_INBOX_WATCH_JITTER_MS,
+  random = Math.random,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  pushWaitMs = PUSH_WAIT_MS,
+} = {}) {
+  // `${relayId}:${id}` of the pending items each paired relay listed last.
+  let lastPending = null;
+  const pendingByRelay = new Map();
+  // Cards pushed from here, and cards claimed here but held back by the cap.
+  const pushed = new Set();
+  const deferred = new Set();
+  let timer = null;
+  let running = false;
+  let stopped = true;
+  // Each start() begins a new timer chain; a tick of an older one (a sweep
+  // still running across stop() and start()) schedules nothing.
+  let generation = 0;
+
+  function safe(fn, fallback) {
+    try {
+      return fn();
+    } catch {
+      return fallback;
+    }
+  }
+
+  async function readRelay(relay, withPush) {
+    const path = `${RELAY_ASK_REMOTE_PATHS.inbox}${withPush ? '?push=1' : ''}`;
+    try {
+      const response = await client.request(relay, 'GET', path, { timeoutMs: REQUEST_TIMEOUT_MS });
+      return Array.isArray(response?.items) ? response.items : [];
+    } catch {
+      return null;
+    }
+  }
+
+  async function pushCards(relay, items) {
+    let sent = 0;
+    for (const item of items) {
+      if (toText(item?.status) !== 'pending' || !PUSHED_KINDS.has(toText(item?.kind))) continue;
+      if (item.notice !== REMOTE_INBOX_NOTICES.you) continue;
+      const key = `${relay.id}:${toText(item.id)}`;
+      if (pushed.has(key)) continue;
+      // Claimed by this request, or claimed earlier and held back by the cap.
+      if (item.claimed !== REMOTE_INBOX_CLAIMS.now && !deferred.has(key)) continue;
+      if (sent >= PUSHES_PER_RELAY) {
+        deferred.add(key);
+        continue;
+      }
+      sent += 1;
+      pushed.add(key);
+      deferred.delete(key);
+      let waitTimer = null;
+      try {
+        await Promise.race([
+          Promise.resolve().then(() => push.notifyRemoteCard({ relay, item })),
+          new Promise((_resolve, reject) => {
+            waitTimer = setTimer(() => reject(new Error(`no answer from the push service in ${Math.round(pushWaitMs / 1000)} s`)), pushWaitMs);
+            waitTimer?.unref?.();
+          }),
+        ]);
+      } catch (error) {
+        try { logger?.warn?.(`[remote-inbox] push for relay ${toText(relay.name) || relay.id} failed: ${error?.message || error}`); } catch {}
+      } finally {
+        if (waitTimer) clearTimer(waitTimer);
+      }
+    }
+  }
+
+  /** One sweep; resolves `{ skipped }` or `{ changed, relays }`. */
+  async function sweep() {
+    const withPush = safe(() => push?.hasQuestionSubscribers?.() === true, false);
+    if (!withPush && !safe(() => hasSockets() === true, false)) return { skipped: true };
+    const relays = safe(() => registry.list() || [], [])
+      .filter((relay) => relay?.id && !UNREACHABLE_STATES.has(toText(relay.lastStatus).toLowerCase()));
+    const listed = new Set(relays.map((relay) => relay.id));
+    for (const id of pendingByRelay.keys()) {
+      if (!listed.has(id)) pendingByRelay.delete(id);
+    }
+    const queue = [...relays];
+    async function worker() {
+      while (queue.length) {
+        const relay = queue.shift();
+        const items = await readRelay(relay, withPush);
+        // A relay that did not answer keeps what it listed last.
+        if (!items) continue;
+        const pending = items.filter((item) => toText(item?.status) === 'pending' && toText(item?.id));
+        const keys = new Set(pending.map((item) => `${relay.id}:${toText(item.id)}`));
+        pendingByRelay.set(relay.id, keys);
+        for (const key of [...pushed, ...deferred]) {
+          if (key.startsWith(`${relay.id}:`) && !keys.has(key)) {
+            pushed.delete(key);
+            deferred.delete(key);
+          }
+        }
+        if (withPush) await pushCards(relay, pending);
+      }
+    }
+    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, queue.length) }, worker));
+    const now = new Set([...pendingByRelay.values()].flatMap((keys) => [...keys]));
+    const changed = lastPending === null
+      ? now.size > 0
+      : now.size !== lastPending.size || [...now].some((key) => !lastPending.has(key));
+    lastPending = now;
+    if (changed) safe(() => emit(REMOTE_INBOX_CHANGED_EVENT), null);
+    return { changed, relays: relays.length };
+  }
+
+  function schedule(chain) {
+    if (stopped || chain !== generation) return;
+    const delay = Math.max(1_000, intervalMs + Math.round((random() * 2 - 1) * jitterMs));
+    timer = setTimer(async () => {
+      if (chain !== generation) return;
+      timer = null;
+      if (!running) {
+        running = true;
+        try {
+          await sweep();
+        } catch (error) {
+          try { logger?.warn?.(`[remote-inbox] sweep failed: ${error?.message || error}`); } catch {}
+        } finally {
+          running = false;
+        }
+      }
+      schedule(chain);
+    }, delay);
+    timer?.unref?.();
+  }
+
+  function start() {
+    if (!stopped) return;
+    stopped = false;
+    generation += 1;
+    schedule(generation);
+  }
+
+  function stop() {
+    stopped = true;
+    if (timer) clearTimer(timer);
+    timer = null;
+  }
+
+  return { start, stop, sweep };
+}

package/server/services/remote-relay-caller-context.mjs

@@ -4,6 +4,7 @@ import { randomUUID as nodeRandomUUID } from 'crypto';
 
 import {
   REMOTE_RELAY_APPROVAL_SOURCE,
+  REMOTE_RELAY_APPROVAL_SUMMARY_MAX,
   REMOTE_RELAY_ERROR_CODES,
   REMOTE_RELAY_PROVIDERS,
 } from '../../shared/remote-relay-contract.mjs';
@@ -103,15 +104,19 @@ const APPROVAL_VERBS = Object.freeze({
 
 /**
  * How the remote turn would run, as far as this relay knows it: the mode (the
- * requested one, else the calling session's, which the dispatcher passes on),
+ * requested one; for a new session else the calling session's, which the
+ * dispatcher passes on; a send without one leaves the target's own),
  * the provider a new session gets (requested, else the caller's), the model
  * and working directory when the agent asked for them, and the session group
  * a new session goes into (`group`, as the target resolved it).
  */
 function describeRemoteTurn(action, args, caller, group = null) {
   const parts = [];
-  const mode = toText(args.mode).toLowerCase() || toText(caller?.mode).toLowerCase();
+  const planOnly = action === 'create_session' && args.planOnly === true;
+  const mode = toText(args.mode).toLowerCase()
+    || (action === 'create_session' ? (planOnly ? 'plan' : toText(caller?.mode).toLowerCase()) : '');
   if (mode) parts.push(`Mode: ${mode}`);
+  if (planOnly) parts.push('Plan only');
   if (action === 'create_session') {
     const requested = toText(args.provider).toLowerCase();
     const callerProvider = toText(caller?.provider).toLowerCase();
@@ -147,6 +152,7 @@ function describeSettingsChange(args) {
   if (typeof args.thinking_enabled === 'boolean') parts.push(`Thinking: ${args.thinking_enabled ? 'on' : 'off'}`);
   if (toText(args.thinking_display)) parts.push(`Thinking text: ${toText(args.thinking_display) === 'omitted' ? 'hidden' : 'visible'}`);
   if (toText(args.cwd)) parts.push(`Folder: ${excerpt(args.cwd)} (its CLI restarts there)`);
+  if (typeof args.planOnly === 'boolean') parts.push(`planOnly: ${args.planOnly}`);
   return parts.join(' · ');
 }
 
@@ -274,6 +280,58 @@ export function formatRemoteRelayApprovalPrompt({ relay, action, args = {}, call
   return lines.join('\n\n');
 }
 
+// A name inside a summary line: short, so the line keeps its point.
+const SUMMARY_NAME_MAX = 60;
+
+function summaryName(value) {
+  const text = toText(value).replace(/\s+/g, ' ');
+  return text.length > SUMMARY_NAME_MAX ? `${text.slice(0, SUMMARY_NAME_MAX - 1)}…` : text;
+}
+
+/**
+ * What an approval card is about, for another relay's Inbox and push:
+ * `{ variant, summary }`. The summary names the kind, the
+ * requesting session and the reason (titles, a model, counts), never the
+ * prompt, the answer or the question the agent would send: those stay on
+ * this relay, in the card itself. Same inputs as the card text.
+ */
+export function formatApprovalSummary({ relay, action, args = {}, caller = null, agentPrompts = 0, localSessions = false, watch = null, sessionSettings = null } = {}) {
+  const requester = `'${summaryName(caller?.title) || shortId(caller?.conversationId)}'`;
+  const by = `requested by ${requester}`;
+  const local = relay?.local === true;
+  const where = local ? 'this relay' : `relay "${summaryName(relay?.name) || 'a remote relay'}"`;
+  let variant;
+  let summary;
+  if (watch && typeof watch === 'object') {
+    variant = 'watch';
+    if (watch.kind === 'transfer') {
+      const count = Number(watch.count) || 0;
+      summary = `Take over ${count} event subscription${count === 1 ? '' : 's'} ${by}`;
+    } else {
+      const count = Array.isArray(watch.sessions) ? watch.sessions.length : 0;
+      summary = `Watch ${watch.all ? 'ALL sessions' : `${count} session${count === 1 ? '' : 's'}`} ${by}`;
+    }
+  } else if (sessionSettings && typeof sessionSettings === 'object') {
+    variant = 'session_settings';
+    summary = `Change settings of '${summaryName(sessionSettings.title) || shortId(sessionSettings.session || args.session)}' ${by}`;
+  } else if (agentPrompts > 0) {
+    variant = 'loop_guard';
+    summary = `Loop guard: ${agentPrompts} prompts by ${requester}`;
+  } else if (localSessions) {
+    variant = 'local_sessions';
+    summary = `Start sessions on this relay ${by}`;
+  } else if (action === 'create_session') {
+    variant = 'create_session';
+    const details = [summaryName(args.title), summaryName(args.model)].filter(Boolean).join(', ');
+    summary = `New session ${by}${details ? `: ${details}` : ''}`;
+  } else {
+    variant = 'write';
+    const verb = APPROVAL_VERBS[action] || toText(action).replace(/_/g, ' ') || 'act';
+    summary = `${verb.charAt(0).toUpperCase()}${verb.slice(1)} on ${where} ${by}`;
+  }
+  return { variant, summary: summary.slice(0, REMOTE_RELAY_APPROVAL_SUMMARY_MAX) };
+}
+
 export function createRemoteRelayCallerContext({
   db,
   repository,
@@ -292,8 +350,12 @@ export function createRemoteRelayCallerContext({
   questionTimeoutMs = DEFAULT_QUESTION_TIMEOUT_MS,
 } = {}) {
   const questionStatements = questions || createQuestionRepository(db);
+  // Plan-only (migration 0035): NULL on a schema without it.
+  const conversationsHavePlanOnly = db.prepare(`PRAGMA table_info(conversations)`).all()
+    .some((column) => column.name === 'plan_only');
   const getConversation = db.prepare(`
-    SELECT id, title, preferred_relay_mode, preferred_model, preferred_reasoning_effort FROM conversations WHERE id = ?
+    SELECT id, title, preferred_relay_mode, preferred_model, preferred_reasoning_effort,
+      ${conversationsHavePlanOnly ? 'plan_only' : 'NULL AS plan_only'} FROM conversations WHERE id = ?
   `);
   const getRuntimeSession = db.prepare(`SELECT provider_type, provider_model, model FROM runtime_sessions WHERE conversation_id = ?`);
   const listProcessingRows = db.prepare(`
@@ -360,9 +422,10 @@ export function createRemoteRelayCallerContext({
   }
 
   /**
-   * `{ conversationId, title, provider, model, effort, mode, processingRowId,
-   * attemptId, userMessageId, hops, originRelayIds }` for the conversation
-   * making the call.
+   * `{ conversationId, title, provider, model, effort, mode, planOnly,
+   * processingRowId, attemptId, userMessageId, hops, originRelayIds }` for the
+   * conversation making the call. A plan-only conversation's `mode` is its
+   * saved one, not its live turn's.
    * `effort` is the reasoning effort of the live turn, else the one the
    * conversation prefers ('' when neither is known).
    * `hops` is how many relays the current turn's prompt already crossed: 0
@@ -388,13 +451,21 @@ export function createRemoteRelayCallerContext({
     const originRelayIds = [...new Set(origins.map((origin) => toText(origin.relayId)))];
     // The prompt with the most hops: what a schedule of this turn's passes on.
     const origin = origins.reduce((best, entry) => (!best || originHops(entry) > originHops(best) ? entry : best), null);
+    const planOnly = Number(conversation?.plan_only) === 1;
     return {
       conversationId: id,
       title: toText(conversation?.title),
       provider: toText(runtime?.provider_type).toLowerCase() || 'github',
       model: toText(live?.model) || toText(runtime?.provider_model) || toText(runtime?.model) || toText(conversation?.preferred_model) || '',
       effort: (toText(live?.reasoning_effort) || toText(conversation?.preferred_reasoning_effort)).toLowerCase(),
-      mode: normalizeMode(live?.relay_mode || conversation?.preferred_relay_mode),
+      // A plan-only conversation's mode is its saved one (plan): the one write
+      // turn of "Approve plan" runs in agent mode, and what it starts or sends
+      // must not pass for an agent-mode caller's (an agent session by default,
+      // no approval card).
+      mode: normalizeMode(planOnly
+        ? (conversation?.preferred_relay_mode || live?.relay_mode)
+        : (live?.relay_mode || conversation?.preferred_relay_mode)),
+      planOnly,
       processingRowId: live?.id || null,
       attemptId: toText(live?.attempt_id) || null,
       userMessageId: live?.id || null,
@@ -474,6 +545,8 @@ export function createRemoteRelayCallerContext({
       conversationId: toText(conversationId) || row.conversation_id,
       relayMode,
       header: watch ? WATCH_HEADER : (localSessions || (sessionSettings && local) ? LOCAL_SESSIONS_HEADER : APPROVAL_HEADER),
+      // What a paired relay's Inbox and push show of this card.
+      ...formatApprovalSummary({ relay, action, args, caller: callerContext, agentPrompts, localSessions, watch, sessionSettings }),
     }, { normalizeRelayMode: normalizeMode, defaultRelayMode });
     questionStatements.insertQuestion.run(
       questionId,

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

@@ -31,6 +31,7 @@ import {
   withRemotePromptHeader,
 } from '../../shared/remote-relay-contract.mjs';
 import { schemaFields } from '../../shared/question-schema.mjs';
+import { PLAN_ONLY_ERROR_CODE, planOnlyRefusesMode } from '../../shared/plan-only.mjs';
 import { matchQuestionChoice } from '../../shared/question-answer-rule.mjs';
 import { ANSWERED_ELSEWHERE_KIND } from '../../shared/steer-settle-markers.mjs';
 import { RELAY_EVENT_DEFAULT_TYPES, RELAY_EVENT_RELAY_LEVEL_TYPES } from '../../shared/relay-events.mjs';
@@ -1540,6 +1541,8 @@ export function createRemoteRelayDispatcher({
       ...(createdBy && ctx?.relay?.local && createdBy === ctx.conversationId ? { startedByYou: true } : {}),
       // The owner let this agent-started session's agents start sessions.
       ...(row?.mayCreateSessions === true ? { mayCreateSessions: true } : {}),
+      // Agents cannot take it out of plan mode.
+      ...(row?.planOnly === true ? { planOnly: true } : {}),
       // The session group it sits in (sessions an agent started here are
       // grouped under that agent's session; the owner can group by hand).
       ...sessionGroupField(row, groups),
@@ -1794,6 +1797,7 @@ export function createRemoteRelayDispatcher({
         ...sessionActivityFields(conversation, { console: true }),
         ...(via ? { via } : {}),
         ...(conversation?.mayCreateSessions === true ? { mayCreateSessions: true } : {}),
+        ...(conversation?.planOnly === true ? { planOnly: true } : {}),
         ...(group ? { group } : {}),
         openUrl: remoteConversationUrl(ctx.relay.url, conversationId) || null,
       },
@@ -2148,7 +2152,8 @@ export function createRemoteRelayDispatcher({
     // Grok pins its model at bootstrap and refuses any other, so it gets none.
     const model = requestedModel
       || (provider === 'grok' ? '' : (toText(conversation?.preferredModel) || toText(runtime.providerModel) || toText(runtime.model)));
-    const mode = args.mode || ctx.caller.mode || toText(conversation?.preferredRelayMode) || '';
+    // Only a mode the agent names: without one the target runs in its own.
+    const mode = toText(args.mode);
     // The remote runs a prompt that names no effort with its provider's
     // default, not with the one the session is set to: pass that one on, so
     // the session keeps its own. This session's effort is never mirrored here.
@@ -2296,7 +2301,14 @@ export function createRemoteRelayDispatcher({
         note = `${provider} on relay "${ctx.relay.name}" does not offer ${ctx.caller.model}; the session uses its default model ${model || '(none)'}.`;
       }
     }
-    const mode = args.mode || ctx.caller.mode || toText(catalog.status.defaultRelayMode) || '';
+    // planOnly starts the session locked in plan mode: with no mode named it
+    // starts in plan; another mode named is refused before anything is made.
+    const planOnly = args.planOnly === true || toText(args.planOnly).toLowerCase() === 'true';
+    if (planOnly && planOnlyRefusesMode(args.mode)) {
+      throw new DispatchFailure(400, REMOTE_RELAY_ERROR_CODES.invalidInput,
+        `planOnly keeps a session in plan mode; it cannot start in ${toText(args.mode)} mode. Leave mode out or name "plan". No session was created.`);
+    }
+    const mode = args.mode || (planOnly ? 'plan' : ctx.caller.mode) || toText(catalog.status.defaultRelayMode) || '';
     const title = args.title || firstLine(args.text, TITLE_MAX) || 'Remote session';
     const origin = await buildOrigin(ctx);
 
@@ -2327,6 +2339,7 @@ export function createRemoteRelayDispatcher({
         providerType: provider,
         ...(model ? { model } : {}),
         ...(mode ? { relayMode: mode } : {}),
+        ...(planOnly ? { planOnly: true } : {}),
         ...(effort ? { reasoningEffort: effort } : {}),
         title,
         ...(args.cwd ? { cwd: args.cwd } : {}),
@@ -2372,6 +2385,11 @@ export function createRemoteRelayDispatcher({
     } else if (args.group && (!group || (ctx.group?.id && group.id !== ctx.group.id))) {
       groupWarning = `The session was created, but not in group "${clipLine(args.group, 80)}": ${groupWhere(ctx)} put it ${group ? `in "${group.name || group.id}" (${group.id})` : 'in no group'}. Tell the user.`;
     }
+    // A relay that knows planOnly echoes it; an older one created the session
+    // without the lock (in the mode asked for).
+    const planOnlyWarning = planOnly && bootstrap?.planOnly !== true
+      ? `The session was created WITHOUT the plan-only lock: ${groupWhere(ctx)} ignored planOnly (its OAR is older and does not take it). It started in ${mode || 'its default'} mode, but agents can switch it to another mode. Tell the user.`
+      : null;
     const boundModel = toText(bootstrap?.selectedModel) || model;
     // A relay that swapped the asked model for another (one that predates
     // these checks does for Copilot) is named, never passed over in silence.
@@ -2436,14 +2454,20 @@ export function createRemoteRelayDispatcher({
         // The session group it went into, as list_sessions shows it.
         group,
         ...(groupWarning ? { groupWarning } : {}),
+        ...(planOnly ? { planOnly: bootstrap?.planOnly === true } : {}),
+        ...(planOnlyWarning ? { planOnlyWarning } : {}),
       },
     });
-    if (!groupWarning) return result;
+    if (!groupWarning && !planOnlyWarning) return result;
     // Never a plain success: the summary and the note say what is missing.
+    const missing = [
+      groupWarning ? `no group: ${groupReported ? 'not applied' : 'target too old'}` : '',
+      planOnlyWarning ? 'no plan-only lock: target too old' : '',
+    ].filter(Boolean).join('; ');
     return {
       ...result,
-      summary: `${result.summary} (no group: ${groupReported ? 'not applied' : 'target too old'})`,
-      note: [groupWarning, result.note].map(toText).filter(Boolean).join(' '),
+      summary: `${result.summary} (${missing})`,
+      note: [groupWarning, planOnlyWarning, result.note].map(toText).filter(Boolean).join(' '),
     };
   }
 
@@ -2639,6 +2663,10 @@ export function createRemoteRelayDispatcher({
     if (remoteCode === SESSION_SETTINGS_CODES.busy) {
       return failed(409, C.busy, text, { reason: toText(body.reason) || null });
     }
+    // A plan-only session: no other mode while the flag stays.
+    if (remoteCode === PLAN_ONLY_ERROR_CODE) {
+      return failed(409, PLAN_ONLY_ERROR_CODE, text, { note: 'Clear the flag in the same call (planOnly: false with the mode), or ask the user.' });
+    }
     if (remoteCode === SESSION_SETTINGS_CODES.groupNotFound || remoteCode === SESSION_SETTINGS_CODES.groupAmbiguous) {
       return failed(400, C.unknownGroup, text, {
         groups: mapGroupList(body).slice(0, REMOTE_RELAY_GROUP_LIMITS.refusalMax).map((group) => ({ id: group.id, name: group.name })),
@@ -3486,6 +3514,13 @@ export function createRemoteRelayDispatcher({
       return failure(404, C.notFound, what ? `${what} was not found on relay "${relay.name}".` : message, extra);
     }
     const remoteCode = toText(remoteBody?.code) || null;
+    // A plan-only session refused a mode the agent named.
+    if (remoteCode === PLAN_ONLY_ERROR_CODE) {
+      const session = args.session ? `Session ${args.session} on relay "${relay.name}"` : `Relay "${relay.name}"`;
+      return failure(409, PLAN_ONLY_ERROR_CODE,
+        `${session} is plan-only: agents can't switch it to another mode. Send without mode (it runs in plan), or clear planOnly with update_session first, or ask the user. Nothing was sent.`,
+        { ...extra, remoteCode });
+    }
     const supportedModels = Array.isArray(remoteBody?.supportedModels) ? remoteBody.supportedModels.slice(0, 50) : null;
     // A refused effort: the ones the remote's model takes, so the agent can pick one.
     const supportedEfforts = isEffortRejection(error) ? supportedEffortsOf(error) : [];

package/server/services/restart-resume-service.mjs

@@ -39,6 +39,8 @@
  */
 
 import { randomUUID } from 'node:crypto';
+import { resumeRelayMode } from '../../shared/plan-only.mjs';
+import { readPlanOnly } from './conversation-preferences-service.mjs';
 
 export const RESTART_RESUME_SETTING_KEY = 'restart_resume_notes';
 export const RESTART_RESUME_KIND = 'relay-restart-resume';
@@ -91,7 +93,7 @@ export function createRestartResumeService({
   if (!db || !stmts) throw new Error('createRestartResumeService requires db and stmts');
   const listProcessing = db.prepare(`
     SELECT id, conversation_id, model, model_variant_id, reasoning_effort, context_tier, relay_mode,
-           owner_sdk_session_id, runtime_session_id
+           owner_sdk_session_id, runtime_session_id, text
     FROM queue WHERE status = 'processing'
   `);
   const statusOf = db.prepare(`SELECT status FROM queue WHERE id = ?`);
@@ -212,7 +214,8 @@ export function createRestartResumeService({
     // The model and mode the interrupted turn ran with.
     const model = text(cutRow?.model) || text(latestModel) || text(runtimeSession?.provider_model) || text(runtimeSession?.model) || null;
     const modelVariant = text(cutRow?.model_variant_id) || model;
-    const relayMode = text(cutRow?.relay_mode) || 'agent';
+    // On a plan-only session only the "Approve plan" turn goes on in agent mode.
+    const relayMode = resumeRelayMode({ relayMode: cutRow?.relay_mode, text: cutRow?.text, planOnly: readPlanOnly(conversation) });
     const owner = text(cutRow?.owner_sdk_session_id) || text(runtimeSession?.sdk_session_id) || null;
     const write = db.transaction(() => {
       stmts.insertMsg.run(