@oar-sh/oar 0.9.13 → 0.9.14

package/server/cursor-worker/cursor-session-worker.mjs

@@ -17,6 +17,7 @@ import { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-fil
 import { createControlPoller } from '../../shared/control-poller.mjs';
 import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
 import { createCursorTurnRunner } from './cursor-turn-runner.mjs';
+import { resolveCursorSessionStoreDir } from '../services/cursor-session-root-service.mjs';
 
 // Windows console launch: the launcher names the worker log, this copies
 // stdout/stderr into it. A no-op wherever the launcher redirects instead.
@@ -57,8 +58,14 @@ async function main() {
     // renewal hint, which is more visible to the user than a dead worker.
     console.warn('cursor-session-worker: CURSOR_API_KEY is not set; turns will fail until it is provided');
   }
-  const storeDir = String(process.env.CURSOR_AGENT_STORE_DIR || '').trim()
-    || path.resolve(__dirname, '..', 'data', 'cursor-agents');
+  // `$CURSOR_AGENT_STORE_DIR`, else `cursor-agents` in the relay's data dir:
+  // the same folder the relay's Session root looks in.
+  const storeDir = resolveCursorSessionStoreDir({
+    env: process.env,
+    serverDir: path.resolve(__dirname, '..'),
+    configPath,
+    sdkSessionId,
+  });
 
   const api = createApiClient({
     serverUrl,

package/server/cursor-worker/cursor-turn-runner.mjs

@@ -23,6 +23,7 @@ import { renderMediaEmbedInstructionBlock } from '../../shared/media-embed-instr
 import { EMPTY_TURN_COMPLETION_NOTE } from '../../shared/empty-turn-completion.mjs';
 import { resolveFallbackContextLimitTokens } from '../../shared/context-window-fallbacks.mjs';
 import { countPlanLikeLines } from '../../shared/plan-lines.mjs';
+import { explainLaunchFailure, missingWorkingDirectoryError } from '../../shared/worker-runtime/working-directory.mjs';
 
 // Stale-auth recovery budget per turn: expiry is routine on long-lived
 // handles, and one retry proved too small in practice (an orchestrator turn
@@ -122,6 +123,9 @@ export function createCursorTurnRunner({
   resolveModelParamsImpl = resolveCursorReasoningParams,
   createNormalizerImpl = createSdkMessageNormalizer,
   buildUserMessageImpl = buildCursorUserMessage,
+  // The error an agent started in `cwd` fails with up front, or null
+  // (shared/worker-runtime/working-directory.mjs).
+  checkWorkingDirectoryImpl = missingWorkingDirectoryError,
   // Whether agent handles carry the relay's `remote_relay` tool
   // (shared/remote-relay-tool-core.mjs). Default: ask the relay.
   remoteRelayToolGate = null,
@@ -174,7 +178,9 @@ export function createCursorTurnRunner({
   // plain refusal the model can relay instead of a failed turn.
   const previewTool = createPreviewTool({
     api,
-    getConversationId: () => activeMessage?.conversationId || '',
+    // Between turns, the worker's own session (as remote_relay below): list
+    // and close are scoped to a conversation and refused without one.
+    getConversationId: () => activeMessage?.conversationId || sdkSessionId || '',
     dbg,
   });
   const customTools = {
@@ -301,6 +307,10 @@ export function createCursorTurnRunner({
       agentHandle = null;
     }
     if (!agentHandle) {
+      // The agent works in the conversation's folder: a folder that is gone
+      // fails the turn with its name (and is no reason to drop the agent).
+      const missingFolder = checkWorkingDirectoryImpl(cwd);
+      if (missingFolder) throw missingFolder;
       const durableId = String(message.cursorAgentId || '').trim() || cursorAgentId;
       const agents = buildCursorSubagentAgents(rosterModels);
       await remoteRelayGate.ready();
@@ -309,11 +319,15 @@ export function createCursorTurnRunner({
       try {
         agentHandle = await createAgentHandleImpl({ ...options, agentId: durableId });
       } catch (error) {
-        if (!durableId) throw error;
+        if (!durableId) throw explainLaunchFailure(error, cwd, { check: checkWorkingDirectoryImpl });
         // The durable agent may have been pruned server-side; fall back to a
         // fresh agent rather than wedging the conversation.
         dbg('cursor agent resume failed, creating fresh agent', error?.message || String(error));
-        agentHandle = await createAgentHandleImpl({ ...options, agentId: '' });
+        try {
+          agentHandle = await createAgentHandleImpl({ ...options, agentId: '' });
+        } catch (freshError) {
+          throw explainLaunchFailure(freshError, cwd, { check: checkWorkingDirectoryImpl });
+        }
       }
     }
     // Only recorded once a handle exists: a create that threw leaves the
@@ -787,6 +801,7 @@ export function createCursorTurnRunner({
           // A stall is told in the user's terms, and with its own advice: the
           // run was cancelled, so sending the message again is all it takes.
           message: classified.text || classified.message,
+          ...(classified.guidance ? { guidance: classified.guidance } : {}),
           ...(classified.isStalled ? { guidance: 'Send the message again to retry.' } : {}),
           failedAt: new Date().toISOString(),
           queueMessageId: String(message.id || '') || null,

package/server/grok-worker/grok-sdk-adapter.mjs

@@ -6,12 +6,26 @@ import { AcpClient, extractGrokModelsFromInitialize, pickAllowOnceOptionId } fro
 import { createAcpHostServices } from './acp-host-services.mjs';
 import { createSdkMessageNormalizer } from './sdk-message-normalizer.mjs';
 import { describeTurnStall, isTurnStalledError } from '../../shared/worker-runtime/turn-liveness.mjs';
+import { WORKING_DIRECTORY_MISSING_CODE, isWorkingDirectoryMissingError } from '../../shared/worker-runtime/working-directory.mjs';
 
 export { extractGrokModelsFromInitialize };
 
 export function classifyGrokError(error) {
   const message = String(error?.message || error || '').trim();
   const lower = message.toLowerCase();
+  // First, and above all before the ENOENT branch: a spawn in a folder that
+  // is gone fails with ENOENT too, and the runner puts it down to the folder,
+  // whose path may hold any of the words matched below.
+  if (isWorkingDirectoryMissingError(error)) {
+    return {
+      code: `grok.${WORKING_DIRECTORY_MISSING_CODE}`,
+      message,
+      text: message,
+      guidance: error.guidance,
+      isAuth: false,
+      isBusy: false,
+    };
+  }
   // No bare 'auth' token: it would match unrelated words ("author…") in
   // arbitrary agent error text and misclassify them as login failures.
   if (

package/server/grok-worker/grok-turn-runner.mjs

@@ -12,6 +12,7 @@ import { fetchRemoteRelayInflight } from '../../shared/remote-relay-tool-core.mj
 import { renderMediaEmbedInstructionBlock } from '../../shared/media-embed-instructions.mjs';
 import { countPlanLikeLines } from '../../shared/plan-lines.mjs';
 import { EMPTY_TURN_COMPLETION_NOTE } from '../../shared/empty-turn-completion.mjs';
+import { explainLaunchFailure, missingWorkingDirectoryError } from '../../shared/worker-runtime/working-directory.mjs';
 
 const PLAN_BOARD_ACTIONS = [
   { id: 'autopilot', label: 'Implement in autopilot', mode: 'autopilot' },
@@ -64,6 +65,7 @@ function buildGrokTerminalError(classified, message) {
     code: classified.code,
     stableCode: classified.code,
     message: classified.text || classified.message,
+    ...(classified.guidance ? { guidance: classified.guidance } : {}),
     // A stalled turn was cancelled and its agent is restarted for the next
     // message, so sending the message again is all it takes.
     ...(classified.isStalled ? { guidance: 'Send the message again to retry.' } : {}),
@@ -115,6 +117,9 @@ export function createGrokTurnRunner({
   createAgentHandleImpl = createGrokAgentHandle,
   startGrokTurnImpl = startGrokTurn,
   classifyErrorImpl = classifyGrokError,
+  // The error a Grok CLI started in `cwd` fails with up front, or null
+  // (shared/worker-runtime/working-directory.mjs).
+  checkWorkingDirectoryImpl = missingWorkingDirectoryError,
   getPreviewInstructions = createPreviewInstructionsProvider({ api }),
   env = process.env,
   nodePath = process.execPath,
@@ -200,6 +205,11 @@ export function createGrokTurnRunner({
 
   async function ensureAgentHandle(message, model) {
     if (agentHandle) return agentHandle;
+    // The CLI is spawned in the conversation's folder; a folder that is gone
+    // fails with ENOENT, which would otherwise read as a CLI that is not
+    // installed (classifyGrokError).
+    const missingFolder = checkWorkingDirectoryImpl(cwd);
+    if (missingFolder) throw missingFolder;
     const resumeId = String(message.grokNativeSessionId || grokNativeSessionId || '').trim();
     agentHandle = await createAgentHandleImpl({
       command,
@@ -215,7 +225,7 @@ export function createGrokTurnRunner({
         ? { AcpClientImpl: withAcpMcpServers(AcpClient, acpMcpServers), mcpServers: acpMcpServers }
         : {}),
       dbg,
-    });
+    }).catch((error) => { throw explainLaunchFailure(error, cwd, { check: checkWorkingDirectoryImpl }); });
     if (agentHandle.sessionId) {
       await persistNativeSessionId(message, agentHandle.sessionId);
     }
@@ -427,7 +437,7 @@ export function createGrokTurnRunner({
     const previewBlock = previewInstructionsSent || acpMcpServers.length
       ? ''
       : await Promise.resolve()
-        .then(() => getPreviewInstructions?.())
+        .then(() => getPreviewInstructions?.({ conversationId: message.conversationId || sdkSessionId || '' }))
         .catch(() => '');
     const mediaBlock = mediaInstructionsSent ? '' : renderMediaEmbedInstructionBlock();
     const promptText = [previewBlock, mediaBlock, modeNudge, userText].filter(Boolean).join('\n\n');
@@ -594,7 +604,7 @@ export function createGrokTurnRunner({
         : classified.isStalled
           ? classified.text
             || `System note: the Grok turn stalled and was stopped (${classified.message}). Send a new message to retry.`
-          : `System note: the Grok turn failed (${classified.message}).`;
+          : classified.text || `System note: the Grok turn failed (${classified.message}).`;
       await publishResponse(message, {
         text: noteText,
         model: message.providerModel || defaultModel || null,

package/server/public/app/api-client.js

@@ -1560,13 +1560,15 @@ export async function loadRelayQuestion(questionId) {
   return apiFetch(`/api/relay-question/${encodeURIComponent(id)}`);
 }
 
-export async function answerRelayQuestion(questionId, answer, sdkSessionId = null) {
+// `onErrorResponse` reads the relay's refusal (why, and a card's choices).
+export async function answerRelayQuestion(questionId, answer, sdkSessionId = null, { onErrorResponse } = {}) {
   const id = String(questionId || '').trim();
   if (!id) return null;
   const sessionId = String(sdkSessionId || '').trim();
   return apiFetch(`/api/relay-question/${encodeURIComponent(id)}/answer`, {
     method: 'POST',
     body: JSON.stringify({ answer, sdk_session_id: sessionId || undefined }),
+    onErrorResponse,
   });
 }
 

package/server/public/app/ask-user-view.js

@@ -14,6 +14,7 @@ import { schemaFieldsFromQuestion } from './question-schema-view.mjs';
 import { composeMultiSelectAnswer, isMultiSelectQuestion, offersMultiSelectToggle } from './question-multi-select.mjs';
 import { isChatInteractionHeld } from './selection-guard.mjs';
 import { questionCardHeadLabel } from './conversation-provider-indicator.mjs';
+import { questionAcceptsFreeText } from './question-answer-rule.mjs';
 import { beginOwnSend, followsTranscriptEnd, refreshJumpButton, scrollAfterOwnSend } from './transcript-jump-bottom-view.mjs';
 
 let relayQuestionRenderHash = '';
@@ -265,6 +266,10 @@ export function renderRelayQuestions() {
     const modeTag = question.mode ? ` <span class="msg-mode">${escHtml(question.mode)}</span>` : '';
     const contextText = String(question?.context?.rationale || '').trim();
     const contextHtml = contextText ? `<div class="relay-question-context">${renderLinkedPlainText(contextText)}</div>` : '';
+    // The card's own title ("Agent sessions", "Remote relay", a Claude
+    // question's header), above the question.
+    const headerText = String(question?.context?.header || '').trim();
+    const headerHtml = headerText ? `<div class="relay-question-header">${escHtml(headerText)}</div>` : '';
     const fields = schemaFieldsFromQuestion(question);
     const structuredQuestion = fields.length > 0;
 
@@ -296,14 +301,21 @@ export function renderRelayQuestions() {
           choices.map((choice) => `<button class="relay-question-choice" disabled>${escHtml(choice)}</button>`).join('')
         }</div>`;
       }
-      const showReplyControls = question.status === 'pending';
+      // A card that takes no typed text (approval and permission cards) is
+      // answered by its choices alone: no reply box, and a multi-select one
+      // keeps only its "Reply with selection".
+      const freeText = questionAcceptsFreeText(question);
+      const showReplyControls = question.status === 'pending' && (freeText || multiSelect);
       const draftText = String(relayQuestionDrafts.get(question.id) || '');
       const replyPlaceholder = multiSelect
         ? 'Add another answer or a note (optional)… (Ctrl/Cmd+Enter to send)'
         : 'Type a reply… (Ctrl/Cmd+Enter to send)';
+      const replyInputHtml = freeText
+        ? `<textarea id="relay-question-input-${question.id}" placeholder="${replyPlaceholder}" onkeydown="handleRelayQuestionKey(event, '${question.id}')" oninput="onRelayQuestionDraftInput('${question.id}', this.value)">${escHtml(draftText)}</textarea>`
+        : '';
       const replyHtml = showReplyControls
         ? `<div class="relay-question-reply">
-            <textarea id="relay-question-input-${question.id}" placeholder="${replyPlaceholder}" onkeydown="handleRelayQuestionKey(event, '${question.id}')" oninput="onRelayQuestionDraftInput('${question.id}', this.value)">${escHtml(draftText)}</textarea>
+            ${replyInputHtml}
             <button class="relay-question-submit" onclick="${multiSelect ? 'submitRelayQuestionMultiSelect' : 'submitRelayQuestionAnswer'}('${question.id}')">${multiSelect ? 'Reply with selection' : 'Reply'}</button>
           </div>`
         : '';
@@ -320,6 +332,7 @@ export function renderRelayQuestions() {
     wrapper.innerHTML = `
       <div class="relay-question-card${question.status === 'timed_out' ? ' relay-question-timed-out' : ''}">
         <div class="relay-question-head">${questionCardHeadLabel(conversations[question.conversationId])}${modeTag} · ${fmtDate(question.createdAt)}</div>
+        ${headerHtml}
         <div class="relay-question-body">${renderLinkedPlainText(question.prompt || '')}</div>
         ${contextHtml}
         ${answeredHtml}
@@ -580,6 +593,15 @@ async function enqueueRelayAnswerForSync(questionId, body) {
   return queued;
 }
 
+// The relay's reason for refusing an answer (a card that takes only its
+// choices names them), or '' when it gave none.
+function relayAnswerRefusalText(refusal) {
+  const reason = String(refusal?.error || '').trim();
+  if (!reason) return '';
+  const choices = Array.isArray(refusal?.choices) ? refusal.choices.map((choice) => String(choice)).filter(Boolean) : [];
+  return choices.length ? `${reason}. Choices: ${choices.join(', ')}.` : reason;
+}
+
 export async function submitRelayQuestionAnswer(questionId, presetAnswer = null) {
   const input = document.getElementById(`relay-question-input-${questionId}`);
   // Ctrl/Cmd+Enter in a multi-select card's text field sends the ticked
@@ -600,15 +622,18 @@ export async function submitRelayQuestionAnswer(questionId, presetAnswer = null)
     const question = relayQuestions.get(questionId) || null;
     const sdkSessionId = String(question?.sdkSessionId || '').trim();
     const singleFieldStructuredAnswer = resolveSingleFieldStructuredAnswer(question, answer);
+    let refusal = null;
     const r = singleFieldStructuredAnswer
       ? await answerRelayQuestionStructured(questionId, singleFieldStructuredAnswer, sdkSessionId || null)
-      : await answerRelayQuestion(questionId, answer, sdkSessionId || null);
+      : await answerRelayQuestion(questionId, answer, sdkSessionId || null, {
+        onErrorResponse: async (response) => { refusal = await response.json().catch(() => null); },
+      });
     if (!r?.question) {
       const queued = await enqueueRelayAnswerForSync(questionId, singleFieldStructuredAnswer
         ? { structuredAnswer: singleFieldStructuredAnswer, sdk_session_id: sdkSessionId || undefined }
         : { answer, sdk_session_id: sdkSessionId || undefined });
       if (queued) return;
-      throw new Error('Failed to submit relay question answer');
+      throw new Error(relayAnswerRefusalText(refusal) || 'Failed to submit relay question answer');
     }
     relayQuestionDrafts.delete(questionId);
     relayQuestionStructuredDrafts.delete(questionId);

package/server/public/app/conversation-provider-indicator.mjs

@@ -33,15 +33,25 @@ export function isConversationUsingClaudeCloudProvider(conversation = null) {
 // The marker that tells a cloud chat from a local Claude one at a glance.
 const CLAUDE_CLOUD_MARKER = '☁';
 
+const PROVIDER_NAMES = Object.freeze({
+  openai: 'OpenAI',
+  claude: 'Claude',
+  'claude-cloud': 'Claude Cloud',
+  cursor: 'Cursor',
+  grok: 'Grok',
+  github: 'Copilot',
+  'github-copilot': 'Copilot',
+});
+
+// A provider type's name as the list pill and the question card say it; ''
+// when unknown. The relay's question push uses it too
+// (services/push-dispatch-service.mjs).
+export function providerDisplayName(providerType = '') {
+  return PROVIDER_NAMES[String(providerType || '').trim().toLowerCase()] || '';
+}
+
 function conversationProviderName(conversation = null) {
-  const providerType = resolveConversationProviderType(conversation);
-  if (providerType === 'openai') return 'OpenAI';
-  if (providerType === 'claude') return 'Claude';
-  if (providerType === 'claude-cloud') return 'Claude Cloud';
-  if (providerType === 'cursor') return 'Cursor';
-  if (providerType === 'grok') return 'Grok';
-  if (providerType === 'github' || providerType === 'github-copilot') return 'Copilot';
-  return '';
+  return providerDisplayName(resolveConversationProviderType(conversation));
 }
 
 // An unresolved provider stays unlabelled rather than defaulting to Copilot, so

package/server/public/app/question-answer-rule.mjs

@@ -0,0 +1,15 @@
+// Browser mirror of questionAcceptsFreeText in shared/question-answer-rule.mjs
+// (the relay's answer route applies the same rule). The browser cannot import
+// shared/ (only server/public is served), so this is a hand-kept copy;
+// question-answer-rule.test.mjs asserts it behaves exactly like the original.
+
+/**
+ * Whether a card takes typed text. A card with choices takes it only when it
+ * says so (`allowFreeform: true`); a missing flag counts as false there, as
+ * the create route and the relay's question rows read it. Without choices a
+ * card always does: it could not be answered otherwise.
+ */
+export function questionAcceptsFreeText(question) {
+  const choices = Array.isArray(question?.choices) ? question.choices : [];
+  return question?.allowFreeform === true || choices.length === 0;
+}

package/server/public/app/question-multi-select.mjs

@@ -14,14 +14,21 @@
 // answer is the selected labels joined with ", " — plus whatever the user
 // typed as an extra answer — which is Claude's own multi-select answer format.
 
+import { questionAcceptsFreeText } from './question-answer-rule.mjs';
+
 function choiceCount(question) {
   return Array.isArray(question?.choices) ? question.choices.length : 0;
 }
 
-/** Whether the card offers the "Select several" switch. */
+/**
+ * Whether the card offers the "Select several" switch. Never on a card that
+ * takes no typed text: the relay takes several choices there only when the
+ * provider flagged the card multi-select.
+ */
 export function offersMultiSelectToggle(question) {
   if (!question || typeof question !== 'object') return false;
-  return choiceCount(question) >= 2 && question?.context?.allowMultiSelect === true;
+  return choiceCount(question) >= 2 && question?.context?.allowMultiSelect === true
+    && questionAcceptsFreeText(question);
 }
 
 /**

package/server/public/app/relay-event-view.mjs

@@ -24,6 +24,7 @@ const EVENT_TYPES = new Set([
   'heartbeat',
   'link_lost',
   'link_restored',
+  'relay_restarted',
 ]);
 const URGENT_TYPES = new Set(['question_asked', 'error']);
 const DIGEST_PATTERN = /^Digest of \d+ events?/;
@@ -43,6 +44,7 @@ const TYPE_LABELS = Object.freeze({
   heartbeat: 'heartbeat',
   link_lost: 'link lost',
   link_restored: 'link back',
+  relay_restarted: 'relay restarted',
 });
 
 function defaultEscape(value) {
@@ -181,6 +183,8 @@ export function watchersOf(subscriptions, conversationId, { includeAll = true }
 export function watchingChipText(summary) {
   if (!summary?.subscriptions?.length) return '';
   if (summary.all) return summary.count ? `watching all sessions (+${summary.count} listed)` : 'watching all sessions';
+  // Only relay_restarted: no session is watched.
+  if (!summary.count) return 'waiting for a relay restart';
   return `watching ${summary.count} session${summary.count === 1 ? '' : 's'}`;
 }
 
@@ -198,7 +202,7 @@ function describeSubscription(sub, conversations) {
   const listed = (Array.isArray(sub.sessions) ? sub.sessions : []).filter((session) => session?.id).map(titleOf).join(', ');
   const what = sub.scope === 'all'
     ? (paired ? `All sessions of ${relay}` : 'All sessions')
-    : (paired ? `${relay} · ${listed}` : listed);
+    : (paired ? `${relay} · ${listed}` : (listed || 'This relay'));
   const extras = [
     sub.once ? 'once' : '',
     sub.heartbeatMinutes ? `heartbeat ${sub.heartbeatMinutes} min` : '',

package/server/public/index.html

@@ -5905,6 +5905,10 @@
     color: var(--muted);
     font-size: var(--fs-meta-xs);
   }
+  .relay-question-header {
+    font-weight: 600;
+    color: var(--text);
+  }
   .relay-question-body {
     line-height: 1.5;
     color: var(--text);
@@ -7190,7 +7194,7 @@
             checked
           >
         </div>
-        <div class="settings-help" style="margin-top: 6px;">Hide the menu action when host suspend is unsupported or not needed on this device.</div>
+        <div class="settings-help" style="margin-top: 6px;">Shows or hides the menu action in this browser only. Suspend works only when the relay runs on Windows; a queued suspend still shows its banner here either way.</div>
         <div class="settings-row" style="margin-top: 12px; margin-bottom: 0;">
           <label for="scroll-on-send-toggle">Jump to the end when I send a message</label>
           <input
@@ -7232,7 +7236,7 @@
             onchange="updateTurnCeilingSetting(this.value)"
           >
         </div>
-        <div class="settings-help" style="margin-top: 6px;">A hard cap on how long one turn may run before the relay requeues it. Turns are already kept alive by worker heartbeats, and a turn waiting on your answer to a question is never cut off — so this only catches a worker that has hung. Set to 0 for no limit.</div>
+        <div class="settings-help" style="margin-top: 6px;">A hard cap on how long one turn may run before the relay requeues it, counted from the start of the turn or from your last answer to one of its questions. Turns are already kept alive by worker heartbeats, and the relay never cuts off a turn waiting on your answer to a question — so this only catches a worker that has hung. Grok also enforces the limit itself, counted from the start of the prompt and without pausing for questions (remote relay approvals). Set to 0 for no limit.</div>
         <div class="settings-row settings-row-column" style="margin-top: 12px; margin-bottom: 0;">
           <label for="background-task-timeout-slider">Background task timeout <span id="background-task-timeout-value">4 h</span></label>
           <input
@@ -7489,7 +7493,7 @@
             <div style="display: flex; gap: 8px; margin-top: 8px;">
               <button id="copilot-save-btn" type="button" class="summary-btn" onclick="saveCopilotSettings()">Save Copilot settings</button>
             </div>
-            <div class="settings-help">Chooses how GitHub Copilot conversations run. <strong>SDK</strong> is the default: a headless worker per conversation with mid-turn steering and background task cards — no CLI extension to install, but no tmux inspector for those sessions. <strong>Extension</strong> runs the Copilot CLI in a terminal session, which you can attach to with the tmux inspector. A relay that cannot run the SDK engine uses Extension. Applies to newly started conversations; sessions already running keep their engine until their worker restarts.</div>
+            <div class="settings-help">Chooses how GitHub Copilot conversations run. <strong>SDK</strong> is the default: a headless worker per conversation with mid-turn steering and background task cards — no CLI extension to install, but no tmux inspector for those sessions. <strong>Extension</strong> runs the Copilot CLI in a terminal session, which you can attach to with the tmux inspector. A relay where no engine was saved and that cannot run the SDK engine uses Extension. Applies whenever a conversation's worker starts; sessions already running keep their engine until their worker restarts.</div>
           </div>
         </div>
         <div
@@ -7883,7 +7887,7 @@
               <button id="cursor-dashboard-token-save-btn" type="button" class="summary-btn" onclick="saveCursorDashboardToken()">Save token</button>
               <button id="cursor-dashboard-token-remove-btn" type="button" class="summary-btn" onclick="removeCursorDashboardToken()">Remove</button>
             </div>
-            <div class="settings-help">Unlocks the live "Included in plan" percentage bars on Check Usage. Detected automatically from this machine's Cursor IDE login when one exists; paste the <code>WorkosCursorSessionToken</code> cookie from a logged-in cursor.com tab (DevTools → Application → Cookies) only for headless relay hosts or to use a different account. Headless hosts can also set <code>CURSOR_SESSION_TOKEN</code> in the relay environment. Tokens stay on the relay.</div>
+            <div class="settings-help">Unlocks the live percentage bars on Check Usage: "Plan usage (total)", "Auto + Composer" and "API". Detected automatically from this machine's Cursor IDE login when one exists; paste the <code>WorkosCursorSessionToken</code> cookie from a logged-in cursor.com tab (DevTools → Application → Cookies) only for headless relay hosts or to use a different account. Headless hosts can also set <code>CURSOR_SESSION_TOKEN</code> in the relay environment. Tokens stay on the relay.</div>
           </div>
         </div>
       </div>
@@ -7929,7 +7933,7 @@
             checked
           >
         </div>
-        <div class="settings-help" style="margin-top: 6px;">When off, agents on paired relays can still read sessions here, but cannot send prompts, start sessions, answer questions or stop turns. The relay token stays the real boundary: anyone holding it has full access.</div>
+        <div class="settings-help" style="margin-top: 6px;">When off, agents on paired relays can still list, read and wait on sessions here, but cannot send prompts, start sessions, answer questions, stop turns, cancel queued turns, archive or unarchive sessions, or watch sessions here for events. The relay token stays the real boundary: anyone holding it has full access.</div>
         <!-- Agent sessions (agent-sessions-settings-ui.js). Hidden until the relay
              answers with settings; a relay without the route never shows it. -->
         <div id="agent-sessions-section" hidden>

package/server/relay-exit-codes.mjs

@@ -2,3 +2,9 @@
 
 // Intentional relay restart requested via authenticated localhost API.
 export const RELAY_RESTART_EXIT_CODE = 75;
+// The runtime stopped on purpose and starting it again at once cannot help:
+// its database needs a decision (adoptEarlierDatabase refused), or its data
+// folder cannot be made (ensureDataDirs). The supervisors do not retry it, so
+// its one line is said once; the code goes on to whatever started the relay.
+// 78 is sysexits' EX_CONFIG.
+export const RELAY_STOP_EXIT_CODE = 78;

package/server/relay-self-restart.mjs

@@ -1,6 +1,6 @@
 import { spawn } from 'child_process';
 import path from 'path';
-import { RELAY_RESTART_EXIT_CODE } from './relay-exit-codes.mjs';
+import { RELAY_RESTART_EXIT_CODE, RELAY_STOP_EXIT_CODE } from './relay-exit-codes.mjs';
 
 // Role selection travels on argv, never in the environment. The runtime's env is
 // inherited by tmux worker sessions and by the Copilot CLI it launches, and the
@@ -151,6 +151,11 @@ export async function runDirectRelaySupervisor({
         return await exitImpl(0);
       }
 
+      // Stopped on purpose, with its reason already said: not a crash.
+      if (exitCode === RELAY_STOP_EXIT_CODE) {
+        return await exitImpl(RELAY_STOP_EXIT_CODE);
+      }
+
       const attempt = crashCount + 1;
       logger?.error?.(`[relay] runtime crashed with exit code ${exitCode ?? 'null'} (crash ${attempt}/${maxCrashRestarts}).`);
       if (attempt >= maxCrashRestarts) {

package/server/relay-tools.md

@@ -2,51 +2,54 @@
 
 For any user-facing question or clarification, use the ask_user tool so the web relay can render question cards and buttons. Never ask questions in plain assistant text.
 
-When using ask_user, ALWAYS include a `choices` array with 2-6 answer options so the web relay can render clickable buttons. Example:
+When using ask_user, ALWAYS include a `choices` array with 2-8 answer options so the web relay can render clickable buttons. The relay keeps the first 8 choices and drops the rest. Example:
 ```json
 {
-  "question": "<QUIZ_QUESTION_TEXT>",
-  "choices": ["<CHOICE_A>", "<CHOICE_B>", "<CHOICE_C>", "<CHOICE_D>"]
+  "question": "The login test fails because the session cookie expires too early. How should I fix it?",
+  "choices": ["Fix the cookie lifetime in the code", "Update the test to match the code", "Leave it and only report it"]
 }
 ```
-At runtime, inject the question and choices from a random item in your quiz pool.
 Only omit choices when the question genuinely requires freeform text input (e.g., "What is your name?").
 
 When the user may pick several of the choices (they are not mutually exclusive), set `"multi_select": true` if your ask_user tool offers that field; otherwise begin the question with "Select all that apply:". Either way, expect an answer that lists several choices separated by ", ".
 
 In autopilot, still call ask_user when user input is truly blocking, because the relay bridge can surface the question even when the direct SDK question hook is bypassed.
 
-For relay restarts in extension-managed mode, require explicit user permission first, then use the authenticated localhost API `POST /api/relay/shutdown`. Do not restart by killing processes or using respawn scripts.
+For a relay restart or shutdown, require explicit user permission first, then use the authenticated localhost API `POST /api/relay/shutdown`. Do not restart by killing processes or using respawn scripts.
 
-Note: shutdown is queued and only completes when the current turn finishes, so it is pointless to wait for it to interrupt an active turn.
+Note: the request is queued. The relay only shuts down or restarts once no turn is running on it, your own included (after a maximum wait it asks the user), and it holds new messages until then, so end your turn instead of waiting for the restart. The answer names the sessions it waits for (`waitingFor`), the messages it holds (`held`) and the background tasks (`backgroundTasks`, each with whether it `survives`): tell the user.
 
 Use `restart: true` in the request body when the user wants a real relay restart rather than a plain shutdown. Example request body: `{ "reason": "manual-restart", "requestedBy": "localhost-api", "restart": true }`.
 
 Never pass `immediate` in that request body: it restarts without waiting for the running turns, which only the user may decide, with Restart now in the web UI.
 
+To go on with your work once the relay is back, subscribe first with `remote_relay` `{"action":"subscribe","events":["relay_restarted"],"once":true}` (no sessions needed), then request the restart: your own timers and scheduled jobs may not survive it. A restart requested while a turn that `relay_restarted` woke is still running does not wake that conversation (a `once` subscription ends with it).
+
 ## Preview servers
 
-Publish a local web server or a static directory on a public preview URL so the user can open it from any device, or list/close existing previews. Use this whenever the user wants to see, try, or share something with a web UI — never ask them to open localhost or forward a port. For a dev server: call this FIRST with {action:"create", port} to get the basePath, then start the server configured to serve under that basePath (Vite --base, Next basePath, Express mount prefix); the proxy forwards X-Forwarded-Prefix but does not rewrite bodies, so root-absolute asset paths will not work. For plain files or a build output: pass {action:"create", dir} instead and the relay serves the directory itself — no dev server needed. Always tell the user the returned URL and that the link is public: anyone who has it can reach the app without logging in. Publishing the same port or directory again in this conversation returns the same link. Previews never expire and survive a relay restart (a port preview until the machine reboots); close them with {action:"close"} when the user is done.
+Publish a local web server or a static directory on a public preview URL so the user can open it from any device, or list/close this conversation's previews. Use this whenever the user wants to see, try, or share something with a web UI — never ask them to open localhost or forward a port. For a dev server: call this FIRST with {action:"create", port} to get the basePath, then start the server configured to serve under that basePath (Vite --base, Next basePath, Express mount prefix); the proxy forwards X-Forwarded-Prefix but does not rewrite bodies, so root-absolute asset paths will not work. For plain files or a build output: pass {action:"create", dir} instead and the relay serves the directory itself — no dev server needed. Always tell the user the returned URL and that the link is public: anyone who has it can reach the app without logging in. Publishing the same port or directory again in this conversation returns the same link. Previews never expire and survive a relay restart (a port preview until the machine reboots); close them with {action:"close"} when the user is done.
 
-If you have a `preview` tool, use it. Otherwise use the authenticated localhost API (same auth as `POST /api/relay/shutdown`): `POST /api/previews` with `{ "conversationId": "<conv>", "port": 5173, "label": "web app" }` (or `"dir": "./dist"` instead of the port) publishes, `GET /api/previews` lists, `DELETE /api/previews/:token` closes the link without touching the dev server behind it. A 503 with `details` means the preview lane is disabled or misconfigured — surface those details, they are the operator's fix. See `docs/preview-servers.md`.
+If you have a `preview` tool, use it. Otherwise use the authenticated localhost API (same auth as `POST /api/relay/shutdown`): `POST /api/previews` with `{ "conversationId": "<conv>", "port": 5173, "label": "web app" }` (or `"dir": "./dist"` instead of the port) publishes, `GET /api/previews?conversationId=<conv>` lists this conversation's previews, `DELETE /api/previews/:token?conversationId=<conv>` closes one of them without touching the dev server behind it. Always pass the conversation: you may list and close only this conversation's previews, another conversation's is refused (403), and the relay-wide list is the user's (Settings → Previews). A 503 with `details` means the preview lane is disabled or misconfigured — surface those details, they are the operator's fix. See `docs/preview-servers.md`.
 
 ## Remote relays
 
 If you have a `remote_relay` tool, it works with sessions on OAR relays: the other relays this relay is paired with and, when its owner allows it, this relay itself. It lists and reads sessions, prompts a session, starts a new one and waits for its reply. Start with `{"action":"list_relays"}`.
 
-A paired relay stays locked until the user mentions it in this conversation (`@name` or its plain name); a locked relay refuses everything except `list_relays`, so ask the user to mention it rather than retrying. Use a paired relay only when the user asks for work there or mentions it.
+A paired relay stays locked until the user mentions it in this conversation (`@name` or its plain name) or an agent on that relay writes to this conversation; a locked relay refuses everything except `list_relays`, so ask the user to mention it rather than retrying. Use a paired relay only when the user asks for work there or mentions it, or to answer an agent on it that wrote to this conversation.
 
 This relay itself is listed with "self": true when its owner switched agent sessions on, and is addressed by its name or as "this"; it needs no mention. Use it to hand parts of your task to other sessions:
 
 - `create_session` starts a session with any provider that `relay_info` lists: a local one in a folder ("cwd"), or provider "claude-cloud" with "repo" (a GitHub URL or owner/repo) and an optional "branch". At most 4 sessions you started may work at the same time; a fifth is refused until one finishes.
 - The first `create_session` on this relay shows the user an approval card, once per conversation. A session that an agent created cannot create sessions itself (one level only).
 - Sessions you start here are grouped under this session in the user's sidebar. `list_sessions` lists in the sidebar's order (a group sorts by its newest session, head first) and shows the group as a "group" field (id, name, role); `read_session` adds the group's live members with their state. Agents only read groups, the user arranges them.
-- A "model" for `create_session` or `send` must be an id `relay_info` lists for the provider (Claude also takes "opus", "sonnet", "haiku"). An unknown id is refused with the close matches ("unknown model 'gpt-5-4' for Copilot; did you mean 'gpt-5.4'?") and nothing is created or sent: pick from the list instead of guessing. If the answer has a "modelNote" saying the model could not be checked, the relay had no model list yet.
+- A "model" for `create_session` or `send` must be an id `relay_info` lists for the provider (Claude also takes "opus", "sonnet", "haiku"). An unknown id is refused with the close matches and the valid ids (`Unknown model 'gpt-5-4' for Copilot on relay "…"; did you mean 'gpt-5.4'? Valid ids: … Nothing was sent.`), and nothing is created or sent: pick from the list instead of guessing. If the answer has a "modelNote" saying the model could not be checked, the relay had no model list yet.
 - A new session knows nothing of this conversation: write a self-contained prompt. A Claude Cloud session works on a fresh clone in a sandbox at Anthropic, so name the branch it should work on and push.
 - Follow each session with `wait` (the message id comes back from `create_session` and `send`) and `read_session`; "wait_seconds" is limited to the maximum set on the relay (default 600).
 - Sessions run on the relay owner's accounts and cost their usage: start only what the task needs.
 - `read_task_output` ("session", "task_id" from `read_session`'s tasks, optional "lines") reads the end of a background shell or Monitor task's output, also for an hour after it ended: the last lines, minutes since its last output, and pass/fail counts for a test run. Credentials are scrubbed out.
 
-On this relay and on a paired one, `subscribe` wakes you when something happens in the sessions you watch, instead of polling them. Leave "events" out unless you need more: the default (question_asked, error, turn_end, subagent_finished, task_failed, stalled, all_idle) wakes you for questions, errors, replies, finished sub-agents, failed tasks (a non-zero exit included), stalls and all_idle, but not for each shell command that ended well. To get those too, pass that list plus "task_finished" (and "task_started" for the starts); each one costs you a turn, so do it only if you must follow every command.
+On this relay and on a paired one, `subscribe` ("sessions": ids, or ["all"]) wakes you when something happens in the sessions you watch, instead of polling them. Leave "events" out unless you need more: the default (question_asked, error, turn_end, subagent_finished, task_failed, stalled, all_idle) wakes you for questions, errors, replies, finished sub-agents, failed tasks (a non-zero exit included), stalls and all_idle, but not for each shell command that ended well. To get those too, pass that list plus "task_finished" (and "task_started" for the starts); each one costs you a turn, so do it only if you must follow every command. "relay_restarted" (this relay only, never in the default) wakes you when the relay runs again after a restart, with who requested it and why; named alone it needs no sessions.
+
+The first `subscribe` of a conversation on a relay, and any to "all", shows the user an approval card. `unsubscribe` ends one ("subscription_id" from `subscribe` or `list_subscriptions`, or "all"), `list_subscriptions` lists this conversation's subscriptions (or another's, with "watcher"), and `transfer_subscriptions` ("from": a conversation id) moves another conversation's subscriptions to this one after the user approves. `usage` shows what each provider plan of a relay has left and whether a Claude usage limit has paused turns there: check it before you start work that costs. `stop` stops a session's running turn and `archive` archives a session. The `remote_relay` tool's own description is the full reference for every action and field.
 
 Write actions may first wait for the user's approval. If a result lists `pendingQuestions`, the other agent is waiting for an answer: ask the user (unless they told you to decide), then pass it on with `answer_question`. Always tell the user which relay and session you worked on.