@kortix/agent-tunnel 0.13.53 → 0.13.55

package/src/agent/capabilities/security.test.ts

@@ -72,7 +72,7 @@ describe('local capability permission enforcement', () => {
       () => '/trusted/cua-driver',
     );
     expect(registry.getCapabilityNames()).toEqual(['desktop']);
-    expect(registry.getHandler('desktop.cua.get_screen_size')).not.toBeNull();
+    expect(registry.getHandler('desktop.cua.call')).not.toBeNull();
   });
   test('a permission scope cannot widen the local filesystem ceiling', async () => {
     const handler = createFilesystemCapability(config()).methods.get('fs.read')!;
@@ -154,19 +154,59 @@ describe('local capability permission enforcement', () => {
     ).rejects.toThrow('not in the allowed commands list');
   });
 
-  test('desktop feature scopes deny before invoking cua-driver', async () => {
-    const handler = createDesktopCapability().methods.get('desktop.cua.click')!;
-    await expect(
-      handler({
-        x: 10,
-        y: 10,
-        __permission: {
-          permissionId: 'permission-1',
-          capability: 'desktop',
-          scope: { features: ['screenshot'] },
-        },
-      }),
-    ).rejects.toThrow('desktop feature "mouse" is not allowed');
+  test('a desktop grant allows every driver tool, and a legacy feature scope no longer narrows it', async () => {
+    const binary = join(root, 'fake-call-driver');
+    const log = join(root, 'call-args.jsonl');
+    await writeFile(binary, [
+      '#!/usr/bin/env node',
+      `require('node:fs').appendFileSync(${JSON.stringify(log)}, JSON.stringify(process.argv.slice(2, 4)) + '\\n');`,
+      `process.stdout.write('{"ok":true}');`,
+    ].join('\n'));
+    await chmod(binary, 0o700);
+    const previousBinary = process.env.CUA_DRIVER_BIN;
+    process.env.CUA_DRIVER_BIN = binary;
+    try {
+      const call = createDesktopCapability().methods.get('desktop.cua.call')!;
+      const __permission = { permissionId: 'p', capability: 'desktop', scope: { features: ['screenshot'] } };
+      // health_report was never in Kortix's tool list; the driver owns that list.
+      expect(await call({ tool: 'health_report', args: {}, __permission })).toEqual({ ok: true });
+      await expect(call({ tool: 'install_ffmpeg', __permission })).rejects.toThrow('local-only');
+      await expect(call({ tool: 'click', __permission: { ...__permission, capability: 'shell' } }))
+        .rejects.toThrow('desktop permission required');
+      const calls = (await readFile(log, 'utf8')).trim().split('\n').map((line) => JSON.parse(line));
+      expect(calls.at(-1)).toEqual(['call', 'health_report']);
+    } finally {
+      if (previousBinary === undefined) delete process.env.CUA_DRIVER_BIN;
+      else process.env.CUA_DRIVER_BIN = previousBinary;
+    }
+  });
+
+  test('a failed call reports missing macOS grants as computer_desktop_permission_missing (-32013)', async () => {
+    const binary = join(root, 'fake-untrusted-driver');
+    await writeFile(binary, [
+      '#!/usr/bin/env node',
+      'const [command, tool] = process.argv.slice(2);',
+      `if (command === 'call' && tool === 'check_permissions') process.stdout.write('{"accessibility":false,"screen_recording":false}');`,
+      `else if (command === 'call') { process.stderr.write('AX is not trusted'); process.exitCode = 1; }`,
+      `else process.stdout.write('running');`,
+    ].join('\n'));
+    await chmod(binary, 0o700);
+    const previousBinary = process.env.CUA_DRIVER_BIN;
+    process.env.CUA_DRIVER_BIN = binary;
+    let restarts = 0;
+    try {
+      const call = createDesktopCapability({ onPermissionMissing: () => restarts++ }).methods.get('desktop.cua.call')!;
+      const error = await call({ tool: 'click', args: { pid: 1 }, __permission: { permissionId: 'p', capability: 'desktop', scope: {} } })
+        .catch((err: unknown) => err as Error & { code?: number });
+      expect((error as Error).message).toBe(
+        'computer_desktop_permission_missing: macOS has not given CuaDriver Accessibility and Screen Recording on this computer.',
+      );
+      expect((error as { code?: number }).code).toBe(-32013);
+      expect(restarts).toBe(1);
+    } finally {
+      if (previousBinary === undefined) delete process.env.CUA_DRIVER_BIN;
+      else process.env.CUA_DRIVER_BIN = previousBinary;
+    }
   });
 
   test('desktop discovery dispatches to driver metadata commands and preserves unsupported output', async () => {
@@ -195,8 +235,6 @@ describe('local capability permission enforcement', () => {
         scope: { features: ['computer_use'] },
       };
       await expect(list({})).rejects.toThrow('desktop permission required');
-      await expect(list({ __permission: { ...__permission, scope: { features: ['screenshot'] } } }))
-        .rejects.toThrow('not allowed');
       expect(await list({ __permission })).toEqual({ tools: 'double_click' });
       expect(await describeTool({ tool: 'double_click', __permission }))
         .toEqual({ description: 'Double click coordinates' });

package/src/agent/cli-help.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { spawnSync } from "child_process";
-import { mkdtempSync, rmSync } from "fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "fs";
 import { tmpdir } from "os";
 import { join, resolve } from "path";
 
@@ -20,6 +20,8 @@ const DOCUMENTED_SURFACE = [
   "status",
   "logs",
   "logout",
+  "access",
+  "keep-awake",
   "--daemon",
   "--foreground",
 ] as const;
@@ -84,6 +86,55 @@ describe("agent tunnel service UX", () => {
     );
 
     expect(result.status).toBe(2);
-    expect(result.stderr).toContain("--keep-awake is not supported");
+    expect(result.stderr).toContain("--keep-awake is not a flag. Run: agent-tunnel keep-awake on");
+  });
+});
+
+describe("access and keep-awake: the one way to change them on this computer", () => {
+  const run = (home: string, ...args: string[]) =>
+    spawnSync("bun", ["run", CLI_PATH, ...args], {
+      encoding: "utf8",
+      env: { ...process.env, AGENT_TUNNEL_HOME: home },
+    });
+
+  test("changes access and keep awake, prints the state, and writes access.json", () => {
+    const home = mkdtempSync(join(tmpdir(), "agent-tunnel-cli-access-"));
+    try {
+      const shown = JSON.parse(run(home, "access", "--json").stdout);
+      expect(shown).toMatchObject({ mode: "always", keepAwake: false, pendingRequest: null });
+
+      const ask = run(home, "access", "ask", "--json");
+      expect(ask.status).toBe(0);
+      expect(JSON.parse(ask.stdout).mode).toBe("ask");
+
+      const granted = JSON.parse(run(home, "access", "--allow-for", "60", "--json").stdout);
+      expect(Date.parse(granted.grantedUntil) - Date.now()).toBeGreaterThan(59 * 60_000);
+
+      expect(JSON.parse(run(home, "access", "--revoke", "--json").stdout).grantedUntil).toBeNull();
+      expect(JSON.parse(run(home, "keep-awake", "on", "--json").stdout).keepAwake).toBe(true);
+      expect(JSON.parse(readFileSync(join(home, "access.json"), "utf8"))).toMatchObject({ mode: "ask", keepAwake: true });
+
+      const status = JSON.parse(run(home, "status", "--json").stdout);
+      expect(status.access).toMatchObject({ mode: "ask", keepAwake: true, keepAwakeSupported: process.platform !== "win32" });
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test("refuses a wrong mode or duration with exit 1 and changes nothing", () => {
+    const home = mkdtempSync(join(tmpdir(), "agent-tunnel-cli-access-"));
+    try {
+      const mode = run(home, "access", "sometimes");
+      expect(mode.status).toBe(1);
+      expect(mode.stderr).toContain("Access is one of: ask, always, off");
+      const minutes = run(home, "access", "--allow-for", "soon");
+      expect(minutes.status).toBe(1);
+      expect(minutes.stderr).toContain("--allow-for takes minutes");
+      const awake = run(home, "keep-awake", "maybe");
+      expect(awake.status).toBe(1);
+      expect(existsSync(join(home, "access.json"))).toBe(false);
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
   });
 });

package/src/agent/cli.ts

@@ -4,7 +4,17 @@ import { hostname } from 'os';
 import { join } from 'path';
 
 import { PAIR_AGAIN_COMMAND, TunnelAgent } from './agent';
-import { accessFilePath, accessRequestPath, desktopAppPath, readAccess, writeAccess } from './access';
+import {
+  accessFilePath,
+  accessRequestPath,
+  accessView,
+  applyAccess,
+  desktopAppPath,
+  readAccess,
+  writeAccess,
+  type AccessChange,
+  type AccessView,
+} from './access';
 import { printStartupBanner } from './banner';
 import { createEnabledCapabilityRegistry } from './capabilities/enabled-registry';
 import { loadConfig, type TunnelConfig } from './config';
@@ -18,12 +28,12 @@ import {
   requestDeviceAuthorization,
 } from './device-auth';
 import { collapseRepeatedLines, isShellStartupNoise } from './log-format';
-import { anyFlag, isInteractiveTerminal, isTruthyFlag, promptYesNo } from './prompts';
+import { anyFlag, isInteractiveTerminal, isTruthyFlag } from './prompts';
 import {
-  DEFAULT_INSTALL_BACKGROUND_SERVICE,
   agentTunnelHome,
   getServicePaths,
   getServiceStatus,
+  installedAppRunner,
   rotateServiceLogs,
   serviceLogFiles,
 } from './service';
@@ -34,6 +44,7 @@ import {
   describeService,
   renderServiceAction,
 } from './service-control';
+import { watchForRestart } from './self-restart';
 import { readAgentState, writeAgentState } from './state-file';
 import { blankLine, c, clearScreen, field, glyph, stripAnsi } from './terminal';
 import { agentTunnelVersion } from './version';
@@ -43,16 +54,22 @@ const BACKGROUND_FLAGS = ['daemon', 'service', 'background', 'always-online'] as
 const FOREGROUND_FLAGS = ['foreground', 'no-daemon', 'no-service', 'no-background'] as const;
 const DEFAULT_LOG_LINES = 60;
 
+/** `_` holds the words after the command (`access always` → `_: 'always'`). */
 type Flags = Record<string, string>;
 
 function parseArgs(argv: string[]): { command: string; flags: Flags } {
   const flags: Flags = {};
+  const words: string[] = [];
   for (let i = 3; i < argv.length; i++) {
     const arg = argv[i];
-    if (!arg.startsWith('--')) continue;
+    if (!arg.startsWith('--')) {
+      words.push(arg);
+      continue;
+    }
     const next = argv[i + 1];
     flags[arg.slice(2)] = next && !next.startsWith('--') ? argv[++i] : 'true';
   }
+  if (words.length > 0) flags._ = words.join(' ');
   return { command: argv[2] || 'help', flags };
 }
 
@@ -90,7 +107,17 @@ function startAgent(config: TunnelConfig, options: { service?: boolean } = {}):
     process.stdout.write = process.stderr.write.bind(process.stderr) as typeof process.stdout.write;
     options = { ...options, service: true };
   }
-  const registry = createEnabledCapabilityRegistry(config);
+  let agent: TunnelAgent | null = null;
+  const restart = options.service
+    ? watchForRestart((reason) => {
+        process.stdout.write(`[agent-tunnel] restarting: ${reason}\n`);
+        agent?.disconnect();
+        process.exit(0);
+      })
+    : null;
+  const registry = createEnabledCapabilityRegistry(config, undefined, {
+    onPermissionMissing: restart?.permissionMissing,
+  });
   if (config.enabledCapabilities?.includes('desktop') && !registry.has('desktop')) {
     console.error(
       '[agent-tunnel] Computer Use is approved but unavailable: install the trusted cua-driver locally, then restart Agent Tunnel.',
@@ -111,7 +138,7 @@ function startAgent(config: TunnelConfig, options: { service?: boolean } = {}):
 
   // A service never stops on its own (R2): a refused credential waits in
   // `rejected` and re-reads config.json, so pairing again heals it.
-  const agent = new TunnelAgent(
+  agent = new TunnelAgent(
     config,
     registry,
     // The agent passes the credential it uses NOW: a re-pair picked up by a
@@ -126,7 +153,7 @@ function startAgent(config: TunnelConfig, options: { service?: boolean } = {}):
 
   const shutdown = () => {
     if (!options.service) console.log(`\n${c.dim}  Shutting down…${c.reset}`);
-    agent.disconnect();
+    agent?.disconnect();
     process.exit(0);
   };
   process.on('SIGTERM', shutdown);
@@ -135,26 +162,38 @@ function startAgent(config: TunnelConfig, options: { service?: boolean } = {}):
 
 // ── pairing ──────────────────────────────────────────────────────────────────
 
-async function chooseBackgroundMode(flags: Flags): Promise<boolean> {
+/**
+ * A person at a terminal gets what the desktop app gives: a background
+ * connection, no question asked, and the exact commands that pause, resume,
+ * and remove it. `--foreground` keeps it in this terminal only. A script
+ * (no TTY) or `--json` keeps the foreground default it always had.
+ */
+function chooseBackgroundMode(flags: Flags): boolean {
   if (anyFlag(flags, BACKGROUND_FLAGS)) return true;
   if (anyFlag(flags, FOREGROUND_FLAGS)) return false;
-  if (jsonMode || !isInteractiveTerminal()) return false;
+  return !jsonMode && isInteractiveTerminal();
+}
 
+function printServiceControls(): void {
+  const npx = 'npx @kortix/agent-tunnel@latest';
+  console.log(`  ${c.dim}Runs in the background: starts at login, restarts after failures, keeps running after this terminal closes.${c.reset}`);
+  if (installedAppRunner()) {
+    console.log(`  ${c.dim}It runs on the Kortix app on this Mac: same connection, same macOS permissions. Control it from Your computer in the app.${c.reset}`);
+  }
   blankLine();
-  console.log(`  ${glyph.warn} ${c.bold}Security note${c.reset}`);
-  console.log(`  ${c.dim}Background mode starts at login, continues after this terminal closes, and restarts after failures.${c.reset}`);
-  console.log(`  ${c.dim}The computer must remain powered on, awake, and connected to the internet.${c.reset}`);
+  field('Pause', `${c.white}${npx} stop${c.reset}`);
+  field('Resume', `${c.white}${npx} start${c.reset}`);
+  field('Disconnect', `${c.white}${npx} logout${c.reset}`);
   blankLine();
-
-  return promptYesNo('  Install the background service now?', DEFAULT_INSTALL_BACKGROUND_SERVICE);
 }
 
 /** Starts the agent the way the caller asked for, and returns. */
 async function launch(config: TunnelConfig, flags: Flags, lease?: { serviceWasActive: boolean }): Promise<void> {
-  if (await chooseBackgroundMode(flags)) {
+  if (chooseBackgroundMode(flags)) {
     saveCredentials(config.tunnelId, config.token, config.apiUrl);
     if (!jsonMode) {
       renderServiceAction('install', SERVICE_ACTIONS.install.run());
+      printServiceControls();
       return;
     }
     // Return instead of process.exit(): an exit can cut off a piped stdout.
@@ -408,7 +447,7 @@ function commandStatus(flags: Flags): void {
       serviceLabel: getServicePaths().label,
       service,
       state: readAgentState(),
-      access: readAccess(),
+      access: accessView(),
       lastActivity: lastServiceActivity(),
     }, null, 2));
     return;
@@ -566,6 +605,69 @@ function commandServiceAction(action: ServiceAction, flags: Flags): void {
   renderServiceAction(action, SERVICE_ACTIONS[action].run());
 }
 
+/** "Ask each time · allowed until 14:05", for a person at a terminal. */
+function describeAccess(view: AccessView): string {
+  const clock = (iso: string) => new Date(iso).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+  if (view.mode === 'always') return `${c.white}Always allowed${c.reset}`;
+  if (view.mode === 'off') return `${c.white}Off${c.reset} ${c.dim}(every agent call is refused)${c.reset}`;
+  const now = view.grantedUntil
+    ? `allowed until ${clock(view.grantedUntil)}`
+    : view.deniedUntil
+      ? `denied until ${clock(view.deniedUntil)}`
+      : 'asks before the next call';
+  return `${c.white}Ask each time${c.reset} ${c.dim}· ${now}${c.reset}`;
+}
+
+function printAccess(view: AccessView, flags: Flags): void {
+  if (isTruthyFlag(flags.json)) {
+    console.log(JSON.stringify(view, null, 2));
+    return;
+  }
+  const npx = 'npx @kortix/agent-tunnel@latest';
+  blankLine();
+  field('access', describeAccess(view));
+  field('keep awake', view.keepAwakeSupported ? (view.keepAwake ? `${c.white}on${c.reset}` : `${c.white}off${c.reset}`) : `${c.dim}not available on this system${c.reset}`);
+  if (view.pendingRequest) {
+    field('waiting', `${c.white}${view.pendingRequest.change ? 'a change asked for through Kortix' : `an agent call (${view.pendingRequest.capability})`}${c.reset}`);
+    field('', `${c.dim}${npx} access --allow-for 60   or   --deny${c.reset}`);
+  }
+  blankLine();
+  console.log(`  ${c.dim}Change it:${c.reset} ${c.white}${npx} access ask|always|off${c.reset}${c.dim}, --allow-for <minutes>, --revoke, --deny${c.reset}`);
+  blankLine();
+}
+
+/**
+ * `access [ask|always|off] [--allow-for <minutes>] [--revoke] [--deny]`: when
+ * Kortix may use this computer. The person at this machine is its owner, so
+ * this widens access too; the desktop app runs this command after its own
+ * confirmation. No change prints the current state.
+ */
+function commandAccess(flags: Flags): void {
+  const change: AccessChange = {};
+  if (flags._) change.mode = flags._ as AccessChange['mode'];
+  if (flags['allow-for'] !== undefined) {
+    change.grantMinutes = Number(flags['allow-for']);
+    if (!(change.grantMinutes > 0)) fail('--allow-for takes minutes, at most 1440. Example: agent-tunnel access --allow-for 60');
+  }
+  if (isTruthyFlag(flags.revoke)) change.revoke = true;
+  if (isTruthyFlag(flags.deny)) change.deny = true;
+  if (Object.keys(change).length === 0) return printAccess(accessView(), flags);
+  if (change.mode !== undefined && !['ask', 'always', 'off'].includes(change.mode)) {
+    fail('Access is one of: ask, always, off. Example: agent-tunnel access ask');
+  }
+  // A grant applies in "Ask each time"; from another mode it means "ask, allowed for now".
+  if (change.grantMinutes !== undefined && change.mode === undefined && readAccess().mode !== 'ask') change.mode = 'ask';
+  printAccess(applyAccess(change), flags);
+}
+
+/** `keep-awake [on|off]`: hold off system sleep while the agent runs (macOS, Linux). */
+function commandKeepAwake(flags: Flags): void {
+  if (flags._ === undefined) return printAccess(accessView(), flags);
+  if (flags._ !== 'on' && flags._ !== 'off') fail('Keep awake is on or off. Example: agent-tunnel keep-awake on');
+  if (!accessView().keepAwakeSupported) fail('Keep awake is not available on this system yet.');
+  printAccess(applyAccess({ keepAwake: flags._ === 'on' }), flags);
+}
+
 // ── dispatch ─────────────────────────────────────────────────────────────────
 
 interface Command {
@@ -581,6 +683,11 @@ const COMMANDS: Record<string, Command> = {
     run: commandConnect,
   },
   status: { summary: 'Show pairing, capabilities, and service state (--json)', run: commandStatus },
+  access: {
+    summary: 'When Kortix may use this computer: ask, always, off (--allow-for <min>, --revoke, --deny, --json)',
+    run: commandAccess,
+  },
+  'keep-awake': { summary: 'Keep this computer awake while connected: on, off (--json)', run: commandKeepAwake },
   logs: { summary: 'Show recent service logs (--lines <n>, --all, --clear)', run: commandLogs },
   start: {
     summary: 'Start the background service (resumes a paused one)',
@@ -620,7 +727,7 @@ const OPTIONS: ReadonlyArray<readonly [string, string]> = [
   ['--reauth', 'With connect: discard the saved credential and pair again'],
   ['--daemon / --foreground', 'With connect: skip the prompt and choose the mode'],
   ['--project-id <uuid>', 'With connect: offer "Also share with <project>" on the approval page; the computer is yours in every project either way'],
-  ['--json', 'With connect: NDJSON events, no prompts. With status and logout: machine-readable output'],
+  ['--json', 'With connect: NDJSON events, no prompts. With status, access, keep-awake, and logout: machine-readable output'],
   ['--keep-service', 'With logout: keep the background service installed'],
 ];
 
@@ -658,7 +765,7 @@ const { command, flags } = parseArgs(process.argv);
 jsonMode = command === 'connect' && isTruthyFlag(flags.json);
 
 if (Object.prototype.hasOwnProperty.call(flags, 'keep-awake')) {
-  console.error(`  ${glyph.bad} --keep-awake is not supported. Configure sleep behavior in the operating system.`);
+  console.error(`  ${glyph.bad} --keep-awake is not a flag. Run: agent-tunnel keep-awake on`);
   process.exit(2);
 }
 
@@ -669,7 +776,8 @@ const resolved =
 if (!resolved) {
   showHelp();
 } else {
-  void Promise.resolve(resolved.run(flags)).catch((error: unknown) => {
+  // `.then`: a command that throws synchronously reports like one that rejects.
+  void Promise.resolve().then(() => resolved.run(flags)).catch((error: unknown) => {
     fail(error instanceof Error ? error.message : String(error));
   });
 }

package/src/agent/credential-probe.ts

@@ -1,5 +1,5 @@
 import '../node-ws-polyfill';
-import { AGENT_REPLACED_CLOSE_CODE, AGENT_VERSION, isCredentialRejection } from './agent';
+import { AGENT_REPLACED_CLOSE_CODE, AGENT_VERSION, isCredentialRejection, openRelaySocket } from './agent';
 import { buildTunnelWsUrl, trustedCredential, type TunnelConfig } from './config';
 
 /**
@@ -36,18 +36,18 @@ export function probeCredentials(
   return new Promise<CredentialProbeResult>((resolve) => {
     let socket: WebSocket;
     try {
-      socket = new WebSocket(new URL(buildTunnelWsUrl(config)));
+      socket = openRelaySocket(new URL(buildTunnelWsUrl(config)).href);
     } catch {
       resolve('unreachable');
       return;
     }
 
     // resolve() is idempotent, so the first verdict wins and later events are
-    // harmless no-ops. That removes any need to track settled state by hand.
+    // harmless no-ops. Resolve before close(): Bun fires 'close' inside it.
     const settle = (result: CredentialProbeResult): void => {
       clearTimeout(timer);
-      try { socket.close(1000, 'probe complete'); } catch {}
       resolve(result);
+      try { socket.close(1000, 'probe complete'); } catch {}
     };
 
     const timer = setTimeout(() => settle('unreachable'), options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS);

package/src/agent/self-restart.test.ts

@@ -0,0 +1,24 @@
+import { expect, test } from 'bun:test';
+import { mkdtempSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import { runtimeFingerprint } from './self-restart';
+
+test('an update that swaps a runtime file in place changes the fingerprint', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'self-restart-'));
+  try {
+    const binary = join(dir, 'Kortix');
+    writeFileSync(binary, 'v1');
+    const started = runtimeFingerprint([binary]);
+    expect(runtimeFingerprint([binary])).toBe(started);
+    // An app updater writes the new bundle beside the old one and renames it over.
+    writeFileSync(join(dir, 'next'), 'v1');
+    renameSync(join(dir, 'next'), binary);
+    expect(runtimeFingerprint([binary])).not.toBe(started);
+    rmSync(binary);
+    expect(runtimeFingerprint([binary])).toBe('missing');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/agent/self-restart.ts

@@ -0,0 +1,47 @@
+import { statSync } from 'fs';
+
+/** Identity of the files this process runs; a replaced file changes it. */
+export function runtimeFingerprint(files: readonly string[]): string {
+  return files
+    .map((file) => {
+      try {
+        const stat = statSync(file);
+        return `${stat.ino}:${stat.mtimeMs}:${stat.size}`;
+      } catch {
+        return 'missing';
+      }
+    })
+    .join('|');
+}
+
+/** A macOS grant refused this long after start is not a grant this process missed. */
+const PERMISSION_RESTART_MIN_UPTIME_S = 5 * 60;
+
+/**
+ * A background service must not outlive its own code or its macOS grants:
+ *
+ * - An app update replaces the binary under the running agent. macOS then
+ *   cannot validate the old process's signature and refuses it Accessibility
+ *   and Screen Recording, while the updated app itself shows them allowed.
+ * - A grant made in System Settings applies to processes started after it.
+ *
+ * Both are healed by exiting: the supervisor (launchd KeepAlive, systemd
+ * Restart=always, the Windows loop) starts the service again on the current
+ * code with the current grants.
+ */
+export function watchForRestart(exit: (reason: string) => void, intervalMs = 60_000): {
+  permissionMissing: () => void;
+} {
+  const files = [process.execPath, process.argv[1]].filter((file): file is string => Boolean(file));
+  const started = runtimeFingerprint(files);
+  setInterval(() => {
+    if (runtimeFingerprint(files) !== started) exit('its code was updated');
+  }, intervalMs).unref();
+  return {
+    permissionMissing: () => {
+      if (process.uptime() < PERMISSION_RESTART_MIN_UPTIME_S) return;
+      // After the refusal is sent: the caller gets the actionable error first.
+      setTimeout(() => exit('macOS refused a desktop permission'), 1_000).unref();
+    },
+  };
+}

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

@@ -13,6 +13,7 @@ import {
   rotateServiceLogs,
 } from './service';
 import { collapseRepeatedLines } from './log-format';
+import { AGENT_VERSION } from './agent';
 import { probeCredentials } from './credential-probe';
 
 const CLI_PATH = resolve(import.meta.dir, 'cli.ts');
@@ -104,6 +105,51 @@ describe('service log hygiene', () => {
 });
 
 describe('credential probe and the single-agent rule', () => {
+  test('every relay socket opens through openRelaySocket', () => {
+    const src = resolve(import.meta.dir, '..');
+    const raw: string[] = [];
+    for (const file of new Bun.Glob('**/*.ts').scanSync(src)) {
+      if (file.endsWith('.test.ts')) continue;
+      readFileSync(join(src, file), 'utf8').split('\n').forEach((line, i) => {
+        if (/\bnew WebSocket\(/.test(line) && !/^\s*(\/\/|\*)/.test(line)) raw.push(`${file}:${i + 1}`);
+      });
+    }
+    expect(raw).toEqual([]);
+  });
+
+  test('auth_ok is valid, though Bun fires close inside socket.close()', async () => {
+    let userAgent: string | null = null as string | null;
+    const server = Bun.serve({
+      port: 0,
+      fetch(request, server) {
+        // Cloudflare refuses an upgrade without a User-Agent, and Bun sends none by default.
+        userAgent = request.headers.get('user-agent');
+        return server.upgrade(request) ? undefined : new Response('no upgrade', { status: 400 });
+      },
+      websocket: {
+        message(ws) {
+          ws.send(JSON.stringify({ type: 'auth_ok' }));
+        },
+      },
+    });
+
+    try {
+      const result = await probeCredentials(
+        {
+          apiUrl: `http://127.0.0.1:${server.port}/v1/tunnel`,
+          tunnelId: '00000000-0000-4000-8000-000000000001',
+          token: 'kortix_tnl_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+          wsPath: '/ws',
+        } as never,
+        { timeoutMs: 5_000 },
+      );
+      expect(result).toBe('valid');
+      expect(userAgent).toBe(`kortix-agent-tunnel/${AGENT_VERSION}`);
+    } finally {
+      server.stop(true);
+    }
+  }, 30_000);
+
   test('treats being replaced as proof the credential is valid', async () => {
     // The relay only replaces a socket it already registered, and registration
     // happens after a successful handshake.

package/src/agent/service.test.ts

@@ -10,6 +10,7 @@ import {
   agentTunnelHome,
   buildServiceShellCommand,
   getServicePaths,
+  installedAppRunner,
   runnerPartsFor,
   serviceLabelFor,
   isEphemeralRunnerPath,
@@ -28,7 +29,32 @@ describe('agent tunnel service definitions', () => {
     const command = buildServiceShellCommand();
     expect(command).toContain("'run'");
     expect(command).toContain("'--service'");
-    expect(command).toStartWith('exec ');
+    // `export …;` first when it runs on the installed Kortix app (ELECTRON_RUN_AS_NODE).
+    expect(command).toMatch(/^(export [^;]+; )?exec /);
+  });
+
+  test('a CLI install on a Mac with the Kortix app runs on the app runtime', () => {
+    const root = mkdtempSync(join(tmpdir(), 'kortix-app-'));
+    try {
+      const app = join(root, 'Kortix.app');
+      expect(installedAppRunner([app], 'darwin')).toBeNull();
+      mkdirSync(join(app, 'Contents', 'MacOS'), { recursive: true });
+      mkdirSync(join(app, 'Contents', 'Resources', 'agent-tunnel'), { recursive: true });
+      writeFileSync(join(app, 'Contents', 'MacOS', 'Kortix'), '');
+      writeFileSync(join(app, 'Contents', 'Resources', 'agent-tunnel', 'agent-cli.js'), '');
+      const runner = installedAppRunner([join(root, 'Missing.app'), app], 'darwin')!;
+      expect(runner).toEqual({
+        execPath: join(app, 'Contents', 'MacOS', 'Kortix'),
+        script: join(app, 'Contents', 'Resources', 'agent-tunnel', 'agent-cli.js'),
+      });
+      expect(installedAppRunner([app], 'linux')).toBeNull();
+      const parts = runnerPartsFor(runner.script, { execPath: runner.execPath, electron: 'installed-app' });
+      expect(parts.command).toBe(runner.execPath);
+      expect(parts.args).toEqual([runner.script, 'run', '--service']);
+      expect(parts.env?.ELECTRON_RUN_AS_NODE).toBe('1');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
   });
 
   test('launchd plist restarts and runs at login', () => {