@oar-sh/oar 0.9.13 → 0.9.15

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

@@ -8,6 +8,7 @@ import {
   isTurnStalledError,
   resolveTurnStallWindows,
 } from '../../shared/worker-runtime/turn-liveness.mjs';
+import { WORKING_DIRECTORY_MISSING_CODE, isWorkingDirectoryMissingError } from '../../shared/worker-runtime/working-directory.mjs';
 
 /**
  * The only module in the repo that imports `@cursor/sdk` (and its
@@ -422,6 +423,19 @@ export function classifyCursorError(error) {
   const message = String(error?.message || error);
   const isRetryable = error?.isRetryable === true;
   const name = String(error?.name || '');
+  // The conversation's folder is gone; the message names it.
+  if (isWorkingDirectoryMissingError(error)) {
+    return {
+      isAuth: false,
+      isBusy: false,
+      isRetryable: false,
+      code: WORKING_DIRECTORY_MISSING_CODE,
+      stableCode: `cursor.${WORKING_DIRECTORY_MISSING_CODE}`,
+      message,
+      text: message,
+      guidance: error.guidance,
+    };
+  }
   if (isTurnStalledError(error)) {
     return {
       isAuth: false,
@@ -611,12 +625,13 @@ const modelParameterDefsCache = new Map();
 
 /**
  * Map the composer's reasoning effort onto the model params Cursor expects on
- * `agent.send`. Effort lives in a per-model parameter named 'effort' or
- * 'reasoning' ('extra-high' is Cursor's spelling of 'xhigh'); models that also
- * expose a boolean 'thinking' parameter only honor the higher tiers with
- * thinking enabled, so an explicit effort turns thinking on and 'none' turns it
- * off. Best-effort like readModelContextWindow: null on any failure or when the
- * model has no matching parameter, which sends the model's default variant.
+ * `agent.send`. Effort lives in a per-model parameter named 'effort',
+ * 'reasoning' or 'reasoning_effort', consulted in that order ('extra-high' is
+ * Cursor's spelling of 'xhigh'); models that also expose a boolean 'thinking'
+ * parameter only honor the higher tiers with thinking enabled, so an explicit
+ * effort turns thinking on and 'none' turns it off. Best-effort like
+ * readModelContextWindow: null on any failure or when the model has no
+ * matching parameter, which sends the model's default variant.
  */
 export async function resolveCursorReasoningParams({
   apiKey,
@@ -651,7 +666,7 @@ export async function resolveCursorReasoningParams({
   const paramsById = new Map(
     parameters.map((param) => [String(param?.id || '').trim().toLowerCase(), param]),
   );
-  const effortParam = paramsById.get('effort') || paramsById.get('reasoning');
+  const effortParam = paramsById.get('effort') || paramsById.get('reasoning') || paramsById.get('reasoning_effort');
   const hasThinkingParam = paramsById.has('thinking');
   const effortValues = new Set(
     (Array.isArray(effortParam?.values) ? effortParam.values : [])

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/app/settings-modal.js

@@ -1502,6 +1502,11 @@ const WINDOWS_BOOT_CUSTOMISATION_LABELS = Object.freeze({
   'boot-delay': 'boot delay',
   launcher: 'launcher edited or from an older OAR',
   'launcher-missing': 'launcher missing',
+  user: 'account',
+  'run-level': 'run level',
+  settings: 'settings',
+  other: 'other parts',
+  unreadable: 'unreadable',
 });
 
 function windowsAutostartStatusText() {
@@ -1511,21 +1516,30 @@ function windowsAutostartStatusText() {
   }
   if (boot?.lastError) return boot.lastError;
   if (boot?.readError) return `The boot task could not be read: ${boot.readError}`;
+  const [startupEntry] = windowsAutostartState?.signinHandMade || [];
+  if (startupEntry) {
+    const starts = startupEntry.otherInstall ? ` (it starts the OAR install in ${startupEntry.otherInstall})` : '';
+    return `A Startup entry OAR did not make is there: ${startupEntry.path}${starts}. OAR leaves it as it is; to replace it, keeping a copy: oar autostart signin --replace.`;
+  }
   if (windowsAutostartState?.mode === 'boot' && windowsAutostartState?.signinEnabled) {
     return 'A sign-in Startup entry also exists and can double-start the relay. Re-select "At system startup" to clean it up.';
   }
+  // OAR never deletes or writes over an entry it did not make (as `oar autostart`).
+  const replaceHint = 'OAR leaves it as it is; to replace it, keeping a copy: oar autostart boot --replace';
   if (windowsAutostartState?.mode === 'boot' && boot?.customised) {
     const labels = (boot.customisations || []).map((name) => WINDOWS_BOOT_CUSTOMISATION_LABELS[name] || name);
-    return `The boot task or its launcher differs from what OAR generates (${labels.join(', ')}). Re-selecting "At system startup" regenerates both and keeps a changed launcher as a .bak copy.`;
+    return boot.handMade?.length
+      ? `The boot task or its launcher was changed by hand (${labels.join(', ')}). ${replaceHint}.`
+      : `The boot task or its launcher differs from what OAR generates (${labels.join(', ')}). Re-selecting "At system startup" regenerates it.`;
   }
   if (windowsAutostartState?.mode === 'boot' && boot?.launcherBackupPath) {
     return `The previous launcher was replaced and kept as ${boot.launcherBackupPath}.`;
   }
   if (boot?.taskStatus === 'foreign') {
-    return `A task named "${boot.taskName}" exists but was not created by OAR. Selecting "At system startup" replaces it.`;
+    return `A task named "${boot.taskName}" exists but was not created by OAR. ${replaceHint}.`;
   }
   if (boot?.legacyTaskPresent && windowsAutostartState?.mode !== 'boot') {
-    return 'A pre-rebrand boot task exists. Selecting "At system startup" migrates it (one admin confirmation).';
+    return `A pre-rebrand boot task exists. ${replaceHint}.`;
   }
   return '';
 }

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) {