@kortix/agent-tunnel 0.13.41 → 0.13.43

package/src/agent/service.test.ts

@@ -1,12 +1,17 @@
 import { describe, expect, test } from 'bun:test';
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
+import { posixShellCommand } from './service-drivers';
 import { join } from 'node:path';
+import { homedir } from 'node:os';
 import {
   DEFAULT_INSTALL_BACKGROUND_SERVICE,
   SERVICE_LABEL,
+  agentTunnelHome,
   buildServiceShellCommand,
   getServicePaths,
+  runnerPartsFor,
+  serviceLabelFor,
   isEphemeralRunnerPath,
   renderLaunchdPlist,
   renderSystemdUnit,
@@ -30,18 +35,22 @@ describe('agent tunnel service definitions', () => {
     const plist = renderLaunchdPlist('exec /bin/echo tunnel');
     expect(plist).toContain(`<string>${SERVICE_LABEL}</string>`);
     expect(plist).toContain('<key>RunAtLoad</key>');
-    expect(plist).toContain('<key>KeepAlive</key>');
+    // R3: the service runs forever. launchd restarts it on ANY exit, at most every 10 s.
+    expect(plist).toContain('<key>KeepAlive</key>\n  <true/>');
+    expect(plist).toContain('<key>ThrottleInterval</key>\n  <integer>10</integer>');
+    expect(plist).not.toContain('SuccessfulExit');
     expect(plist).toContain('<key>Umask</key>');
     expect(plist).toContain('agent-tunnel.out.log');
     expect(plist).toContain('agent-tunnel.err.log');
   });
 
-  test('systemd unit restarts on failure but not after a terminal exit', () => {
+  test('systemd unit restarts on any exit (R3)', () => {
     const unit = renderSystemdUnit('exec /bin/echo tunnel');
     expect(unit).toContain('Description=Kortix Agent Tunnel');
-    // Restart=always respawned the agent forever when the credential was
-    // missing or revoked, which no restart can fix.
-    expect(unit).toContain('Restart=on-failure');
+    // The agent itself never exits for a bad credential any more (it waits in
+    // `rejected`), so any exit is a crash worth restarting.
+    expect(unit).toContain('Restart=always');
+    expect(unit).toContain('RestartSec=5');
     expect(unit).toContain('UMask=0077');
     expect(unit).toContain('WantedBy=default.target');
     expect(unit).toContain('agent-tunnel.out.log');
@@ -57,6 +66,7 @@ describe('agent tunnel service definitions', () => {
     expect(script).toContain('while ($true)');
     expect(script).toContain("& 'node' 'agent-tunnel.js' 'run' '--service'");
     expect(script).toContain('Start-Sleep -Seconds 5');
+    expect(script).not.toContain('break');
   });
 
   test('treats package-manager caches as ephemeral runner locations', () => {
@@ -92,6 +102,8 @@ describe('agent tunnel service definitions', () => {
       const copied = vendorRunner(cached, paths);
       expect(copied).toBe(paths.vendoredRunner);
       expect(readFileSync(copied, 'utf8')).toBe('// cached bundle\n');
+      // The copy reports the same version as the CLI that installed it (R5).
+      expect(JSON.parse(readFileSync(join(home, 'bin', 'package.json'), 'utf8'))).toMatchObject({ name: '@kortix/agent-tunnel' });
     } finally {
       rmSync(home, { recursive: true, force: true });
     }
@@ -111,3 +123,112 @@ describe('agent tunnel service definitions', () => {
     expect(paths.windowsScript).toContain('agent-tunnel-service.ps1');
   });
 });
+
+describe('AGENT_TUNNEL_HOME isolation', () => {
+  const defaultHome = join(homedir(), '.agent-tunnel');
+
+  test('defaults to ~/.agent-tunnel and honours the override', () => {
+    expect(agentTunnelHome({})).toBe(defaultHome);
+    expect(agentTunnelHome({ AGENT_TUNNEL_HOME: '  ' })).toBe(defaultHome);
+    expect(agentTunnelHome({ AGENT_TUNNEL_HOME: '/tmp/kortix-dev/agent-tunnel' })).toBe(
+      '/tmp/kortix-dev/agent-tunnel',
+    );
+  });
+
+  test('the default home keeps the historical service label', () => {
+    expect(serviceLabelFor(defaultHome)).toBe(SERVICE_LABEL);
+    expect(serviceLabelFor(`${defaultHome}/`)).toBe(SERVICE_LABEL);
+  });
+
+  test('any other home gets a stable 8-hex suffix derived from its path', () => {
+    const label = serviceLabelFor('/tmp/kortix-dev/agent-tunnel');
+    expect(label).toMatch(/^ai\.kortix\.agent-tunnel\.[0-9a-f]{8}$/);
+    expect(serviceLabelFor('/tmp/kortix-dev/agent-tunnel')).toBe(label);
+    expect(serviceLabelFor('/tmp/kortix-dev/other')).not.toBe(label);
+  });
+
+  test('service files of a non-default home never touch the real service', () => {
+    const paths = getServicePaths('/tmp/kortix-dev/agent-tunnel');
+    expect(paths.label).not.toBe(SERVICE_LABEL);
+    expect(paths.configDir).toBe('/tmp/kortix-dev/agent-tunnel');
+    expect(paths.logDir).toBe('/tmp/kortix-dev/agent-tunnel/logs');
+    expect(paths.launchdPlist).toEndWith(`/LaunchAgents/${paths.label}.plist`);
+    expect(paths.systemdUnit).toEndWith(`/${paths.label}.service`);
+    expect(paths.windowsScript).toStartWith('/tmp/kortix-dev/agent-tunnel');
+    expect(renderLaunchdPlist('exec true', paths)).toContain(`<string>${paths.label}</string>`);
+  });
+});
+
+describe('service runner', () => {
+  const devPaths = getServicePaths('/tmp/kortix-dev/agent-tunnel');
+
+  test('a Node runner carries a non-default home into the service env', () => {
+    const runner = runnerPartsFor('/opt/kortix/agent-cli.js', { execPath: '/usr/local/bin/node' }, devPaths);
+    expect(runner).toEqual({
+      command: '/usr/local/bin/node',
+      args: ['/opt/kortix/agent-cli.js', 'run', '--service'],
+      env: { AGENT_TUNNEL_HOME: '/tmp/kortix-dev/agent-tunnel' },
+    });
+    expect(runnerPartsFor('/opt/kortix/agent-cli.js', { execPath: 'node' }, getServicePaths()).env).toEqual({});
+  });
+
+  test('an Electron runner sets ELECTRON_RUN_AS_NODE and is never vendored', () => {
+    // An npx-looking path would be vendored under Node; the app bundle never is.
+    const script = '/Applications/Kortix.app/Contents/Resources/agent-tunnel/agent-cli.js';
+    const runner = runnerPartsFor(
+      script,
+      { execPath: '/Applications/Kortix.app/Contents/MacOS/Kortix', electron: '39.8.1' },
+      devPaths,
+    );
+    expect(runner.command).toBe('/Applications/Kortix.app/Contents/MacOS/Kortix');
+    expect(runner.args).toEqual([script, 'run', '--service']);
+    expect(runner.env).toEqual({
+      AGENT_TUNNEL_HOME: '/tmp/kortix-dev/agent-tunnel',
+      ELECTRON_RUN_AS_NODE: '1',
+    });
+  });
+
+  test('a Linux AppImage runs the AppImage file with a vendored bundle', () => {
+    const home = mkdtempSync(join(tmpdir(), 'agent-tunnel-appimage-'));
+    try {
+      const mount = join(home, '.mount_KortixAbc', 'resources', 'agent-tunnel');
+      mkdirSync(mount, { recursive: true });
+      writeFileSync(join(mount, 'agent-cli.js'), '// bundle\n');
+      const paths = getServicePaths(join(home, 'agent-home'));
+      const runner = runnerPartsFor(
+        join(mount, 'agent-cli.js'),
+        { execPath: join(home, '.mount_KortixAbc', 'kortix'), electron: '39.8.1', appImage: '/home/u/Kortix.AppImage' },
+        paths,
+      );
+      expect(runner.command).toBe('/home/u/Kortix.AppImage');
+      expect(runner.args[0]).toBe(paths.vendoredRunner);
+      expect(readFileSync(paths.vendoredRunner, 'utf8')).toBe('// bundle\n');
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test('launchd and systemd commands export the runner env before exec', () => {
+    const command = posixShellCommand({
+      command: '/Applications/Kortix.app/Contents/MacOS/Kortix',
+      args: ['agent-cli.js', 'run', '--service'],
+      env: { AGENT_TUNNEL_HOME: "/tmp/it's here", ELECTRON_RUN_AS_NODE: '1' },
+    });
+    expect(command).toStartWith(`export AGENT_TUNNEL_HOME='/tmp/it'\\''s here' ELECTRON_RUN_AS_NODE='1'; exec `);
+    expect(renderLaunchdPlist(command, devPaths)).toContain('ELECTRON_RUN_AS_NODE=&apos;1&apos;');
+    expect(renderSystemdUnit(command, devPaths)).toContain('ELECTRON_RUN_AS_NODE=');
+    // No env, no export: the default service definition is unchanged.
+    expect(posixShellCommand({ command: 'node', args: ['a.js'] })).toStartWith('exec ');
+  });
+
+  test('the Windows script sets the env and waits for a GUI-subsystem binary', () => {
+    const script = renderWindowsPowerShellScript({
+      command: 'C:\\Kortix\\Kortix.exe',
+      args: ['agent-cli.js', 'run', '--service'],
+      env: { AGENT_TUNNEL_HOME: 'C:\\dev\\agent-tunnel', ELECTRON_RUN_AS_NODE: '1' },
+    });
+    expect(script).toContain("$env:AGENT_TUNNEL_HOME = 'C:\\dev\\agent-tunnel'");
+    expect(script).toContain("$env:ELECTRON_RUN_AS_NODE = '1'");
+    expect(script).toContain("& 'C:\\Kortix\\Kortix.exe' 'agent-cli.js' 'run' '--service' | Out-Null");
+  });
+});

package/src/agent/service.ts

@@ -1,9 +1,10 @@
-import { chmodSync, copyFileSync, existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from 'fs';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'fs';
 import { platform } from 'os';
 import { join } from 'path';
 
 import {
   SUPPORTED_PLATFORMS_MESSAGE,
+  type Outcome,
   type RunnerParts,
   posixShellCommand,
   serviceDriver,
@@ -12,7 +13,9 @@ import {
   type ServicePaths,
   getServicePaths,
   rotateServiceLogs,
+  serviceHomeEnv,
 } from './service-paths';
+import { agentTunnelVersion } from './version';
 
 export {
   DEFAULT_INSTALL_BACKGROUND_SERVICE,
@@ -20,7 +23,10 @@ export {
   SERVICE_LABEL,
   TERMINAL_SERVICE_EXIT_CODE,
   type ServicePaths,
+  agentTunnelHome,
   getServicePaths,
+  serviceHomeEnv,
+  serviceLabelFor,
   rotateServiceLogs,
   serviceLogFiles,
 } from './service-paths';
@@ -34,6 +40,13 @@ export interface ServiceStatus {
   platform: NodeJS.Platform;
   installed: boolean;
   active: boolean | null;
+  /** False while paused: disabled in the supervisor, so login does not start it. */
+  enabled?: boolean;
+  /**
+   * The installed unit is exactly what `install` would write now. False after
+   * an app update or move: the unit points at an old runner (R5).
+   */
+  upToDate?: boolean;
   path?: string;
   detail?: string;
 }
@@ -52,7 +65,9 @@ export function isEphemeralRunnerPath(path: string): boolean {
     normalized.includes('/_npx/') ||
     normalized.includes('/_cacache/') ||
     normalized.includes('/.pnpm-store/') ||
-    normalized.includes('/.yarn/$$virtual/')
+    normalized.includes('/.yarn/$$virtual/') ||
+    // A Linux AppImage is mounted at a new /tmp/.mount_* path on every launch.
+    normalized.includes('/.mount_')
   );
 }
 
@@ -68,6 +83,13 @@ export function vendorRunner(scriptPath: string, paths: ServicePaths = getServic
   const source = realpathSync(scriptPath);
   copyFileSync(source, paths.vendoredRunner);
   try { chmodSync(paths.vendoredRunner, 0o700); } catch {}
+  // The copy has no package.json beside it, so it would report version
+  // "unknown" and the desktop's version check (R5) could never pass.
+  writeFileSync(
+    join(paths.binDir, 'package.json'),
+    JSON.stringify({ name: '@kortix/agent-tunnel', version: agentTunnelVersion(), private: true }),
+    { mode: 0o600 },
+  );
   writeFileSync(
     join(paths.binDir, 'agent-cli.source.json'),
     JSON.stringify({ source, vendoredFrom: scriptPath }, null, 2),
@@ -76,11 +98,45 @@ export function vendorRunner(scriptPath: string, paths: ServicePaths = getServic
   return paths.vendoredRunner;
 }
 
-function currentRunnerParts(): RunnerParts {
-  const script = process.argv[1];
-  if (script && existsSync(script)) {
-    return { command: process.execPath, args: [vendorRunner(script), 'run', '--service'] };
+/**
+ * The command the supervisor runs: this interpreter and this bundle.
+ *
+ * Under Electron (the desktop app runs the bundle with ELECTRON_RUN_AS_NODE)
+ * the interpreter is the app binary, which must be told to act as Node again,
+ * and the bundle sits inside the app, which the updater replaces in place, so
+ * it is not vendored. A Linux AppImage is the exception: its mount path changes
+ * per launch, so the service runs the AppImage file and a vendored bundle.
+ */
+export function runnerPartsFor(
+  script: string,
+  runtime: { execPath: string; electron?: string; appImage?: string } = {
+    execPath: process.execPath,
+    electron: process.versions.electron,
+    appImage: process.env.APPIMAGE,
+  },
+  paths: ServicePaths = getServicePaths(),
+  vendor: (script: string, paths: ServicePaths) => string = vendorRunner,
+): RunnerParts {
+  const env = serviceHomeEnv(paths.configDir);
+  if (runtime.electron) {
+    return {
+      command: runtime.appImage || runtime.execPath,
+      args: [runtime.appImage ? vendor(script, paths) : script, 'run', '--service'],
+      env: { ...env, ELECTRON_RUN_AS_NODE: '1' },
+    };
   }
+  return { command: runtime.execPath, args: [vendor(script, paths), 'run', '--service'], env };
+}
+
+/** Where vendorRunner WOULD put the bundle, without copying anything. */
+const plannedRunner = (script: string, paths: ServicePaths) =>
+  isEphemeralRunnerPath(script) ? paths.vendoredRunner : script;
+
+function currentRunnerParts(
+  vendor: (script: string, paths: ServicePaths) => string = vendorRunner,
+): RunnerParts {
+  const script = process.argv[1];
+  if (script && existsSync(script)) return runnerPartsFor(script, undefined, getServicePaths(), vendor);
   throw new Error(
     'Cannot install the background service because the current Agent Tunnel executable was not found',
   );
@@ -98,11 +154,7 @@ export function buildServiceShellCommand(): string {
  * functions.
  */
 function withDriver(
-  operate: (driver: NonNullable<ReturnType<typeof serviceDriver>>, paths: ServicePaths, installed: boolean) => {
-    active?: boolean | null;
-    installed?: boolean;
-    detail?: string;
-  },
+  operate: (driver: NonNullable<ReturnType<typeof serviceDriver>>, paths: ServicePaths, installed: boolean) => Outcome,
   fallback: { installed: boolean; active: boolean | null },
 ): ServiceStatus {
   const driver = serviceDriver();
@@ -121,6 +173,8 @@ function withDriver(
     platform: platform(),
     installed: outcome.installed ?? installed,
     active: outcome.active ?? fallback.active,
+    ...(outcome.enabled !== undefined ? { enabled: outcome.enabled } : {}),
+    ...(outcome.upToDate !== undefined ? { upToDate: outcome.upToDate } : {}),
     path,
     detail: outcome.detail,
   };
@@ -163,6 +217,33 @@ export function stopService(): ServiceStatus {
   );
 }
 
+/** R3: stops the service and keeps it stopped across login and reboot. */
+export function pauseService(): ServiceStatus {
+  return withDriver(
+    (driver, paths, installed) => ({ ...driver.pause(paths, installed), active: false }),
+    { installed: false, active: false },
+  );
+}
+
+/**
+ * Reverses pauseService. A unit that points at an old runner (the app moved or
+ * updated while paused) is rewritten first, so Resume never starts a unit whose
+ * executable is gone.
+ */
+export function resumeService(): ServiceStatus {
+  const current = getServiceStatus();
+  // Install enables the job on every supervisor, so it also ends the pause.
+  if (current.installed && current.upToDate === false) return installService();
+  return resumeUnit();
+}
+
+function resumeUnit(): ServiceStatus {
+  return withDriver(
+    (driver, paths, installed) => driver.resume(paths, installed),
+    { installed: false, active: null },
+  );
+}
+
 export function restartService(): ServiceStatus {
   stopService();
   return startService();
@@ -180,7 +261,13 @@ export function getServiceStatus(): ServiceStatus {
     };
   }
   return withDriver(
-    (driver, paths, installed) => driver.status(paths, installed),
+    (driver, paths, installed) => {
+      let upToDate = false;
+      try {
+        upToDate = installed && readFileSync(driver.unitPath(paths), 'utf8') === driver.render(paths, currentRunnerParts(plannedRunner));
+      } catch {}
+      return { ...driver.status(paths, installed), upToDate };
+    },
     { installed: false, active: null },
   );
 }

package/src/agent/state-file.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { readAgentState, stateFilePath, writeAgentState } from './state-file';
+
+describe('agent state file', () => {
+  test('writes the status atomically, privately, and reads it back', () => {
+    const home = join(mkdtempSync(join(tmpdir(), 'agent-tunnel-state-')), 'home');
+    try {
+      expect(readAgentState(home)).toBeNull();
+      const tunnel = { tunnelId: '00000000-0000-4000-8000-000000000001', apiUrl: 'http://127.0.0.1:8008/v1/tunnel' };
+
+      writeAgentState('connecting', tunnel, home);
+      writeAgentState('online', tunnel, home);
+
+      const state = readAgentState(home);
+      expect(state).toMatchObject({ ...tunnel, status: 'online', pid: process.pid });
+      expect(Date.parse(state!.since)).toBeGreaterThan(Date.now() - 5_000);
+      expect(typeof state!.agentVersion).toBe('string');
+      expect(statSync(stateFilePath(home)).mode & 0o077).toBe(0);
+      expect(statSync(home).mode & 0o077).toBe(0);
+      // No temp file is left behind.
+      expect(readdirSync(home)).toEqual(['state.json']);
+      // The state never carries the credential.
+      expect(JSON.stringify(state)).not.toContain('token');
+    } finally {
+      rmSync(join(home, '..'), { recursive: true, force: true });
+    }
+  });
+});

package/src/agent/state-file.ts

@@ -0,0 +1,58 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+import type { TunnelAgentStatus } from './agent';
+import { agentTunnelHome } from './service-paths';
+import { agentTunnelVersion } from './version';
+
+/**
+ * `<home>/state.json`: the running agent's connection status, for local
+ * observers such as the desktop tray. It holds no credential.
+ */
+export interface AgentStateFile {
+  tunnelId: string;
+  apiUrl: string;
+  status: TunnelAgentStatus;
+  /** ISO time of the last status change. */
+  since: string;
+  agentVersion: string;
+  pid: number;
+}
+
+export function stateFilePath(home: string = agentTunnelHome()): string {
+  return join(home, 'state.json');
+}
+
+/** Atomic and private. A status write never stops the agent. */
+export function writeAgentState(
+  status: TunnelAgentStatus,
+  tunnel: { tunnelId: string; apiUrl: string },
+  home: string = agentTunnelHome(),
+): void {
+  const state: AgentStateFile = {
+    tunnelId: tunnel.tunnelId,
+    apiUrl: tunnel.apiUrl,
+    status,
+    since: new Date().toISOString(),
+    agentVersion: agentTunnelVersion(),
+    pid: process.pid,
+  };
+  try {
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    const tmp = join(home, `state.${process.pid}.${Date.now()}.tmp`);
+    writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    try { chmodSync(tmp, 0o600); } catch {}
+    renameSync(tmp, stateFilePath(home));
+  } catch {
+    // Observers fall back to "unknown"; the tunnel itself is unaffected.
+  }
+}
+
+export function readAgentState(home: string = agentTunnelHome()): AgentStateFile | null {
+  try {
+    const parsed = JSON.parse(readFileSync(stateFilePath(home), 'utf8')) as AgentStateFile;
+    return parsed && typeof parsed === 'object' && typeof parsed.status === 'string' ? parsed : null;
+  } catch {
+    return null;
+  }
+}

package/src/client/tunnel-client.ts

@@ -91,6 +91,10 @@ export class TunnelClient {
     return data.result;
   }
 
+  /**
+   * Kept for published 0.1.x callers. The current API never returns a
+   * `requestId` (permission requests were removed), so this equals `rpc`.
+   */
   async rpcWithPermissionFlow(method: string, params: Record<string, unknown> = {}): Promise<unknown> {
     try {
       return await this.rpc(method, params);
@@ -147,9 +151,8 @@ export class TunnelClient {
     this.cachedTunnelId = null;
     throw new TunnelClientError(
       -1,
-      'No tunnel connection found. The user needs to set up Agent Tunnel first:\n' +
-      '1. Create a tunnel connection\n' +
-      '2. Connect the local machine from the Kortix desktop app or run the tunnel connect command',
+      'No tunnel connection found. Connect this computer from the Kortix desktop app, ' +
+      'or run `npx @kortix/agent-tunnel connect`.',
     );
   }
 }

package/src/server/ws-handler.test.ts

@@ -140,7 +140,7 @@ describe('tunnel WebSocket identity binding', () => {
 
     expect(relay.isConnected('tunnel-1')).toBe(false);
     expect(socket.closes).toContainEqual({
-      code: 4001,
+      code: 1011,
       reason: 'authentication response failed',
     });
   });
@@ -155,4 +155,34 @@ describe('tunnel WebSocket identity binding', () => {
 
     expect(socket.closes).toContainEqual({ code: 4002, reason: 'message too large' });
   });
+
+  // A relay that cannot finish auth (database down during a deploy, overload)
+  // must not tell the agent its credential is bad: agents stop for good on 4001.
+  test('closes with a retryable code when the authenticator throws', async () => {
+    const relay = new TunnelRelay();
+    const handlers = createWsHandlers(relay, {
+      onAuthenticate: async () => {
+        throw new Error('database unavailable');
+      },
+    });
+    const socket = fakeWs();
+    handlers.onOpen('tunnel-1', socket);
+    const originalError = console.error;
+    console.error = () => {};
+    try {
+      await handlers.onMessage('tunnel-1', socket, JSON.stringify({ type: 'auth', token: 't' }));
+    } finally {
+      console.error = originalError;
+    }
+    expect(socket.closes).toEqual([{ code: 1011, reason: 'authentication error' }]);
+  });
+
+  test('closes with a retryable code when auth does not complete in time', async () => {
+    const relay = new TunnelRelay();
+    const handlers = createWsHandlers(relay, { authTimeoutMs: 5 });
+    const socket = fakeWs();
+    handlers.onOpen('tunnel-1', socket);
+    await Bun.sleep(20);
+    expect(socket.closes).toEqual([{ code: 1013, reason: 'auth timeout' }]);
+  });
 });

package/src/server/ws-handler.ts

@@ -39,7 +39,7 @@ export function createWsHandlers(relay: TunnelRelay, opts?: WsHandlerOptions): W
       const timer = setTimeout(() => {
         pendingConnections.delete(ws);
         try {
-          ws.close(4001, 'auth timeout');
+          ws.close(1013, 'auth timeout');
         } catch {}
       }, authTimeoutMs);
 
@@ -135,7 +135,7 @@ export function createWsHandlers(relay: TunnelRelay, opts?: WsHandlerOptions): W
             );
           } catch {
             try {
-              ws.close(4001, 'authentication response failed');
+              ws.close(1011, 'authentication response failed');
             } catch {}
             return;
           }
@@ -149,7 +149,7 @@ export function createWsHandlers(relay: TunnelRelay, opts?: WsHandlerOptions): W
           pendingConnections.delete(ws);
           console.error(`[tunnel-ws] Auth error for ${tunnelId}:`, err);
           try {
-            ws.close(4001, 'authentication error');
+            ws.close(1011, 'authentication error');
           } catch {}
         }
 

package/src/shared/types.ts

@@ -42,6 +42,12 @@ export const TunnelErrorCode = {
   EXPIRED: -32005,
   RATE_LIMITED: -32006,
   AUTH_FAILED: -32007,
+  /** The owner has not answered the access prompt on the machine (contract v2 X1). */
+  ACCESS_PENDING: -32010,
+  /** The owner denied access on the machine; fails fast until the denial lapses. */
+  ACCESS_DENIED: -32011,
+  /** The owner turned computer access off on the machine. */
+  ACCESS_OFF: -32012,
 } as const;
 
 export type TunnelErrorCodeValue = (typeof TunnelErrorCode)[keyof typeof TunnelErrorCode];
@@ -183,6 +189,12 @@ export interface TunnelAuthMessage {
   /** RPC capability handlers registered in this exact agent process. */
   capabilities?: TunnelCapability[];
   agentVersion?: string;
+  /**
+   * True from agents that report their access mode (`tunnel.access.state`).
+   * Lets the API drop a mode stored by an earlier agent when an older one
+   * that enforces nothing connects with the same credential.
+   */
+  reportsAccess?: boolean;
 }
 
 /** Result returned by onAuthenticate hook on success. */