@oar-sh/oar 0.9.13 → 0.9.15

package/shared/preview-instructions.mjs

@@ -15,40 +15,45 @@ const DEFAULT_TTL_MS = 6 * 60 * 60 * 1000;
 
 /**
  * Resolves the instruction block for this relay, or '' when the preview lane
- * is off. Preview settings only change on relay restart, so the answer is
- * cached: this must not become a per-turn HTTP call.
+ * is off. Preview settings only change on relay restart, so the lane facts are
+ * cached: this must not become a per-turn HTTP call. The block itself is
+ * rendered per call for `{ conversationId }`, the conversation it is sent to,
+ * so the API calls it teaches are scoped to that conversation.
  */
 export function createPreviewInstructionsProvider({
   api,
   ttlMs = DEFAULT_TTL_MS,
   now = () => Date.now(),
 } = {}) {
-  let cachedText = '';
+  // null: the lane is off; else its public base URL.
+  let cachedLane = null;
   let cachedUntil = 0;
   let inFlight = null;
 
   async function load() {
     const response = await api('GET', '/api/previews');
-    const text = response?.enabled === true
-      ? renderPreviewInstructionBlock({ publicBaseUrl: response?.publicBaseUrl || '' })
-      : '';
-    cachedText = text;
+    const lane = response?.enabled === true ? { publicBaseUrl: response?.publicBaseUrl || '' } : null;
+    cachedLane = lane;
     cachedUntil = now() + ttlMs;
-    return text;
+    return lane;
   }
 
-  return async function getPreviewInstructions() {
+  function render(lane, conversationId) {
+    return lane ? renderPreviewInstructionBlock({ publicBaseUrl: lane.publicBaseUrl, conversationId }) : '';
+  }
+
+  return async function getPreviewInstructions({ conversationId = '' } = {}) {
     if (typeof api !== 'function') return '';
-    if (cachedUntil > now()) return cachedText;
+    if (cachedUntil > now()) return render(cachedLane, conversationId);
     if (!inFlight) {
       // A failed lookup is deliberately not cached, and yields no block: an
       // unreachable relay must neither lose the capability for the rest of the
       // process nor advertise one that would 503.
       inFlight = load()
-        .catch(() => '')
+        .catch(() => null)
         .finally(() => { inFlight = null; });
     }
-    return inFlight;
+    return render(await inFlight, conversationId);
   };
 }
 

package/shared/preview-tool-core.mjs

@@ -15,9 +15,9 @@ export const PREVIEW_TOOL_NAME = 'preview';
 
 export const PREVIEW_TOOL_DESCRIPTION =
   '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. '
+  + '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 '
@@ -37,7 +37,7 @@ export const PREVIEW_TOOL_INPUT_SCHEMA = {
     action: {
       type: 'string',
       enum: ['create', 'list', 'close'],
-      description: 'create: publish a port or directory. list: live previews. close: unpublish one.',
+      description: 'create: publish a port or directory. list: this conversation\'s live previews. close: unpublish one of them.',
     },
     port: {
       type: 'integer',
@@ -114,10 +114,19 @@ export async function executePreviewTool(input, { api, conversationId = '' } = {
   if (typeof api !== 'function') return { ok: false, error: 'Preview API unavailable in this worker' };
   const parsed = validatePreviewToolInput(input);
   if (!parsed.ok) return parsed;
+  // list and close reach only this conversation's previews: a preview's token
+  // is its only credential. The relay enforces the same scope for every
+  // request that names a conversation (routes/preview-routes.mjs). A create
+  // without one would land in no conversation's scope, so it is refused too.
+  const conversation = toText(conversationId);
+  const scope = `conversationId=${encodeURIComponent(conversation)}`;
+  if (!conversation) {
+    return { ok: false, error: 'This tool call is not bound to a conversation; it cannot publish, list or close previews' };
+  }
 
   try {
     if (parsed.action === 'list') {
-      const response = await api('GET', '/api/previews');
+      const response = await api('GET', `/api/previews?${scope}`);
       return {
         ok: true,
         enabled: response?.enabled === true,
@@ -138,7 +147,7 @@ export async function executePreviewTool(input, { api, conversationId = '' } = {
     if (parsed.action === 'close') {
       let token = parsed.token;
       if (!token) {
-        const response = await api('GET', `/api/previews?conversationId=${encodeURIComponent(conversationId)}`);
+        const response = await api('GET', `/api/previews?${scope}`);
         const live = response?.previews || [];
         if (live.length === 0) return { ok: false, error: 'No live previews in this conversation' };
         if (live.length > 1) {
@@ -150,12 +159,14 @@ export async function executePreviewTool(input, { api, conversationId = '' } = {
         }
         token = live[0].token;
       }
-      const response = await api('DELETE', `/api/previews/${token}`);
+      // Another conversation's token is refused by the relay (403); its
+      // message comes back as the answer.
+      const response = await api('DELETE', `/api/previews/${token}?${scope}`);
       return { ok: true, closed: { token, label: response?.preview?.label || null } };
     }
 
     const body = {
-      conversationId,
+      conversationId: conversation,
       label: parsed.label || undefined,
       ...(parsed.port ? { port: parsed.port } : { dir: parsed.dir }),
     };
@@ -176,26 +187,33 @@ export async function executePreviewTool(input, { api, conversationId = '' } = {
         : hint,
     };
   } catch (error) {
-    return { ok: false, error: String(error?.message || error) };
+    // A scope refusal (403) in its own words, without the HTTP wrapper.
+    const refusal = Number(error?.status) === 403 ? toText(error?.detail) : '';
+    return { ok: false, error: refusal || String(error?.message || error) };
   }
 }
 
 /**
  * The instruction block for providers without a custom-tool surface. Generated
  * from the same description/schema strings the tool uses; keep any wording
- * change up in the constants, never here.
+ * change up in the constants, never here. `conversationId` is the conversation
+ * the block is sent to: written into every call, so the model's natural call
+ * is the scoped one (without it, a plain GET would list the whole relay).
  */
-export function renderPreviewInstructionBlock({ publicBaseUrl = '' } = {}) {
+export function renderPreviewInstructionBlock({ publicBaseUrl = '', conversationId = '' } = {}) {
   const base = toText(publicBaseUrl) || 'https://<preview-host>';
+  const id = toText(conversationId);
+  const conv = id ? JSON.stringify(id).slice(1, -1) : '<conv>';
+  const convQuery = id ? encodeURIComponent(id) : '<conv>';
   return `## Preview servers
 
 ${PREVIEW_TOOL_DESCRIPTION}
 
 There is no \`${PREVIEW_TOOL_NAME}\` tool on this provider — use the authenticated localhost API (same auth as /api/relay/shutdown):
 
-- Publish a running dev server: \`POST /api/previews\` with \`{ "conversationId": "<conv>", "port": 5173, "label": "web app" }\` → \`{ "url": "${base}/test_<token>/", "basePath": "/test_<token>/" }\`. Register FIRST, then start the server under the returned basePath.
-- Publish files without a server: \`POST /api/previews\` with \`{ "conversationId": "<conv>", "dir": "./dist", "label": "built site" }\` — the relay serves the directory itself. \`dir\` must live inside the conversation's workspace root.
-- List: \`GET /api/previews\` (\`?conversationId=\` filters). Close: \`DELETE /api/previews/:token\` — closes the link only, never the dev server behind it.
+- Publish a running dev server: \`POST /api/previews\` with \`{ "conversationId": "${conv}", "port": 5173, "label": "web app" }\` → \`{ "url": "${base}/test_<token>/", "basePath": "/test_<token>/" }\`. Register FIRST, then start the server under the returned basePath.
+- Publish files without a server: \`POST /api/previews\` with \`{ "conversationId": "${conv}", "dir": "./dist", "label": "built site" }\` — the relay serves the directory itself. \`dir\` must live inside the conversation's workspace root.
+- List this conversation's previews: \`GET /api/previews?conversationId=${convQuery}\`. Close one: \`DELETE /api/previews/:token?conversationId=${convQuery}\` — closes the link only, never 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 to the user. A 400 names exactly what was refused (relay-owned port, non-loopback host, dir outside the workspace root).`;
 }

package/shared/question-answer-rule.mjs

@@ -0,0 +1,63 @@
+// What an answer to a question card means, in one place. The relay's answer
+// route (a card that takes no typed text accepts only its choices), the card
+// view (no reply box on such a card; server/public/app/question-answer-rule.mjs
+// is its browser copy) and every reader of an approve / deny
+// card (OAR's own remote-relay approvals, Claude Cloud's and Copilot's
+// permission cards) apply the same rule: an answer is a choice when it equals
+// the choice's label trimmed and in any case.
+
+function answerKey(value) {
+  return String(value ?? '').trim().toLowerCase();
+}
+
+/** The card's own label for `answer`, or null when it is none of `choices`. */
+export function matchQuestionChoice(answer, choices) {
+  const key = answerKey(answer);
+  if (!key || !Array.isArray(choices)) return null;
+  for (const choice of choices) {
+    const label = String(choice ?? '').trim();
+    if (label && answerKey(label) === key) return label;
+  }
+  return null;
+}
+
+/**
+ * An approve / deny card's answer: 'approve' for its approve choice, 'deny'
+ * for its deny choice, null for anything else. A caller decides what null
+ * means for its card; it is never the user's plain Deny.
+ */
+export function readApprovalAnswer(answer, { approve, deny }) {
+  const key = answerKey(answer);
+  if (!key) return null;
+  if (key === answerKey(approve)) return 'approve';
+  if (key === answerKey(deny)) return 'deny';
+  return null;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * The answer a card that takes no typed text accepts, as the card's labels:
+ * one choice, or on a multi-select card several, ", "-joined the way the card
+ * sends them. null when the answer is not made of the card's choices.
+ */
+export function closedQuestionAnswer({ choices, multiSelect = false } = {}, answer) {
+  const single = matchQuestionChoice(answer, choices);
+  if (single || !multiSelect) return single;
+  const labels = [];
+  for (const part of String(answer ?? '').split(',')) {
+    const label = matchQuestionChoice(part, choices);
+    if (!label) return null;
+    if (!labels.includes(label)) labels.push(label);
+  }
+  return labels.length ? labels.join(', ') : null;
+}

package/shared/relay-events.mjs

@@ -37,7 +37,12 @@ export const RELAY_EVENT_HEARTBEAT_TYPE = 'heartbeat';
 export const RELAY_EVENT_LINK_LOST_TYPE = 'link_lost';
 export const RELAY_EVENT_LINK_RESTORED_TYPE = 'link_restored';
 const LINK_EVENT_TYPES = Object.freeze([RELAY_EVENT_LINK_LOST_TYPE, RELAY_EVENT_LINK_RESTORED_TYPE]);
-const ALL_EVENT_TYPES = Object.freeze([...RELAY_EVENT_TYPES, RELAY_EVENT_HEARTBEAT_TYPE, ...LINK_EVENT_TYPES]);
+// An event of this relay, not of a session: its runtime started again. Only
+// a subscription that names it gets it (never the default), and one that
+// names nothing else needs no sessions.
+export const RELAY_EVENT_RELAY_RESTARTED_TYPE = 'relay_restarted';
+export const RELAY_EVENT_RELAY_LEVEL_TYPES = Object.freeze([RELAY_EVENT_RELAY_RESTARTED_TYPE]);
+const ALL_EVENT_TYPES = Object.freeze([...RELAY_EVENT_TYPES, RELAY_EVENT_HEARTBEAT_TYPE, ...LINK_EVENT_TYPES, ...RELAY_EVENT_RELAY_LEVEL_TYPES]);
 
 // Not an event of its own but a narrower task_finished a subscription can
 // name: the end of a task other than a shell command (a sub-agent's). Its
@@ -46,19 +51,28 @@ const ALL_EVENT_TYPES = Object.freeze([...RELAY_EVENT_TYPES, RELAY_EVENT_HEARTBE
 // whole context; a failed one is still a task_failed.
 export const RELAY_EVENT_SUBAGENT_FINISHED_TYPE = 'subagent_finished';
 
-// What `events` may name: the event types and the narrower subagent_finished.
+// What `events` may name: the event types, the narrower subagent_finished
+// and the relay's own relay_restarted.
 export const RELAY_EVENT_SUBSCRIBABLE_TYPES = Object.freeze([
   ...RELAY_EVENT_TYPES.slice(0, RELAY_EVENT_TYPES.indexOf('task_finished') + 1),
   RELAY_EVENT_SUBAGENT_FINISHED_TYPE,
   ...RELAY_EVENT_TYPES.slice(RELAY_EVENT_TYPES.indexOf('task_finished') + 1),
+  ...RELAY_EVENT_RELAY_LEVEL_TYPES,
 ]);
 
 // What a subscription gets when it names no events: everything but the
 // start of a task, and of the task ends that went well only a sub-agent's
 // (subagent_finished, not task_finished): the start of a task and every
-// shell command's end a watcher asks for explicitly.
+// shell command's end a watcher asks for explicitly. relay_restarted is
+// never a default: a wake-up after each restart is asked for by name.
 export const RELAY_EVENT_DEFAULT_TYPES = Object.freeze(RELAY_EVENT_SUBSCRIBABLE_TYPES
-  .filter((type) => type !== 'task_started' && type !== 'task_finished'));
+  .filter((type) => type !== 'task_started' && type !== 'task_finished' && !RELAY_EVENT_RELAY_LEVEL_TYPES.includes(type)));
+
+/** Whether `events` names relay-level events only (then no sessions are needed). */
+export function isRelayLevelOnly(types) {
+  const list = (Array.isArray(types) ? types : []).map(toText).filter(Boolean);
+  return list.length > 0 && list.every((type) => RELAY_EVENT_RELAY_LEVEL_TYPES.includes(type));
+}
 
 // The default before subagent_finished: every type but task_started. A
 // subscription made without events stored exactly this list.
@@ -249,11 +263,47 @@ function taskOutcome(detail) {
   return parts.join(', ');
 }
 
+/** `2026-10-20 14:05 UTC`, or '' for a time that does not parse. */
+function utcMinute(value) {
+  const ms = Date.parse(String(value || ''));
+  return Number.isFinite(ms) ? `${new Date(ms).toISOString().slice(0, 16).replace('T', ' ')} UTC` : '';
+}
+
+// The end of a relay_restarted line: what the agent should do, and the loop
+// guard said up front (services/relay-event-service.mjs noteRelayStarted).
+export const RELAY_RESTARTED_ADVICE = 'Timers and jobs your CLI scheduled before may be gone: check what you were waiting for and carry on. '
+  + 'A restart requested while this turn runs does not wake you again.';
+
+function relayRestartedLine(prefix, detail) {
+  const startedAt = utcMinute(detail.startedAt);
+  const stoppedAt = utcMinute(detail.stoppedAt);
+  const requestedAt = utcMinute(detail.requestedAt);
+  const since = `${prefix}${RELAY_EVENT_RELAY_RESTARTED_TYPE}: the relay runs again${startedAt ? ` since ${startedAt}` : ''}`;
+  if (detail.stop !== 'requested' && detail.stop !== 'stopped') {
+    // No record: a crash, a forced stop (on Windows a supervisor's stop ends
+    // the process without its signal handler) or a reboot.
+    return `${since}; the relay did not record how it stopped (for example a crash, a forced stop or a reboot). ${RELAY_RESTARTED_ADVICE}`;
+  }
+  let how;
+  if (detail.stop === 'requested') {
+    const action = oneLine(detail.action, 20) === 'shutdown' ? 'shutdown' : 'restart';
+    const by = oneLine(detail.requestedBy, 80);
+    const reason = oneLine(detail.reason, 140);
+    how = `after a ${action} requested${by ? ` by ${quote(by, 80)}` : ''}${requestedAt ? ` at ${requestedAt}` : ''}`
+      + `${reason ? ` (reason ${quote(reason, 140)})` : ''}`;
+  } else {
+    const reason = oneLine(detail.reason, 140);
+    how = `after it was stopped${reason ? ` (${reason.replace(/[()]/g, '')})` : ''}${stoppedAt ? ` at ${stoppedAt}` : ''}`;
+  }
+  return `${since}, ${how}. ${RELAY_RESTARTED_ADVICE}`;
+}
+
 /** One line of the event message, the watcher's to read. */
 export function formatRelayEventLine(event) {
   const type = oneLine(event?.type, 40);
   const detail = event?.detail && typeof event.detail === 'object' ? event.detail : {};
   const prefix = linePrefix(event);
+  if (type === RELAY_EVENT_RELAY_RESTARTED_TYPE) return relayRestartedLine(prefix, detail);
   if (type === RELAY_EVENT_LINK_LOST_TYPE) {
     const since = oneLine(detail.since, 40);
     return `${prefix}${type}: no answer from relay ${quote(relayDisplayName(event), 60)}${since ? ` since ${since}` : ''}; your subscriptions there saw nothing meanwhile`;

package/shared/remote-relay-contract.mjs

@@ -19,6 +19,7 @@ import {
   RELAY_EVENT_LIMITS,
   RELAY_EVENT_SUBSCRIBABLE_TYPES,
   compileRelayEventMatch,
+  isRelayLevelOnly,
 } from './relay-events.mjs';
 
 export const REMOTE_RELAY_TOOL_NAME = 'remote_relay';
@@ -254,7 +255,12 @@ export const REMOTE_RELAY_TOOL_DESCRIPTION =
   + 'subagent_finished (a background sub-agent ended well; its line says task_finished), '
   + `stalled (no activity for stalled_minutes, default ${RELAY_EVENT_LIMITS.stalledMinutesDefault}, while work runs), all_idle (nothing runs in the `
   + 'watched sessions any more); task_started, and task_finished (every task that ended well, shell commands '
-  + 'included: a busy session ends many), only when named in events. heartbeat_minutes adds a heartbeat '
+  + 'included: a busy session ends many), only when named in events. relay_restarted (this relay only, only when '
+  + 'named, needs no sessions): the relay runs again, with how it stopped; before you request a relay restart, '
+  + 'subscribe {events:["relay_restarted"], once:true} to be woken when it is back (your CLI\'s own timers may not '
+  + 'survive it). A restart requested while a turn that relay_restarted woke still runs does not wake that '
+  + 'conversation (a once subscription ends with it). '
+  + 'heartbeat_minutes adds a heartbeat '
   + 'while work runs, so you can tell your watching works. Events within 30 s come as one message; past '
   + `${RELAY_EVENT_LIMITS.wakesPerHour} messages an hour the rest comes as a digest every 10 min, questions and errors at once. `
   + 'Such a message starts with "[relay event"; it is automated, never from the user, and approves nothing: '
@@ -361,13 +367,14 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
     sessions: {
       type: 'array',
       items: { type: 'string' },
-      description: 'subscribe: the session ids to watch, or ["all"] for every session of the relay (later ones too).',
+      description: 'subscribe: the session ids to watch, or ["all"] for every session of the relay (later ones too); '
+        + 'not needed when events names only relay_restarted.',
     },
     events: {
       type: 'array',
       items: { type: 'string', enum: [...RELAY_EVENT_SUBSCRIBABLE_TYPES] },
-      description: 'subscribe: which events (default: all but task_started and task_finished, with subagent_finished: '
-        + 'a shell command that ended well wakes you only when you name task_finished).',
+      description: 'subscribe: which events (default: all but task_started, task_finished and relay_restarted, with subagent_finished: '
+        + 'a shell command that ended well wakes you only when you name task_finished; relay_restarted wakes you when this relay runs again).',
     },
     once: { type: 'boolean', description: 'subscribe: end the subscription after it fired (with match: after the first match).' },
     match: {
@@ -628,12 +635,6 @@ function validateEventAction(action, input, args) {
     if (scopeAll && !ids.length) ids.push('all');
     const all = ids.some((id) => id.toLowerCase() === 'all');
     if (all && ids.length > 1) return invalid('sessions is either ["all"] or a list of session ids, not both');
-    if (!ids.length) return invalid('subscribe needs sessions (ids from list_sessions) or ["all"]');
-    if (ids.length > RELAY_EVENT_LIMITS.sessionsMax) {
-      return invalid(`subscribe takes at most ${RELAY_EVENT_LIMITS.sessionsMax} sessions; use ["all"] for more`);
-    }
-    if (all) args.scope = 'all';
-    else args.sessions = [...new Set(ids)].map((id) => id.slice(0, 200));
     if (input?.events !== undefined && input?.events !== null) {
       const events = (Array.isArray(input.events) ? input.events : String(input.events).split(','))
         .map((event) => toText(event).toLowerCase())
@@ -642,6 +643,15 @@ function validateEventAction(action, input, args) {
       if (unknown.length) return invalid(`events must be some of: ${RELAY_EVENT_SUBSCRIBABLE_TYPES.join(', ')} (not ${unknown.join(', ')})`);
       if (events.length) args.events = [...new Set(events)];
     }
+    // relay_restarted alone watches no session.
+    if (!ids.length && !isRelayLevelOnly(args.events)) {
+      return invalid('subscribe needs sessions (ids from list_sessions) or ["all"], unless events names only relay_restarted');
+    }
+    if (ids.length > RELAY_EVENT_LIMITS.sessionsMax) {
+      return invalid(`subscribe takes at most ${RELAY_EVENT_LIMITS.sessionsMax} sessions; use ["all"] for more`);
+    }
+    if (all) args.scope = 'all';
+    else if (ids.length) args.sessions = [...new Set(ids)].map((id) => id.slice(0, 200));
     if (input?.once === true || toText(input?.once).toLowerCase() === 'true') args.once = true;
     const match = String(input?.match ?? '');
     if (match.trim()) {

package/shared/subagent-timeline.mjs

@@ -16,6 +16,10 @@ export const SUBAGENT_TIMELINE_ENTRY_MAX_CHARS = 256 * 1024;
 
 export const SUBAGENT_TIMELINE_TOOL_NAME_MAX_CHARS = 200;
 
+// Background task types that are a sub-agent run, with a model of its own
+// (vs. a shell, monitor or workflow): the run a task panel row opens.
+export const SUBAGENT_TASK_TYPES = new Set(['local_agent', 'agent', 'subagent']);
+
 export function isSubagentTimelineKind(kind) {
   return SUBAGENT_TIMELINE_KINDS.includes(String(kind || ''));
 }

package/shared/windows-system-tools.mjs

@@ -33,6 +33,31 @@ export function readEnvValue(env, name) {
   return '';
 }
 
+/**
+ * On Windows, TEMP and TMP as the relay and its children get them: without
+ * surrounding quotes (`"D:\My Temp"` puts PowerShell into ConstrainedLanguage
+ * mode), and a folder that is not there replaced by the user's own temp
+ * folder. Changes `env` in place; returns what changed, for one log line.
+ */
+export function normalizeTempEnv({ env = process.env, platform = process.platform, existsImpl = fs.existsSync } = {}) {
+  if (platform !== 'win32') return [];
+  const local = readEnvValue(env, 'LOCALAPPDATA') || (readEnvValue(env, 'USERPROFILE') && path.win32.join(readEnvValue(env, 'USERPROFILE'), 'AppData', 'Local'));
+  const fallback = local ? path.win32.join(local, 'Temp') : '';
+  const changes = [];
+  for (const name of ['TEMP', 'TMP']) {
+    const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name);
+    if (!key) continue;
+    const before = String(env[key]);
+    let value = before.trim().replace(/^"(.*)"$/, '$1').trim();
+    if ((!path.win32.isAbsolute(value) || !existsImpl(value)) && fallback && existsImpl(fallback)) value = fallback;
+    if (value !== before) {
+      env[key] = value;
+      changes.push(`${name} ${before} -> ${value}`);
+    }
+  }
+  return changes;
+}
+
 /** The key PATH is stored under in `env` (`Path` on most Windows machines). */
 export function envPathKey(env, platform = process.platform) {
   if (env && typeof env === 'object') {

package/shared/worker-runtime/config-loader.mjs

@@ -2,6 +2,9 @@ import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 
+import { RESCUE_DIR_NAME } from "../../server/services/earlier-database-service.mjs";
+import { resolveRelayStateDirs, resolveStateLayout } from "../../server/services/oar-state-layout.mjs";
+
 function toAbsolutePath(value) {
   if (!value) return "";
   return path.isAbsolute(value) ? value : path.resolve(process.cwd(), value);
@@ -12,15 +15,21 @@ function looksLikeServerDir(serverDir) {
   return fs.existsSync(path.join(serverDir, "server.js")) && fs.existsSync(path.join(serverDir, "config.json"));
 }
 
-export function resolveRelayPaths(importMetaUrl) {
+/**
+ * Where the extension finds the relay, its config and logs. A global install
+ * uses the state root's folders as `oar start` does, and `RELAY_ENV` pins
+ * them for the managed relay (not `server/data`, which `npm i -g` deletes).
+ * The environment wins; a checkout keeps its `server/` folders.
+ */
+export function resolveRelayPaths(importMetaUrl, { env = process.env, platform = process.platform } = {}) {
   const __dirname = path.dirname(fileURLToPath(importMetaUrl));
   const projectServerDir = path.resolve(__dirname, "../../../server");
   const cwdServerDir = path.resolve(process.cwd(), "server");
-  const envRoot = toAbsolutePath(process.env.COPILOT_WEB_RELAY_ROOT || "");
-  const envServerDir = toAbsolutePath(process.env.COPILOT_WEB_RELAY_SERVER_DIR || "");
-  const envConfigPath = toAbsolutePath(process.env.COPILOT_WEB_RELAY_CONFIG || "");
-  const envToolsPath = toAbsolutePath(process.env.COPILOT_WEB_RELAY_TOOLS || "");
-  const envLogDir = toAbsolutePath(process.env.COPILOT_WEB_RELAY_LOG_DIR || "");
+  const envRoot = toAbsolutePath(env.COPILOT_WEB_RELAY_ROOT || "");
+  const envServerDir = toAbsolutePath(env.COPILOT_WEB_RELAY_SERVER_DIR || "");
+  const envConfigPath = toAbsolutePath(env.COPILOT_WEB_RELAY_CONFIG || "");
+  const envToolsPath = toAbsolutePath(env.COPILOT_WEB_RELAY_TOOLS || "");
+  const envLogDir = toAbsolutePath(env.COPILOT_WEB_RELAY_LOG_DIR || "");
 
   const resolvedServerDir =
     (looksLikeServerDir(envServerDir) && envServerDir) ||
@@ -30,11 +39,23 @@ export function resolveRelayPaths(importMetaUrl) {
     projectServerDir;
 
   const SERVER_DIR = resolvedServerDir;
-  const CONFIG_PATH = envConfigPath || path.resolve(SERVER_DIR, "config.json");
+  const packageRoot = path.dirname(SERVER_DIR);
+  const layout = resolveStateLayout({ packageRoot, env, platform });
+  const stateDirs = layout.checkout ? null : resolveRelayStateDirs({ packageRoot, env, platform, layout });
+  const CONFIG_PATH = envConfigPath
+    || (stateDirs ? path.join(layout.configDir, "config.json") : path.resolve(SERVER_DIR, "config.json"));
   const RELAY_TOOLS_PATH = envToolsPath || path.resolve(SERVER_DIR, "relay-tools.md");
-  const LOG_DIR = envLogDir || path.resolve(SERVER_DIR, "logs");
+  const LOG_DIR = envLogDir || stateDirs?.logDir || path.resolve(SERVER_DIR, "logs");
   const SERVER_LOG_PATH = path.resolve(LOG_DIR, "server.log");
   const SERVER_ERR_PATH = path.resolve(LOG_DIR, "server-err.log");
+  const RELAY_ENV = stateDirs
+    ? {
+      COPILOT_WEB_RELAY_ROOT: packageRoot,
+      COPILOT_WEB_RELAY_CONFIG: CONFIG_PATH,
+      COPILOT_WEB_RELAY_DATA_DIR: stateDirs.dataDir,
+      COPILOT_WEB_RELAY_LOG_DIR: LOG_DIR,
+    }
+    : {};
 
   return {
     __dirname,
@@ -44,9 +65,34 @@ export function resolveRelayPaths(importMetaUrl) {
     LOG_DIR,
     SERVER_LOG_PATH,
     SERVER_ERR_PATH,
+    RELAY_ENV,
   };
 }
 
+/**
+ * The package's `server/config.json` (or the newest rescued one) copied to the
+ * state root when it has none: copy only, never over one. Returns the source.
+ */
+export function carryOverPackageConfig({ serverDir, configPath, dataDir, fsImpl = fs } = {}) {
+  if (!configPath || !dataDir || fsImpl.existsSync(configPath)) return null;
+  const sources = [path.join(serverDir, "config.json")];
+  try {
+    const rescueRoot = path.join(dataDir, RESCUE_DIR_NAME);
+    for (const name of fsImpl.readdirSync(rescueRoot).filter((entry) => !entry.endsWith(".partial")).sort().reverse()) {
+      sources.push(path.join(rescueRoot, name, "config.json"));
+    }
+  } catch {}
+  const source = sources.find((file) => fsImpl.existsSync(file));
+  if (!source) return null;
+  try {
+    fsImpl.mkdirSync(path.dirname(configPath), { recursive: true });
+    fsImpl.copyFileSync(source, configPath, fs.constants.COPYFILE_EXCL);
+    return source;
+  } catch {
+    return null;
+  }
+}
+
 export function loadTokenFromConfig(configPath) {
   try {
     const cfg = loadRelayConfig(configPath);

package/shared/worker-runtime/prompt-context.mjs

@@ -99,7 +99,9 @@ export function createRelayPromptBuilder({
       // Guidance is advisory: a preview lookup that fails must cost the block,
       // never the turn.
       const previewBlock = typeof getPreviewInstructions === "function"
-        ? await Promise.resolve().then(getPreviewInstructions).catch(() => "")
+        ? await Promise.resolve()
+          .then(() => getPreviewInstructions({ conversationId: String(message?.conversationId || "") }))
+          .catch(() => "")
         : "";
       instructions = applyPreviewInstructions(toolInstructions, previewBlock);
     }

package/shared/worker-runtime/working-directory.mjs

@@ -0,0 +1,65 @@
+// The session's working directory, checked before a runtime is started in it.
+//
+// A session runs in the folder it was given (COPILOT_WORKSPACE_ROOT). When that
+// folder is gone (deleted, renamed, a drive unmounted), spawning a process in
+// it fails with ENOENT, the code a missing executable has too, and each SDK
+// takes it for that: the Claude Agent SDK reports a native binary that "exists
+// but failed to launch" and blames the libc, Grok's classifier a CLI that is
+// not installed. The workers check the folder before they start anything in
+// it, and put a launch error that happens while the folder is missing down to
+// the folder. A tmux launch does not catch it earlier: `tmux new-session -c`
+// falls back to the home folder, so the worker starts and only the folder in
+// its environment is wrong.
+
+import fs from 'node:fs';
+
+export const WORKING_DIRECTORY_MISSING_CODE = 'working-directory-missing';
+
+export const WORKING_DIRECTORY_GUIDANCE =
+  'Restore the folder, or choose another working directory for this conversation (⋯ → Change CWD), '
+  + 'then send the message again.';
+
+// What a failed launch says, in the words of the SDKs: Node's spawn error, the
+// Claude Agent SDK's own wording for it.
+const LAUNCH_FAILURE_TEXT = /\bENOENT\b|\bspawn\b|failed to launch|failed to spawn|not found at/i;
+
+/**
+ * The error a turn fails with when `cwd` cannot be worked in, or null when it
+ * can. Only an answer that the folder is not there counts: a folder that
+ * cannot be read (EACCES, a network drive that does not answer) is left to the
+ * launch, which says more about it than a guess would.
+ */
+export function missingWorkingDirectoryError(cwd, { statSync = fs.statSync } = {}) {
+  const folder = String(cwd || '').trim();
+  if (!folder) return null;
+  let stats = null;
+  try {
+    stats = statSync(folder);
+  } catch (error) {
+    if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') return null;
+  }
+  if (stats?.isDirectory()) return null;
+  const error = new Error(stats
+    ? `The working directory of this conversation is not a folder: ${folder}.`
+    : `The working directory of this conversation no longer exists: ${folder}.`);
+  error.code = WORKING_DIRECTORY_MISSING_CODE;
+  error.workingDirectory = folder;
+  error.guidance = WORKING_DIRECTORY_GUIDANCE;
+  return error;
+}
+
+export function isWorkingDirectoryMissingError(error) {
+  return error?.code === WORKING_DIRECTORY_MISSING_CODE;
+}
+
+/**
+ * A launch that failed while the folder is missing failed because of it: the
+ * folder's error in its place. Any other error, or one that does not look like
+ * a failed launch, is returned as it is.
+ */
+export function explainLaunchFailure(error, cwd, { check = missingWorkingDirectoryError } = {}) {
+  if (isWorkingDirectoryMissingError(error)) return error;
+  const text = `${error?.code || ''} ${error?.message || error || ''}`;
+  if (!LAUNCH_FAILURE_TEXT.test(text)) return error;
+  return check(cwd) || error;
+}