@oddessentials/agent-guild 0.26.0 → 0.27.0

package/src/manager/tailscale.mjs

@@ -0,0 +1,201 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { resolveCommand } from './command-resolver.mjs';
+import { parseAllowedHosts } from './access-policy.mjs';
+
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value);
+export const remoteError = (code, message, status = 409) => Object.assign(new Error(message), { code, status });
+
+export function findTailscale(env = process.env, platform = process.platform, exists = fs.existsSync) {
+  const onPath = resolveCommand(platform === 'win32' ? 'tailscale.exe' : 'tailscale', env, platform);
+  const candidates = [onPath];
+  if (platform === 'win32') {
+    for (const dir of [env.ProgramFiles, env['ProgramFiles(x86)'], 'C:\\Program Files']) {
+      if (dir) candidates.push(path.win32.join(dir, 'Tailscale', 'tailscale.exe'));
+    }
+  } else if (platform === 'darwin') {
+    candidates.push('/Applications/Tailscale.app/Contents/MacOS/Tailscale', '/usr/local/bin/tailscale', '/opt/homebrew/bin/tailscale');
+  } else candidates.push('/usr/bin/tailscale', '/usr/local/bin/tailscale');
+  return candidates.find((file) => file && (platform !== 'win32' || /\.exe$/i.test(file)) && exists(file)) || null;
+}
+
+export function approvalLink(output) {
+  for (const match of output.matchAll(/https:\/\/[^\s<>"']+/g)) {
+    try {
+      const url = new URL(match[0]);
+      if (url.hostname === 'login.tailscale.com' && !url.username && !url.password && !url.port) return url.href;
+    } catch {}
+  }
+  return null;
+}
+
+export function runTailscale(file, args, { env = process.env, signal, onApproval, timeout = 15000 } = {}) {
+  return new Promise((resolve, reject) => {
+    let output = '';
+    const child = execFile(file, args, {
+      env: { ...env, TAILSCALE_BE_CLI: '1' }, windowsHide: true, timeout, maxBuffer: 1024 * 1024, encoding: 'utf8', signal,
+    }, (error, stdout, stderr) => {
+      if (!error) return resolve(stdout);
+      const detail = `${stderr || ''}\n${stdout || ''}`.trim().slice(-2000);
+      const url = approvalLink(detail || output);
+      if (url) return reject(Object.assign(remoteError('approval_required', 'Approve HTTPS in Tailscale, then continue setup.'), { approvalUrl: url }));
+      if (/access denied|permission denied|must be.*(?:root|admin)|sudo tailscale|not permitted|serve config denied/i.test(detail)) {
+        return reject(remoteError('permission_required', 'Tailscale needs permission to configure remote access.'));
+      }
+      if (error.killed || error.code === 'ABORT_ERR') return reject(remoteError('tailscale_timeout', 'Tailscale did not finish. Check its connection and try again.'));
+      reject(remoteError('tailscale_error', detail || 'Could not communicate with Tailscale. Open Tailscale and check its connection.'));
+    });
+    const collect = (chunk) => {
+      output = (output + chunk).slice(-8192);
+      const url = approvalLink(output);
+      if (url) onApproval?.(url);
+    };
+    child.stdout?.on('data', collect);
+    child.stderr?.on('data', collect);
+  });
+}
+
+function parseJson(raw) {
+  let value;
+  try { value = JSON.parse(raw); } catch {}
+  if (value === null) return {};
+  if (!object(value)) throw remoteError('tailscale_response', 'Tailscale returned an unreadable status. Update Tailscale and try again.');
+  return value;
+}
+
+export function validateServeConfig(config) {
+  if (!object(config)) throw remoteError('tailscale_response', 'Tailscale returned an unreadable Serve configuration.');
+  for (const key of ['TCP', 'Web', 'AllowFunnel', 'Foreground', 'Services']) {
+    if (config[key] !== undefined && config[key] !== null && !object(config[key])) {
+      throw remoteError('tailscale_response', 'Tailscale returned an unsupported Serve configuration.');
+    }
+  }
+  for (const [port, value] of Object.entries(config.TCP || {})) {
+    if (!/^[1-9]\d{0,4}$/.test(port) || Number(port) > 65535 || !object(value)) {
+      throw remoteError('tailscale_response', 'Tailscale returned an unsupported TCP configuration.');
+    }
+  }
+  for (const value of Object.values(config.Web || {})) {
+    if (!object(value) || !object(value.Handlers) || Object.values(value.Handlers).some((handler) => !object(handler))) {
+      throw remoteError('tailscale_response', 'Tailscale returned an unsupported web configuration.');
+    }
+  }
+  if (Object.values(config.AllowFunnel || {}).some((value) => typeof value !== 'boolean')) {
+    throw remoteError('tailscale_response', 'Tailscale returned an unsupported Funnel configuration.');
+  }
+  for (const value of Object.values(config.Foreground || {})) {
+    if (!object(value) || value.Foreground) throw remoteError('tailscale_response', 'Tailscale returned an unsupported foreground configuration.');
+    validateServeConfig(value);
+  }
+  return config;
+}
+
+const ordered = (value) => Array.isArray(value) ? value.map(ordered)
+  : object(value) ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, ordered(value[key])])) : value;
+export const sameConfig = (a, b) => JSON.stringify(ordered(a)) === JSON.stringify(ordered(b));
+export const routeAuthority = (route) => `${route.host}:${route.port}`;
+export const routeUrl = (route) => `https://${route.host}${route.port === 443 ? '' : `:${route.port}`}`;
+
+function foregroundPort(config, port) {
+  return Object.values(config.Foreground || {}).some((entry) => entry.TCP?.[port] || Object.keys(entry.Web || {}).some((key) => key.endsWith(`:${port}`)));
+}
+
+export function portOccupied(config, port) {
+  return Boolean(config.TCP?.[port] || Object.keys(config.Web || {}).some((key) => key.endsWith(`:${port}`))
+    || Object.keys(config.AllowFunnel || {}).some((key) => key.endsWith(`:${port}`)) || foregroundPort(config, port));
+}
+
+export function routeMatches(config, route) {
+  const authority = routeAuthority(route);
+  const web = config.Web?.[authority];
+  const handler = web?.Handlers?.['/'];
+  if (!sameConfig(config.TCP?.[route.port], { HTTPS: true }) || !object(web) || !object(handler)
+    || Object.entries(config.AllowFunnel || {}).some(([key, value]) => value && key.endsWith(`:${route.port}`)) || foregroundPort(config, route.port)
+    || Object.keys(web.Handlers).length !== 1 || Object.keys(web).some((key) => key !== 'Handlers')
+    || Object.keys(handler).some((key) => key !== 'Proxy')
+    || Object.keys(config.Web || {}).some((key) => key !== authority && key.endsWith(`:${route.port}`))) return false;
+  try {
+    const target = new URL(handler.Proxy);
+    return target.origin === new URL(route.target).origin && target.pathname === '/' && !target.search && !target.hash && !target.username && !target.password;
+  } catch { return false; }
+}
+
+export function chooseRoute(info, target, previous = null) {
+  if (previous) {
+    if (previous.nodeId !== info.nodeId || previous.host !== info.host) {
+      throw remoteError('network_changed', 'This computer’s Tailscale identity or address changed. Disable the saved connection before setting up the new address.');
+    }
+    if (portOccupied(info.config, previous.port) && !routeMatches(info.config, previous)) {
+      throw remoteError('route_changed', 'The saved Tailscale route was changed outside Agent Guild. Review it in Tailscale before continuing.');
+    }
+    return { ...previous, target };
+  }
+  for (const key of Object.keys(info.config.TCP || {})) {
+    const port = Number(key);
+    const route = { nodeId: info.nodeId, host: info.host, port, target };
+    if (Number.isInteger(port) && port > 0 && port <= 65535 && routeMatches(info.config, route)) return route;
+  }
+  const port = [443, ...Array.from({ length: 32 }, (_, i) => 8443 + i)].find((candidate) => !portOccupied(info.config, candidate));
+  if (!port) throw remoteError('no_port', 'No available HTTPS port was found. Free a Serve port in Tailscale and try again.');
+  return { nodeId: info.nodeId, host: info.host, port, target };
+}
+
+export class Tailscale {
+  constructor({ env = process.env, platform = process.platform, find = findTailscale, run = runTailscale } = {}) {
+    Object.assign(this, { env, platform, find, run });
+  }
+
+  async command(args, options = {}) {
+    const file = this.find(this.env, this.platform);
+    if (!file) throw remoteError('not_installed', 'Install Tailscale on this computer to connect it to your network.');
+    return this.run(file, args, { env: this.env, ...options });
+  }
+
+  async inspect(options = {}) {
+    const version = (await this.command(['version'], options)).trim().split(/\s/)[0];
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+    if (!match || Number(match[1]) < 1 || (Number(match[1]) === 1 && Number(match[2]) < 52)) {
+      throw remoteError('update_required', 'Update Tailscale to version 1.52 or later to set up remote access.');
+    }
+    const status = parseJson(await this.command(['status', '--json', '--peers=false'], options));
+    if (!['Running', 'Starting'].includes(status.BackendState)) {
+      throw remoteError('not_connected', 'Open Tailscale and connect this computer to your network, then continue.');
+    }
+    const host = typeof status.Self?.DNSName === 'string' ? status.Self.DNSName.replace(/\.$/, '').toLowerCase() : null;
+    const nodeId = status.Self?.ID;
+    if (!host || typeof nodeId !== 'string' || !nodeId || !host.endsWith('.ts.net')) {
+      throw remoteError('address_unavailable', 'Tailscale has not assigned this computer an HTTPS address yet. Check its connection and MagicDNS settings.');
+    }
+    try { parseAllowedHosts(host); } catch { throw remoteError('address_unavailable', 'Tailscale returned an invalid HTTPS address.'); }
+    const config = validateServeConfig(parseJson(await this.command(['serve', 'status', '--json'], options)));
+    return { version, host, nodeId, config, httpsReady: Array.isArray(status.CertDomains) && status.CertDomains.includes(host) };
+  }
+
+  async enable(route, previous, options = {}) {
+    const before = await this.inspect(options);
+    if (before.nodeId !== route.nodeId || before.host !== route.host) throw remoteError('network_changed', 'Tailscale changed networks during setup. Check the connection and try again.');
+    if (routeMatches(before.config, route)) return;
+    if (portOccupied(before.config, route.port) && !(previous && routeMatches(before.config, previous))) {
+      throw remoteError('route_changed', 'The selected HTTPS port is now in use. Check the connection and try again.');
+    }
+    await this.command(['serve', '--bg', `--https=${route.port}`, '--set-path=/', route.target], { ...options, timeout: 30000 });
+    const after = await this.inspect(options);
+    if (after.nodeId !== route.nodeId || after.host !== route.host || !routeMatches(after.config, route)) {
+      throw remoteError('setup_incomplete', 'Tailscale has not finished setting up the private HTTPS route. Complete any approval, then continue.');
+    }
+  }
+
+  async remove(route, options = {}) {
+    const info = await this.inspect(options);
+    if (info.nodeId !== route.nodeId || info.host !== route.host) throw remoteError('network_changed', 'Connect Tailscale to the original network to remove its saved route.');
+    if (!portOccupied(info.config, route.port)) return info;
+    if (!routeMatches(info.config, route)) throw remoteError('route_changed', 'This Serve route was changed outside Agent Guild. It has been left in place; review it in Tailscale.');
+    await this.command(['serve', '--bg', `--https=${route.port}`, '--set-path=/', 'off'], options);
+    const after = await this.inspect(options);
+    if (after.nodeId !== route.nodeId || after.host !== route.host || portOccupied(after.config, route.port)) {
+      throw remoteError('cleanup_incomplete', 'The Serve route is still present. Check Tailscale and retry cleanup.');
+    }
+    return after;
+  }
+}

package/web/app.js

@@ -6,6 +6,7 @@ import { TerminalCopy } from './terminal-copy.js';
 import { topbarInline, dockMode, clampDockWidth, stageBesideDock, splitMode, clampRatio, bindSplitter, DOCK_MIN, SPLIT_RATIO_MIN } from './layout.js';
 import { highlightParts, rankRepos, recentFirst, remember, repoForOrigin, repoKey } from './repo-search.js';
 import { createActivityFavicon, isSessionWorking } from './activity-favicon.js';
+import { createRemoteAccessUI } from './remote-access.js';
 
 const TOKEN_KEY = 'agentGuild.token';
 const CWD_KEY = 'agentGuild.cwd';
@@ -120,6 +121,7 @@ function setConnection(kind, label) {
   el.title = label;
   // The manager can only be stopped, restarted or upgraded while the page can reach it.
   state.connected = kind === 'ok';
+  state.remoteAccessUI?.connectionChanged();
   $('manager').hidden = !state.connected;
   if (!state.connected) closeMenu($('manager-menu'));
   renderFolderTools();
@@ -4257,13 +4259,13 @@ class TerminalView {
   }
 
   connect() {
-    if (this.disposed) return;
+    if (this.disposed || state.remoteRevoked) return;
     const ws = new WebSocket(wsUrl(`/sessions/${this.id}/terminal`));
     this.ws = ws;
     ws.onopen = () => { this.retry = 0; this.sent = { cols: 0, rows: 0 }; this.sendSize(); };
     ws.onmessage = (event) => this.onMessage(JSON.parse(event.data));
     ws.onclose = (event) => {
-      if (this.disposed || event.code === 4404 || event.code === 4410) return;
+      if (this.disposed || event.code === 4403 || event.code === 4404 || event.code === 4410) return;
       const delay = Math.min(5000, 300 * 2 ** this.retry++);
       setTimeout(() => this.connect(), delay);
     };
@@ -4860,7 +4862,7 @@ function showManagerUnavailable() {
 }
 
 function connectEvents() {
-  if (state.pageAway) return;
+  if (state.pageAway || state.remoteRevoked) return;
   const ws = new WebSocket(wsUrl('/events'));
   state.eventsSocket = ws;
   ws.onopen = () => {
@@ -4881,6 +4883,7 @@ function connectEvents() {
       state.launcher = typeof msg.launcher === 'string' ? msg.launcher : null;
       state.folderOpener = msg.folderOpener || null;
       state.folderPicker = msg.folderPicker || null;
+      state.remoteAccessUI?.setAvailable(msg.remoteAccess);
       renderVersion();
       setConnection('ok', 'Connected to session manager');
       state.sessions = new Map(msg.sessions.map((s) => [s.id, s]));
@@ -4895,6 +4898,8 @@ function connectEvents() {
       // A changelog.updated sent while the socket was down is lost; catch up the open panel.
       if ($('changelog').open) loadChangelog();
       if (dockShows('github')) loadGitHub();
+    } else if (msg.type === 'remote-access.updated') {
+      state.remoteAccessUI?.updated();
     } else if (msg.type === 'news.updated') {
       loadNews();
     } else if (msg.type === 'github.updated') {
@@ -4921,8 +4926,15 @@ function connectEvents() {
       scheduleStats();
     }
   };
-  ws.onclose = () => {
+  ws.onclose = (event) => {
     if (state.pageAway || state.eventsSocket !== ws) return;
+    if (event?.code === 4403) {
+      state.remoteRevoked = true;
+      managerLoss.cancel();
+      state.remoteAccessUI?.close();
+      setConnection('down', 'Remote access changed. Your terminals are still running. Reopen an enabled address to reconnect.');
+      return;
+    }
     if (state.managerUnavailable) {
       showManagerUnavailable();
     } else if (state.stopping && state.stopRemaining !== null) {
@@ -4964,6 +4976,7 @@ let statsInterval;
 let newsTimer;
 
 function showAuth(message = '') {
+  state.remoteAccessUI?.setAvailable(null);
   managerLoss.cancel();
   closePanel();
   closeModels();
@@ -5380,5 +5393,6 @@ addEventListener('scroll', publishTopbarHeight, { passive: true });
 publishTopbarHeight();
 applyDockLayout();
 
+state.remoteAccessUI = createRemoteAccessUI({ api, getToken: () => state.token, isConnected: () => state.connected, onAuthError: showAuth });
 state.token = readTokenFromHash() || load(TOKEN_KEY);
 boot();

package/web/index.html

@@ -35,6 +35,7 @@
         <button id="notes-open" class="btn notes-open" type="button" aria-controls="dock" aria-pressed="false">Notes</button>
         <button id="settings" class="btn settings menu-button" type="button" popovertarget="settings-menu" aria-haspopup="dialog">Settings</button>
         <div id="settings-menu" class="settings-menu menu" popover role="dialog" aria-label="Settings">
+          <button id="remote-access-open" class="btn" type="button" aria-haspopup="dialog" hidden>Remote access</button>
           <fieldset id="skin-choices"><legend>Skin</legend></fieldset>
           <fieldset>
             <legend>Mode</legend>
@@ -259,6 +260,70 @@
     </div>
   </dialog>
 
+  <dialog id="remote-access" class="models remote-access" aria-labelledby="remote-access-title">
+    <div class="models-bar">
+      <div class="models-heading">
+        <h2 id="remote-access-title">Remote access</h2>
+        <p class="sub">Use Agent Guild on another device</p>
+      </div>
+      <button id="remote-close" class="btn" type="button">Close</button>
+    </div>
+    <div class="models-body remote-body">
+      <p>Access your running terminals through your Tailscale network. Your computer must be awake with Agent Guild and Tailscale running.</p>
+      <div class="remote-status" role="status" aria-live="polite" aria-atomic="true">
+        <strong id="remote-status-title">Checking connection…</strong>
+        <p id="remote-status-text"></p>
+      </div>
+      <p id="remote-error" class="remote-error" role="alert" hidden></p>
+      <div id="remote-address-row" hidden>
+        <label for="remote-address">Your remote address</label>
+        <input id="remote-address" class="remote-address" readonly spellcheck="false">
+        <div class="remote-actions">
+          <button id="remote-connect" class="btn primary" type="button" aria-expanded="false" aria-controls="remote-share">Connect another device</button>
+          <button id="remote-copy-address" class="btn" type="button">Copy address</button>
+          <a id="remote-open-address" class="btn" target="_blank" rel="noopener noreferrer">Open</a>
+        </div>
+      </div>
+      <div id="remote-share" class="remote-share" hidden>
+        <p>Connect the other device to Tailscale, then scan this code or open the sign-in link.</p>
+        <canvas id="remote-qr" role="img" aria-label="QR code to sign into Agent Guild" hidden></canvas>
+        <p id="remote-qr-note" class="sub"></p>
+        <label for="remote-signin">Anyone with this code or link can use your terminals.</label>
+        <input id="remote-signin" class="remote-address" readonly spellcheck="false" autocomplete="off">
+        <button id="remote-copy-signin" class="btn" type="button">Copy sign-in link</button>
+      </div>
+      <div class="remote-actions">
+        <button id="remote-primary" class="btn primary" type="button">Enable remote access</button>
+        <a id="remote-help" class="btn primary" target="_blank" rel="noopener noreferrer" hidden></a>
+        <button id="remote-check" class="btn" type="button">Check connection</button>
+        <button id="remote-disable" class="btn danger" type="button" hidden>Disable remote access</button>
+      </div>
+      <div id="remote-disable-confirm" class="remote-confirm" hidden>
+        <p>Disconnect remote browsers? Your terminals will keep running. Local access stays available.</p>
+        <div class="remote-actions">
+          <button id="remote-disable-yes" class="btn danger" type="button">Disable remote access</button>
+          <button id="remote-disable-no" class="btn" type="button">Keep enabled</button>
+        </div>
+      </div>
+      <details id="remote-details">
+        <summary>Connection details</summary>
+        <p id="remote-diagnostics" class="sub"></p>
+        <button id="remote-forget" class="btn" type="button" hidden>Leave the changed route in Tailscale</button>
+      </details>
+      <details id="remote-advanced">
+        <summary>Use another reverse proxy</summary>
+        <p id="remote-custom-note">Configure your proxy separately, then enter the hosts and browser origins it uses. Saving applies immediately and replaces environment settings.</p>
+        <form id="remote-custom-form">
+          <label for="remote-hosts">Allowed hosts, separated by commas</label>
+          <input id="remote-hosts" placeholder="guild.example.com" spellcheck="false" autocomplete="off" maxlength="16384">
+          <label for="remote-origins">Allowed origins, separated by commas</label>
+          <input id="remote-origins" placeholder="https://guild.example.com" spellcheck="false" autocomplete="off" maxlength="16384">
+          <button id="remote-custom-save" class="btn" type="submit">Save proxy settings</button>
+        </form>
+      </details>
+    </div>
+  </dialog>
+
   <dialog id="models" class="models" aria-labelledby="models-title">
     <div class="models-bar">
       <span id="models-icon" class="provider-icon small"></span>

package/web/remote-access.js

@@ -0,0 +1,236 @@
+export function remotePresentation(data) {
+  if (!data) return { title: 'Checking connection…', text: 'Looking for Tailscale on this computer.', label: 'Enable remote access' };
+  const problem = data.problem;
+  if (data.busy && problem?.code !== 'approval_required') return {
+    title: data.busy === 'checking' ? 'Checking connection…' : data.busy === 'disabling' ? 'Disabling remote access…' : 'Preparing remote access…',
+    text: 'Your terminal sessions keep running.', label: 'Please wait…',
+  };
+  if (data.pending === 'disable') return { title: 'Tailscale cleanup needed', text: problem?.code === 'permission_required'
+    ? 'Remote access is blocked. Run the cleanup command in Connection details from a terminal with permission to manage Tailscale, then retry cleanup.'
+    : problem?.message || 'Access through the saved address is blocked. Retry to remove its Serve route.', label: 'Retry cleanup', action: 'disable',
+    ...(['not_installed', 'update_required'].includes(problem?.code) ? { help: 'https://tailscale.com/download', helpLabel: 'Get Tailscale' } : {}) };
+  if (problem?.approvalUrl) return { title: 'One step needed in Tailscale', text: problem.message, help: problem.approvalUrl, helpLabel: 'Open Tailscale approval', label: 'Continue setup' };
+  if (problem?.code === 'not_installed') return { title: 'Connect this computer to Tailscale', text: problem.message, help: 'https://tailscale.com/download', helpLabel: 'Install Tailscale', label: 'Continue setup' };
+  if (problem?.code === 'update_required') return { title: 'Update Tailscale', text: problem.message, help: 'https://tailscale.com/download', helpLabel: 'Get Tailscale', label: 'Continue setup' };
+  if (problem?.code === 'not_connected' || problem?.code === 'address_unavailable') return { title: 'Connect Tailscale', text: problem.message, label: 'Continue setup' };
+  if (problem?.code === 'permission_required') return { title: 'Tailscale needs permission', text: 'Open a terminal on this computer with permission to manage Tailscale. The connection details below show the command to run, then choose Continue setup.', label: 'Continue setup' };
+  if (problem) return { title: data.pending === 'enable' ? 'Finish setting up remote access' : 'Connection needs attention', text: problem.message, label: data.mode === 'tailscale' ? 'Repair connection' : data.candidate?.existing ? 'Use existing route' : 'Continue setup' };
+  if (data.mode === 'tailscale') return {
+    title: 'Remote access enabled', text: data.connection?.ok ? 'The secure address reaches this manager. Connect another device to start using it.'
+      : data.connection ? 'The route is configured, but this computer could not verify the secure connection. Check Tailscale, then try the address on your other device.' : 'Your saved Tailscale address is ready to check.',
+    label: 'Repair connection', hidePrimary: true,
+  };
+  if (data.candidate?.existing) return { title: 'Your Tailscale route is ready', text: 'A private route already points to this manager. Use it to let Agent Guild save and manage this connection.', label: 'Use existing route' };
+  if (data.mode === 'custom') return { title: 'Custom proxy access configured', text: data.source === 'environment' ? 'These settings came from the launch environment. Save them below to keep them across launches.' : 'Your proxy settings are saved and active.', label: 'Set up Tailscale' };
+  if (!data.tailscale) return { title: 'Set up remote access', text: 'Check this computer’s Tailscale connection to get started.', label: 'Enable remote access' };
+  return { title: 'Tailscale connected', text: 'Enable a private address for your running terminals. Your settings will be saved for future launches.', label: 'Enable remote access' };
+}
+
+export function createRemoteAccessUI({ api, getToken, isConnected, onAuthError }) {
+  const $ = (id) => document.getElementById(id);
+  const dialog = $('remote-access');
+  let data = null, request = 0, loading = false, posting = false, timer = null, sharing = false, shareGeneration = 0, editRevision = null, dirty = false;
+  let available = false, waitingForApproval = false;
+
+  function clearShare() {
+    sharing = false;
+    shareGeneration++;
+    $('remote-share').hidden = true;
+    $('remote-connect').setAttribute('aria-expanded', 'false');
+    $('remote-signin').value = '';
+    const canvas = $('remote-qr');
+    canvas.getContext('2d')?.clearRect(0, 0, canvas.width, canvas.height);
+    canvas.hidden = true;
+  }
+
+  function render() {
+    const presentation = remotePresentation(data);
+    const busy = loading || posting || Boolean(data?.busy) || !isConnected();
+    $('remote-status-title').textContent = presentation.title;
+    $('remote-status-text').textContent = isConnected() ? presentation.text : 'Reconnect to the manager to change remote access.';
+    $('remote-status-title').parentElement.dataset.ready = String(data?.mode === 'tailscale' && !data.problem && !data.busy && Boolean(data.connection?.ok));
+    $('remote-primary').textContent = presentation.label;
+    $('remote-primary').hidden = Boolean(presentation.hidePrimary || (presentation.help && !presentation.action));
+    $('remote-primary').disabled = busy || !data;
+    $('remote-check').disabled = busy || !data;
+    $('remote-disable').disabled = busy || !data;
+    $('remote-disable').hidden = !data || (data.mode === 'off' && !data.pending);
+    $('remote-disable-yes').disabled = busy;
+    $('remote-custom-save').disabled = busy || !data || data.mode === 'tailscale' || Boolean(data.pending);
+    for (const id of ['remote-hosts', 'remote-origins']) $(id).disabled = !data || data.mode === 'tailscale' || Boolean(data.pending);
+    $('remote-custom-note').textContent = data?.mode === 'tailscale' || data?.pending
+      ? 'Disable Tailscale remote access and finish any cleanup before switching to another proxy.'
+      : 'Configure your proxy separately, then enter the hosts and browser origins it uses. Saving applies immediately and replaces environment settings.';
+    $('remote-help').hidden = !presentation.help;
+    if (presentation.help) { $('remote-help').href = presentation.help; $('remote-help').textContent = presentation.helpLabel; }
+    $('remote-address-row').hidden = !data?.url;
+    $('remote-address').value = data?.url || '';
+    $('remote-open-address').href = data?.url || '#';
+    $('remote-connect').disabled = busy;
+    $('remote-copy-address').disabled = busy;
+    $('remote-copy-signin').disabled = busy;
+    if (!data?.url || !isConnected() || data.busy === 'disabling') clearShare();
+    $('remote-forget').hidden = data?.pending !== 'disable' || !['route_changed', 'network_changed'].includes(data.problem?.code);
+    $('remote-forget').disabled = busy;
+    const diagnostics = [data?.tailscale ? `Tailscale ${data.tailscale.version} · ${data.tailscale.hostname}` : '',
+      data?.source === 'saved' ? 'Settings are saved on the manager computer.' : data?.source === 'environment' ? 'Settings currently come from the launch environment.' : '',
+      data?.connection?.checkedAt ? `Last connection check: ${new Date(data.connection.checkedAt).toLocaleString()}` : '',
+      data?.command ? `On the manager computer: ${data.command}` : '',
+    ].filter(Boolean);
+    $('remote-diagnostics').textContent = diagnostics.join('\n');
+    if (data && !dirty) {
+      $('remote-hosts').value = data.hosts.join(', ');
+      $('remote-origins').value = data.origins.join(', ');
+      editRevision = data.revision;
+    }
+    if (data?.problem?.approvalUrl) waitingForApproval = true;
+  }
+
+  function showError(error) {
+    if (error.name === 'AuthError' || error.message === 'The access token was rejected.') { close(); onAuthError(error.message); return; }
+    $('remote-error').textContent = error.message || 'Could not change remote access. Try again.';
+    $('remote-error').hidden = false;
+  }
+
+  function schedule() {
+    clearTimeout(timer);
+    if (dialog.open && available && isConnected()) timer = setTimeout(() => refresh(!data?.busy), data?.busy ? 800 : 30000);
+  }
+
+  async function refresh(check = false) {
+    if (!dialog.open || !available || !isConnected() || loading || posting) return;
+    const generation = ++request;
+    loading = true;
+    if (check) $('remote-error').hidden = true;
+    render();
+    try {
+      const result = await api(check ? 'POST' : 'GET', check ? '/remote-access/check' : '/remote-access');
+      if (generation !== request || !dialog.open) return;
+      if (data?.url !== result.remoteAccess.url) clearShare();
+      data = result.remoteAccess;
+    } catch (error) { if (generation === request && dialog.open) showError(error); }
+    finally { if (generation === request) { loading = false; render(); schedule(); } }
+    if (waitingForApproval && !data?.busy && data?.pending === 'enable' && data?.tailscale?.httpsReady && dialog.open) {
+      waitingForApproval = false;
+      await change('enable');
+    }
+  }
+
+  async function change(action, extra = {}) {
+    if (!data || posting || data.busy || !isConnected()) return;
+    posting = true;
+    const generation = ++request;
+    $('remote-error').hidden = true;
+    $('remote-disable-confirm').hidden = true;
+    if (action !== 'enable') clearShare();
+    render();
+    try {
+      const result = await api('PUT', '/remote-access', { revision: data.revision, action, adopt: Boolean(data.candidate?.existing), ...extra });
+      if (generation !== request || !dialog.open) return;
+      data = result.remoteAccess;
+      if (action === 'custom') dirty = false;
+    } catch (error) {
+      if (generation === request && dialog.open) {
+        showError(error);
+        if (error.code === 'stale_settings') {
+          dirty = false;
+          try { data = (await api('GET', '/remote-access')).remoteAccess; } catch (refreshError) { showError(refreshError); }
+        }
+      }
+    } finally { if (generation === request) { posting = false; render(); schedule(); } }
+  }
+
+  async function copy(input, button) {
+    try {
+      if (!navigator.clipboard) throw new Error('Clipboard unavailable');
+      await navigator.clipboard.writeText(input.value);
+      const label = button.textContent;
+      button.textContent = 'Copied';
+      setTimeout(() => { button.textContent = label; }, 1600);
+    } catch {
+      input.focus(); input.select();
+      $('remote-error').textContent = 'The link is selected. Use your browser’s Copy command.';
+      $('remote-error').hidden = false;
+    }
+  }
+
+  async function toggleShare() {
+    if (sharing) { clearShare(); return; }
+    if (!data?.url || !getToken() || !isConnected()) return;
+    sharing = true;
+    const generation = ++shareGeneration;
+    const url = new URL(data.url);
+    url.hash = new URLSearchParams({ token: getToken() }).toString();
+    $('remote-signin').value = url.href;
+    $('remote-share').hidden = false;
+    $('remote-connect').setAttribute('aria-expanded', 'true');
+    $('remote-qr-note').textContent = 'Preparing QR code…';
+    try {
+      const { default: qrcode } = await import('./vendor/qrcode.mjs');
+      if (!sharing || generation !== shareGeneration || !dialog.open) return;
+      const code = qrcode(0, 'M');
+      code.addData(url.href, 'Byte');
+      code.make();
+      const count = code.getModuleCount(), scale = 5, border = 4;
+      const canvas = $('remote-qr');
+      canvas.width = canvas.height = (count + border * 2) * scale;
+      const context = canvas.getContext('2d');
+      context.fillStyle = '#ffffff'; context.fillRect(0, 0, canvas.width, canvas.height);
+      context.fillStyle = '#000000';
+      for (let row = 0; row < count; row++) for (let col = 0; col < count; col++) {
+        if (code.isDark(row, col)) context.fillRect((col + border) * scale, (row + border) * scale, scale, scale);
+      }
+      canvas.hidden = false;
+      $('remote-qr-note').textContent = '';
+    } catch { if (generation === shareGeneration) $('remote-qr-note').textContent = 'The QR code could not load. Use the sign-in link below.'; }
+  }
+
+  function close() {
+    request++; loading = false; posting = false;
+    clearTimeout(timer); clearShare();
+    $('remote-disable-confirm').hidden = true;
+    if (dialog.open) dialog.close();
+  }
+
+  $('remote-access-open').addEventListener('click', async () => {
+    $('settings-menu').hidePopover?.();
+    $('topbar-menu').hidePopover?.();
+    if (!dialog.open) dialog.showModal();
+    $('remote-error').hidden = true;
+    dirty = false;
+    await refresh(false);
+    await refresh(true);
+  });
+  $('remote-close').addEventListener('click', close);
+  dialog.addEventListener('click', (event) => { if (event.target === dialog && event.clientX !== 0) {
+    const rect = dialog.getBoundingClientRect();
+    if (event.clientX < rect.left || event.clientX > rect.right || event.clientY < rect.top || event.clientY > rect.bottom) close();
+  } });
+  dialog.addEventListener('close', () => { close(); ($('settings').checkVisibility() ? $('settings') : $('menu-toggle')).focus(); });
+  $('remote-primary').addEventListener('click', () => change(remotePresentation(data).action || 'enable'));
+  $('remote-check').addEventListener('click', () => refresh(true));
+  $('remote-disable').addEventListener('click', () => { $('remote-disable-confirm').hidden = false; $('remote-disable-yes').focus(); });
+  $('remote-disable-yes').addEventListener('click', () => change('disable'));
+  $('remote-disable-no').addEventListener('click', () => { $('remote-disable-confirm').hidden = true; $('remote-disable').focus(); });
+  $('remote-forget').addEventListener('click', () => change('forget'));
+  $('remote-connect').addEventListener('click', toggleShare);
+  $('remote-copy-address').addEventListener('click', () => copy($('remote-address'), $('remote-copy-address')));
+  $('remote-copy-signin').addEventListener('click', () => copy($('remote-signin'), $('remote-copy-signin')));
+  for (const id of ['remote-hosts', 'remote-origins']) $(id).addEventListener('input', () => { dirty = true; });
+  $('remote-custom-form').addEventListener('submit', (event) => {
+    event.preventDefault();
+    const list = (id) => $(id).value.split(',').map((value) => value.trim()).filter(Boolean);
+    change('custom', { revision: editRevision, hosts: list('remote-hosts'), origins: list('remote-origins') });
+  });
+  addEventListener('focus', () => { if (dialog.open && !data?.busy) refresh(true); });
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'hidden') clearShare();
+    else if (dialog.open && !data?.busy) refresh(true);
+  });
+  return {
+    setAvailable(capability) { available = Boolean(capability?.available); $('remote-access-open').hidden = !available; if (!available) close(); },
+    updated() { if (dialog.open) refresh(false); },
+    connectionChanged() { render(); if (!isConnected()) { clearTimeout(timer); clearShare(); } else schedule(); },
+    close,
+  };
+}

package/web/styles.css

@@ -559,6 +559,29 @@ body:has(#app[hidden]):has(#auth[hidden]):has(#stopped[hidden])::after {
 .models-heading { flex: 1; min-width: 0; }
 .models-heading .sub { margin: 2px 0 0; color: var(--muted); font-size: 0.78rem; }
 .models-body { flex: 1; min-height: 0; overflow: auto; padding: 0 14px 14px; }
+.remote-access { width: min(560px, calc(100vw - 24px)); max-height: calc(100dvh - 24px); }
+.remote-body { padding: 4px 20px 20px; font-size: 0.9rem; }
+.remote-body > p { color: var(--muted); line-height: 1.6; }
+.remote-status { padding: 16px; margin: 16px 0; border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface-2); }
+.remote-status[data-ready="true"] { border-color: var(--ok); }
+.remote-status strong { font-size: 1rem; }
+.remote-status p { margin: 6px 0 0; color: var(--muted); line-height: 1.5; }
+.remote-actions { display: flex; flex-wrap: wrap; gap: 8px; margin: 12px 0; }
+.remote-body .btn { min-height: 42px; }
+.remote-body a.btn { display: inline-flex; align-items: center; justify-content: center; text-decoration: none; }
+.remote-body label { display: block; margin: 12px 0 6px; font-size: 0.8rem; }
+.remote-body input { width: 100%; min-width: 0; box-sizing: border-box; padding: 10px; border: 1px solid var(--border); border-radius: 6px; background: var(--surface-2); color: var(--text); font: inherit; font-size: 0.8rem; }
+.remote-body input:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }
+.remote-body details { border-top: 1px solid var(--border); margin-top: 18px; padding-top: 14px; }
+.remote-body summary { cursor: pointer; color: var(--muted); }
+.remote-body .sub { font-size: 0.8rem; color: var(--muted); line-height: 1.5; white-space: pre-line; overflow-wrap: anywhere; }
+.remote-body form .btn { margin-top: 12px; }
+.remote-body .remote-error { color: var(--danger); overflow-wrap: anywhere; }
+.remote-share, .remote-confirm { padding: 14px; border: 1px solid var(--border); border-radius: var(--radius); margin: 14px 0; }
+.remote-share p { margin-top: 0; line-height: 1.5; }
+.remote-share canvas { display: block; width: min(100%, 260px); height: auto; margin: 16px auto; image-rendering: pixelated; }
+.remote-share canvas[hidden] { display: none; }
+.remote-share .btn { margin-top: 12px; }
 .model-columns, .model-toggle { display: grid; grid-template-columns: minmax(0, 1fr) repeat(3, 6.5rem) 4.5rem; align-items: center; gap: 8px; }
 .model-columns {
   position: sticky; top: 0; z-index: 1; padding: 10px 8px 6px; background: var(--surface);