@oar-sh/oar 0.9.12 → 0.9.14

package/server/services/windows-boot-autostart-service.mjs

@@ -3,6 +3,7 @@ import path from 'path';
 import { execFile, spawn } from 'child_process';
 
 import { resolveOarRoot } from './oar-state-migration-service.mjs';
+import { resolveLayoutStateDirs, resolveRelayStateDirs } from './oar-state-layout.mjs';
 import {
   describeExecError,
   describeSpawnEnvironment,
@@ -11,8 +12,14 @@ import {
 import {
   LEGACY_WINDOWS_AUTOSTART_FILENAME,
   WINDOWS_AUTOSTART_FILENAME,
+  autostartWaitLines,
+  buildLauncherFile,
   escapeBatchValue,
+  launcherNodeLine,
+  launcherScriptsMatch,
+  readLauncherNodePath,
   resolveWindowsStartupDirectory,
+  stateDirLines,
 } from './windows-autostart-service.mjs';
 
 /**
@@ -48,7 +55,8 @@ export const BOOT_ELEVATION_SCRIPT_FILENAME = 'oar-relay-elevate.ps1';
 // Where a regenerated launcher keeps the one it replaced, when they differ.
 export const BOOT_LAUNCHER_BACKUP_SUFFIX = '.bak';
 const ELEVATION_TIMEOUT_MS = 120_000;
-export const BOOT_TEMP_WAIT_SECONDS = 120;
+// Next to the launcher: a wait for TEMP and the data drive that ran out (see
+// autostartWaitLines; AUTOSTART_WAIT_SECONDS is the limit).
 export const BOOT_LAUNCHER_LOG_FILENAME = 'oar-web-relay-launcher.log';
 // Each schtasks query; the settings page waits on two of them.
 const QUERY_TIMEOUT_MS = 6_000;
@@ -69,6 +77,8 @@ function escapeXml(value) {
 /**
  * The launcher the task executes. Same shape as the sign-in .cmd minus the
  * `title` line: a boot task runs in session 0 where no console is ever shown.
+ * Like it, the launcher pins the config and the data and log folders `oar
+ * start` uses, so both start the same relay.
  *
  * Node's folder goes at the end of PATH. The relay itself runs on the
  * absolute path below, but a boot task's PATH can lack the user's Node (a
@@ -76,65 +86,142 @@ function escapeXml(value) {
  * and the CLIs and commands the workers start may call a bare `node`. At the
  * end it only matters when PATH has no Node of its own.
  *
- * Before Node starts, the launcher waits up to BOOT_TEMP_WAIT_SECONDS for the
- * %TEMP% folder: at boot it can live on a drive that a startup script creates
- * only after the task has fired, and Node, the workers and their CLIs then
- * fail creating their temp files. It costs nothing when the folder is there,
- * is skipped when TEMP is not set, and a wait that runs out is logged to
- * BOOT_LAUNCHER_LOG_FILENAME next to the launcher before Node starts anyway.
+ * Before Node starts it waits for %TEMP% and the data drive (autostartWaitLines),
+ * logging a wait that ran out to BOOT_LAUNCHER_LOG_FILENAME beside it.
  */
+const BOOT_LAUNCHER_HEADER = [
+  '@echo off',
+  'rem Generated by OAR settings (system-startup autostart). Regenerated on',
+  'rem every settings change - do not edit by hand.',
+];
+
+function bootLauncherInputs({ packageRoot, nodePath, workingDirectory, pathImpl }) {
+  if (!normalizeText(packageRoot)) {
+    throw new Error('Windows boot autostart requires the package root.');
+  }
+  if (!normalizeText(nodePath)) {
+    throw new Error('Windows boot autostart requires the Node.js executable path.');
+  }
+  const resolvedPackageRoot = pathImpl.resolve(String(packageRoot));
+  return {
+    serverPath: pathImpl.join(resolvedPackageRoot, 'server', 'server.js'),
+    resolvedNodePath: pathImpl.resolve(nodePath),
+    cwdTarget: normalizeText(workingDirectory)
+      ? pathImpl.resolve(String(workingDirectory))
+      : resolvedPackageRoot,
+  };
+}
+
+function configLines(configPath, pathImpl) {
+  return normalizeText(configPath)
+    ? [`set "COPILOT_WEB_RELAY_CONFIG=${escapeBatchValue(pathImpl.resolve(configPath))}"`]
+    : [];
+}
+
+// 0.9.11 to 0.9.13's wait (%TEMP% only, 120 s), verbatim, so a refresh knows it.
+const EARLIER_BOOT_TEMP_WAIT_LINES = [
+  'if "%TEMP%"=="" goto oar_start',
+  'set /a OAR_TEMP_WAIT=0',
+  ':oar_wait_temp',
+  'if exist "%TEMP%\\" goto oar_start',
+  'if %OAR_TEMP_WAIT% geq 120 goto oar_temp_missing',
+  '"%SystemRoot%\\System32\\ping.exe" -n 2 127.0.0.1 >nul',
+  'set /a OAR_TEMP_WAIT+=1',
+  'goto oar_wait_temp',
+  ':oar_temp_missing',
+  `echo [%DATE% %TIME%] "%TEMP%" still missing after 120 s; starting the relay anyway.>>"%~dp0${BOOT_LAUNCHER_LOG_FILENAME}"`,
+  ':oar_start',
+  'set "OAR_TEMP_WAIT="',
+];
+
+// The boot launcher's lines after the padding, with the wait and the Node
+// line's ending given (see launcherNodeLine).
+function bootBodyLines({ resolvedNodePath, serverPath, cwdTarget, configPath, dataDir, logDir, pathImpl, waitLines, nodeLineOptions = {} }) {
+  return [
+    `set "PATH=%PATH%;${escapeBatchValue(pathImpl.dirname(resolvedNodePath))}"`,
+    ...configLines(configPath, pathImpl),
+    ...stateDirLines({ dataDir, logDir, pathImpl }),
+    ...waitLines,
+    `cd /d "${escapeBatchValue(cwdTarget)}"`,
+    launcherNodeLine(resolvedNodePath, serverPath, nodeLineOptions),
+  ];
+}
+
 export function buildBootLauncherScript({
   packageRoot,
   nodePath = process.execPath,
   configPath = '',
+  dataDir = '',
+  logDir = '',
   // Where the relay process lives, NOT where its code lives: on Windows a
   // process pins its cwd, and self-update must be able to replace the package
   // directory. Callers pass the OAR state root; the package-root default only
   // serves builders that predate self-update.
   workingDirectory = '',
+  // Size of the file this one replaces (see buildLauncherFile).
+  coverBytes = 0,
   pathImpl = path,
 } = {}) {
-  if (!normalizeText(packageRoot)) {
-    throw new Error('Windows boot autostart requires the package root.');
-  }
-  if (!normalizeText(nodePath)) {
-    throw new Error('Windows boot autostart requires the Node.js executable path.');
-  }
-  const resolvedPackageRoot = pathImpl.resolve(String(packageRoot));
-  const serverPath = pathImpl.join(resolvedPackageRoot, 'server', 'server.js');
-  const resolvedNodePath = pathImpl.resolve(nodePath);
-  const lines = [
-    '@echo off',
-    'rem Generated by OAR settings (system-startup autostart). Regenerated on',
-    'rem every settings change - do not edit by hand.',
-    `set "PATH=%PATH%;${escapeBatchValue(pathImpl.dirname(resolvedNodePath))}"`,
+  const { serverPath, resolvedNodePath, cwdTarget } = bootLauncherInputs({ packageRoot, nodePath, workingDirectory, pathImpl });
+  return buildLauncherFile({
+    headerLines: BOOT_LAUNCHER_HEADER,
+    bodyLines: bootBodyLines({
+      resolvedNodePath,
+      serverPath,
+      cwdTarget,
+      configPath,
+      dataDir,
+      logDir,
+      pathImpl,
+      waitLines: autostartWaitLines({ dataDir, logTarget: `"%~dp0${BOOT_LAUNCHER_LOG_FILENAME}"`, pathImpl }),
+    }),
+    coverBytes,
+  });
+}
+
+/**
+ * The launchers earlier versions generated, newest first: the padded one
+ * before 0.9.14 shipped (120 s TEMP wait, `& exit /b`; needs `dataDir` and
+ * `logDir`), 0.9.11 to 0.9.13, then 0.9.2 to 0.9.10.
+ */
+export function buildEarlierBootLauncherScripts({
+  packageRoot,
+  nodePath,
+  configPath = '',
+  dataDir = '',
+  logDir = '',
+  workingDirectory = '',
+  pathImpl = path,
+} = {}) {
+  const { serverPath, resolvedNodePath, cwdTarget } = bootLauncherInputs({ packageRoot, nodePath, workingDirectory, pathImpl });
+  const nodeLine = `"${escapeBatchValue(resolvedNodePath)}" "${escapeBatchValue(serverPath)}"`;
+  const cdLine = `cd /d "${escapeBatchValue(cwdTarget)}"`;
+  return [
+    buildLauncherFile({
+      headerLines: BOOT_LAUNCHER_HEADER,
+      bodyLines: bootBodyLines({
+        resolvedNodePath,
+        serverPath,
+        cwdTarget,
+        configPath,
+        dataDir,
+        logDir,
+        pathImpl,
+        waitLines: EARLIER_BOOT_TEMP_WAIT_LINES,
+        nodeLineOptions: { ending: 'exit /b' },
+      }),
+    }),
+    [
+      ...BOOT_LAUNCHER_HEADER,
+      `set "PATH=%PATH%;${escapeBatchValue(pathImpl.dirname(resolvedNodePath))}"`,
+      ...configLines(configPath, pathImpl),
+      ...EARLIER_BOOT_TEMP_WAIT_LINES,
+      cdLine,
+      nodeLine,
+      '',
+    ].join('\r\n'),
+    [...BOOT_LAUNCHER_HEADER, ...configLines(configPath, pathImpl), cdLine, nodeLine, ''].join('\r\n'),
   ];
-  if (normalizeText(configPath)) {
-    lines.push(`set "COPILOT_WEB_RELAY_CONFIG=${escapeBatchValue(pathImpl.resolve(configPath))}"`);
-  }
-  const cwdTarget = normalizeText(workingDirectory)
-    ? pathImpl.resolve(String(workingDirectory))
-    : resolvedPackageRoot;
-  lines.push(
-    // About one second a round: ping waits a second between its two echoes.
-    // By full path, since the PATH of an early boot may not lead to System32.
-    'if "%TEMP%"=="" goto oar_start',
-    'set /a OAR_TEMP_WAIT=0',
-    ':oar_wait_temp',
-    'if exist "%TEMP%\\" goto oar_start',
-    `if %OAR_TEMP_WAIT% geq ${BOOT_TEMP_WAIT_SECONDS} goto oar_temp_missing`,
-    '"%SystemRoot%\\System32\\ping.exe" -n 2 127.0.0.1 >nul',
-    'set /a OAR_TEMP_WAIT+=1',
-    'goto oar_wait_temp',
-    ':oar_temp_missing',
-    `echo [%DATE% %TIME%] "%TEMP%" still missing after ${BOOT_TEMP_WAIT_SECONDS} s; starting the relay anyway.>>"%~dp0${BOOT_LAUNCHER_LOG_FILENAME}"`,
-    ':oar_start',
-    'set "OAR_TEMP_WAIT="',
-    `cd /d "${escapeBatchValue(cwdTarget)}"`,
-    `"${escapeBatchValue(resolvedNodePath)}" "${escapeBatchValue(serverPath)}"`,
-    '',
-  );
-  return lines.join('\r\n');
 }
 
 function unescapeXml(value) {
@@ -273,15 +360,8 @@ export function describeTaskCustomisations(xmlText, { launcherPath, workingDirec
   return differences;
 }
 
-/** Same launcher, whatever the line endings and trailing blanks. */
-export function launcherScriptsMatch(actual, expected) {
-  const normalize = (value) => String(value == null ? '' : value)
-    .split(/\r?\n/)
-    .map((line) => line.replace(/\s+$/, ''))
-    .join('\n')
-    .trim();
-  return normalize(actual) === normalize(expected);
-}
+// Shared with the sign-in entry; still exported from here for its callers.
+export { launcherScriptsMatch };
 
 /**
  * Ours or someone else's? A task counts as ours when its action runs our
@@ -380,6 +460,7 @@ export function createWindowsBootAutostartService({
   const oarRoot = () => resolveOarRoot(env, platform);
   const launcherPath = () => pathImpl.join(oarRoot(), BOOT_LAUNCHER_FILENAME);
   const xmlPath = () => pathImpl.join(oarRoot(), BOOT_TASK_XML_FILENAME);
+  const serverPath = () => pathImpl.join(pathImpl.resolve(String(packageRoot || '')), 'server', 'server.js');
   const elevationScriptPath = () => pathImpl.join(oarRoot(), BOOT_ELEVATION_SCRIPT_FILENAME);
 
   function log(message) {
@@ -416,8 +497,49 @@ export function createWindowsBootAutostartService({
     }
   }
 
-  function generatedLauncher() {
-    return buildBootLauncherScript({ packageRoot, nodePath, configPath, workingDirectory: oarRoot(), pathImpl });
+  function generatedLauncher({ stateDirs, coverBytes = 0, nodePathOverride = null } = {}) {
+    return buildBootLauncherScript({
+      packageRoot,
+      nodePath: nodePathOverride || nodePath,
+      configPath,
+      ...(stateDirs || resolveRelayStateDirs({ packageRoot, env, platform, fsImpl, pathImpl })),
+      workingDirectory: oarRoot(),
+      coverBytes,
+      pathImpl,
+    });
+  }
+
+  /**
+   * Brings a launcher an earlier version wrote (see
+   * buildEarlierBootLauncherScripts) up to date; the relay calls this once it
+   * runs. The task runs the launcher file, so this needs no elevation. Only a
+   * launcher exactly as that version generated it for this install and its
+   * config is rewritten, keeping the Node it runs; an edited one stays (it
+   * reads as customised, and enabling again replaces it, keeping a copy). It
+   * pins only the install's own folders (resolveLayoutStateDirs). True when
+   * it rewrote the launcher.
+   */
+  // `onEarlierForm`: the earlier form found (`pinnedData` false: package database).
+  function refreshInstalledLauncher({ onEarlierForm } = {}) {
+    if (!supported || spawnsDisabled()) return false;
+    const stateDirs = resolveLayoutStateDirs({ packageRoot, env, platform, fsImpl, pathImpl });
+    if (!stateDirs) return false;
+    const current = readLauncher();
+    if (current === null) return false;
+    const launcherNodePath = readLauncherNodePath(current, serverPath());
+    if (!launcherNodePath) return false;
+    const earlier = buildEarlierBootLauncherScripts({
+      packageRoot, nodePath: launcherNodePath, configPath, ...stateDirs, workingDirectory: oarRoot(), pathImpl,
+    });
+    const matched = earlier.find((script) => launcherScriptsMatch(current, script, { ignoreCase: true }));
+    if (!matched) return false;
+    onEarlierForm?.({ path: launcherPath(), pinnedData: matched.includes('COPILOT_WEB_RELAY_DATA_DIR') });
+    writeFileAtomic(launcherPath(), generatedLauncher({
+      stateDirs,
+      nodePathOverride: launcherNodePath,
+      coverBytes: Buffer.byteLength(current, 'utf8'),
+    }));
+    return true;
   }
 
   /** What differs from the generated task and launcher, for a task that runs our launcher. */
@@ -430,7 +552,12 @@ export function createWindowsBootAutostartService({
     if (launcher === null) differences.push('launcher-missing');
     else {
       try {
-        if (!launcherScriptsMatch(launcher, generatedLauncher())) differences.push('launcher');
+        // Against the Node the launcher runs, as the repair keeps it: a moved
+        // Node is no customisation.
+        const ownNodePath = readLauncherNodePath(launcher, serverPath());
+        if (!launcherScriptsMatch(launcher, generatedLauncher({ nodePathOverride: ownNodePath }))) {
+          differences.push('launcher');
+        }
       } catch {}
     }
     return differences;
@@ -608,7 +735,7 @@ export function createWindowsBootAutostartService({
         return { ...(await getState()), accepted: false };
       }
     }
-    writeFileAtomic(launcherPath(), launcher);
+    writeFileAtomic(launcherPath(), generatedLauncher({ coverBytes: previous === null ? 0 : Buffer.byteLength(previous, 'utf8') }));
     const who = await execFileImpl(tool('whoami'), ['/user', '/fo', 'csv']);
     const sid = parseSidFromWhoami(who.stdout);
     if (!sid) {
@@ -667,5 +794,6 @@ export function createWindowsBootAutostartService({
     getState,
     requestEnable,
     requestDisable,
+    refreshInstalledLauncher,
   };
 }

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