@oar-sh/oar 0.9.10 → 0.9.12

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

@@ -3,6 +3,11 @@ import path from 'path';
 import { execFile, spawn } from 'child_process';
 
 import { resolveOarRoot } from './oar-state-migration-service.mjs';
+import {
+  describeExecError,
+  describeSpawnEnvironment,
+  windowsSystemToolPath,
+} from '../../shared/windows-system-tools.mjs';
 import {
   LEGACY_WINDOWS_AUTOSTART_FILENAME,
   WINDOWS_AUTOSTART_FILENAME,
@@ -40,7 +45,13 @@ export const LEGACY_BOOT_TASK_NAME = 'copilot-remote-relay';
 export const BOOT_LAUNCHER_FILENAME = 'oar-web-relay-launcher.cmd';
 export const BOOT_TASK_XML_FILENAME = 'oar-relay-task.xml';
 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;
+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;
 
 function normalizeText(value) {
   return String(value == null ? '' : value).trim();
@@ -58,6 +69,19 @@ 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.
+ *
+ * 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
+ * version manager's folder, an entry that refers to an unexpanded variable),
+ * 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.
  */
 export function buildBootLauncherScript({
   packageRoot,
@@ -78,10 +102,12 @@ export function buildBootLauncherScript({
   }
   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))}"`,
   ];
   if (normalizeText(configPath)) {
     lines.push(`set "COPILOT_WEB_RELAY_CONFIG=${escapeBatchValue(pathImpl.resolve(configPath))}"`);
@@ -90,13 +116,36 @@ export function buildBootLauncherScript({
     ? 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(pathImpl.resolve(nodePath))}" "${escapeBatchValue(serverPath)}"`,
+    `"${escapeBatchValue(resolvedNodePath)}" "${escapeBatchValue(serverPath)}"`,
     '',
   );
   return lines.join('\r\n');
 }
 
+function unescapeXml(value) {
+  return String(value)
+    .replaceAll('"', '"')
+    .replaceAll(''', "'")
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&');
+}
+
 /**
  * Task Scheduler XML, settings ported verbatim from the proven manual task.
  * The S4U principal is registered by SID, not account name: a by-name
@@ -176,17 +225,64 @@ export function parseTaskXml(xmlText) {
   const text = String(xmlText == null ? '' : xmlText);
   const grab = (tag) => {
     const match = text.match(new RegExp(`<${tag}>([^<]*)</${tag}>`));
-    return match ? match[1].trim() : null;
+    return match ? unescapeXml(match[1]).trim() : null;
   };
+  const bootTrigger = text.match(/<BootTrigger>([\s\S]*?)<\/BootTrigger>/);
+  const bootDelay = bootTrigger ? (bootTrigger[1].match(/<Delay>([^<]*)<\/Delay>/)?.[1]?.trim() || null) : null;
   return {
     command: grab('Command'),
     argumentsLine: grab('Arguments'),
     workingDirectory: grab('WorkingDirectory'),
     logonType: grab('LogonType'),
     userId: grab('UserId'),
+    hasBootTrigger: Boolean(bootTrigger),
+    bootDelay,
   };
 }
 
+function sameText(a, b) {
+  return normalizeText(a).toLowerCase() === normalizeText(b).toLowerCase();
+}
+
+// Windows paths: no case, either slash, no trailing separator.
+function samePath(a, b) {
+  const normalize = (value) => normalizeText(value).replaceAll('/', '\\').replace(/\\+$/, '').toLowerCase();
+  return normalize(a) === normalize(b);
+}
+
+/**
+ * How a task that runs our launcher differs from the one buildBootTaskXml
+ * registers, as short names (empty when it does not). Only what the generated
+ * XML sets is compared: Task Scheduler adds its own defaults on export, and
+ * the run level, for one, is not set by OAR.
+ */
+export function describeTaskCustomisations(xmlText, { launcherPath, workingDirectory } = {}) {
+  const parsed = parseTaskXml(xmlText);
+  const differences = [];
+  if (!sameText(parsed.command, 'C:\\Windows\\System32\\cmd.exe')
+    || normalizeText(parsed.argumentsLine).replace(/\s+/g, ' ').toLowerCase()
+      !== `/d /c "${normalizeText(launcherPath)}"`.toLowerCase()) {
+    differences.push('action');
+  }
+  if (normalizeText(workingDirectory) && !samePath(parsed.workingDirectory, workingDirectory)) {
+    differences.push('working-directory');
+  }
+  if (!sameText(parsed.logonType, 'S4U')) differences.push('logon-type');
+  if (!parsed.hasBootTrigger) differences.push('trigger');
+  else if (!sameText(parsed.bootDelay, 'PT30S')) differences.push('boot-delay');
+  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);
+}
+
 /**
  * Ours or someone else's? A task counts as ours when its action runs our
  * launcher path; anything else under our name is `foreign` and the UI offers
@@ -206,23 +302,25 @@ export function classifyTaskXml(xmlText, { launcherPath } = {}) {
  * and nothing else — in one script, so one UAC covers the whole transition
  * out of any mixed state (legacy-named task, hand-made task, fresh install).
  */
-export function buildElevationScript({ action, xmlPath } = {}) {
+export function buildElevationScript({ action, xmlPath, schtasksPath = 'schtasks' } = {}) {
+  // PowerShell runs a quoted path only behind the call operator.
+  const schtasks = /[\\/]/.test(schtasksPath) ? `& "${schtasksPath}"` : schtasksPath;
   if (action === 'enable') {
     if (!normalizeText(xmlPath)) {
       throw new Error('The enable sweep needs the task XML path.');
     }
     return [
-      `schtasks /delete /tn "${LEGACY_BOOT_TASK_NAME}" /f 2>$null`,
-      `schtasks /delete /tn "${BOOT_TASK_NAME}" /f 2>$null`,
-      `schtasks /create /tn "${BOOT_TASK_NAME}" /xml "${xmlPath}"`,
+      `${schtasks} /delete /tn "${LEGACY_BOOT_TASK_NAME}" /f 2>$null`,
+      `${schtasks} /delete /tn "${BOOT_TASK_NAME}" /f 2>$null`,
+      `${schtasks} /create /tn "${BOOT_TASK_NAME}" /xml "${xmlPath}"`,
       'exit $LASTEXITCODE',
       '',
     ].join('\r\n');
   }
   if (action === 'disable') {
     return [
-      `schtasks /delete /tn "${BOOT_TASK_NAME}" /f 2>$null`,
-      `schtasks /delete /tn "${LEGACY_BOOT_TASK_NAME}" /f 2>$null`,
+      `${schtasks} /delete /tn "${BOOT_TASK_NAME}" /f 2>$null`,
+      `${schtasks} /delete /tn "${LEGACY_BOOT_TASK_NAME}" /f 2>$null`,
       'exit 0',
       '',
     ].join('\r\n');
@@ -236,13 +334,19 @@ export function parseSidFromWhoami(stdout) {
   return match ? match[1] : null;
 }
 
+// `startError` is set when the program did not run at all (not found, timed
+// out): unlike an exit code, that says nothing about the task.
 function defaultExecFileImpl(file, args) {
   return new Promise((resolve) => {
-    execFile(file, args, { windowsHide: true }, (error, stdout, stderr) => {
+    execFile(file, args, { windowsHide: true, timeout: QUERY_TIMEOUT_MS }, (error, stdout, stderr) => {
+      const exitCode = typeof error?.code === 'number' ? error.code : null;
       resolve({
-        code: error ? (typeof error.code === 'number' ? error.code : 1) : 0,
+        code: error ? (exitCode ?? 1) : 0,
         stdout: String(stdout || ''),
         stderr: String(stderr || ''),
+        startError: error && (exitCode === null || error.killed)
+          ? describeExecError(error)
+          : null,
       });
     });
   });
@@ -262,12 +366,16 @@ export function createWindowsBootAutostartService({
   clearTimeoutImpl = clearTimeout,
   now = () => Date.now(),
   logger = console,
+  // Full path of a Windows program (schtasks, whoami, powershell).
+  systemToolPath = (name) => windowsSystemToolPath(name, { env }),
 } = {}) {
   const supported = platform === 'win32';
   // One elevation in flight at a time; getState() reports it and the
   // completion callback resolves it.
   let pending = null; // { action, startedAt, timer, child }
   let lastError = null;
+  // The launcher an enable replaced, kept beside it (see requestEnable).
+  let launcherBackupPath = null;
 
   const oarRoot = () => resolveOarRoot(env, platform);
   const launcherPath = () => pathImpl.join(oarRoot(), BOOT_LAUNCHER_FILENAME);
@@ -278,9 +386,54 @@ export function createWindowsBootAutostartService({
     try { logger?.log?.(`[boot-autostart] ${message}`); } catch {}
   }
 
+  const tool = (name) => systemToolPath(name);
+
+  /**
+   * The task's XML, null when there is no such task, or `{ readError }` when
+   * schtasks itself could not run: that says nothing about the task, so it
+   * must not read as "missing".
+   */
   async function queryTaskXml(taskName) {
-    const result = await execFileImpl('schtasks', ['/query', '/tn', taskName, '/xml']);
-    return result.code === 0 ? result.stdout : null;
+    let result;
+    try {
+      result = await execFileImpl(tool('schtasks'), ['/query', '/tn', taskName, '/xml']);
+    } catch (error) {
+      result = { code: 1, stdout: '', stderr: '', startError: describeExecError(error) };
+    }
+    if (result?.startError) {
+      log(`schtasks /query ${taskName} did not run: ${result.startError}; ${describeSpawnEnvironment(env, platform)}`);
+      // The details stay in the log (they can name folders on the host).
+      return { readError: 'schtasks could not be run; the relay log has the details.' };
+    }
+    return result?.code === 0 ? result.stdout : null;
+  }
+
+  function readLauncher() {
+    try {
+      return fsImpl.existsSync(launcherPath()) ? String(fsImpl.readFileSync(launcherPath(), 'utf8')) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  function generatedLauncher() {
+    return buildBootLauncherScript({ packageRoot, nodePath, configPath, workingDirectory: oarRoot(), pathImpl });
+  }
+
+  /** What differs from the generated task and launcher, for a task that runs our launcher. */
+  function customisationsOf(xmlText) {
+    const differences = describeTaskCustomisations(xmlText, {
+      launcherPath: launcherPath(),
+      workingDirectory: oarRoot(),
+    });
+    const launcher = readLauncher();
+    if (launcher === null) differences.push('launcher-missing');
+    else {
+      try {
+        if (!launcherScriptsMatch(launcher, generatedLauncher())) differences.push('launcher');
+      } catch {}
+    }
+    return differences;
   }
 
   function startupCmdPaths() {
@@ -338,16 +491,29 @@ export function createWindowsBootAutostartService({
     }
     const ownXml = await queryTaskXml(BOOT_TASK_NAME);
     const legacyXml = await queryTaskXml(LEGACY_BOOT_TASK_NAME);
-    const taskStatus = ownXml === null
-      ? (legacyXml !== null ? 'legacy' : 'missing')
-      : classifyTaskXml(ownXml, { launcherPath: launcherPath() });
+    const readError = ownXml?.readError || null;
+    const legacyKnown = typeof legacyXml === 'string';
+    let taskStatus;
+    if (readError) taskStatus = 'unknown';
+    else if (ownXml === null) taskStatus = legacyKnown ? 'legacy' : 'missing';
+    else taskStatus = classifyTaskXml(ownXml, { launcherPath: launcherPath() });
+    // A task that runs our launcher but is not quite the one OAR registers (no
+    // boot delay, an edited launcher) still is boot mode; it is reported,
+    // never failed on.
+    const customisations = taskStatus === 'ready' ? customisationsOf(ownXml) : [];
+    let launcherPresent = false;
+    try { launcherPresent = fsImpl.existsSync(launcherPath()); } catch {}
     return {
       supported: true,
       platform,
       taskStatus,
       taskName: BOOT_TASK_NAME,
-      legacyTaskPresent: legacyXml !== null,
-      launcherPath: fsImpl.existsSync(launcherPath()) ? launcherPath() : null,
+      legacyTaskPresent: legacyKnown,
+      launcherPath: launcherPresent ? launcherPath() : null,
+      customised: customisations.length > 0,
+      customisations,
+      launcherBackupPath,
+      readError,
       pendingElevation: pending ? pending.action : null,
       lastError,
       manualCommand: manualCommandFor(pending?.action || 'enable'),
@@ -374,12 +540,13 @@ export function createWindowsBootAutostartService({
    * script, so its exit is the "elevation finished (or was declined)" signal.
    */
   function spawnElevated(action, onSettled) {
-    const child = spawnImpl('powershell.exe', [
+    const powershell = tool('powershell.exe');
+    const child = spawnImpl(powershell, [
       '-NoProfile',
       '-NonInteractive',
       '-Command',
       [
-        '$p = Start-Process -FilePath powershell.exe -Verb RunAs -Wait -PassThru -WindowStyle Hidden -ArgumentList',
+        `$p = Start-Process -FilePath '${powershell.replaceAll("'", "''")}' -Verb RunAs -Wait -PassThru -WindowStyle Hidden -ArgumentList`,
         `'-NoProfile','-ExecutionPolicy','Bypass','-File','${elevationScriptPath()}'`,
         '; exit $p.ExitCode',
       ].join(' '),
@@ -425,8 +592,24 @@ export function createWindowsBootAutostartService({
       return { ...(await getState()), accepted: false };
     }
     lastError = null;
-    writeFileAtomic(launcherPath(), buildBootLauncherScript({ packageRoot, nodePath, configPath, workingDirectory: oarRoot(), pathImpl }));
-    const who = await execFileImpl('whoami', ['/user', '/fo', 'csv']);
+    const launcher = generatedLauncher();
+    const previous = readLauncher();
+    if (previous !== null && !launcherScriptsMatch(previous, launcher)) {
+      // An edited (or older) launcher is replaced, but kept: one copy, the
+      // latest replaced one.
+      const backupPath = `${launcherPath()}${BOOT_LAUNCHER_BACKUP_SUFFIX}`;
+      try {
+        fsImpl.writeFileSync(backupPath, previous);
+        launcherBackupPath = backupPath;
+        log(`the launcher differed from the generated one; saved it as ${backupPath}`);
+      } catch (error) {
+        log(`could not save the current launcher as ${backupPath}: ${error?.message || error}`);
+        lastError = 'Could not keep a copy of the current launcher next to it, so it was not replaced; the relay log has the details.';
+        return { ...(await getState()), accepted: false };
+      }
+    }
+    writeFileAtomic(launcherPath(), launcher);
+    const who = await execFileImpl(tool('whoami'), ['/user', '/fo', 'csv']);
     const sid = parseSidFromWhoami(who.stdout);
     if (!sid) {
       lastError = 'Could not determine the current user SID (whoami /user failed).';
@@ -438,7 +621,7 @@ export function createWindowsBootAutostartService({
       packageRoot: pathImpl.resolve(String(packageRoot)),
       workingDirectory: oarRoot(),
     })));
-    writeFileAtomic(elevationScriptPath(), buildElevationScript({ action: 'enable', xmlPath: xmlPath() }));
+    writeFileAtomic(elevationScriptPath(), buildElevationScript({ action: 'enable', xmlPath: xmlPath(), schtasksPath: tool('schtasks') }));
     spawnElevated('enable', (ok) => {
       if (ok) {
         // Mutual exclusion: boot mode owns startup now, so the sign-in
@@ -463,7 +646,8 @@ export function createWindowsBootAutostartService({
       return { ...(await getState()), accepted: false };
     }
     lastError = null;
-    writeFileAtomic(elevationScriptPath(), buildElevationScript({ action: 'disable' }));
+    launcherBackupPath = null;
+    writeFileAtomic(elevationScriptPath(), buildElevationScript({ action: 'disable', schtasksPath: tool('schtasks') }));
     spawnElevated('disable', (ok) => {
       if (ok) {
         try {

package/shared/claude-background-command-limit.mjs

@@ -0,0 +1,83 @@
+// How long a backgrounded Bash command of a Claude session may run before
+// Claude Code stops it, when the agent passes no `timeout` of its own. The
+// CLI's own default is 30 minutes; long test or GPU runs were cut off there.
+//
+// Shared so the settings slider, the relay that stores the value and the
+// worker that hands it to the CLI agree on bounds, steps and formatting. The
+// browser mirrors the default in
+// server/public/app/claude-background-command-limit-options.mjs (only
+// server/public is served), and the slider's static markup in
+// server/public/index.html starts at it; unit tests pin both to this module.
+
+export const CLAUDE_BACKGROUND_COMMAND_LIMIT_MIN_MINUTES = 30;
+export const CLAUDE_BACKGROUND_COMMAND_LIMIT_MAX_MINUTES = 480;
+export const CLAUDE_BACKGROUND_COMMAND_LIMIT_STEP_MINUTES = 30;
+export const DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MINUTES = 120;
+
+/** Clamped to 30 min … 8 h and snapped to the slider's 30-minute steps. */
+export function normalizeClaudeBackgroundCommandLimitMinutes(value, fallback = DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MINUTES) {
+  if (value === null || value === undefined) return fallback;
+  if (typeof value === 'string' && value.trim() === '') return fallback;
+  if (typeof value !== 'number' && typeof value !== 'string') return fallback;
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  const step = CLAUDE_BACKGROUND_COMMAND_LIMIT_STEP_MINUTES;
+  const snapped = Math.round(numeric / step) * step;
+  return Math.min(
+    CLAUDE_BACKGROUND_COMMAND_LIMIT_MAX_MINUTES,
+    Math.max(CLAUDE_BACKGROUND_COMMAND_LIMIT_MIN_MINUTES, snapped),
+  );
+}
+
+export function claudeBackgroundCommandLimitMinutesToMs(minutes) {
+  return normalizeClaudeBackgroundCommandLimitMinutes(minutes) * 60_000;
+}
+
+export const DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MS = DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MINUTES * 60_000;
+
+/** An unset setting means "never configured", which is the default. */
+export function readClaudeBackgroundCommandLimitSetting(storedValue) {
+  const text = storedValue === null || storedValue === undefined ? '' : String(storedValue).trim();
+  return normalizeClaudeBackgroundCommandLimitMinutes(text);
+}
+
+export function parseClaudeBackgroundCommandLimitUpdate(value) {
+  const minutes = normalizeClaudeBackgroundCommandLimitMinutes(value, null);
+  if (minutes === null) return { ok: false, error: 'backgroundCommandLimitMinutes must be a number' };
+  return { ok: true, minutes };
+}
+
+export function formatClaudeBackgroundCommandLimitLabel(minutes) {
+  const normalized = normalizeClaudeBackgroundCommandLimitMinutes(minutes);
+  if (normalized < 60) return `${normalized} min`;
+  const hours = Math.floor(normalized / 60);
+  const remainder = normalized % 60;
+  return remainder ? `${hours} h ${remainder} min` : `${hours} h`;
+}
+
+/** The fields every Claude settings payload carries for the slider. */
+export function claudeBackgroundCommandLimitSettingsFields(settings = {}) {
+  return {
+    backgroundCommandLimitMinutes: normalizeClaudeBackgroundCommandLimitMinutes(settings?.backgroundCommandLimitMinutes),
+    backgroundCommandLimitMinMinutes: CLAUDE_BACKGROUND_COMMAND_LIMIT_MIN_MINUTES,
+    backgroundCommandLimitMaxMinutes: CLAUDE_BACKGROUND_COMMAND_LIMIT_MAX_MINUTES,
+    backgroundCommandLimitStepMinutes: CLAUDE_BACKGROUND_COMMAND_LIMIT_STEP_MINUTES,
+    backgroundCommandLimitDefaultMinutes: DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MINUTES,
+  };
+}
+
+/**
+ * What a delivery's `settings` does to the worker's limit (ms): an absent or
+ * junk key (an older relay) keeps the last known value; a present one is
+ * clamped like the setting itself.
+ */
+export function resolveDeliveredClaudeBackgroundCommandLimitMs(current, settings) {
+  const kept = Number.isFinite(Number(current)) && Number(current) > 0
+    ? claudeBackgroundCommandLimitMinutesToMs(Number(current) / 60_000)
+    : DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MS;
+  if (!settings || typeof settings !== 'object') return kept;
+  if (!Object.prototype.hasOwnProperty.call(settings, 'claudeBackgroundCommandLimitMs')) return kept;
+  const delivered = Number(settings.claudeBackgroundCommandLimitMs);
+  if (settings.claudeBackgroundCommandLimitMs === null || !Number.isFinite(delivered) || delivered <= 0) return kept;
+  return claudeBackgroundCommandLimitMinutesToMs(delivered / 60_000);
+}

package/shared/preview-tool-core.mjs

@@ -25,8 +25,10 @@ export const PREVIEW_TOOL_DESCRIPTION =
   + 'paths will not work. For plain files or a build output: pass {action:'
   + '"create", dir} instead and the relay serves the directory itself — no dev '
   + 'server needed. Always tell the user the returned URL and that the link is '
-  + 'public: anyone who has it can reach the app without logging in. Previews '
-  + 'never expire on their own; close them with {action:"close"} when the user '
+  + 'public: anyone who has it can reach the app without logging in. Publishing '
+  + 'the same port or directory again in this conversation returns the same '
+  + 'link. Previews never expire and survive a relay restart (a port preview '
+  + 'until the machine reboots); close them with {action:"close"} when the user '
   + 'is done.';
 
 export const PREVIEW_TOOL_INPUT_SCHEMA = {
@@ -126,6 +128,9 @@ export async function executePreviewTool(input, { api, conversationId = '' } = {
           target: entry.mode === 'static' ? entry.rootDir : `localhost:${entry.targetPort}`,
           online: entry.online,
           conversationId: entry.conversationId,
+          // Stored but not served: the relay could not check it after a
+          // restart and tries again. It can be closed.
+          ...(entry.unverified === true ? { unverified: true } : {}),
         })),
       };
     }
@@ -155,15 +160,20 @@ export async function executePreviewTool(input, { api, conversationId = '' } = {
       ...(parsed.port ? { port: parsed.port } : { dir: parsed.dir }),
     };
     const response = await api('POST', '/api/previews', body);
+    const existing = response?.existing === true;
+    const hint = parsed.port
+      ? `Serve the app under ${response?.basePath} (the proxy strips the prefix and sends X-Forwarded-Prefix). Tell the user the URL and that the link is public.`
+      : 'The directory is served as-is; relative asset paths work, root-absolute ones do not. Tell the user the URL and that the link is public.';
     return {
       ok: true,
+      existing,
       url: response?.url,
       basePath: response?.basePath,
       token: response?.preview?.token,
       mode: response?.preview?.mode || (parsed.port ? 'port' : 'static'),
-      hint: parsed.port
-        ? `Serve the app under ${response?.basePath} (the proxy strips the prefix and sends X-Forwarded-Prefix). Tell the user the URL and that the link is public.`
-        : 'The directory is served as-is; relative asset paths work, root-absolute ones do not. Tell the user the URL and that the link is public.',
+      hint: existing
+        ? `This conversation already publishes this ${parsed.port ? 'port' : 'directory'}: same link as before, label unchanged. ${hint}`
+        : hint,
     };
   } catch (error) {
     return { ok: false, error: String(error?.message || error) };

package/shared/remote-relay-contract.mjs

@@ -37,6 +37,7 @@ export const REMOTE_RELAY_ACTIONS = Object.freeze([
   'usage',
   'list_sessions',
   'read_session',
+  'read_task_output',
   'wait',
   'send',
   'create_session',
@@ -63,6 +64,7 @@ export const REMOTE_RELAY_ACTION_PERMISSION = Object.freeze({
   usage: 'read',
   list_sessions: 'read',
   read_session: 'read',
+  read_task_output: 'read',
   wait: 'read',
   send: 'prompt',
   create_session: 'full',
@@ -120,6 +122,11 @@ export const REMOTE_RELAY_LIMITS = Object.freeze({
   listMax: 100,
   readDefault: 10,
   readMax: 50,
+  // read_task_output: lines of a background task's output, and the most
+  // text one call returns.
+  taskOutputLinesDefault: 200,
+  taskOutputLinesMax: 500,
+  taskOutputBytesMax: 32 * 1024,
   maxCharsDefault: 12000,
   maxCharsMax: 50000,
   perMessageChars: 4000,
@@ -217,7 +224,9 @@ export const REMOTE_RELAY_TOOL_DESCRIPTION =
   + 'with cwd, provider "claude-cloud" with repo and an optional branch), then wait for and read '
   + 'each one. The first create_session here shows the user an approval card once per '
   + 'conversation. A session you created cannot create sessions itself, and every session '
-  + 'runs on the relay owner\'s accounts, so start only what the task needs. A new session '
+  + 'runs on the relay owner\'s accounts, so start only what the task needs. Sessions you start '
+  + 'here are grouped under this session in the owner\'s sidebar; list_sessions and read_session '
+  + 'show the group (read-only for agents, the owner arranges groups). A new session '
   + 'knows nothing of this conversation: write a self-contained prompt, and for '
   + '"claude-cloud" (a sandbox with a fresh clone of the repository) name the branch to '
   + 'work on and to push. '
@@ -233,6 +242,9 @@ export const REMOTE_RELAY_TOOL_DESCRIPTION =
   + 'usage reports what the provider plans of a relay have left (Copilot, Claude, Claude Cloud, Cursor, Grok: '
   + 'meters with used, allowance, remaining, utilization and reset time; providers not set up or not tracked say so) '
   + 'and whether a Claude usage limit has paused turns there, before you start work that costs. '
+  + 'read_task_output {session, task_id} reads the end of a background shell or Monitor task\'s output there '
+  + '(task ids from read_session\'s tasks; also for an hour after the task ended): the last lines, minutes '
+  + 'since its last output, and pass/fail counts when it is a test run; credentials are scrubbed. '
   + 'Event subscriptions: subscribe to sessions of this relay or of a paired relay (ids, or "all" for every '
   + 'session there, later ones too) and the relay wakes you with a message when something happens there: '
   + 'question_asked (with the question and its options), error (failed turn, usage limit, worker died), '
@@ -261,7 +273,8 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
       type: 'string',
       enum: [...REMOTE_RELAY_ACTIONS],
       description: 'list_relays: the relays (this one included when allowed) and whether each is unlocked here. relay_info: providers, models, '
-        + 'workspaces of a relay. usage: what each provider\'s plan has left there and any usage-limit pause. list_sessions / read_session: discover and read sessions. send: prompt an '
+        + 'workspaces of a relay. usage: what each provider\'s plan has left there and any usage-limit pause. list_sessions / read_session: discover and read sessions. '
+        + 'read_task_output: the end of a background shell task\'s output. send: prompt an '
         + 'existing session. create_session: start a new session with a first prompt. wait: keep waiting for '
         + 'a reply. answer_question: answer a question the remote agent asked. stop: stop the running turn. '
         + 'archive: archive a session. subscribe / unsubscribe / list_subscriptions / transfer_subscriptions: '
@@ -369,6 +382,13 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
     subscription_id: { type: 'string', description: 'unsubscribe: the id subscribe returned, or "all".' },
     watcher: { type: 'string', description: 'list_subscriptions: another conversation\'s id, to see its subscriptions (default: this one).' },
     from: { type: 'string', description: 'transfer_subscriptions: the id of the conversation whose subscriptions move here.' },
+    task_id: { type: 'string', description: 'read_task_output: the background task\'s id (taskId in read_session\'s tasks).' },
+    lines: {
+      type: 'integer',
+      minimum: 1,
+      maximum: REMOTE_RELAY_LIMITS.taskOutputLinesMax,
+      description: `read_task_output: how many of the last output lines (default ${REMOTE_RELAY_LIMITS.taskOutputLinesDefault}).`,
+    },
   },
   required: ['action'],
 });
@@ -388,7 +408,7 @@ function invalid(error) {
   return { ok: false, code: REMOTE_RELAY_ERROR_CODES.invalidInput, error };
 }
 
-const SESSION_ACTIONS = new Set(['read_session', 'wait', 'send', 'stop', 'archive']);
+const SESSION_ACTIONS = new Set(['read_session', 'read_task_output', 'wait', 'send', 'stop', 'archive']);
 
 /**
  * The longest wait a relay may be set to allow, from whatever was stored or
@@ -493,6 +513,18 @@ export function validateRemoteRelayToolInput(input = {}, { maxWaitSeconds } = {}
     args.max_chars = maxChars;
     args.include_activity = input?.include_activity === true || toText(input?.include_activity).toLowerCase() === 'true';
     optionalText('before', 1000);
+  } else if (action === 'read_task_output') {
+    const taskId = toText(input?.task_id);
+    if (!taskId) return invalid('read_task_output needs task_id (a taskId from read_session\'s tasks)');
+    if (taskId.length > 200 || /[\s/\\]/.test(taskId)) return invalid('task_id is not a task id');
+    args.task_id = taskId;
+    const lines = clampInteger(input?.lines, {
+      min: 1,
+      max: REMOTE_RELAY_LIMITS.taskOutputLinesMax,
+      fallback: REMOTE_RELAY_LIMITS.taskOutputLinesDefault,
+    });
+    if (lines === null) return invalid('lines must be a number');
+    args.lines = lines;
   } else if (action === 'wait') {
     const messageId = toText(input?.message_id);
     if (!messageId) return invalid('wait needs message_id (from send or create_session)');

package/shared/share-path-privacy.mjs

@@ -0,0 +1,30 @@
+// What a shared conversation shows of the relay host's paths and file names.
+// One relay-wide setting; the owner's own view is never filtered. Shared so the
+// settings route, the share routes and the Settings control agree.
+
+export const SHARE_PATH_PRIVACY_SETTING_KEY = 'share_path_privacy';
+
+export const SHARE_PATH_PRIVACY_MODES = Object.freeze(['show', 'filename', 'hide']);
+export const DEFAULT_SHARE_PATH_PRIVACY_MODE = 'filename';
+
+export const SHARE_PATH_PRIVACY_LABELS = Object.freeze({
+  show: 'Show every path and file name',
+  filename: 'Hide the path, show the file name',
+  hide: 'Hide paths and file names',
+});
+
+function asMode(value) {
+  const mode = String(value ?? '').trim().toLowerCase();
+  return SHARE_PATH_PRIVACY_MODES.includes(mode) ? mode : null;
+}
+
+/** An unset or unreadable setting means the default, never "show". */
+export function readSharePathPrivacySetting(storedValue) {
+  return asMode(storedValue) || DEFAULT_SHARE_PATH_PRIVACY_MODE;
+}
+
+export function parseSharePathPrivacyUpdate(value) {
+  const mode = asMode(value);
+  if (!mode) return { ok: false, error: `mode must be one of ${SHARE_PATH_PRIVACY_MODES.join(', ')}` };
+  return { ok: true, mode };
+}