@oar-sh/oar 0.9.18 → 0.9.20

package/server/services/worker-scope.mjs

@@ -0,0 +1,77 @@
+/**
+ * Session workers of a relay that a systemd user service runs start in a
+ * scope of their own (`systemd-run --user --scope`), so a stop or restart of
+ * the service, which ends every process in its cgroup (KillMode=mixed), does
+ * not take them along. A tmux server the call starts lands in that scope; a
+ * running one is only talked to. With `--scope` systemd-run executes the
+ * command in place: its process id, environment and exit stay the worker's.
+ *
+ * Whether it can is asked once per runtime, at the first worker start (or
+ * the first restart picture, which says whether the workers survive):
+ * the runtime's parent must be the unit's main process (a relay started inside
+ * a worker that still sits in the service's cgroup looks like the service,
+ * but is not it), and systemd-run must work (it needs the user bus). Anything
+ * else starts workers as before, with one log line.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+export const WORKER_SCOPE_PREFIX = Object.freeze(['--user', '--scope', '--collect', '--quiet', '--']);
+
+function failure(result) {
+  if (result?.error) return result.error.code || result.error.message || String(result.error);
+  const said = String(result?.stderr || '').trim().split('\n')[0];
+  return `status ${result?.status ?? 'none'}${said ? `: ${said}` : ''}`;
+}
+
+/**
+ * `wrap(command, args)` → `{ command, args }`: the call through systemd-run
+ * where workers get scopes of their own, else the call as it is. `hosting`
+ * is detectRelayHosting()'s answer for this runtime.
+ */
+export function createWorkerScope({
+  hosting = null,
+  spawnSyncImpl = spawnSync,
+  parentPid = process.ppid,
+  log = null,
+} = {}) {
+  let scoped = null;
+
+  const decide = () => {
+    if (!hosting?.systemd || !hosting.userManager || !hosting.unit) return false;
+    const run = (command, args) => {
+      try {
+        return spawnSyncImpl(command, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 5_000 }) || { status: null };
+      } catch (error) {
+        return { status: null, error };
+      }
+    };
+    const main = run('systemctl', ['--user', 'show', '-p', 'MainPID', '--value', hosting.unit]);
+    const mainPid = Number(String(main.stdout ?? '').trim());
+    if (main.status !== 0 || mainPid !== parentPid) {
+      log?.(`session workers start without a scope of their own: ${hosting.unit} is not this relay's service (main process ${main.status === 0 ? mainPid || 'none' : `unknown, ${failure(main)}`}, relay supervisor ${parentPid}).`);
+      return false;
+    }
+    const probe = run('systemd-run', [...WORKER_SCOPE_PREFIX, 'true']);
+    if (probe.status !== 0) {
+      log?.(`session workers start without a scope of their own (systemd-run: ${failure(probe)}); a stop or restart of ${hosting.unit} ends them.`);
+      return false;
+    }
+    log?.(`session workers start in scopes of their own (systemd-run --user --scope): they keep running through a stop or restart of ${hosting.unit}.`);
+    return true;
+  };
+
+  const inUse = () => {
+    if (scoped === null) scoped = decide();
+    return scoped;
+  };
+
+  return {
+    // Whether workers start in scopes of their own; asked once, by whichever
+    // comes first (a worker start, or a restart picture).
+    inUse,
+    wrap(command, args = []) {
+      return inUse() ? { command: 'systemd-run', args: [...WORKER_SCOPE_PREFIX, command, ...args] } : { command, args };
+    },
+  };
+}

package/shared/plan-board-actions.mjs

@@ -0,0 +1,130 @@
+/**
+ * The buttons of a `plan_ready` card, one list for every provider: the Claude,
+ * Copilot, Cursor and Grok workers post it, the CLI extension adds
+ * "Approve plan" to the Copilot CLI's own list, and the relay's action route
+ * builds the follow-up message from the same table.
+ *
+ * - `approve_only` marks the plan approved. Its follow-up runs one turn in
+ *   agent mode (plan mode blocks writes, and the plan doc still has to be
+ *   committed); the session's saved mode stays plan.
+ * - `autopilot` / `autopilot_fleet` and `interactive` leave plan mode: the
+ *   session goes on in the mode the follow-up runs in.
+ * - `exit_only` only settles the card.
+ *
+ * No follow-up carries the plan: the session wrote it, and repeating it read
+ * as a new instruction to carry it out.
+ */
+
+export const PLAN_BOARD_APPROVE_ONLY = 'approve_only';
+
+export const PLAN_BOARD_ACTIONS = Object.freeze([
+  Object.freeze({ id: 'approve_only', label: 'Approve plan', mode: 'agent' }),
+  Object.freeze({ id: 'autopilot', label: 'Implement in autopilot', mode: 'autopilot' }),
+  Object.freeze({ id: 'interactive', label: 'Stop here and prompt myself', mode: 'agent' }),
+  Object.freeze({ id: 'exit_only', label: 'Stop here', mode: 'agent' }),
+]);
+
+/** The actions that take the session out of plan mode for good. */
+export const PLAN_BOARD_LEAVES_PLAN = Object.freeze(['autopilot', 'autopilot_fleet', 'interactive']);
+
+export const PLAN_BOARD_LABELS = Object.freeze({
+  approve_only: 'Approve plan',
+  autopilot: 'Implement in autopilot',
+  autopilot_fleet: 'Implement with autopilot fleet',
+  interactive: 'Stop here and prompt myself',
+  exit_only: 'Stop here',
+});
+
+const FOLLOWUP_TEXTS = Object.freeze({
+  approve_only: 'Plan approved by the user. Do not implement. Finish only the plan-only steps you were given, then stop.',
+  autopilot: 'Please implement the approved plan now.',
+  autopilot_fleet: 'Please implement the approved plan using autopilot_fleet where useful.',
+  interactive: 'I approved the plan. Let\'s proceed interactively with implementation.',
+});
+
+const FOLLOWUP_MODES = Object.freeze({
+  approve_only: 'agent',
+  autopilot: 'autopilot',
+  autopilot_fleet: 'autopilot',
+  interactive: 'agent',
+});
+
+function actionId(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+/** Whether `id` is one of the actions this table knows. */
+export function isKnownPlanBoardAction(id) {
+  return Object.prototype.hasOwnProperty.call(PLAN_BOARD_LABELS, actionId(id));
+}
+
+/** The button's label; an id the table does not know is spelled out. */
+export function planBoardActionLabel(id) {
+  const key = actionId(id);
+  if (Object.prototype.hasOwnProperty.call(PLAN_BOARD_LABELS, key)) return PLAN_BOARD_LABELS[key];
+  return key.replace(/[_-]+/g, ' ').replace(/\b\w/g, (char) => char.toUpperCase()) || 'Select';
+}
+
+/** The message the action queues, or '' when it queues none. */
+export function planBoardFollowupText(id) {
+  const key = actionId(id);
+  return Object.prototype.hasOwnProperty.call(FOLLOWUP_TEXTS, key) ? FOLLOWUP_TEXTS[key] : '';
+}
+
+/** The relay mode the follow-up runs in, or null for an action without one. */
+export function planBoardFollowupMode(id) {
+  const key = actionId(id);
+  return Object.prototype.hasOwnProperty.call(FOLLOWUP_MODES, key) ? FOLLOWUP_MODES[key] : null;
+}
+
+/**
+ * `actions` with "Approve plan" first when it is missing. The others keep
+ * their order and their entries (a CLI's own list, a card stored before the
+ * button existed). Entries may be ids or `{ id }` objects.
+ */
+export function withApproveOnly(actions) {
+  const list = Array.isArray(actions) ? actions : [];
+  const has = list.some((entry) => actionId(typeof entry === 'string' ? entry : entry?.id) === PLAN_BOARD_APPROVE_ONLY);
+  if (has) return list.slice();
+  return [{ ...PLAN_BOARD_ACTIONS[0] }, ...list];
+}
+
+/** Whether a card is a pending plan card, the one kind "Approve plan" is added to. */
+export function isPendingPlanBoard(board) {
+  return String(board?.boardType || '').trim().toLowerCase() === 'plan_ready'
+    && (String(board?.status || 'pending').trim().toLowerCase() || 'pending') === 'pending';
+}
+
+/**
+ * The actions a card shows: a pending plan card gets "Approve plan" even when
+ * it was stored before the button existed. A settled card shows what it was
+ * stored with.
+ */
+export function planBoardShownActions(board, actions = board?.actions) {
+  return isPendingPlanBoard(board) ? withApproveOnly(actions) : (Array.isArray(actions) ? actions : []);
+}
+
+/**
+ * The card's actions from the Copilot CLI's own `exit_plan_mode` arguments
+ * (ids or `{ id | actionId | value }` entries), in the CLI's order, each id
+ * once, with "Approve plan" added. Without any, the shared list. An id the
+ * table does not know keeps no mode: pressing it only settles the card.
+ */
+export function planBoardActionsFromCli(rawActions) {
+  const ids = Array.isArray(rawActions)
+    ? rawActions
+      .map((entry) => {
+        if (typeof entry === 'string') return actionId(entry);
+        if (entry && typeof entry === 'object') return actionId(entry.id || entry.actionId || entry.value);
+        return '';
+      })
+      .filter(Boolean)
+    : [];
+  if (!ids.length) return PLAN_BOARD_ACTIONS.map((entry) => ({ ...entry }));
+  const unique = [...new Set(ids)];
+  return withApproveOnly(unique.map((id) => ({
+    id,
+    label: planBoardActionLabel(id),
+    mode: id === 'exit_only' ? 'agent' : planBoardFollowupMode(id),
+  })));
+}

package/shared/plan-only.mjs

@@ -0,0 +1,43 @@
+/**
+ * Plan-only sessions: a conversation flagged `plan_only` stays in
+ * plan mode as far as agents go. A relay_tool send or update_session that
+ * names another mode is refused with 409 and this code; the owner's own
+ * controls still change the mode, and clearing the flag frees the session.
+ * The lock protects against mistakes, not against an agent that clears it.
+ */
+
+import { planBoardFollowupMode, planBoardFollowupText } from './plan-board-actions.mjs';
+
+export const PLAN_ONLY_ERROR_CODE = 'plan_only';
+
+export const PLAN_ONLY_REFUSAL_TEXT = 'This session is plan-only; agents can\'t change its mode. Clear planOnly first, or ask the user.';
+
+export const PLAN_ONLY_REFUSAL = Object.freeze({ ok: false, code: PLAN_ONLY_ERROR_CODE, error: PLAN_ONLY_REFUSAL_TEXT });
+
+/**
+ * Whether naming `mode` is refused on a plan-only session: any mode but plan,
+ * one the relay does not know included (it must not fall back to a writing
+ * mode). No mode named refuses nothing.
+ */
+export function planOnlyRefusesMode(mode) {
+  const text = String(mode ?? '').trim().toLowerCase();
+  return !!text && text !== 'plan';
+}
+
+/**
+ * The mode a turn cut off (a usage limit, a relay restart) goes on in. As it
+ * ran, except on a plan-only session: there only the "Approve plan" turn
+ * finishes in the agent mode it ran in (the same single turn); any other
+ * goes on in plan. The session's saved mode is not touched either way.
+ * The board does not store the message it queued, so that turn is known by
+ * both its exact line and its agent mode; anything else goes on in plan.
+ */
+export function resumeRelayMode({ relayMode = '', text = '', planOnly = false } = {}) {
+  const stored = String(relayMode || '').trim().toLowerCase();
+  const mode = stored || 'agent';
+  if (!planOnly || mode === 'plan') return mode;
+  // The mode as stored: the board stores agent, never an empty one.
+  const approveTurn = stored === planBoardFollowupMode('approve_only')
+    && String(text || '').trim() === planBoardFollowupText('approve_only');
+  return approveTurn ? mode : 'plan';
+}

package/shared/relay-asks.mjs

@@ -35,6 +35,9 @@ export const RELAY_ASK_CLOSED_STATUSES = Object.freeze(['answered', 'dismissed']
 // Socket event the relay sends on every change of an ask (`{ ask }`) and
 // of the Inbox's count (`{ pending }`).
 export const RELAY_ASK_SOCKET_EVENT = 'relay_ask_updated';
+// Socket event (no payload) the relay sends when the pending items of its
+// paired relays' Inboxes changed (remote-inbox-watch-service.mjs).
+export const INBOX_REMOTE_CHANGED_EVENT = 'inbox_remote_changed';
 
 export const RELAY_ASK_LIMITS = Object.freeze({
   questionMax: 500,

package/shared/relay-events.mjs

@@ -33,6 +33,9 @@ export const RELAY_EVENT_TYPES = Object.freeze([
   'task_failed',
   'stalled',
   'all_idle',
+  // The user settled a plan card (board) of the session: its action, and the
+  // message it queued (none for exit_only).
+  'board_settled',
 ]);
 
 // Not one a subscription names in `events`: `heartbeat_minutes` turns it on.
@@ -97,6 +100,26 @@ export const RELAY_EVENT_LEGACY_DEFAULT_TYPES = Object.freeze([
   'all_idle',
 ]);
 
+// The default from subagent_finished until board_settled (0.9.19): a
+// subscription made without events then stored exactly this list, and takes
+// today's default as well. Unlike the older one, a watcher who names exactly
+// this list now gets it read as the default too (board_settled added): there
+// is no type to add beside it that changes nothing.
+export const RELAY_EVENT_PRE_BOARD_DEFAULT_TYPES = Object.freeze([
+  'question_asked',
+  'error',
+  'turn_end',
+  'subagent_finished',
+  'task_failed',
+  'stalled',
+  'all_idle',
+]);
+
+function sameTypeSet(types, reference) {
+  const unique = new Set((Array.isArray(types) ? types : []).map(toText).filter(Boolean));
+  return unique.size === reference.length && reference.every((type) => unique.has(type));
+}
+
 /**
  * The events a stored subscription takes. A list that is exactly the old
  * default (any order, no more, no less) was the default, not a choice, and
@@ -106,14 +129,14 @@ export const RELAY_EVENT_LEGACY_DEFAULT_TYPES = Object.freeze([
  */
 export function effectiveRelayEventTypes(types) {
   const list = Array.isArray(types) ? types.map(toText).filter(Boolean) : [];
-  return isLegacyDefaultRelayEventTypes(list) ? [...RELAY_EVENT_DEFAULT_TYPES] : list;
+  return isLegacyDefaultRelayEventTypes(list) || sameTypeSet(list, RELAY_EVENT_PRE_BOARD_DEFAULT_TYPES)
+    ? [...RELAY_EVENT_DEFAULT_TYPES]
+    : list;
 }
 
 /** Whether a list is exactly the old default as a set (any order, repeats ignored). */
 export function isLegacyDefaultRelayEventTypes(types) {
-  const unique = new Set((Array.isArray(types) ? types : []).map(toText).filter(Boolean));
-  return unique.size === RELAY_EVENT_LEGACY_DEFAULT_TYPES.length
-    && RELAY_EVENT_LEGACY_DEFAULT_TYPES.every((type) => unique.has(type));
+  return sameTypeSet(types, RELAY_EVENT_LEGACY_DEFAULT_TYPES);
 }
 
 /**
@@ -403,6 +426,9 @@ export function relayEventMatchText(event) {
   if (event?.type === 'task_finished' || event?.type === 'task_failed') {
     return [detail.description, detail.summary].map(toText).filter(Boolean).join('\n');
   }
+  if (event?.type === 'board_settled') {
+    return [detail.action, detail.actionLabel, detail.title].map(toText).filter(Boolean).join('\n');
+  }
   return null;
 }
 
@@ -576,6 +602,14 @@ export function formatRelayEventLine(event) {
       const what = oneLine(detail.what, 80) || 'work';
       return `${head}: no activity for ${Number.isFinite(minutes) ? minutes : '?'} min while ${what} is still running`;
     }
+    case 'board_settled': {
+      const action = oneLine(detail.action, 80);
+      const label = oneLine(detail.actionLabel, 120) || action || 'settled';
+      const ids = [action ? `action ${action}` : '', oneLine(detail.boardId, 80) ? `board_id ${oneLine(detail.boardId, 80)}` : ''].filter(Boolean);
+      // exit_only queues nothing: the session stops there.
+      ids.push(oneLine(detail.queuedMessageId, 80) ? `queued message ${oneLine(detail.queuedMessageId, 80)}` : 'nothing queued');
+      return `${head} ${quote(detail.title || 'plan card', 200)} → ${quote(label, 120)} (${ids.join(', ')})`;
+    }
     default:
       return head;
   }

package/shared/remote-relay-contract.mjs

@@ -153,6 +153,9 @@ export const REMOTE_RELAY_SESSION_SETTINGS = Object.freeze([
   'thinking_display',
   // The working directory: the session's CLI restarts there.
   'cwd',
+  // Plan-only: agents may set and clear it; set, a send or an
+  // update_session naming another mode is refused.
+  'planOnly',
 ]);
 export const REMOTE_RELAY_THINKING_DISPLAYS = THINKING_DISPLAY_MODES;
 // update_session's `group` value that takes a session out of its group (JSON
@@ -175,6 +178,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',
@@ -322,13 +336,17 @@ export const REMOTE_RELAY_TOOL_DESCRIPTION =
   + 'show the group. Agents can name an existing group when they create a session (group: an id '
   + 'or name relay_info lists, on this relay or a paired one). update_session {session, ...} sets '
   + 'another session\'s model, effort, mode, auto_compact_window, title, group (an id or name; a name '
-  + 'not there yet makes a new group; "none" takes the session out), thinking and cwd (its CLI restarts '
-  + 'there; not while it works) for its next turns without prompting it, and answers the settings and '
+  + 'not there yet makes a new group; "none" takes the session out), thinking, cwd (its CLI restarts '
+  + 'there; not while it works) and planOnly for its next turns without prompting it, and answers the settings and '
   + 'what changed. A session this conversation started may be changed freely; any other (the owner\'s, '
   + 'another agent\'s, the one that started you) needs the owner\'s Allow once per conversation and relay; '
   + 'your own conversation never. A group the owner made is never removed that way (it may stay empty). A mode '
-  + 'set so 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). Renaming and dissolving groups stay the owner\'s. An argument an action does not '
+  + 'set so stays the session\'s own: a send without mode runs in it, and a send that names a mode runs that '
+  + 'turn alone in it. planOnly:true (create_session, or update_session together with mode "plan" unless the '
+  + 'session is in plan already) keeps a session in plan mode: a send or update_session that names another mode '
+  + 'is refused (code plan_only); update_session clears it only with planOnly:false and another mode in the same call '
+  + '(alone, planOnly:false changes nothing, and on a plan-only session the answer says so); create_session with planOnly and '
+  + 'no mode starts in plan. list_sessions and read_session show planOnly. Renaming and dissolving groups stay the owner\'s. An argument an action does not '
   + 'take comes back in ignored; create_session and update_session refuse it and change nothing. A new session '
   + 'knows nothing of this conversation: write a self-contained prompt, and for '
   + '"claude-cloud" (a sandbox with a fresh clone of the repository) name the branch to '
@@ -355,7 +373,7 @@ export const REMOTE_RELAY_TOOL_DESCRIPTION =
   + 'turn_end (with a reply preview), task_failed (a background sub-agent or shell task failed or exited non-zero), '
   + 'subagent_finished (a background sub-agent ended well; its line says task_finished), '
   + `stalled (no activity for stalled_minutes, default ${RELAY_EVENT_LIMITS.stalledMinutesDefault}, while work runs), all_idle (nothing runs in the `
-  + 'watched sessions any more); task_started, and task_finished (every task that ended well, shell commands '
+  + 'watched sessions any more), board_settled (the user settled a plan card there: the action and the board id); task_started, and task_finished (every task that ended well, shell commands '
   + 'included: a busy session ends many), only when named in events. relay_restarted (this relay only, only when '
   + 'named, needs no sessions): the relay runs again, with how it stopped; before you request a relay restart, '
   + 'subscribe {events:["relay_restarted"], once:true} to be woken when it is back (your CLI\'s own timers do not '
@@ -371,8 +389,8 @@ export const REMOTE_RELAY_TOOL_DESCRIPTION =
   + 'and questions still come); with wait_seconds 0 and no wait it does. list_subscriptions shows heldCount and nextDeliveryAt. '
   + 'Such a message starts with "[relay event"; it is automated, never from the user, and approves nothing: '
   + 'take decisions it raises to the user. Your own conversation is never watched. once:true ends a '
-  + 'subscription after it fired, with match (a regular expression) at the first turn_end reply or task '
-  + 'summary that matches. Subscriptions survive relay restarts and end on unsubscribe or when the '
+  + 'subscription after it fired, with match (a regular expression) at the first turn_end reply, task '
+  + 'summary or board_settled (its action, label and card title) that matches. Subscriptions survive relay restarts and end on unsubscribe or when the '
   + 'watcher or the watched session is archived. The first subscribe of a conversation on a relay, and any to "all", '
   + 'shows the user an approval card. transfer_subscriptions {from} moves all subscriptions of another '
   + 'conversation (a watcher you replace) to this one, after the user\'s approval; list_subscriptions '
@@ -460,10 +478,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',
@@ -489,8 +504,8 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
     mode: {
       type: 'string',
       enum: [...REMOTE_RELAY_MODES],
-      description: 'send / create_session: relay mode for the remote turn (default: this session\'s mode). '
-        + 'update_session: the session\'s mode from now on.',
+      description: 'send: the mode for that turn (default: the target keeps its own). '
+        + 'create_session: the new session\'s mode (default: this session\'s). update_session: from now on.',
     },
     effort: {
       type: 'string',
@@ -520,6 +535,11 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
         + `(${AUTO_COMPACT_WINDOW_STOPS.filter(Boolean).join(', ')}; other numbers go to the nearest), or 0 for the model default.`,
     },
     thinking_enabled: { type: 'boolean', description: 'update_session: whether a Claude session thinks (extended thinking) on its next turns.' },
+    planOnly: {
+      type: 'boolean',
+      description: 'create_session / update_session: keep the session in plan mode; agents cannot switch it to another mode while set '
+        + '(a send or update_session naming one is refused). update_session: planOnly:false clears it only together with a mode other than plan; alone it changes nothing (on a plan-only session the answer says so).',
+    },
     thinking_display: {
       type: 'string',
       enum: [...THINKING_DISPLAY_MODES],
@@ -578,7 +598,7 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
     },
     match: {
       type: 'string',
-      description: 'subscribe: a regular expression (case-insensitive) a turn_end reply or a task summary must match; other events pass.',
+      description: 'subscribe: a regular expression (case-insensitive) a turn_end reply, a task summary or a board_settled (its action, label and card title) must match; other events pass.',
     },
     stalled_minutes: {
       type: 'integer',
@@ -677,7 +697,7 @@ export const REMOTE_RELAY_ACTION_ARGUMENTS = Object.freeze({
   read_task_output: Object.freeze(['session', 'task_id', 'lines']),
   wait: Object.freeze(['session', 'message_id', 'wait_seconds']),
   send: Object.freeze(['session', 'text', 'wait_seconds', 'model', 'mode', 'effort', 'if_busy', 'provider']),
-  create_session: Object.freeze(['text', 'provider', 'model', 'cwd', 'repo', 'branch', 'mode', 'effort', 'title', 'group', 'wait_seconds']),
+  create_session: Object.freeze(['text', 'provider', 'model', 'cwd', 'repo', 'branch', 'mode', 'effort', 'title', 'group', 'wait_seconds', 'planOnly']),
   update_session: Object.freeze(['session', ...REMOTE_RELAY_SESSION_SETTINGS]),
   answer_question: Object.freeze(['question_id', 'answer', 'choices']),
   stop: Object.freeze(['session']),
@@ -759,6 +779,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 +801,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 +847,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 +917,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);
@@ -920,6 +954,13 @@ function validateToolInput(input, { maxWaitSeconds, now } = {}) {
         if (!isValidBranchName(branchText)) return invalid(`branch "${branchText.slice(0, 80)}" is not a valid branch name`);
         args.branch = branchText;
       }
+      // Plan-only: kept in plan mode; false (or left out) is no lock.
+      const planOnly = input?.planOnly;
+      if (planOnly !== undefined && planOnly !== null && toText(planOnly) !== '') {
+        const flag = readBoolean(planOnly);
+        if (flag === null) return invalid('planOnly must be true or false');
+        if (flag) args.planOnly = true;
+      }
     }
   } else if (action === 'update_session') {
     const settings = validateRemoteRelaySessionSettings(input);
@@ -1008,6 +1049,12 @@ export function validateRemoteRelaySessionSettings(input) {
     if (enabled === null) return invalid('thinking_enabled must be true or false');
     values.thinking_enabled = enabled;
   }
+  const planOnly = input?.planOnly;
+  if (planOnly !== undefined && planOnly !== null && toText(planOnly) !== '') {
+    const flag = readBoolean(planOnly);
+    if (flag === null) return invalid('planOnly must be true or false');
+    values.planOnly = flag;
+  }
   const display = toText(input?.thinking_display).toLowerCase();
   if (display) {
     if (!THINKING_DISPLAY_MODES.includes(display)) return invalid(`thinking_display must be one of: ${THINKING_DISPLAY_MODES.join(', ')}`);
@@ -1245,6 +1292,36 @@ export function formatSessionGroupList(groups, max = REMOTE_RELAY_GROUP_LIMITS.r
 // a dispatcher never offers one to its agent. Defined in relay-asks.mjs.
 export { REMOTE_RELAY_APPROVAL_SOURCE };
 
+// What an approval card is about: its context carries one of these
+// as `variant`, and a `summary` of at most this many characters (kind,
+// requesting session, reason; never the prompt, answer or question text). A
+// paired relay's Inbox shows them in place of the card text it never gets.
+export const REMOTE_RELAY_APPROVAL_VARIANTS = Object.freeze([
+  'create_session', 'loop_guard', 'write', 'session_settings', 'watch', 'local_sessions',
+]);
+export const REMOTE_RELAY_APPROVAL_SUMMARY_MAX = 160;
+// Each variant's kind label, without titles: the Inbox row's head, and the
+// push body of a device whose preview preference is off.
+export const REMOTE_RELAY_APPROVAL_VARIANT_LABELS = Object.freeze({
+  create_session: 'New session',
+  loop_guard: 'Loop guard',
+  write: 'Write',
+  session_settings: 'Session settings',
+  watch: 'Watch',
+  local_sessions: 'Start sessions',
+});
+
+// Who pushes a card a turn waits on (an approval, a blocking ask_user) when a
+// paired relay that can push reads this relay's Inbox (`?push=1`): `notice`
+// on each such pending item. `here`: this relay's own push reached a device;
+// `wait`: its push is not settled yet; `you`: the caller holds the claim and
+// pushes; `other`: another paired relay holds it. With `you`, `claimed` says
+// whether this request recorded the claim (`now`, the caller pushes) or the
+// caller held it already (`before`, e.g. after the caller restarted: no
+// second push).
+export const REMOTE_INBOX_NOTICES = Object.freeze({ here: 'here', wait: 'wait', you: 'you', other: 'other' });
+export const REMOTE_INBOX_CLAIMS = Object.freeze({ now: 'now', before: 'before' });
+
 /** True for such a card: a formatted question, or a stored request envelope (both carry `context`). */
 export function isRemoteRelayApprovalQuestion(question) {
   const context = question && typeof question === 'object' ? question.context : null;