@oar-sh/oar 0.9.19 → 0.9.21

package/server/services/worker-replacement.mjs

@@ -0,0 +1,197 @@
+/**
+ * Replacing a session's worker: the stop and the launch that the Claude
+ * billing swap (claude-billing-swap-service.mjs) and the worker recycle
+ * (worker-recycle-service.mjs) share, and the predicate both use to tell
+ * whether a worker may be replaced now.
+ *
+ * The stop is the kill route's: nothing may start the session while it is
+ * stopped, every process of the session must be gone before it counts as
+ * stopped, and only then is the registry entry dropped. The launch never
+ * reuses a live process, so two CLIs never share a session's transcript.
+ * The fence keeps the deliveries away from the process being replaced for the
+ * whole of it (createWorkerReplacementFence).
+ */
+
+import { stopSessionWorkerProcesses as defaultStopSessionWorkerProcesses } from './session-worker-stop-service.mjs';
+
+/**
+ * What keeps a worker from being replaced now: null when nothing does, else
+ * 'turn', 'question', 'compaction' or 'background'. From the steering
+ * snapshot its heartbeat sends; a worker too old to say `releasable` is read
+ * from the rest of it.
+ */
+export function workerReleaseHold(worker) {
+  if (!worker) return null;
+  const steering = worker.steering || null;
+  if (steering && typeof steering.releasable === 'boolean') {
+    return steering.releasable ? null : (steering.releaseHold || 'turn');
+  }
+  if (steering) {
+    if (steering.holdReason === 'question') return 'question';
+    if (steering.holdReason === 'compaction') return 'compaction';
+    if (steering.turnActive) return 'turn';
+    if (steering.autoCompactWindow?.backgroundWork) return 'background';
+    return null;
+  }
+  return String(worker.status || '') === 'processing' ? 'turn' : null;
+}
+
+function toFencePid(value) {
+  const pid = Number(value);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+/**
+ * The replacement fence: while a worker process is being replaced, no work
+ * is handed to it.
+ *
+ * The killed marker the stop sets does not do this. It lapses after the
+ * supervisor's short kill grace (a stop that verifies every process gone can
+ * take longer), and any path that relaunches a session lifts it at once
+ * (`clearRestartSchedule({ resetKilledMarker: true })`, the delivery's own
+ * fallback restart among them), after which a delivery would start a turn on
+ * the very process being killed. The fence is its own structure, so nothing
+ * that resets the supervisor's lifecycle state touches it.
+ *
+ * Keyed by session and the pid being replaced: the new worker has another
+ * pid and is never fenced, so it takes the work that waited meanwhile. A
+ * request that names no pid cannot be told from the old process and is
+ * refused while the session's fence is up.
+ *
+ * - `hold(sid, pid)`: raise the fence for that process of the session.
+ * - `isHeld(sid, pid)`: true while the fence is up for that pid (or for any
+ *   pid of the session, when `pid` is unknown).
+ * - `release(sid, pid?)`: lower it; with a pid, only if that is the fenced
+ *   one, so a late release from an older replacement never lifts a newer one.
+ */
+export function createWorkerReplacementFence() {
+  const held = new Map();
+
+  function key(sid) {
+    return String(sid || '').trim();
+  }
+
+  function hold(sid, pid) {
+    const sessionId = key(sid);
+    if (!sessionId) return false;
+    held.set(sessionId, toFencePid(pid));
+    return true;
+  }
+
+  function isHeld(sid, pid = null) {
+    const sessionId = key(sid);
+    if (!sessionId || !held.has(sessionId)) return false;
+    const fencedPid = held.get(sessionId);
+    const askingPid = toFencePid(pid);
+    // An unknown pid on either side: the old process cannot be ruled out.
+    if (fencedPid === null || askingPid === null) return true;
+    return fencedPid === askingPid;
+  }
+
+  function release(sid, pid = undefined) {
+    const sessionId = key(sid);
+    if (!sessionId || !held.has(sessionId)) return false;
+    if (pid !== undefined && toFencePid(pid) !== held.get(sessionId)) return false;
+    held.delete(sessionId);
+    return true;
+  }
+
+  function list() {
+    return Array.from(held, ([sdkSessionId, pid]) => ({ sdkSessionId, pid }));
+  }
+
+  return { hold, isHeld, release, list };
+}
+
+export function createWorkerReplacement({
+  // The session worker registry: getWorker(sid), removeWorker(sid).
+  registry,
+  // The session worker supervisor: markKilled, cancelPendingStart,
+  // clearRestartSchedule, resetHealth, ensureWorker.
+  supervisor,
+  // Handed to stopSessionWorkerProcesses to find every process of a session.
+  processInspector = null,
+  // session-worker-stop-service.mjs by default; tests inject a fake so they
+  // need no processes: async ({ sdkSessionId, worker, processInspector,
+  // isPidAliveImpl, killTmuxSessionImpl }) → { ok, error?, remainingPids? }.
+  stopSessionWorkerProcesses = defaultStopSessionWorkerProcesses,
+  isProcessAlive = undefined,
+  killTmuxSession = undefined,
+  logger = console,
+  // The caller's tag for its warnings ('BILLING SWAP', 'WORKER RECYCLE'), and
+  // a function for the runtime's own log prefix, or a fixed string.
+  logPrefix = '',
+  // The replacement fence the caller raises before the stop and lowers once
+  // the launch is done (createWorkerReplacementFence). Passed in so the
+  // runtime's replacements and its delivery paths share one; this module
+  // only hands it back.
+  fence = createWorkerReplacementFence(),
+} = {}) {
+  if (typeof stopSessionWorkerProcesses !== 'function') {
+    throw new Error('createWorkerReplacement requires stopSessionWorkerProcesses');
+  }
+
+  function prefix() {
+    try {
+      return typeof logPrefix === 'function' ? String(logPrefix() || '') : String(logPrefix || '');
+    } catch {
+      return '';
+    }
+  }
+
+  /**
+   * Stop every process of the session. `{ ok: true }` once they are all gone
+   * and the registry and the supervisor's health state are cleared; else
+   * `{ ok: false, error, remainingPids }`, and the caller retries with a
+   * backoff.
+   *
+   * `keepKilled: true` is for a session that must stay stopped (an archived
+   * conversation): the killed marker set here is left in place on either
+   * outcome, as the archive route leaves it, so nothing relaunches the
+   * session meanwhile.
+   */
+  async function stopWorker(sid, { keepKilled = false } = {}) {
+    const worker = registry?.getWorker?.(sid) || null;
+    // Nothing may start the session while it is being stopped: a launch then
+    // would adopt the old process, kind and build and all.
+    supervisor?.markKilled?.(sid);
+    // A stop that fails backs off (the caller retries it). Unless the session
+    // is to stay stopped, the killed marker goes with it, so the session's
+    // worker, alive or relaunched, keeps asking for work meanwhile.
+    const backOff = (error, remainingPids = []) => {
+      if (!keepKilled) supervisor?.clearRestartSchedule?.(sid, { resetKilledMarker: true });
+      const remaining = remainingPids.length ? ` remaining=${remainingPids.join(',')}` : '';
+      const marker = keepKilled ? 'kill marker kept' : 'kill marker cleared';
+      try {
+        logger.warn?.(`${prefix()}STOP FAILED session=${String(sid).slice(0, 8)} ${error}${remaining} — ${marker}, retrying with a backoff`);
+      } catch {}
+      return { ok: false, error, remainingPids };
+    };
+    let stopped = null;
+    try {
+      await supervisor?.cancelPendingStart?.(sid, { wait: true });
+      stopped = await stopSessionWorkerProcesses({
+        sdkSessionId: sid,
+        worker,
+        processInspector,
+        isPidAliveImpl: isProcessAlive,
+        killTmuxSessionImpl: killTmuxSession,
+      });
+    } catch (error) {
+      return backOff(String(error?.message || error || 'worker-stop-failed'));
+    }
+    if (!stopped?.ok) return backOff(stopped?.error || 'worker-survived-stop', stopped?.remainingPids || []);
+    registry?.removeWorker?.(sid);
+    supervisor?.resetHealth?.(sid, { clearFailureCount: false });
+    return { ok: true };
+  }
+
+  /** Launch the session's worker, never reusing a live process: `{ ok, error }`. */
+  async function launchWorker(sid) {
+    supervisor?.clearRestartSchedule?.(sid, { resetKilledMarker: true });
+    const launched = await supervisor?.ensureWorker?.(sid, { allowProcessReuse: false });
+    return { ok: launched?.ok === true, error: launched?.error || null };
+  }
+
+  return { stopWorker, launchWorker, fence };
+}

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/build-id.mjs

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// The build id names the code a process runs, so the relay can tell a session
+// worker that started on older code from one that runs what the relay runs.
+//
+// It is `${version}+${commit.slice(0, 12)}` when both are known, the version
+// alone when there is no commit, and null when there is no version either. The
+// commit is part of it because on a git checkout a deploy is a new
+// commit at the same version; on an npm install without a `gitHead` stamp the
+// version alone decides.
+//
+// The relay and every worker compute it once at process start and never read
+// it again, so a tree that moved on under a running process still describes
+// the code that process started with.
+//
+// This module lives in shared/ because both the relay and the workers import
+// it; it depends on nothing beyond node:fs and node:path for the same reason.
+
+const COMMIT_PATTERN = /^[0-9a-f]{40}$/i;
+const COMMIT_ID_LENGTH = 12;
+
+// The relay stores the build id a worker states, so what it accepts is bounded
+// in length and limited to the characters a version and a commit use.
+const BUILD_ID_MAX_LENGTH = 80;
+const BUILD_ID_PATTERN = /^[A-Za-z0-9+._-]+$/;
+
+function readFileText(fsImpl, filePath) {
+  try {
+    return String(fsImpl.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function readPackageManifest(packageRoot, { fsImpl, pathImpl }) {
+  if (!packageRoot) return null;
+  try {
+    const manifest = JSON.parse(readFileText(fsImpl, pathImpl.join(packageRoot, 'package.json')) || '');
+    return manifest && typeof manifest === 'object' ? manifest : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The commit a git checkout has checked out, read from its .git files rather
+ * than from a `git` process: HEAD, then the loose ref, then packed-refs. A
+ * linked worktree's .git is a file naming its git dir, whose refs live in the
+ * common dir. Anything unexpected reads as null. `pathImpl` is the host's path
+ * module; tests pass path.posix and path.win32.
+ */
+export function readGitCommit(root, { fsImpl = fs, pathImpl = path } = {}) {
+  if (!root) return null;
+  const dotGit = pathImpl.join(root, '.git');
+  let gitDir = dotGit;
+  const pointer = readFileText(fsImpl, dotGit);
+  if (pointer !== null) {
+    const match = pointer.match(/^gitdir:\s*(.+)$/m);
+    if (!match) return null;
+    gitDir = pathImpl.resolve(root, match[1].trim());
+  }
+  const head = readFileText(fsImpl, pathImpl.join(gitDir, 'HEAD'));
+  if (head === null) return null;
+  const headText = head.trim();
+  if (COMMIT_PATTERN.test(headText)) return headText.toLowerCase();
+  const refMatch = headText.match(/^ref:\s*(\S+)$/);
+  if (!refMatch) return null;
+  const ref = refMatch[1];
+  const commonDirText = readFileText(fsImpl, pathImpl.join(gitDir, 'commondir'));
+  const commonDir = commonDirText ? pathImpl.resolve(gitDir, commonDirText.trim()) : gitDir;
+  for (const dir of new Set([gitDir, commonDir])) {
+    const loose = readFileText(fsImpl, pathImpl.join(dir, ...ref.split('/')));
+    if (loose && COMMIT_PATTERN.test(loose.trim())) return loose.trim().toLowerCase();
+  }
+  const packed = readFileText(fsImpl, pathImpl.join(commonDir, 'packed-refs')) || '';
+  for (const line of packed.split(/\r?\n/)) {
+    const [hash, name] = line.trim().split(/\s+/);
+    if (name === ref && COMMIT_PATTERN.test(hash || '')) return hash.toLowerCase();
+  }
+  return null;
+}
+
+/** The commit this build came from: the checkout's HEAD, else a `gitHead` stamp in package.json. */
+export function resolveBuildCommit(packageRoot, { fsImpl = fs, pathImpl = path } = {}) {
+  const fromGit = readGitCommit(packageRoot, { fsImpl, pathImpl });
+  if (fromGit) return fromGit;
+  const stamp = String(readPackageManifest(packageRoot, { fsImpl, pathImpl })?.gitHead || '').trim();
+  return COMMIT_PATTERN.test(stamp) ? stamp.toLowerCase() : null;
+}
+
+/** The package.json `version`, or null when the manifest cannot be read or names none. */
+export function readPackageVersion(packageRoot, { fsImpl = fs, pathImpl = path } = {}) {
+  const version = readPackageManifest(packageRoot, { fsImpl, pathImpl })?.version;
+  return typeof version === 'string' && version.trim() ? version.trim() : null;
+}
+
+/**
+ * The build id of the tree at `packageRoot`: `{ version, commit, id }`. Call it
+ * once at process start and keep the result; see the header for why.
+ */
+export function resolveBuildId(packageRoot, { fsImpl = fs, pathImpl = path } = {}) {
+  const version = readPackageVersion(packageRoot, { fsImpl, pathImpl });
+  const commit = resolveBuildCommit(packageRoot, { fsImpl, pathImpl });
+  let id = null;
+  if (version && commit) id = `${version}+${commit.slice(0, COMMIT_ID_LENGTH)}`;
+  else if (version) id = version;
+  return { version, commit, id };
+}
+
+/**
+ * True only when both ids are known and differ. An unknown id on either side
+ * is not evidence of a change, so it never reads as one.
+ */
+export function buildIdsDiffer(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const left = a.trim();
+  const right = b.trim();
+  return !!left && !!right && left !== right;
+}
+
+/** A stated build id, trimmed, or null when it is too long or carries other characters. */
+export function normalizeBuildId(value) {
+  if (typeof value !== 'string') return null;
+  const text = value.trim();
+  if (!text || text.length > BUILD_ID_MAX_LENGTH || !BUILD_ID_PATTERN.test(text)) return null;
+  return text;
+}

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;
   }