@kortix/agent-tunnel 0.13.41 → 0.13.43

package/src/agent/service-drivers.ts

@@ -4,7 +4,7 @@ import { homedir, platform, userInfo } from 'os';
 import { dirname, join } from 'path';
 import { powershellQuote, shellQuote, xmlEscape } from './service-quoting';
 import type { ServicePaths } from './service-paths';
-import { SERVICE_LABEL, TERMINAL_SERVICE_EXIT_CODE, getServicePaths } from './service-paths';
+import { getServicePaths } from './service-paths';
 
 /**
  * One driver per supervisor.
@@ -17,10 +17,16 @@ import { SERVICE_LABEL, TERMINAL_SERVICE_EXIT_CODE, getServicePaths } from './se
 export interface ServiceDriver {
   /** File that proves the service is installed, and is shown to the user. */
   unitPath(paths: ServicePaths): string;
+  /** The unit file contents `install` writes for this runner. */
+  render(paths: ServicePaths, runner: RunnerParts): string;
   install(paths: ServicePaths, runner: RunnerParts): Outcome;
   uninstall(paths: ServicePaths): Outcome;
   start(paths: ServicePaths, installed: boolean): Outcome;
   stop(paths: ServicePaths, installed: boolean): Outcome;
+  /** R3: stop AND keep it stopped across login and reboot, until resume. */
+  pause(paths: ServicePaths, installed: boolean): Outcome;
+  /** Reverses pause: enable, load, start. */
+  resume(paths: ServicePaths, installed: boolean): Outcome;
   status(paths: ServicePaths, installed: boolean): Outcome;
 }
 
@@ -28,6 +34,8 @@ export interface ServiceDriver {
 export interface RunnerParts {
   command: string;
   args: string[];
+  /** Extra environment for the supervised process (AGENT_TUNNEL_HOME, ELECTRON_RUN_AS_NODE). */
+  env?: Record<string, string>;
 }
 
 /**
@@ -37,13 +45,23 @@ export interface RunnerParts {
  */
 export function posixShellCommand(runner: RunnerParts): string {
   const interpreter = `"$(command -v ${shellQuote(runner.command)} 2>/dev/null || command -v node)"`;
-  return `exec ${interpreter} ${runner.args.map(shellQuote).join(' ')}`;
+  // Exported inside the command, after the login shell's profile has run, so
+  // one rendering serves launchd and systemd alike and no profile can drop it.
+  const env = Object.entries(runner.env ?? {});
+  const exports = env.length
+    ? `export ${env.map(([key, value]) => `${key}=${shellQuote(value)}`).join(' ')}; `
+    : '';
+  return `${exports}exec ${interpreter} ${runner.args.map(shellQuote).join(' ')}`;
 }
 
 export interface Outcome {
   /** `null` means "requested, but the supervisor did not confirm". */
   active?: boolean | null;
   installed?: boolean;
+  /** False while paused (disabled in the supervisor). */
+  enabled?: boolean;
+  /** Status only: the unit on disk equals what install would write now. */
+  upToDate?: boolean;
   detail?: string;
 }
 
@@ -52,16 +70,23 @@ interface CommandResult {
   detail: string;
 }
 
-function run(command: string, args: string[]): CommandResult {
-  const result = spawnSync(command, args, { encoding: 'utf8' });
-  return {
-    ok: result.status === 0,
-    detail: [result.stdout, result.stderr].filter(Boolean).join('\n').trim(),
-  };
-}
+/** The one place a supervisor command runs. Replaced in tests. */
+export const supervisor = {
+  run(command: string, args: string[]): CommandResult {
+    const result = spawnSync(command, args, { encoding: 'utf8' });
+    return {
+      ok: result.status === 0,
+      detail: [result.stdout, result.stderr].filter(Boolean).join('\n').trim(),
+    };
+  },
+};
+const run = (command: string, args: string[]): CommandResult => supervisor.run(command, args);
 
 const notInstalled = (what: string): CommandResult => ({ ok: false, detail: `${what} is not installed.` });
 
+/** Blocking pause between supervisor retries. Replaced in tests. */
+export const pause = { ms(ms: number): void { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } };
+
 function joinDetails(...results: CommandResult[]): string {
   return results.map((result) => result.detail).filter(Boolean).join('\n');
 }
@@ -82,14 +107,14 @@ function logPaths(paths: ServicePaths): { stdout: string; stderr: string } {
 
 export function renderLaunchdPlist(command: string, paths: ServicePaths = getServicePaths()): string {
   const { stdout, stderr } = logPaths(paths);
-  // KeepAlive is conditional: a clean exit means the agent stopped for a reason
-  // restarting cannot fix, such as a missing or revoked credential.
+  // KeepAlive is unconditional (R3): the agent never exits on its own for a bad
+  // credential any more, so any exit is a crash. Pause is `launchctl disable`.
   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>${xmlEscape(SERVICE_LABEL)}</string>
+  <string>${xmlEscape(paths.label)}</string>
   <key>ProgramArguments</key>
   <array>
     <string>/bin/sh</string>
@@ -99,10 +124,9 @@ export function renderLaunchdPlist(command: string, paths: ServicePaths = getSer
   <key>RunAtLoad</key>
   <true/>
   <key>KeepAlive</key>
-  <dict>
-    <key>SuccessfulExit</key>
-    <false/>
-  </dict>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
   <key>Umask</key>
   <integer>63</integer>
   <key>StandardOutPath</key>
@@ -132,7 +156,7 @@ Wants=network-online.target
 Type=simple
 UMask=0077
 ExecStart=/bin/sh -lc ${shellQuote(command)}
-Restart=on-failure
+Restart=always
 RestartSec=5
 WorkingDirectory=${homedir()}
 Environment=PATH=/usr/local/bin:/usr/bin:/bin
@@ -144,15 +168,18 @@ WantedBy=default.target
 `;
 }
 
-export function renderWindowsPowerShellScript(runner: { command: string; args: string[] }): string {
+export function renderWindowsPowerShellScript(runner: RunnerParts): string {
   const command = powershellQuote(runner.command);
   const args = runner.args.map(powershellQuote).join(' ');
+  const env = Object.entries(runner.env ?? {})
+    .map(([key, value]) => `$env:${key} = ${powershellQuote(value)}\n`)
+    .join('');
   return `$ErrorActionPreference = 'Continue'
-while ($true) {
-  & ${command}${args ? ` ${args}` : ''}
-  # A clean exit means the agent stopped for a reason restarting cannot fix,
-  # such as a missing or revoked credential. Anything else is a crash worth retrying.
-  if ($LASTEXITCODE -eq ${TERMINAL_SERVICE_EXIT_CODE}) { break }
+${env}while ($true) {
+  # The pipe makes PowerShell wait for a GUI-subsystem binary (the desktop
+  # app's Kortix.exe) and set $LASTEXITCODE; a bare call returns at once.
+  & ${command}${args ? ` ${args}` : ''} | Out-Null
+  # The agent never exits on its own (R2), so every exit is restarted.
   Start-Sleep -Seconds 5
 }
 `;
@@ -162,14 +189,27 @@ while ($true) {
 
 const launchd: ServiceDriver = {
   unitPath: (paths) => paths.launchdPlist,
+  render: (paths, runner) => renderLaunchdPlist(posixShellCommand(runner), paths),
 
   install(paths, runner) {
     mkdirSync(dirname(paths.launchdPlist), { recursive: true });
-    writeFileSync(paths.launchdPlist, renderLaunchdPlist(posixShellCommand(runner), paths), { mode: 0o600 });
+    writeFileSync(paths.launchdPlist, launchd.render(paths, runner), { mode: 0o600 });
     run('launchctl', ['bootout', launchdTarget(), paths.launchdPlist]);
-    const boot = run('launchctl', ['bootstrap', launchdTarget(), paths.launchdPlist]);
-    const kick = run('launchctl', ['kickstart', '-k', `${launchdTarget()}/${SERVICE_LABEL}`]);
-    return { installed: true, active: boot.ok || kick.ok ? true : null, detail: joinDetails(boot, kick) };
+    run('launchctl', ['enable', `${launchdTarget()}/${paths.label}`]);
+    // `bootstrap` right after `bootout` often fails with "5: Input/output error"
+    // while launchd still tears the old job down. Only `print` proves the job
+    // is loaded, so retry until it does.
+    let boot: CommandResult = { ok: false, detail: '' };
+    let kick: CommandResult = { ok: false, detail: '' };
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (attempt > 0) pause.ms(1_000);
+      boot = run('launchctl', ['bootstrap', launchdTarget(), paths.launchdPlist]);
+      kick = run('launchctl', ['kickstart', '-k', `${launchdTarget()}/${paths.label}`]);
+      if (run('launchctl', ['print', `${launchdTarget()}/${paths.label}`]).ok) {
+        return { installed: true, active: true, detail: joinDetails(boot, kick) };
+      }
+    }
+    return { installed: true, active: null, detail: joinDetails(boot, kick) };
   },
 
   uninstall(paths) {
@@ -183,7 +223,7 @@ const launchd: ServiceDriver = {
     const boot = installed
       ? run('launchctl', ['bootstrap', launchdTarget(), paths.launchdPlist])
       : notInstalled('LaunchAgent');
-    const kick = run('launchctl', ['kickstart', '-k', `${launchdTarget()}/${SERVICE_LABEL}`]);
+    const kick = run('launchctl', ['kickstart', '-k', `${launchdTarget()}/${paths.label}`]);
     return { active: boot.ok || kick.ok ? true : null, detail: joinDetails(boot, kick) };
   },
 
@@ -194,10 +234,29 @@ const launchd: ServiceDriver = {
     return { detail: stop.detail };
   },
 
+  pause(paths) {
+    // `disable` is stored by launchd across logins; bootstrap refuses a disabled job.
+    const disable = run('launchctl', ['disable', `${launchdTarget()}/${paths.label}`]);
+    const stop = run('launchctl', ['bootout', launchdTarget(), paths.launchdPlist]);
+    return { enabled: disable.ok ? false : undefined, detail: joinDetails(disable, stop) };
+  },
+
+  resume(paths, installed) {
+    const enable = run('launchctl', ['enable', `${launchdTarget()}/${paths.label}`]);
+    const boot = installed
+      ? run('launchctl', ['bootstrap', launchdTarget(), paths.launchdPlist])
+      : notInstalled('LaunchAgent');
+    const kick = run('launchctl', ['kickstart', `${launchdTarget()}/${paths.label}`]);
+    return { enabled: enable.ok, active: boot.ok || kick.ok ? true : null, detail: joinDetails(enable, boot, kick) };
+  },
+
   status(paths, installed) {
-    const status = run('launchctl', ['print', `${launchdTarget()}/${SERVICE_LABEL}`]);
+    const disabled = run('launchctl', ['print-disabled', launchdTarget()]);
+    const enabled = !new RegExp(`"${paths.label.replace(/\./g, '\\.')}" => (disabled|true)`).test(disabled.detail);
+    const status = run('launchctl', ['print', `${launchdTarget()}/${paths.label}`]);
     return {
       active: status.ok,
+      enabled,
       detail: status.detail || (installed ? readFileSync(paths.launchdPlist, 'utf8') : undefined),
     };
   },
@@ -205,83 +264,169 @@ const launchd: ServiceDriver = {
 
 const systemd: ServiceDriver = {
   unitPath: (paths) => paths.systemdUnit,
+  render: (paths, runner) => renderSystemdUnit(posixShellCommand(runner), paths),
 
   install(paths, runner) {
     mkdirSync(dirname(paths.systemdUnit), { recursive: true });
-    writeFileSync(paths.systemdUnit, renderSystemdUnit(posixShellCommand(runner), paths), { mode: 0o600 });
+    writeFileSync(paths.systemdUnit, systemd.render(paths, runner), { mode: 0o600 });
     const reload = run('systemctl', ['--user', 'daemon-reload']);
-    const enable = run('systemctl', ['--user', 'enable', '--now', `${SERVICE_LABEL}.service`]);
-    return { installed: true, active: enable.ok ? true : null, detail: joinDetails(reload, enable) };
+    const enable = run('systemctl', ['--user', 'enable', `${paths.label}.service`]);
+    // `enable --now` leaves an already-running agent alone, so an app update
+    // never rolled it (R5). `restart` starts a stopped unit too.
+    const restart = run('systemctl', ['--user', 'restart', `${paths.label}.service`]);
+    return {
+      installed: true,
+      active: restart.ok ? true : null,
+      detail: joinDetails(reload, enable, restart, ensureLinger()),
+    };
   },
 
   uninstall(paths) {
     const existed = existsSync(paths.systemdUnit);
-    const disable = run('systemctl', ['--user', 'disable', '--now', `${SERVICE_LABEL}.service`]);
+    const disable = run('systemctl', ['--user', 'disable', '--now', `${paths.label}.service`]);
     if (existed) rmSync(paths.systemdUnit, { force: true });
     run('systemctl', ['--user', 'daemon-reload']);
     return { detail: disable.detail };
   },
 
-  start(_paths, installed) {
+  start(paths, installed) {
     const start = installed
-      ? run('systemctl', ['--user', 'start', `${SERVICE_LABEL}.service`])
+      ? run('systemctl', ['--user', 'start', `${paths.label}.service`])
       : notInstalled('systemd unit');
     return { active: start.ok ? true : null, detail: start.detail };
   },
 
-  stop(_paths, installed) {
+  stop(paths, installed) {
     const stop = installed
-      ? run('systemctl', ['--user', 'stop', `${SERVICE_LABEL}.service`])
+      ? run('systemctl', ['--user', 'stop', `${paths.label}.service`])
       : notInstalled('systemd unit');
     return { detail: stop.detail };
   },
 
-  status() {
-    const status = run('systemctl', ['--user', 'is-active', `${SERVICE_LABEL}.service`]);
-    return { active: status.ok, detail: status.detail };
+  pause(paths) {
+    const disable = run('systemctl', ['--user', 'disable', '--now', `${paths.label}.service`]);
+    return { enabled: disable.ok ? false : undefined, active: false, detail: disable.detail };
+  },
+
+  resume(paths) {
+    const enable = run('systemctl', ['--user', 'enable', '--now', `${paths.label}.service`]);
+    return { enabled: enable.ok, active: enable.ok ? true : null, detail: enable.detail };
+  },
+
+  status(paths) {
+    const status = run('systemctl', ['--user', 'is-active', `${paths.label}.service`]);
+    const enabled = run('systemctl', ['--user', 'is-enabled', `${paths.label}.service`]);
+    return { active: status.ok, enabled: enabled.ok, detail: status.detail };
   },
 };
 
+/**
+ * A user service stops at logout and does not start at boot unless the user
+ * lingers: an SSH-only server would go offline when the session ends.
+ */
+function ensureLinger(): CommandResult {
+  const user = userInfo().username;
+  const linger = run('loginctl', ['show-user', user, '-p', 'Linger']);
+  if (/Linger=yes/.test(linger.detail)) return { ok: true, detail: '' };
+  if (run('loginctl', ['enable-linger', user]).ok) return { ok: true, detail: 'Enabled lingering: the service keeps running after logout and starts at boot.' };
+  return {
+    ok: false,
+    detail: `Warning: the service stops when you log out and starts only at your next login. Run \`loginctl enable-linger ${user}\` (may need sudo) to keep it running.`,
+  };
+}
+
+/**
+ * Task Scheduler definition. schtasks' own defaults stop the task on battery,
+ * refuse to start it on battery, and kill it after 72 h, and a visible console
+ * window ends the loop when the user closes it. Written as UTF-16, the
+ * encoding schtasks /XML expects.
+ */
+export function renderWindowsTaskXml(paths: ServicePaths, user: string): string {
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo><Description>Kortix Agent Tunnel</Description></RegistrationInfo>
+  <Triggers><LogonTrigger><Enabled>true</Enabled><UserId>${xmlEscape(user)}</UserId></LogonTrigger></Triggers>
+  <Principals><Principal id="Author"><UserId>${xmlEscape(user)}</UserId><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <Enabled>true</Enabled>
+  </Settings>
+  <Actions Context="Author"><Exec><Command>powershell.exe</Command><Arguments>${xmlEscape(`-NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -File "${paths.windowsScript}"`)}</Arguments></Exec></Actions>
+</Task>
+`;
+}
+
+const windowsUser = () => (process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${userInfo().username}` : userInfo().username);
+const windowsTaskXmlPath = (paths: ServicePaths) => paths.windowsScript.replace(/\.ps1$/, '.xml');
+
 const scheduledTask: ServiceDriver = {
   unitPath: (paths) => paths.windowsScript,
+  render: (_paths, runner) => renderWindowsPowerShellScript(runner),
 
   install(paths, runner) {
     writeFileSync(paths.windowsScript, renderWindowsPowerShellScript(runner), { mode: 0o600 });
-    const create = run('schtasks.exe', [
-      '/Create', '/TN', SERVICE_LABEL,
-      '/TR', `powershell.exe -NoProfile -ExecutionPolicy Bypass -File "${paths.windowsScript}"`,
-      '/SC', 'ONLOGON', '/F', '/RL', 'LIMITED',
-    ]);
-    const start = run('schtasks.exe', ['/Run', '/TN', SERVICE_LABEL]);
+    const xml = windowsTaskXmlPath(paths);
+    writeFileSync(xml, Buffer.from(`\ufeff${renderWindowsTaskXml(paths, windowsUser())}`, 'utf16le'), { mode: 0o600 });
+    const create = run('schtasks.exe', ['/Create', '/TN', paths.label, '/XML', xml, '/F']);
+    // /Run does nothing while the old loop runs, so an app update never rolled
+    // the agent (R5). End it first; /End on a stopped task only reports an error.
+    run('schtasks.exe', ['/End', '/TN', paths.label]);
+    const start = run('schtasks.exe', ['/Run', '/TN', paths.label]);
     return { installed: create.ok, active: start.ok ? true : null, detail: joinDetails(create, start) };
   },
 
   uninstall(paths) {
     const existed = existsSync(paths.windowsScript);
-    const stop = run('schtasks.exe', ['/End', '/TN', SERVICE_LABEL]);
-    const del = run('schtasks.exe', ['/Delete', '/TN', SERVICE_LABEL, '/F']);
+    const stop = run('schtasks.exe', ['/End', '/TN', paths.label]);
+    const del = run('schtasks.exe', ['/Delete', '/TN', paths.label, '/F']);
     if (existed) rmSync(paths.windowsScript, { force: true });
+    rmSync(windowsTaskXmlPath(paths), { force: true });
     return { detail: joinDetails(stop, del) };
   },
 
-  start(_paths, installed) {
+  start(paths, installed) {
     const start = installed
-      ? run('schtasks.exe', ['/Run', '/TN', SERVICE_LABEL])
+      ? run('schtasks.exe', ['/Run', '/TN', paths.label])
       : notInstalled('Scheduled Task');
     return { active: start.ok ? true : null, detail: start.detail };
   },
 
-  stop(_paths, installed) {
+  stop(paths, installed) {
     const stop = installed
-      ? run('schtasks.exe', ['/End', '/TN', SERVICE_LABEL])
+      ? run('schtasks.exe', ['/End', '/TN', paths.label])
       : notInstalled('Scheduled Task');
     return { detail: stop.detail };
   },
 
+  pause(paths) {
+    const disable = run('schtasks.exe', ['/Change', '/TN', paths.label, '/DISABLE']);
+    const stop = run('schtasks.exe', ['/End', '/TN', paths.label]);
+    return { enabled: disable.ok ? false : undefined, active: false, detail: joinDetails(disable, stop) };
+  },
+
+  resume(paths) {
+    const enable = run('schtasks.exe', ['/Change', '/TN', paths.label, '/ENABLE']);
+    const start = run('schtasks.exe', ['/Run', '/TN', paths.label]);
+    return { enabled: enable.ok, active: start.ok ? true : null, detail: joinDetails(enable, start) };
+  },
+
   status(paths, installed) {
-    const status = run('schtasks.exe', ['/Query', '/TN', SERVICE_LABEL, '/FO', 'LIST', '/V']);
-    const detail = status.detail || (installed ? readFileSync(paths.windowsScript, 'utf8') : undefined);
-    return { active: status.ok ? /Status:\s*Running/i.test(detail ?? '') : false, detail };
+    // schtasks /Query prints localized labels and values ("Wird ausgeführt");
+    // the ScheduledTask State enum is not localized: Ready, Running, Disabled, Queued.
+    const status = run('powershell.exe', [
+      '-NoProfile', '-NonInteractive', '-Command',
+      `(Get-ScheduledTask -TaskName ${powershellQuote(paths.label)} -ErrorAction Stop).State`,
+    ]);
+    const state = status.ok ? status.detail.trim() : '';
+    return {
+      active: state === 'Running',
+      enabled: state !== 'Disabled',
+      detail: state || (installed ? readFileSync(paths.windowsScript, 'utf8') : undefined),
+    };
   },
 };
 
@@ -294,6 +439,10 @@ const DRIVERS: Partial<Record<NodeJS.Platform, ServiceDriver>> = {
 export const SUPPORTED_PLATFORMS_MESSAGE =
   'Background services are supported on macOS launchd, Linux systemd user services, and Windows Scheduled Tasks.';
 
+export function serviceDriverFor(os: NodeJS.Platform): ServiceDriver | undefined {
+  return DRIVERS[os];
+}
+
 export function serviceDriver(): ServiceDriver | undefined {
-  return DRIVERS[platform()];
+  return serviceDriverFor(platform());
 }

package/src/agent/service-lifecycle.test.ts

@@ -6,8 +6,7 @@ import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import {
   MAX_SERVICE_LOG_BYTES,
-  TERMINAL_SERVICE_EXIT_CODE,
-  getServicePaths,
+    getServicePaths,
   renderLaunchdPlist,
   renderSystemdUnit,
   renderWindowsPowerShellScript,
@@ -27,30 +26,30 @@ afterEach(async () => {
   temporaryHomes.clear();
 });
 
-describe('supervisor restart policy', () => {
-  test('launchd restarts only on a failure exit', () => {
+describe('supervisor restart policy (R3)', () => {
+  test('launchd restarts on every exit, throttled to 10 s', () => {
     const plist = renderLaunchdPlist('exec /bin/echo tunnel');
-    expect(plist).toContain('<key>SuccessfulExit</key>');
-    expect(plist).toContain('<false/>');
-    // The old unconditional form is what produced the endless respawn loop.
-    expect(plist).not.toContain('<key>KeepAlive</key>\n  <true/>');
+    expect(plist).toContain('<key>KeepAlive</key>\n  <true/>');
+    expect(plist).toContain('<key>ThrottleInterval</key>');
+    expect(plist).not.toContain('SuccessfulExit');
   });
 
-  test('systemd restarts only on a failure exit', () => {
+  test('systemd restarts on every exit', () => {
     const unit = renderSystemdUnit('exec /bin/echo tunnel');
-    expect(unit).toContain('Restart=on-failure');
-    expect(unit).not.toContain('Restart=always');
+    expect(unit).toContain('Restart=always');
+    expect(unit).not.toContain('Restart=on-failure');
   });
 
-  test('windows loop breaks on the terminal exit code', () => {
+  test('the windows loop never breaks', () => {
     const script = renderWindowsPowerShellScript({
       command: 'node',
       args: ['agent-tunnel.js', 'run', '--service'],
     });
-    expect(script).toContain(`if ($LASTEXITCODE -eq ${TERMINAL_SERVICE_EXIT_CODE}) { break }`);
+    expect(script).not.toContain('break');
+    expect(script).toContain('while ($true)');
   });
 
-  test('run --service exits terminally when no credential is saved', async () => {
+  test('run --service without a credential stays alive and waits for one (R2)', async () => {
     const home = await mkdtemp(join(tmpdir(), 'agent-tunnel-nocred-'));
     temporaryHomes.add(home);
 
@@ -59,10 +58,16 @@ describe('supervisor restart policy', () => {
       stdio: ['ignore', 'pipe', 'pipe'],
     });
     children.add(child);
-    const exitCode = await new Promise<number | null>((r) => child.once('exit', r));
+    let stdout = '';
+    child.stdout?.on('data', (chunk) => { stdout += String(chunk); });
+    const exited = await Promise.race([
+      new Promise<boolean>((r) => child.once('exit', () => r(true))),
+      Bun.sleep(2_500).then(() => false),
+    ]);
 
-    // A non-zero exit here would make the supervisor respawn it forever.
-    expect(exitCode).toBe(TERMINAL_SERVICE_EXIT_CODE);
+    // Exiting here would only make the always-restarting supervisor spin.
+    expect(exited).toBe(false);
+    expect(stdout).toContain('waiting for a credential');
   }, 30_000);
 });
 
@@ -241,8 +246,17 @@ describe('status output', () => {
     child.stdout?.on('data', (chunk) => { stdout += String(chunk); });
     await new Promise((r) => child.once('exit', r));
 
-    const status = JSON.parse(stdout) as { paired: boolean; capabilities: string[] };
+    const status = JSON.parse(stdout) as {
+      paired: boolean;
+      capabilities: string[];
+      access: { mode: string };
+      service: { upToDate?: boolean; enabled?: boolean };
+    };
     expect(status.paired).toBe(true);
     expect(status.capabilities).toEqual(['filesystem', 'shell']);
+    // A machine paired before access control existed stays always-allowed.
+    expect(status.access.mode).toBe('always');
+    // Not installed, so it cannot match what an install would write now.
+    expect(status.service.upToDate).toBe(false);
   }, 30_000);
 });

package/src/agent/service-paths.ts

@@ -1,16 +1,45 @@
+import { createHash } from 'crypto';
 import { readFileSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
-import { join } from 'path';
+import { join, resolve } from 'path';
 
+/** Label of the default service. A non-default AGENT_TUNNEL_HOME gets a suffixed one. */
 export const SERVICE_LABEL = 'ai.kortix.agent-tunnel';
+
+export function defaultAgentTunnelHome(): string {
+  return join(homedir(), '.agent-tunnel');
+}
+
+/**
+ * Config directory: `AGENT_TUNNEL_HOME`, else `~/.agent-tunnel`. The override
+ * lets a desktop dev build or a test pair a second identity on one machine
+ * without touching the real one.
+ */
+export function agentTunnelHome(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.AGENT_TUNNEL_HOME?.trim();
+  return override ? resolve(override) : defaultAgentTunnelHome();
+}
+
+/**
+ * The default home keeps the historical label, so existing installs keep
+ * managing the service they already have. Any other home gets a stable suffix
+ * from its path, so its service never replaces the real one.
+ */
+export function serviceLabelFor(home: string): string {
+  const dir = resolve(home);
+  if (dir === defaultAgentTunnelHome()) return SERVICE_LABEL;
+  return `${SERVICE_LABEL}.${createHash('sha256').update(dir).digest('hex').slice(0, 8)}`;
+}
+
+/** Environment the supervised process needs to find the same home again. */
+export function serviceHomeEnv(home: string = agentTunnelHome()): Record<string, string> {
+  return resolve(home) === defaultAgentTunnelHome() ? {} : { AGENT_TUNNEL_HOME: resolve(home) };
+}
 export const DEFAULT_INSTALL_BACKGROUND_SERVICE = true;
 
 /**
- * Exit code for conditions that restarting cannot fix: no saved credential, or
- * a credential the relay refuses. Every supervisor is configured to restart on
- * failure only, so a terminal condition ends the service instead of spinning.
- * Without this, a revoked token produces an endless respawn loop whose only
- * trace is a log file nobody reads.
+ * Kept for 0.1.x importers only. Since contract v2 (R2) a service never exits
+ * on its own and every supervisor restarts on any exit, so nothing uses it.
  */
 export const TERMINAL_SERVICE_EXIT_CODE = 0;
 
@@ -19,6 +48,8 @@ export const MAX_SERVICE_LOG_BYTES = 5 * 1024 * 1024;
 const RETAINED_LOG_LINES = 500;
 
 export interface ServicePaths {
+  /** launchd label, systemd unit stem, and Scheduled Task name. */
+  label: string;
   configDir: string;
   logDir: string;
   binDir: string;
@@ -28,17 +59,18 @@ export interface ServicePaths {
   windowsScript: string;
 }
 
-export function getServicePaths(): ServicePaths {
+export function getServicePaths(configDir: string = agentTunnelHome()): ServicePaths {
   const home = homedir();
-  const configDir = join(home, '.agent-tunnel');
+  const label = serviceLabelFor(configDir);
   const binDir = join(configDir, 'bin');
   return {
+    label,
     configDir,
     logDir: join(configDir, 'logs'),
     binDir,
     vendoredRunner: join(binDir, 'agent-cli.js'),
-    launchdPlist: join(home, 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`),
-    systemdUnit: join(home, '.config', 'systemd', 'user', `${SERVICE_LABEL}.service`),
+    launchdPlist: join(home, 'Library', 'LaunchAgents', `${label}.plist`),
+    systemdUnit: join(home, '.config', 'systemd', 'user', `${label}.service`),
     windowsScript: join(configDir, 'agent-tunnel-service.ps1'),
   };
 }