conductor-remote 1.116.0 → 1.118.0

package/dist/index.html

@@ -25,8 +25,8 @@
 		<title>Conductor Remote</title>
 		<!-- Runs before the module bundle so it can catch a stale shell that fails to boot. -->
 		<script src="/self-heal.js"></script>
-		<script type="module" crossorigin src="/assets/index-QJR7tn2I.js"></script>
-		<link rel="stylesheet" crossorigin href="/assets/index-DNLdIfZ2.css">
+		<script type="module" crossorigin src="/assets/index-BaS6qXUW.js"></script>
+		<link rel="stylesheet" crossorigin href="/assets/index-BRzsSW8g.css">
 	<link rel="manifest" href="/manifest.webmanifest"></head>
 	<body>
 		<div id="root"></div>

package/dist/push-sw.js

@@ -26,7 +26,7 @@
 //    screen it was left on — `openWindow`'s path is ignored, and a `postMessage` to a
 //    frozen page is dropped (WebKit, reported from iOS 17.1 through 18.x and still
 //    open). The cache outlives both, so the app reads its target when it comes back to
-//    the front; see `usePushRouting` in web/src/hooks.ts.
+//    the front; see `usePushRouting` in web/src/hooks/push.ts.
 
 /** One entry, overwritten per tap: only the newest tap can still be waiting to land. */
 const ROUTE_CACHE = 'push-route'
@@ -116,7 +116,7 @@ self.addEventListener('notificationclick', event => {
 			const clients = await self.clients.matchAll({ type: 'window', includeUncontrolled: true })
 			for (const client of clients) {
 				if (!sameOrigin(client.url)) continue
-				// Handled in web/src/hooks.ts (usePushRouting) — an in-app route change, so the
+				// Handled in web/src/hooks/push.ts (usePushRouting) — an in-app route change, so the
 				// token gate and React state survive the tap. Posted before the focus, since a
 				// refused focus is no reason to skip a message the page may well receive.
 				client.postMessage({ type: 'push-navigate', url })

package/dist/sw.js

@@ -1 +1 @@
-if(!self.define){let e,s={};const i=(i,n)=>(i=new URL(i+".js",n).href,s[i]||new Promise(s=>{if("document"in self){const e=document.createElement("script");e.src=i,e.onload=s,document.head.appendChild(e)}else e=i,importScripts(i),s()}).then(()=>{let e=s[i];if(!e)throw new Error(`Module ${i} didn’t register its module`);return e}));self.define=(n,r)=>{const l=e||("document"in self?document.currentScript.src:"")||location.href;if(s[l])return;let o={};const t=e=>i(e,l),a={module:{uri:l},exports:o,require:t};s[l]=Promise.all(n.map(e=>a[e]||t(e))).then(e=>(r(...e),o))}}define(["./workbox-dcde9eb3"],function(e){"use strict";importScripts("/push-sw.js"),self.addEventListener("message",e=>{e.data&&"SKIP_WAITING"===e.data.type&&self.skipWaiting()}),e.clientsClaim(),e.precacheAndRoute([{url:"self-heal.js",revision:"49bd63adb25a09341f8d2610e8bd3c76"},{url:"push-sw.js",revision:"e7ef44deca46c0539e6ff7bba5eb815e"},{url:"index.html",revision:"9871202c1ab6c45db285485079015279"},{url:"assets/workbox-window.prod.es5-BBnX5xw4.js",revision:null},{url:"assets/pierre-shiki-wasm-C8ETeZem.js",revision:null},{url:"assets/pierre-light-480U9XYS.js",revision:null},{url:"assets/pierre-dark-CyvmCCZW.js",revision:null},{url:"assets/index-QJR7tn2I.js",revision:null},{url:"assets/index-DNLdIfZ2.css",revision:null},{url:"assets/PierrePatch-BPp5Cf-p.js",revision:null},{url:"apple-touch-icon.png",revision:"1127bb396b4648add53dce3f22c92aee"},{url:"icon-192.png",revision:"c5e01ac58768627e18ee7b8b6a9239ef"},{url:"icon-512.png",revision:"a40638c55e310312457a621c9a0002c8"},{url:"icon-maskable-512.png",revision:"a9b0d962686287452216492cd2247499"},{url:"icon.svg",revision:"c1aee186821798733dd477e69a0ef243"},{url:"manifest.webmanifest",revision:"cf88fbc5755108a7fe0616fa160a8a15"}],{}),e.cleanupOutdatedCaches(),e.registerRoute(new e.NavigationRoute(e.createHandlerBoundToURL("/index.html"),{denylist:[/^\/api\//]})),e.registerRoute(({url:e})=>e.pathname.startsWith("/assets/diff-syntax/"),new e.CacheFirst({cacheName:"diff-syntax",plugins:[new e.ExpirationPlugin({maxEntries:32,maxAgeSeconds:31536e3})]}),"GET")});
+if(!self.define){let e,s={};const i=(i,n)=>(i=new URL(i+".js",n).href,s[i]||new Promise(s=>{if("document"in self){const e=document.createElement("script");e.src=i,e.onload=s,document.head.appendChild(e)}else e=i,importScripts(i),s()}).then(()=>{let e=s[i];if(!e)throw new Error(`Module ${i} didn’t register its module`);return e}));self.define=(n,r)=>{const l=e||("document"in self?document.currentScript.src:"")||location.href;if(s[l])return;let o={};const a=e=>i(e,l),t={module:{uri:l},exports:o,require:a};s[l]=Promise.all(n.map(e=>t[e]||a(e))).then(e=>(r(...e),o))}}define(["./workbox-dcde9eb3"],function(e){"use strict";importScripts("/push-sw.js"),self.addEventListener("message",e=>{e.data&&"SKIP_WAITING"===e.data.type&&self.skipWaiting()}),e.clientsClaim(),e.precacheAndRoute([{url:"self-heal.js",revision:"49bd63adb25a09341f8d2610e8bd3c76"},{url:"push-sw.js",revision:"4e0b714c0ea53e85c167e6d8f5b767aa"},{url:"index.html",revision:"47b96bd0013bdc2d5054d22af641f7cf"},{url:"assets/workbox-window.prod.es5-BBnX5xw4.js",revision:null},{url:"assets/pierre-shiki-wasm-C8ETeZem.js",revision:null},{url:"assets/pierre-light-480U9XYS.js",revision:null},{url:"assets/pierre-dark-CyvmCCZW.js",revision:null},{url:"assets/index-BaS6qXUW.js",revision:null},{url:"assets/index-BRzsSW8g.css",revision:null},{url:"assets/PierrePatch-D4YbKD8Q.js",revision:null},{url:"apple-touch-icon.png",revision:"1127bb396b4648add53dce3f22c92aee"},{url:"icon-192.png",revision:"c5e01ac58768627e18ee7b8b6a9239ef"},{url:"icon-512.png",revision:"a40638c55e310312457a621c9a0002c8"},{url:"icon-maskable-512.png",revision:"a9b0d962686287452216492cd2247499"},{url:"icon.svg",revision:"c1aee186821798733dd477e69a0ef243"},{url:"manifest.webmanifest",revision:"cf88fbc5755108a7fe0616fa160a8a15"}],{}),e.cleanupOutdatedCaches(),e.registerRoute(new e.NavigationRoute(e.createHandlerBoundToURL("/index.html"),{denylist:[/^\/api\//]})),e.registerRoute(({url:e})=>e.pathname.startsWith("/assets/diff-syntax/"),new e.CacheFirst({cacheName:"diff-syntax",plugins:[new e.ExpirationPlugin({maxEntries:32,maxAgeSeconds:31536e3})]}),"GET")});

package/dist-node/scripts/nosleep-setup.js

@@ -1,5 +1,5 @@
 // `conductor-remote nosleep setup` — pay the sudo password once, so `nosleep`
-// never asks again. Called from nosleep.ts; not an entrypoint of its own.
+// never asks again. Called from scripts/nosleep.ts; not an entrypoint of its own.
 //
 // Why this exists: `pmset disablesleep` is the only lever that keeps a Mac awake
 // with the lid shut, it needs root, and the login LaunchAgent has no TTY to prompt
@@ -30,7 +30,7 @@ import { execFileSync, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { HELPER_PATH, helperFile, helperReady, installedHelper, SUDOERS_PATH, sudoersFile } from "../src/nosleep-helper.js";
+import { HELPER_PATH, helperFile, helperReady, installedHelper, SUDOERS_PATH, sudoersFile } from "../src/host/nosleep-helper.js";
 const LIBEXEC_DIR = path.dirname(HELPER_PATH);
 /**
  * Every directory between `/` and the helper, root first. The sudoers rule is only as

package/dist-node/scripts/nosleep.js

@@ -14,11 +14,11 @@
 // The helper also owns a process-scoped `caffeinate -d` assertion by default.
 // ScreenSaverDaemon checks that assertion before starting the idle screen saver
 // that locks the session. An explicit lock or lid close can still lock macOS;
-// those sends park in `src/parked.ts` until the next unlock. Strip-clean
+// those sends park in `src/delivery/parked.ts` until the next unlock. Strip-clean
 // (plain-node type-stripping), stdlib-only — see CLAUDE.md.
 import { spawn } from 'node:child_process';
 import { installedServiceEnvironment, preventScreenLockEnabled } from "../src/config.js";
-import { HELPER_PATH, helperFile, helperReady, installedHelper, NOSLEEP_BODY } from "../src/nosleep-helper.js";
+import { HELPER_PATH, helperFile, helperReady, installedHelper, NOSLEEP_BODY } from "../src/host/nosleep-helper.js";
 import { parseDurationSeconds } from "../src/shared.js";
 import { setup, status } from "./nosleep-setup.js";
 /** Parse `90m` / `2h` / `30s` / bare seconds into seconds; null = run until Ctrl-C. */
@@ -55,7 +55,7 @@ async function main() {
     const preventScreenLock = preventScreenLockEnabled(configuredMode);
     // The shared body reads its window from an argument (0 = until killed) rather than
     // having one interpolated in, because the installed helper is a fixed file the
-    // sudoers rule names — see nosleep-helper.ts. `label` is only echoed back, and the
+    // sudoers rule names — see src/host/nosleep-helper.ts. `label` is only echoed back, and the
     // script re-validates it, so the two paths print the same confirmation.
     const args = [String(seconds ?? 0), arg ?? '', preventScreenLock ? '1' : '0'];
     console.info('conductor-remote nosleep — keeping this Mac awake (incl. lid-closed system sleep).');

package/dist-node/scripts/service/commands.js

@@ -0,0 +1,32 @@
+import { config } from "./configuration.js";
+import { FLAG_ENV } from "./flags.js";
+import { install, restart, uninstall } from "./installation.js";
+import { logs, status } from "./presentation.js";
+export function runServiceCommand() {
+    const cmd = process.argv[2] ?? 'status';
+    switch (cmd) {
+        case 'install':
+            install();
+            break;
+        case 'uninstall':
+            uninstall();
+            break;
+        case 'restart':
+            restart();
+            break;
+        case 'status':
+            status();
+            break;
+        case 'config':
+            config();
+            break;
+        case 'logs':
+            logs();
+            break;
+        default:
+            console.error(`unknown command: ${cmd}\n` +
+                'usage: service.ts <install|uninstall|restart|status|config|logs> [flags]\n' +
+                `  flags (install): ${Object.keys(FLAG_ENV).join(', ')}`);
+            process.exit(1);
+    }
+}

package/dist-node/scripts/service/configuration.js

@@ -0,0 +1,205 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { serviceEnvironmentWithSetting } from "../../src/config.js";
+import { exposeStorePath, FUNNEL_PORTS, normalizeExposeMode, relayServeState, tailscaleBin } from "../../src/host/tailscale.js";
+import { readVoiceConfig, setVoiceSetting, VOICE_SETTING_NAMES } from "../../src/voice/config.js";
+import { domain, LABEL, plistPath, projectDir, readPlistEnv } from "./environment.js";
+import { FLAG_ENV } from "./flags.js";
+import { tailscaleState } from "./network.js";
+const CONFIG_KEYS = new Map(Object.entries(FLAG_ENV).map(([flag, env]) => [flag.slice(2), env]));
+const HOME = os.homedir();
+const tilde = (p) => (p.startsWith(HOME) ? `~${p.slice(HOME.length)}` : p);
+const KNOBS = [
+    {
+        name: 'expose',
+        env: 'EXPOSE',
+        // The runtime's own precedence (src/host/tailscale.ts ▸ readExposeMode): env, then the persisted
+        // file, then public. Reported the same way so this can never describe a posture the relay
+        // isn't running.
+        fallback: () => {
+            try {
+                return normalizeExposeMode(fs.readFileSync(exposeStorePath(), 'utf8')) ?? 'public';
+            }
+            catch {
+                return 'public';
+            }
+        },
+        fallbackSource: () => (fs.existsSync(exposeStorePath()) ? 'expose file' : 'default')
+    },
+    { name: 'port', env: 'RELAY_PORT', fallback: () => '8787' },
+    { name: 'voice-port', env: 'VOICE_PORT', fallback: () => '8788' },
+    { name: 'host', env: 'RELAY_HOST', fallback: () => '127.0.0.1' },
+    { name: 'write-strategy', env: 'WRITE_STRATEGY', fallback: () => 'applescript' },
+    { name: 'prevent-screen-lock', env: 'PREVENT_SCREEN_LOCK', fallback: () => 'on' },
+    { name: 'auto-update', env: 'AUTO_UPDATE', fallback: () => 'auto' },
+    { name: 'auto-update-interval', env: 'AUTO_UPDATE_INTERVAL_MINUTES', fallback: () => '5 (minutes)' },
+    {
+        name: 'funnel-watchdog',
+        env: 'FUNNEL_WATCHDOG',
+        // Two gates, not one: it defaults on for the managed daemon and then stands down unless the
+        // posture is public (src/host/funnel-watchdog.ts ▸ wantEnabled + startFunnelWatchdog).
+        fallback: env => (env.CONDUCTOR_REMOTE_MANAGED === '1' ? 'on (managed daemon)' : 'off (not managed)')
+    },
+    { name: 'funnel-watchdog-interval', env: 'FUNNEL_WATCHDOG_INTERVAL_SECONDS', fallback: () => '60 (seconds)' },
+    {
+        name: 'db',
+        env: 'CONDUCTOR_DB',
+        fallback: () => tilde(path.join(HOME, 'Library', 'Application Support', 'com.conductor.app', 'conductor.db'))
+    },
+    {
+        name: 'workspaces',
+        env: 'CONDUCTOR_WORKSPACES',
+        fallback: () => tilde(path.join(HOME, 'conductor', 'workspaces'))
+    }
+];
+/** Set one daemon knob while preserving every other value already baked into the plist. */
+function setConfig(args) {
+    const [name, value, ...extra] = args;
+    const envKey = name ? CONFIG_KEYS.get(name) : undefined;
+    if (!name || value === undefined || extra.length > 0) {
+        console.error('usage: conductor-remote config set <setting> <value>');
+        process.exit(1);
+    }
+    if (name && VOICE_SETTING_NAMES.includes(name)) {
+        try {
+            setVoiceSetting(name, value);
+        }
+        catch (error) {
+            console.error(`config set: ${error instanceof Error ? error.message : error}`);
+            process.exit(1);
+        }
+        if (!fs.existsSync(plistPath)) {
+            console.info(`✓ set ${name}. Install the service to start the voice listener.`);
+            return;
+        }
+        const childEnv = { ...process.env, ...readPlistEnv(), CONDUCTOR_REMOTE_CONFIG_SET: name };
+        const cli = path.join(projectDir, 'bin', 'cli.js');
+        const result = spawnSync(process.execPath, [cli, 'service', 'install'], { env: childEnv, stdio: 'inherit' });
+        if (result.error)
+            console.error(`config set: could not restart the service (${result.error.message})`);
+        process.exit(result.status ?? 1);
+    }
+    if (!envKey) {
+        console.error(`config set: unknown setting "${name}"\n  known: ${[...CONFIG_KEYS.keys(), ...VOICE_SETTING_NAMES].join(', ')}`);
+        process.exit(1);
+    }
+    if (name === 'prevent-screen-lock' && value !== 'on' && value !== 'off') {
+        console.error('config set: prevent-screen-lock must be on or off');
+        process.exit(1);
+    }
+    if (!fs.existsSync(plistPath)) {
+        console.error('config set: the service is not installed. Run `conductor-remote service install` first.');
+        process.exit(1);
+    }
+    // Re-run install in a fresh process so module-level values such as RELAY_PORT see
+    // the new environment. Start from the plist, which protects unrelated settings
+    // from ambient shell variables and from being reset to defaults.
+    const childEnv = serviceEnvironmentWithSetting(process.env, readPlistEnv(), CONFIG_KEYS.values(), envKey, value);
+    childEnv.CONDUCTOR_REMOTE_CONFIG_SET = name;
+    const cli = path.join(projectDir, 'bin', 'cli.js');
+    const result = spawnSync(process.execPath, [cli, 'service', 'install'], { env: childEnv, stdio: 'inherit' });
+    if (result.error)
+        console.error(`config set: could not restart the service (${result.error.message})`);
+    process.exit(result.status ?? 1);
+}
+/** What the daemon is configured with, where values came from, and an optional setter. */
+export function config() {
+    if (process.argv[3] === 'set') {
+        setConfig(process.argv.slice(4));
+        return;
+    }
+    if (process.argv[3] !== undefined) {
+        console.error('usage: conductor-remote config [set <setting> <value>]');
+        process.exit(1);
+    }
+    if (!fs.existsSync(plistPath)) {
+        console.info(`plist:  (not installed)\n\nRun \`conductor-remote service install\` first.`);
+        return;
+    }
+    const env = readPlistEnv();
+    console.info(`plist:  ${tilde(plistPath)}`);
+    console.info(`state:  ${tilde(path.dirname(exposeStorePath()))}`);
+    try {
+        const out = execFileSync('launchctl', ['print', `${domain}/${LABEL}`], { encoding: 'utf8', stdio: 'pipe' });
+        console.info(`daemon: ${out.match(/state = (\S+)/)?.[1] ?? 'unknown'}  (pid ${out.match(/pid = (\d+)/)?.[1] ?? '—'})`);
+    }
+    catch {
+        console.info('daemon: loaded but not running (check `conductor-remote logs`)');
+    }
+    const rows = KNOBS.map(k => {
+        const set = env[k.env];
+        return {
+            name: k.name,
+            value: set ?? k.fallback(env),
+            source: set ? 'plist' : (k.fallbackSource?.(env) ?? 'default')
+        };
+    });
+    // The token is deliberately not a row above: it never rides in the plist, and this output is the
+    // kind of thing that gets pasted into an issue. Shown truncated, like every other log surface here.
+    let token = '(none yet — minted on first start)';
+    try {
+        const raw = fs.readFileSync(path.join(path.dirname(exposeStorePath()), 'token'), 'utf8').trim();
+        if (raw)
+            token = `${raw.slice(0, 4)}…${raw.slice(-4)}`;
+    }
+    catch {
+        // no token file yet
+    }
+    rows.push({ name: 'token', value: token, source: 'token file' });
+    const voice = readVoiceConfig();
+    rows.push({ name: 'voice.openai-key', value: voice.openaiKey ? '(set)' : '(unset)', source: 'voice file' }, { name: 'voice.webhook-secret', value: voice.webhookSecret ? '(set)' : '(unset)', source: 'voice file' }, { name: 'voice.twilio-auth-token', value: voice.twilioAuthToken ? '(set)' : '(unset)', source: 'voice file' }, {
+        name: 'voice.allowed-callers',
+        value: voice.allowedCallers.length ? `${voice.allowedCallers.length} set` : '(unset)',
+        source: 'voice file'
+    }, { name: 'voice.pin', value: voice.pin ? '(set)' : '(unset)', source: 'voice file' }, { name: 'voice.project-id', value: voice.projectId ? '(set)' : '(unset)', source: 'voice file' }, { name: 'voice.public-url', value: voice.publicBaseUrl ?? '(unset)', source: 'voice file' }, { name: 'voice.model', value: voice.model, source: 'voice file' }, { name: 'voice.voice', value: voice.voice, source: 'voice file' }, { name: 'voice.sip-host', value: voice.sipHost, source: 'voice file' });
+    // The HTTPS port is a live Tailscale fact, not a plist knob: :443 by default, elsewhere once another
+    // service holds :443 (see ensureServeOnly), and the phone URL carries whichever it is. Read against the
+    // daemon's own port, since this shell's RELAY_PORT is not the one the relay listens on.
+    const bin = tailscaleBin();
+    const livePort = env.RELAY_PORT ?? '8787';
+    const live = bin ? tailscaleState(bin, livePort) : relayServeState({}, livePort);
+    rows.push({
+        name: 'https-port',
+        value: live.port === null ? '(not fronted)' : String(live.port),
+        source: 'tailscale serve'
+    });
+    const width = Math.max(...rows.map(r => r.name.length));
+    const valueWidth = Math.max(...rows.map(r => r.value.length));
+    console.info('');
+    for (const r of rows) {
+        console.info(`  ${r.name.padEnd(width)}  ${r.value.padEnd(valueWidth)}  ${r.source}`);
+    }
+    console.info('\n  (values come from the daemon\u2019s own plist environment, not this shell\u2019s)');
+    console.info('  change one with: conductor-remote config set <setting> <value>');
+    // The cross-check worth having. A posture the relay believes and a Tailscale that is doing something
+    // else is invisible in every other command, and it is self-healing in the wrong direction: the funnel
+    // watchdog only runs for `public`, so a relay that thinks it is public will re-register Funnel.
+    const configured = rows.find(r => r.name === 'expose')?.value;
+    if (!bin || !configured)
+        return;
+    const liveMode = live.funnelOn ? 'public' : live.port !== null ? 'tailnet' : null;
+    const where = live.port !== null && live.port !== 443 ? ` on :${live.port}` : '';
+    const funnelable = live.port === null || FUNNEL_PORTS.includes(live.port);
+    console.info('');
+    if (liveMode === null) {
+        console.info(`  \u26a0 tailscale is not fronting 127.0.0.1:${livePort} at all — the phone URL is not wired.`);
+        console.info('    Fix with: conductor-remote service install');
+    }
+    else if (liveMode === configured) {
+        console.info(`  \u2713 tailscale agrees: ${liveMode === 'public' ? 'Funnel on (internet-facing)' : 'serve only (tailnet)'}${where}`);
+    }
+    else {
+        console.info(`  \u26a0 tailscale says ${liveMode}${where}, the daemon is configured ${configured}. They must match:`);
+        console.info(`    the funnel watchdog only runs for \`public\`, so the two can heal each other apart.`);
+        if (configured === 'public' && !funnelable) {
+            console.info(`    Funnel cannot listen on :${live.port} (only ${FUNNEL_PORTS.join(', ')}), so either move the relay by hand`);
+            console.info(`    (tailscale funnel --bg --yes --https=<443|8443|10000> ${livePort}) or match the daemon to it:`);
+            console.info('    conductor-remote service install --expose tailnet');
+        }
+        else {
+            console.info(`    Fix with: conductor-remote service install --expose ${configured}`);
+        }
+    }
+}

package/dist-node/scripts/service/environment.js

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { installedServiceEnvironment } from "../../src/config.js";
+import { relayPort } from "../../src/host/tailscale.js";
+import { packageRoot } from "../../src/pkg-root.js";
+export const LABEL = 'no.adluna.conductor-remote';
+export const projectDir = packageRoot(import.meta.dirname);
+export const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+export const logDir = path.join(os.homedir(), 'Library', 'Logs', 'conductor-remote');
+const uid = process.getuid?.() ?? 0;
+export const domain = `gui/${uid}`;
+export 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. */
+export 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.
+ */
+export 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})`);
+    }
+}
+export const RELAY_PORT = relayPort();
+export const VOICE_PORT = String(process.env.VOICE_PORT ?? 8788);
+/**
+ * The daemon's environment, read back out of the plist it was installed with.
+ *
+ * This is the whole point of `config`: `process.env` here belongs to *your shell*, and the daemon
+ * runs under launchd with whatever `buildPlist()` baked in. Reading the shell's env to report the
+ * daemon's configuration is how a posture change can look applied while the running relay still
+ * believes something else — which is exactly the bug that made EXPOSE a plist entry.
+ */
+export function readPlistEnv() {
+    return installedServiceEnvironment();
+}

package/dist-node/scripts/service/flags.js

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+export const FLAG_ENV = {
+    '--expose': 'EXPOSE',
+    '--port': 'RELAY_PORT',
+    '--voice-port': 'VOICE_PORT',
+    '--host': 'RELAY_HOST',
+    '--hostname': 'RELAY_HOSTNAME',
+    '--token': 'RELAY_TOKEN',
+    '--write-strategy': 'WRITE_STRATEGY',
+    '--prevent-screen-lock': 'PREVENT_SCREEN_LOCK',
+    '--auto-update': 'AUTO_UPDATE',
+    '--auto-update-interval': 'AUTO_UPDATE_INTERVAL_MINUTES',
+    '--funnel-watchdog': 'FUNNEL_WATCHDOG',
+    '--funnel-watchdog-interval': 'FUNNEL_WATCHDOG_INTERVAL_SECONDS',
+    '--db': 'CONDUCTOR_DB',
+    '--workspaces': 'CONDUCTOR_WORKSPACES'
+};
+export 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);
+        }
+        if (name === '--prevent-screen-lock' && value !== 'on' && value !== 'off') {
+            console.error(`flag ${name} must be on or off`);
+            process.exit(1);
+        }
+        process.env[envKey] = value;
+    }
+}

package/dist-node/scripts/service/installation.js

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { exposeStorePath } from "../../src/host/tailscale.js";
+import { readVoiceConfig } from "../../src/voice/config.js";
+import { distBuilt, domain, LABEL, logDir, persistPinnedToken, plistPath, projectDir, readPlistEnv } from "./environment.js";
+import { buildPlist, launchctl, reloadAgent } from "./launch-agent.js";
+import { ensureTailscale, resolveExposeMode } from "./network.js";
+import { printUrl, printVoiceRoute } from "./presentation.js";
+import { ensureVoiceFunnel } from "./voice.js";
+/** 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);
+}
+export 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();
+    // Resolve (and persist) the expose posture *before* the plist is written and launchd is reloaded, so
+    // the daemon starts with an explicit EXPOSE in its own environment rather than racing the file
+    // ensureTailscale() writes further down. Folding it back into process.env is how every other knob
+    // travels here (see applyFlags), and it keeps ensureTailscale()'s own resolve a no-op re-read.
+    const requestedExpose = resolveExposeMode();
+    if (readVoiceConfig().publicBaseUrl) {
+        if (requestedExpose !== 'tailnet')
+            console.info('  voice requires the relay itself to stay tailnet-only; forcing EXPOSE=tailnet.');
+        process.env.EXPOSE = 'tailnet';
+        try {
+            fs.mkdirSync(path.dirname(exposeStorePath()), { recursive: true });
+            fs.writeFileSync(exposeStorePath(), 'tailnet');
+        }
+        catch {
+            // The plist still carries the safe posture; this file is only the next install's default.
+        }
+    }
+    else {
+        process.env.EXPOSE = requestedExpose;
+    }
+    fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+    fs.mkdirSync(logDir, { recursive: true });
+    fs.writeFileSync(plistPath, buildPlist());
+    reloadAgent();
+    const changedSetting = process.env.CONDUCTOR_REMOTE_CONFIG_SET;
+    if (changedSetting) {
+        if (changedSetting === 'expose' ||
+            changedSetting === 'port' ||
+            changedSetting === 'voice-port' ||
+            changedSetting === 'hostname' ||
+            changedSetting.startsWith('voice.')) {
+            ensureTailscale();
+            ensureVoiceFunnel();
+        }
+        console.info(`✓ set ${changedSetting}; the relay restarted with the new value.`);
+        console.info('  Check it with: conductor-remote config');
+        return;
+    }
+    console.info(`✓ installed LaunchAgent ${LABEL}`);
+    console.info(`  plist: ${plistPath}`);
+    console.info(`  logs:  ${logDir}/relay.log`);
+    console.info(`  node:  ${process.execPath}`);
+    ensureTailscale();
+    ensureVoiceFunnel();
+    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).');
+}
+export function uninstall() {
+    launchctl('bootout', `${domain}/${LABEL}`);
+    try {
+        fs.rmSync(plistPath);
+    }
+    catch {
+        // already gone
+    }
+    console.info(`✓ removed LaunchAgent ${LABEL}`);
+}
+export function restart() {
+    launchctl('kickstart', '-k', `${domain}/${LABEL}`);
+    console.info(`✓ restarted ${LABEL}`);
+    const env = readPlistEnv();
+    const relayPort = env.RELAY_PORT ?? '8787';
+    printUrl(relayPort);
+    printVoiceRoute(relayPort, env.VOICE_PORT ?? '8788');
+}

package/dist-node/scripts/service/launch-agent.js

@@ -0,0 +1,134 @@
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { domain, LABEL, logDir, plistPath, projectDir } from "./environment.js";
+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. */
+export 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. */
+export 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.
+ */
+export 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. */
+export 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: src/host/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']
+    ];
+    // EXPOSE belongs here with the other runtime knobs, and leaving it out was a real bug. The daemon
+    // reads its posture on every boot (the funnel watchdog only arms itself for `public`), but install()
+    // reloads launchd *before* ensureTailscale() persists the choice — so a fresh `--expose tailnet`
+    // daemon came up reading the old posture, armed the watchdog against a Funnel that was about to be
+    // switched off, and ~3 failed probes later healed it straight back to public. Baking the resolved
+    // value makes the daemon's own environment the answer, so nothing depends on write ordering.
+    if (process.env.EXPOSE)
+        envEntries.push(['EXPOSE', process.env.EXPOSE]);
+    if (process.env.WRITE_STRATEGY)
+        envEntries.push(['WRITE_STRATEGY', process.env.WRITE_STRATEGY]);
+    if (process.env.PREVENT_SCREEN_LOCK)
+        envEntries.push(['PREVENT_SCREEN_LOCK', process.env.PREVENT_SCREEN_LOCK]);
+    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.VOICE_PORT)
+        envEntries.push(['VOICE_PORT', process.env.VOICE_PORT]);
+    if (process.env.AUTO_UPDATE)
+        envEntries.push(['AUTO_UPDATE', process.env.AUTO_UPDATE]);
+    if (process.env.AUTO_UPDATE_INTERVAL_MINUTES)
+        envEntries.push(['AUTO_UPDATE_INTERVAL_MINUTES', process.env.AUTO_UPDATE_INTERVAL_MINUTES]);
+    if (process.env.FUNNEL_WATCHDOG)
+        envEntries.push(['FUNNEL_WATCHDOG', process.env.FUNNEL_WATCHDOG]);
+    if (process.env.FUNNEL_WATCHDOG_INTERVAL_SECONDS)
+        envEntries.push(['FUNNEL_WATCHDOG_INTERVAL_SECONDS', process.env.FUNNEL_WATCHDOG_INTERVAL_SECONDS]);
+    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>
+`;
+}