conductor-remote 1.9.0 → 1.9.1

package/dist-node/scripts/service.js

@@ -0,0 +1,467 @@
+/**
+ * Deploy the relay as a macOS LaunchAgent — the only "deployment" this app has, since it must run
+ * on the Mac that runs Conductor (local SQLite DB, git worktrees, and the sidecar unix socket all
+ * live there). Installs a per-user agent that starts the relay on login and keeps it alive.
+ *
+ *   node scripts/service.ts <install|uninstall|status|restart>
+ *   (or, once installed globally: `conductor-remote service <...>`)
+ *
+ * `yarn deploy` builds dist/ first, then runs `install`.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { packageRoot } from "../src/pkg-root.js";
+import { qrLines } from "./qr.js";
+const LABEL = 'no.adluna.conductor-remote';
+const projectDir = packageRoot(import.meta.dirname);
+const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+const logDir = path.join(os.homedir(), 'Library', 'Logs', 'conductor-remote');
+const uid = process.getuid?.() ?? 0;
+const domain = `gui/${uid}`;
+/**
+ * Install-time knobs are accepted as documented CLI flags OR the matching env var — a flag wins over the
+ * ambient env. Parsed flags are folded back into process.env so everything downstream (and the plist we
+ * bake) keeps reading a single source. Runs before any module-level env read below.
+ */
+const FLAG_ENV = {
+    '--expose': 'EXPOSE',
+    '--port': 'RELAY_PORT',
+    '--host': 'RELAY_HOST',
+    '--token': 'RELAY_TOKEN',
+    '--write-strategy': 'WRITE_STRATEGY',
+    '--auto-update': 'AUTO_UPDATE',
+    '--db': 'CONDUCTOR_DB',
+    '--workspaces': 'CONDUCTOR_WORKSPACES'
+};
+function applyFlags(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--'))
+            continue;
+        const eq = arg.indexOf('=');
+        const name = eq === -1 ? arg : arg.slice(0, eq);
+        const envKey = FLAG_ENV[name];
+        if (!envKey) {
+            console.error(`unknown flag: ${name}\n  known: ${Object.keys(FLAG_ENV).join(', ')}`);
+            process.exit(1);
+        }
+        const value = eq === -1 ? argv[++i] : arg.slice(eq + 1);
+        if (value === undefined) {
+            console.error(`flag ${name} needs a value (e.g. ${name} <value>)`);
+            process.exit(1);
+        }
+        process.env[envKey] = value;
+    }
+}
+// argv[2] is the subcommand (see bottom); flags follow it.
+applyFlags(process.argv.slice(3));
+function xml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/** Run launchctl, swallowing the exit code so "already-loaded"/"not-loaded" states aren't fatal. */
+function launchctl(...args) {
+    try {
+        execFileSync('launchctl', args, { stdio: 'pipe' });
+    }
+    catch {
+        // non-zero is expected for bootout-when-absent etc.; state is asserted by the caller's sequence
+    }
+}
+/** Block the main thread briefly — used to let launchd settle between bootout and bootstrap. */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** Is the agent currently bootstrapped into the user domain? */
+function serviceLoaded() {
+    try {
+        execFileSync('launchctl', ['print', `${domain}/${LABEL}`], { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reload the agent from the freshly written plist. `bootout` of a *running* instance is asynchronous,
+ * so we wait for it to fully unload before `bootstrap` — otherwise bootstrap races the teardown and
+ * fails silently, leaving the relay down after a re-deploy. Bootstrap is retried and its failure is fatal.
+ */
+function reloadAgent() {
+    launchctl('bootout', `${domain}/${LABEL}`);
+    for (let i = 0; i < 30 && serviceLoaded(); i++)
+        sleepSync(100);
+    let bootstrapped = false;
+    for (let i = 0; i < 10 && !bootstrapped; i++) {
+        try {
+            execFileSync('launchctl', ['bootstrap', domain, plistPath], { stdio: 'pipe' });
+            bootstrapped = true;
+        }
+        catch {
+            sleepSync(150);
+        }
+    }
+    if (!bootstrapped) {
+        console.error(`✗ launchctl bootstrap failed for ${plistPath}`);
+        console.error(`  Inspect with: launchctl print ${domain}/${LABEL}`);
+        process.exit(1);
+    }
+    launchctl('enable', `${domain}/${LABEL}`);
+    launchctl('kickstart', '-k', `${domain}/${LABEL}`);
+}
+/** Node runs the relay via the flag-free CLI shim; the absolute execPath is baked at install time. */
+function buildPlist() {
+    const node = xml(process.execPath);
+    const proj = xml(projectDir);
+    const out = xml(path.join(logDir, 'relay.log'));
+    const err = xml(path.join(logDir, 'relay.err.log'));
+    // node's own dir leads so the daemon can find `npm` (adjacent to node) for self-update under launchd's
+    // bare PATH; Homebrew's bin is appended for tailscale/node on Apple Silicon.
+    const nodeDir = path.dirname(process.execPath);
+    const daemonPath = `${nodeDir}:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/opt/homebrew/bin`;
+    // MANAGED marks this as the launchd-supervised instance: autoupdate.ts only self-restarts (exit →
+    // KeepAlive respawn) when it sees this, so a dev `yarn start` or worktree run never auto-updates.
+    const envEntries = [
+        ['PATH', daemonPath],
+        ['CONDUCTOR_REMOTE_MANAGED', '1']
+    ];
+    if (process.env.WRITE_STRATEGY)
+        envEntries.push(['WRITE_STRATEGY', process.env.WRITE_STRATEGY]);
+    if (process.env.RELAY_HOST)
+        envEntries.push(['RELAY_HOST', process.env.RELAY_HOST]);
+    if (process.env.RELAY_PORT)
+        envEntries.push(['RELAY_PORT', process.env.RELAY_PORT]);
+    if (process.env.AUTO_UPDATE)
+        envEntries.push(['AUTO_UPDATE', process.env.AUTO_UPDATE]);
+    if (process.env.CONDUCTOR_DB)
+        envEntries.push(['CONDUCTOR_DB', process.env.CONDUCTOR_DB]);
+    if (process.env.CONDUCTOR_WORKSPACES)
+        envEntries.push(['CONDUCTOR_WORKSPACES', process.env.CONDUCTOR_WORKSPACES]);
+    const envXml = envEntries.map(([k, v]) => `\t\t<key>${xml(k)}</key>\n\t\t<string>${xml(v)}</string>`).join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>Label</key>
+	<string>${LABEL}</string>
+	<key>ProgramArguments</key>
+	<array>
+		<string>${node}</string>
+		<string>${proj}/bin/cli.js</string>
+	</array>
+	<key>WorkingDirectory</key>
+	<string>${proj}</string>
+	<key>EnvironmentVariables</key>
+	<dict>
+${envXml}
+	</dict>
+	<key>RunAtLoad</key>
+	<true/>
+	<key>KeepAlive</key>
+	<true/>
+	<key>ProcessType</key>
+	<string>Background</string>
+	<key>StandardOutPath</key>
+	<string>${out}</string>
+	<key>StandardErrorPath</key>
+	<string>${err}</string>
+</dict>
+</plist>
+`;
+}
+function distBuilt() {
+    return fs.existsSync(path.join(projectDir, 'dist', 'index.html'));
+}
+function tokenStorePath() {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'conductor-remote', 'token');
+}
+/** Read the persisted token (or env override) purely to print the phone URL — never mints one. */
+function currentToken() {
+    if (process.env.RELAY_TOKEN)
+        return process.env.RELAY_TOKEN;
+    try {
+        return fs.readFileSync(tokenStorePath(), 'utf8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A pinned token (`--token` / `RELAY_TOKEN`) is persisted to the token file, not baked into the plist —
+ * the launchd daemon has no such env, so it resolves the secret from this file (config.ts ▸ resolveToken).
+ * Writing it here keeps the daemon, the printed URL, and later `status` all in agreement.
+ */
+function persistPinnedToken() {
+    const token = process.env.RELAY_TOKEN;
+    if (!token)
+        return;
+    try {
+        fs.mkdirSync(path.dirname(tokenStorePath()), { recursive: true });
+        fs.writeFileSync(tokenStorePath(), token, { mode: 0o600 });
+    }
+    catch (err) {
+        console.info(`  ⚠ could not persist --token (${err instanceof Error ? err.message : err})`);
+    }
+}
+const RELAY_PORT = process.env.RELAY_PORT ?? '8787';
+/** Locate the tailscale CLI: PATH first, then the common macOS install locations. Null if absent. */
+function tailscaleBin() {
+    for (const bin of [
+        'tailscale',
+        '/opt/homebrew/bin/tailscale',
+        '/usr/local/bin/tailscale',
+        '/Applications/Tailscale.app/Contents/MacOS/Tailscale'
+    ]) {
+        try {
+            execFileSync(bin, ['version'], { stdio: 'pipe' });
+            return bin;
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return null;
+}
+/** This node's MagicDNS name without the trailing dot, e.g. `mac.taila6dcd6.ts.net`. */
+function magicDnsName(bin) {
+    try {
+        const out = execFileSync(bin, ['status', '--json'], { encoding: 'utf8', stdio: 'pipe' });
+        return (JSON.parse(out)?.Self?.DNSName ?? '').replace(/\.$/, '') || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Where the chosen expose mode is persisted so a later bare `yarn deploy` keeps the same posture. */
+function exposeStorePath() {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'conductor-remote', 'expose');
+}
+function normalizeMode(raw) {
+    const v = raw?.trim().toLowerCase();
+    if (v === 'public' || v === 'funnel')
+        return 'public';
+    if (v === 'tailnet' || v === 'serve' || v === 'private')
+        return 'tailnet';
+    return null;
+}
+/**
+ * Resolve the expose mode. Precedence: `EXPOSE` env (public|funnel / tailnet|serve|private) > persisted
+ * choice > 'public' default. An explicit env value is persisted so re-deploys don't silently flip posture.
+ */
+function resolveExposeMode() {
+    const fromEnv = normalizeMode(process.env.EXPOSE);
+    if (fromEnv) {
+        try {
+            const file = exposeStorePath();
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, fromEnv);
+        }
+        catch {
+            // persistence is a convenience; ignore failures
+        }
+        return fromEnv;
+    }
+    if (process.env.EXPOSE)
+        console.info(`  ⚠ unrecognized EXPOSE=${process.env.EXPOSE} — expected public|tailnet.`);
+    try {
+        const saved = normalizeMode(fs.readFileSync(exposeStorePath(), 'utf8'));
+        if (saved)
+            return saved;
+    }
+    catch {
+        // no saved choice yet
+    }
+    return 'public';
+}
+/** Live serve/funnel state for this node: is the loopback proxy wired, and is Funnel (public) on? */
+function tailscaleState(bin, dns) {
+    if (!dns)
+        return { proxyOk: false, funnelOn: false };
+    try {
+        const out = execFileSync(bin, ['serve', 'status', '--json'], { encoding: 'utf8', stdio: 'pipe' });
+        const cfg = JSON.parse(out);
+        const key = `${dns}:443`;
+        const proxyOk = cfg?.Web?.[key]?.Handlers?.['/']?.Proxy === `http://127.0.0.1:${RELAY_PORT}`;
+        return { proxyOk, funnelOn: Boolean(cfg?.AllowFunnel?.[key]) };
+    }
+    catch {
+        return { proxyOk: false, funnelOn: false };
+    }
+}
+/** Assert the tailnet-only `serve` proxy — used for tailnet mode and as the Funnel fallback. */
+function ensureServeOnly(bin, url, state) {
+    if (state.proxyOk && !state.funnelOn) {
+        console.info(`✓ tailscale serve fronts ${url} → 127.0.0.1:${RELAY_PORT} (tailnet-only)`);
+        return;
+    }
+    try {
+        execFileSync(bin, ['serve', '--bg', RELAY_PORT], { stdio: 'pipe' });
+        console.info(`✓ tailscale serve → ${url} proxies 127.0.0.1:${RELAY_PORT} (tailnet-only)`);
+    }
+    catch (err) {
+        console.info(`\n  ⚠ could not configure tailscale serve (${err instanceof Error ? err.message : err}). Run by hand:`);
+        console.info(`      tailscale serve --bg ${RELAY_PORT}`);
+    }
+}
+/**
+ * Front the loopback relay with a stable HTTPS URL, either publicly (`tailscale funnel`, the default) or
+ * tailnet-only (`tailscale serve`), per resolveExposeMode(). Idempotent — flips Funnel off when switching
+ * back to tailnet — and non-fatal: the relay binds loopback regardless, so a failure here just means the
+ * phone URL isn't wired yet and we print how to do it by hand. Real TLS also satisfies the PWA's
+ * secure-context requirement (a service worker won't register over plain http on a 100.x IP).
+ *
+ * PUBLIC IS INTERNET-FACING: the 128-bit token on every /api/* request is the only gate. Funnel must be
+ * enabled for the tailnet (Admin console) or the funnel command fails — we then fall back to tailnet-only.
+ */
+function ensureTailscale() {
+    const bin = tailscaleBin();
+    if (!bin) {
+        console.info('\n  ⚠ tailscale CLI not found — skipped URL setup. Once Tailscale is installed, run:');
+        console.info(`      tailscale funnel --bg ${RELAY_PORT}   # public, or \`serve\` for tailnet-only`);
+        return;
+    }
+    const dns = magicDnsName(bin);
+    const url = `https://${dns ?? '<node>'}/`;
+    const mode = resolveExposeMode();
+    const state = tailscaleState(bin, dns);
+    if (mode === 'tailnet') {
+        if (state.funnelOn) {
+            try {
+                execFileSync(bin, ['funnel', 'reset'], { stdio: 'pipe' });
+            }
+            catch {
+                // best-effort; ensureServeOnly re-asserts the proxy below
+            }
+            ensureServeOnly(bin, url, { proxyOk: false, funnelOn: false });
+        }
+        else {
+            ensureServeOnly(bin, url, state);
+        }
+        return;
+    }
+    // public (Funnel)
+    if (state.proxyOk && state.funnelOn) {
+        console.info(`✓ tailscale funnel already exposes ${url} → 127.0.0.1:${RELAY_PORT} (public, token-gated)`);
+        return;
+    }
+    try {
+        execFileSync(bin, ['funnel', '--bg', '--yes', RELAY_PORT], { stdio: 'pipe' });
+        console.info(`✓ tailscale funnel → ${url} now public over the internet (token-gated) → 127.0.0.1:${RELAY_PORT}`);
+    }
+    catch (err) {
+        console.info(`\n  ⚠ could not enable Funnel (${err instanceof Error ? err.message.trim() : err}).`);
+        console.info('    Funnel must be enabled for this tailnet: open the URL Tailscale printed above, or add the');
+        console.info('    "funnel" nodeAttr in Admin console ▸ Access controls. Falling back to tailnet-only for now.');
+        ensureServeOnly(bin, url, state);
+    }
+}
+/** Print a scannable QR of `url` (theme-independent black-on-white). Never fatal — QR is a convenience. */
+function printQr(url) {
+    try {
+        console.info(`\n${qrLines(url).join('\n')}`);
+    }
+    catch (err) {
+        console.info(`  (QR skipped: ${err instanceof Error ? err.message : err})`);
+    }
+}
+function printUrl() {
+    const token = currentToken();
+    const frag = `#token=${token ?? '<starts on first run>'}`;
+    const bin = tailscaleBin();
+    const dns = bin ? magicDnsName(bin) : null;
+    const state = bin ? tailscaleState(bin, dns) : { proxyOk: false, funnelOn: false };
+    if (dns && state.proxyOk) {
+        const scope = state.funnelOn ? 'public — any browser, token-gated' : 'same Tailnet only';
+        const url = `https://${dns}/${frag}`;
+        console.info(`\n  Phone URL (HTTPS, ${scope}):\n    ${url}`);
+        if (token) {
+            console.info('\n  Scan to open on your phone:');
+            printQr(url);
+        }
+        return;
+    }
+    // Nothing fronting yet — the relay is only on loopback.
+    console.info(`\n  Local URL:\n    http://127.0.0.1:${RELAY_PORT}/${frag}`);
+    console.info(`\n  ⚠ Not reachable from your phone yet. Run \`tailscale funnel --bg ${RELAY_PORT}\` (public) or \`tailscale serve --bg ${RELAY_PORT}\` (tailnet)${dns ? ` → https://${dns}/` : ''}, then \`yarn service status\`.`);
+}
+/** npx unpacks into a throwaway cache that gets purged; a LaunchAgent baked against it would rot. */
+function isEphemeralInstall(dir) {
+    return /[\\/]_npx[\\/]|[\\/]\.npm[\\/]_npx[\\/]/.test(dir);
+}
+function install() {
+    if (isEphemeralInstall(projectDir)) {
+        console.error(`✗ refusing to install from an npx cache path:\n    ${projectDir}\n` +
+            '  That directory is temporary and gets purged, which would break the LaunchAgent.\n' +
+            '  Install globally first: `npm i -g conductor-remote`, then `conductor-remote service install`.');
+        process.exit(1);
+    }
+    if (!distBuilt()) {
+        console.error('✗ dist/ not built. Run `yarn build` first (or use `yarn deploy`, which builds).');
+        process.exit(1);
+    }
+    persistPinnedToken();
+    fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+    fs.mkdirSync(logDir, { recursive: true });
+    fs.writeFileSync(plistPath, buildPlist());
+    reloadAgent();
+    console.info(`✓ installed LaunchAgent ${LABEL}`);
+    console.info(`  plist: ${plistPath}`);
+    console.info(`  logs:  ${logDir}/relay.log`);
+    console.info(`  node:  ${process.execPath}`);
+    ensureTailscale();
+    printUrl();
+    console.info('\n  Note: a node version change (nvm) invalidates the baked path — re-run `yarn deploy` after upgrading node.');
+    console.info('  Note: the AppleScript write path needs Accessibility permission granted to this node binary (System Settings ▸ Privacy).');
+}
+function uninstall() {
+    launchctl('bootout', `${domain}/${LABEL}`);
+    try {
+        fs.rmSync(plistPath);
+    }
+    catch {
+        // already gone
+    }
+    console.info(`✓ removed LaunchAgent ${LABEL}`);
+}
+function restart() {
+    launchctl('kickstart', '-k', `${domain}/${LABEL}`);
+    console.info(`✓ restarted ${LABEL}`);
+    printUrl();
+}
+function status() {
+    const installed = fs.existsSync(plistPath);
+    console.info(`plist:     ${installed ? plistPath : '(not installed)'}`);
+    if (!installed)
+        return;
+    try {
+        const out = execFileSync('launchctl', ['print', `${domain}/${LABEL}`], { encoding: 'utf8', stdio: 'pipe' });
+        const state = out.match(/state = (\S+)/)?.[1] ?? 'unknown';
+        const pid = out.match(/pid = (\d+)/)?.[1] ?? '—';
+        console.info(`state:     ${state}  (pid ${pid})`);
+    }
+    catch {
+        console.info('state:     loaded but not running (check logs)');
+    }
+    printUrl();
+}
+const cmd = process.argv[2] ?? 'status';
+switch (cmd) {
+    case 'install':
+        install();
+        break;
+    case 'uninstall':
+        uninstall();
+        break;
+    case 'restart':
+        restart();
+        break;
+    case 'status':
+        status();
+        break;
+    default:
+        console.error(`unknown command: ${cmd}\n` +
+            'usage: service.ts <install|uninstall|restart|status> [flags]\n' +
+            `  flags (install): ${Object.keys(FLAG_ENV).join(', ')}`);
+        process.exit(1);
+}

package/dist-node/src/autoupdate.js

@@ -0,0 +1,160 @@
+/**
+ * Self-update for the globally-installed relay daemon.
+ *
+ * The relay ships as a global npm package driven by a KeepAlive LaunchAgent. Without this, staying
+ * current means the user manually re-running `npm i -g conductor-remote && conductor-remote service
+ * install`. Here the running daemon periodically asks the npm registry for the latest published
+ * version and, when it's newer, runs `npm i -g conductor-remote@latest` and exits — launchd's
+ * KeepAlive restarts it into the freshly-installed code (the plist's baked `bin/cli.js` path is stable
+ * across a global reinstall, so no re-`service install` is needed).
+ *
+ * Two hard gates keep this from firing where it shouldn't:
+ *   - CONDUCTOR_REMOTE_MANAGED=1 — set only by `service install` in the plist, so it proves we are the
+ *     launchd-managed daemon and that exit()→KeepAlive-restart is a safe way to reload.
+ *   - projectDir has no `.git` — proves we're the published tarball, not a dev worktree. A worktree's
+ *     LaunchAgent runs from the worktree path, so `npm i -g` wouldn't even swap its code; never touch it.
+ *
+ * `AUTO_UPDATE` overrides the default: `off` disables entirely; `check` polls and reports availability
+ * (via /api/state and the log) but never installs; `on` forces auto when the gates allow it.
+ *
+ * Stdlib + global fetch only — no runtime deps, no transform-requiring syntax (keeps the relay strip-clean).
+ */
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { packageRoot } from "./pkg-root.js";
+const execFileP = promisify(execFile);
+const NAME = 'conductor-remote';
+const projectDir = packageRoot(import.meta.dirname);
+const REGISTRY = process.env.NPM_REGISTRY ?? 'https://registry.npmjs.org';
+const CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
+const FIRST_DELAY_MS = 90 * 1000;
+function readVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(projectDir, 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+const CURRENT = readVersion();
+const status = {
+    current: CURRENT,
+    latest: null,
+    available: false,
+    checkedAt: null,
+    mode: 'off',
+    lastError: null
+};
+/** Snapshot of the updater state, surfaced on /api/state so the phone can show the version and any update. */
+export function updateStatus() {
+    return { ...status };
+}
+/** Parse `x.y.z` (ignoring any prerelease/build suffix) into a comparable tuple; null if unparseable. */
+function parseVersion(v) {
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+/** True when `candidate` is a strictly higher release than `base` (prereleases collapse to their x.y.z). */
+function isNewer(candidate, base) {
+    const a = parseVersion(candidate);
+    const b = parseVersion(base);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] > b[i])
+            return true;
+        if (a[i] < b[i])
+            return false;
+    }
+    return false;
+}
+async function fetchLatest() {
+    // The `/latest` sub-endpoint serves the full manifest as application/json; the abbreviated
+    // `vnd.npm.install-v1+json` media type is only valid on the packument root and 406s here.
+    const res = await fetch(`${REGISTRY}/${NAME}/latest`, {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(10_000)
+    });
+    if (!res.ok)
+        throw new Error(`registry ${res.status}`);
+    const body = (await res.json());
+    return body.version ?? null;
+}
+/** Resolve npm next to the running node (Homebrew/nvm keep them in one bin dir); fall back to PATH. */
+function npmBin() {
+    const adjacent = path.join(path.dirname(process.execPath), 'npm');
+    return fs.existsSync(adjacent) ? adjacent : 'npm';
+}
+async function installLatest() {
+    await execFileP(npmBin(), ['install', '-g', `${NAME}@latest`], {
+        timeout: 300_000,
+        env: { ...process.env, npm_config_yes: 'true' }
+    });
+}
+function log(msg) {
+    console.info(`[auto-update] ${msg}`);
+}
+/**
+ * Effective mode. Precedence: explicit AUTO_UPDATE > gated default.
+ *   off — disabled.  check — poll + report, never install.  auto — poll + install + self-restart.
+ * `auto` (default when unset, or when AUTO_UPDATE=on) requires BOTH gates; without them, an explicit
+ * `on` degrades to `check` (visibility without an unsafe install) and an unset default degrades to `off`
+ * (a dev `yarn start` or worktree daemon stays silent).
+ */
+function resolveMode() {
+    const raw = process.env.AUTO_UPDATE?.trim().toLowerCase();
+    if (raw === 'off' || raw === 'false' || raw === '0')
+        return 'off';
+    if (raw === 'check' || raw === 'notify')
+        return 'check';
+    const managed = process.env.CONDUCTOR_REMOTE_MANAGED === '1';
+    const published = !fs.existsSync(path.join(projectDir, '.git'));
+    const canAuto = managed && published;
+    if (raw === 'on' || raw === 'auto' || raw === '1' || raw === 'true')
+        return canAuto ? 'auto' : 'check';
+    return canAuto ? 'auto' : 'off';
+}
+let inFlight = false;
+async function runCheck(mode) {
+    if (inFlight)
+        return;
+    inFlight = true;
+    try {
+        const latest = await fetchLatest();
+        status.latest = latest;
+        status.checkedAt = Date.now();
+        status.available = latest != null && isNewer(latest, CURRENT);
+        status.lastError = null;
+        if (!status.available || latest == null)
+            return;
+        if (mode === 'check') {
+            log(`update available: ${CURRENT} → ${latest} (AUTO_UPDATE=check — not installing)`);
+            return;
+        }
+        log(`updating ${CURRENT} → ${latest} via \`npm i -g ${NAME}@latest\`…`);
+        await installLatest();
+        log(`installed ${latest}; restarting to apply (launchd KeepAlive brings the relay back).`);
+        // Let the log line flush, then exit; KeepAlive respawns us into the new code.
+        setTimeout(() => process.exit(0), 500).unref();
+    }
+    catch (err) {
+        status.lastError = err instanceof Error ? err.message : String(err);
+        log(`check/update failed: ${status.lastError}`);
+    }
+    finally {
+        inFlight = false;
+    }
+}
+/** Start the periodic self-updater. Safe to call unconditionally — it no-ops unless the gates pass. */
+export function startAutoUpdate() {
+    const mode = resolveMode();
+    status.mode = mode;
+    if (mode === 'off')
+        return;
+    log(`enabled (mode=${mode}, current=${CURRENT}); first check in ${FIRST_DELAY_MS / 1000}s, then every 6h.`);
+    setTimeout(() => void runCheck(mode), FIRST_DELAY_MS).unref();
+    setInterval(() => void runCheck(mode), CHECK_INTERVAL_MS).unref();
+}

package/dist-node/src/config.js

@@ -0,0 +1,60 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { packageRoot } from "./pkg-root.js";
+const home = os.homedir();
+/** Where a generated token is persisted so a phone's saved URL stays valid across relay restarts. */
+function tokenStorePath() {
+    return path.join(home, 'Library', 'Application Support', 'conductor-remote', 'token');
+}
+/**
+ * Stable shared secret. Explicit `RELAY_TOKEN` wins; otherwise reuse a persisted token (or mint and
+ * persist one). Persistence matters for the daemon: a KeepAlive restart must not invalidate the URL
+ * the user added to their home screen.
+ */
+function resolveToken() {
+    if (process.env.RELAY_TOKEN)
+        return process.env.RELAY_TOKEN;
+    const file = tokenStorePath();
+    try {
+        const existing = fs.readFileSync(file, 'utf8').trim();
+        if (existing)
+            return existing;
+    }
+    catch {
+        // no persisted token yet — mint one below
+    }
+    const token = crypto.randomBytes(16).toString('hex');
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, token, { mode: 0o600 });
+    }
+    catch (err) {
+        console.warn(`⚠ could not persist token (${err instanceof Error ? err.message : err}); it will rotate on restart`);
+    }
+    return token;
+}
+/** The relay serves the Vite build. Warn early if it hasn't been built yet. */
+function resolvePublicDir() {
+    const dist = path.join(packageRoot(import.meta.dirname), 'dist');
+    if (!fs.existsSync(path.join(dist, 'index.html'))) {
+        console.warn('⚠ dist/ not built — run `yarn build` (or `yarn preview`). The API works; the PWA will 404 until then.');
+    }
+    return dist;
+}
+export function loadConfig() {
+    // Bind loopback; `tailscale serve` (wired by `yarn deploy`) fronts it with a stable HTTPS tailnet URL.
+    const host = process.env.RELAY_HOST ?? '127.0.0.1';
+    const writeStrategy = process.env.WRITE_STRATEGY === 'sidecar' ? 'sidecar' : 'applescript';
+    return {
+        dbPath: process.env.CONDUCTOR_DB ??
+            path.join(home, 'Library', 'Application Support', 'com.conductor.app', 'conductor.db'),
+        workspacesRoot: process.env.CONDUCTOR_WORKSPACES ?? path.join(home, 'conductor', 'workspaces'),
+        port: Number(process.env.RELAY_PORT ?? 8787),
+        host,
+        token: resolveToken(),
+        writeStrategy,
+        publicDir: resolvePublicDir()
+    };
+}