@kortix/agent-tunnel 0.12.8 → 0.13.0

package/src/agent/service-drivers.ts

@@ -0,0 +1,299 @@
+import { spawnSync } from 'child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+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';
+
+/**
+ * One driver per supervisor.
+ *
+ * These six operations used to be six exported functions, each with the same
+ * three-way `platform()` chain and its own "not supported" throw — fifteen
+ * branches expressing one dispatch. The table below is that dispatch, so adding
+ * or fixing a platform touches one object instead of six functions.
+ */
+export interface ServiceDriver {
+  /** File that proves the service is installed, and is shown to the user. */
+  unitPath(paths: ServicePaths): string;
+  install(paths: ServicePaths, runner: RunnerParts): Outcome;
+  uninstall(paths: ServicePaths): Outcome;
+  start(paths: ServicePaths, installed: boolean): Outcome;
+  stop(paths: ServicePaths, installed: boolean): Outcome;
+  status(paths: ServicePaths, installed: boolean): Outcome;
+}
+
+/** The interpreter plus arguments the supervisor must launch. */
+export interface RunnerParts {
+  command: string;
+  args: string[];
+}
+
+/**
+ * Resolves the interpreter at start rather than baking one absolute path in.
+ * A version-managed Node (nvm, fnm, volta) moves when the user upgrades, which
+ * would otherwise strand the service.
+ */
+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(' ')}`;
+}
+
+export interface Outcome {
+  /** `null` means "requested, but the supervisor did not confirm". */
+  active?: boolean | null;
+  installed?: boolean;
+  detail?: string;
+}
+
+interface CommandResult {
+  ok: boolean;
+  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(),
+  };
+}
+
+const notInstalled = (what: string): CommandResult => ({ ok: false, detail: `${what} is not installed.` });
+
+function joinDetails(...results: CommandResult[]): string {
+  return results.map((result) => result.detail).filter(Boolean).join('\n');
+}
+
+function launchdTarget(): string {
+  const uid = typeof process.getuid === 'function' ? process.getuid() : userInfo().uid;
+  return `gui/${uid}`;
+}
+
+// ── templates ────────────────────────────────────────────────────────────────
+
+function logPaths(paths: ServicePaths): { stdout: string; stderr: string } {
+  return {
+    stdout: join(paths.logDir, 'agent-tunnel.out.log'),
+    stderr: join(paths.logDir, 'agent-tunnel.err.log'),
+  };
+}
+
+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.
+  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>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/sh</string>
+    <string>-lc</string>
+    <string>${xmlEscape(command)}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>Umask</key>
+  <integer>63</integer>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(stdout)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(stderr)}</string>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(homedir())}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+export function renderSystemdUnit(command: string, paths: ServicePaths = getServicePaths()): string {
+  const { stdout, stderr } = logPaths(paths);
+  return `[Unit]
+Description=Kortix Agent Tunnel
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+UMask=0077
+ExecStart=/bin/sh -lc ${shellQuote(command)}
+Restart=on-failure
+RestartSec=5
+WorkingDirectory=${homedir()}
+Environment=PATH=/usr/local/bin:/usr/bin:/bin
+StandardOutput=append:${stdout}
+StandardError=append:${stderr}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export function renderWindowsPowerShellScript(runner: { command: string; args: string[] }): string {
+  const command = powershellQuote(runner.command);
+  const args = runner.args.map(powershellQuote).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 }
+  Start-Sleep -Seconds 5
+}
+`;
+}
+
+// ── drivers ──────────────────────────────────────────────────────────────────
+
+const launchd: ServiceDriver = {
+  unitPath: (paths) => paths.launchdPlist,
+
+  install(paths, runner) {
+    mkdirSync(dirname(paths.launchdPlist), { recursive: true });
+    writeFileSync(paths.launchdPlist, renderLaunchdPlist(posixShellCommand(runner), paths), { 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) };
+  },
+
+  uninstall(paths) {
+    const existed = existsSync(paths.launchdPlist);
+    const stop = run('launchctl', ['bootout', launchdTarget(), paths.launchdPlist]);
+    if (existed) rmSync(paths.launchdPlist, { force: true });
+    return { detail: stop.detail };
+  },
+
+  start(paths, installed) {
+    const boot = installed
+      ? run('launchctl', ['bootstrap', launchdTarget(), paths.launchdPlist])
+      : notInstalled('LaunchAgent');
+    const kick = run('launchctl', ['kickstart', '-k', `${launchdTarget()}/${SERVICE_LABEL}`]);
+    return { active: boot.ok || kick.ok ? true : null, detail: joinDetails(boot, kick) };
+  },
+
+  stop(paths, installed) {
+    const stop = installed
+      ? run('launchctl', ['bootout', launchdTarget(), paths.launchdPlist])
+      : notInstalled('LaunchAgent');
+    return { detail: stop.detail };
+  },
+
+  status(paths, installed) {
+    const status = run('launchctl', ['print', `${launchdTarget()}/${SERVICE_LABEL}`]);
+    return {
+      active: status.ok,
+      detail: status.detail || (installed ? readFileSync(paths.launchdPlist, 'utf8') : undefined),
+    };
+  },
+};
+
+const systemd: ServiceDriver = {
+  unitPath: (paths) => paths.systemdUnit,
+
+  install(paths, runner) {
+    mkdirSync(dirname(paths.systemdUnit), { recursive: true });
+    writeFileSync(paths.systemdUnit, renderSystemdUnit(posixShellCommand(runner), paths), { 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) };
+  },
+
+  uninstall(paths) {
+    const existed = existsSync(paths.systemdUnit);
+    const disable = run('systemctl', ['--user', 'disable', '--now', `${SERVICE_LABEL}.service`]);
+    if (existed) rmSync(paths.systemdUnit, { force: true });
+    run('systemctl', ['--user', 'daemon-reload']);
+    return { detail: disable.detail };
+  },
+
+  start(_paths, installed) {
+    const start = installed
+      ? run('systemctl', ['--user', 'start', `${SERVICE_LABEL}.service`])
+      : notInstalled('systemd unit');
+    return { active: start.ok ? true : null, detail: start.detail };
+  },
+
+  stop(_paths, installed) {
+    const stop = installed
+      ? run('systemctl', ['--user', 'stop', `${SERVICE_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 };
+  },
+};
+
+const scheduledTask: ServiceDriver = {
+  unitPath: (paths) => paths.windowsScript,
+
+  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]);
+    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']);
+    if (existed) rmSync(paths.windowsScript, { force: true });
+    return { detail: joinDetails(stop, del) };
+  },
+
+  start(_paths, installed) {
+    const start = installed
+      ? run('schtasks.exe', ['/Run', '/TN', SERVICE_LABEL])
+      : notInstalled('Scheduled Task');
+    return { active: start.ok ? true : null, detail: start.detail };
+  },
+
+  stop(_paths, installed) {
+    const stop = installed
+      ? run('schtasks.exe', ['/End', '/TN', SERVICE_LABEL])
+      : notInstalled('Scheduled Task');
+    return { detail: stop.detail };
+  },
+
+  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 };
+  },
+};
+
+const DRIVERS: Partial<Record<NodeJS.Platform, ServiceDriver>> = {
+  darwin: launchd,
+  linux: systemd,
+  win32: scheduledTask,
+};
+
+export const SUPPORTED_PLATFORMS_MESSAGE =
+  'Background services are supported on macOS launchd, Linux systemd user services, and Windows Scheduled Tasks.';
+
+export function serviceDriver(): ServiceDriver | undefined {
+  return DRIVERS[platform()];
+}

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

@@ -0,0 +1,248 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import {
+  MAX_SERVICE_LOG_BYTES,
+  TERMINAL_SERVICE_EXIT_CODE,
+  getServicePaths,
+  renderLaunchdPlist,
+  renderSystemdUnit,
+  renderWindowsPowerShellScript,
+  rotateServiceLogs,
+} from './service';
+import { collapseRepeatedLines } from './log-format';
+import { probeCredentials } from './credential-probe';
+
+const CLI_PATH = resolve(import.meta.dir, 'cli.ts');
+const children = new Set<ChildProcess>();
+const temporaryHomes = new Set<string>();
+
+afterEach(async () => {
+  for (const child of children) child.kill('SIGTERM');
+  children.clear();
+  await Promise.all([...temporaryHomes].map((p) => rm(p, { recursive: true, force: true })));
+  temporaryHomes.clear();
+});
+
+describe('supervisor restart policy', () => {
+  test('launchd restarts only on a failure exit', () => {
+    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/>');
+  });
+
+  test('systemd restarts only on a failure exit', () => {
+    const unit = renderSystemdUnit('exec /bin/echo tunnel');
+    expect(unit).toContain('Restart=on-failure');
+    expect(unit).not.toContain('Restart=always');
+  });
+
+  test('windows loop breaks on the terminal exit code', () => {
+    const script = renderWindowsPowerShellScript({
+      command: 'node',
+      args: ['agent-tunnel.js', 'run', '--service'],
+    });
+    expect(script).toContain(`if ($LASTEXITCODE -eq ${TERMINAL_SERVICE_EXIT_CODE}) { break }`);
+  });
+
+  test('run --service exits terminally when no credential is saved', async () => {
+    const home = await mkdtemp(join(tmpdir(), 'agent-tunnel-nocred-'));
+    temporaryHomes.add(home);
+
+    const child = spawn(process.execPath, ['run', CLI_PATH, 'run', '--service'], {
+      env: { ...process.env, HOME: home },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    children.add(child);
+    const exitCode = await new Promise<number | null>((r) => child.once('exit', r));
+
+    // A non-zero exit here would make the supervisor respawn it forever.
+    expect(exitCode).toBe(TERMINAL_SERVICE_EXIT_CODE);
+  }, 30_000);
+});
+
+describe('service log hygiene', () => {
+  test('collapses repeated lines and keeps the count', () => {
+    expect(collapseRepeatedLines(['a', 'a', 'a', 'b', 'a'])).toEqual(['a  (x3)', 'b', 'a']);
+    expect(collapseRepeatedLines([])).toEqual([]);
+    expect(collapseRepeatedLines(['only'])).toEqual(['only']);
+  });
+
+  test('trims a log that grew past the cap', () => {
+    const home = mkdtempSync(join(tmpdir(), 'agent-tunnel-rotate-'));
+    try {
+      const logDir = join(home, 'logs');
+      mkdirSync(logDir, { recursive: true });
+      const paths = { ...getServicePaths(), logDir };
+      const outLog = join(logDir, 'agent-tunnel.out.log');
+
+      const oversized = `${'noise line\n'.repeat(60_000)}final line\n`;
+      writeFileSync(outLog, oversized);
+      expect(oversized.length).toBeGreaterThan(MAX_SERVICE_LOG_BYTES / 10);
+
+      const rotated = rotateServiceLogs(paths, 1024);
+      expect(rotated).toContain(outLog);
+
+      const body = readFileSync(outLog, 'utf8');
+      expect(body).toStartWith('[agent-tunnel] earlier entries trimmed');
+      expect(body).toContain('final line');
+      expect(body.length).toBeLessThan(64 * 1024);
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('credential probe and the single-agent rule', () => {
+  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.
+    const server = Bun.serve({
+      port: 0,
+      fetch(request, server) {
+        return server.upgrade(request) ? undefined : new Response('no upgrade', { status: 400 });
+      },
+      websocket: {
+        message(ws) {
+          ws.close(4004, 'replaced by another agent process');
+        },
+      },
+    });
+
+    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');
+    } finally {
+      server.stop(true);
+    }
+  }, 30_000);
+});
+
+describe('capability approval', () => {
+  test('refuses to save a pairing that approved nothing', async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch(request) {
+        const url = new URL(request.url);
+        if (request.method === 'POST' && url.pathname === '/v1/tunnel/device-auth') {
+          return Response.json(
+            {
+              deviceCode: 'ZERO-0001',
+              deviceSecret: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ123456',
+              verificationUrl: 'https://dev.kortix.com/tunnel/authorize/ZERO-0001',
+              expiresAt: new Date(Date.now() + 60_000).toISOString(),
+              pollIntervalMs: 250,
+            },
+            { status: 201 },
+          );
+        }
+        if (request.method === 'GET' && url.pathname.endsWith('/ZERO-0001/status')) {
+          return Response.json({
+            status: 'approved',
+            tunnelId: '00000000-0000-4000-8000-000000000042',
+            token: 'kortix_tnl_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB',
+            capabilities: [],
+          });
+        }
+        return new Response('not found', { status: 404 });
+      },
+    });
+
+    const home = await mkdtemp(join(tmpdir(), 'agent-tunnel-zerocap-'));
+    temporaryHomes.add(home);
+    await mkdir(join(home, '.agent-tunnel'), { recursive: true, mode: 0o700 });
+
+    const child = spawn(
+      process.execPath,
+      [
+        'run',
+        CLI_PATH,
+        'connect',
+        '--foreground',
+        '--api-url',
+        `http://127.0.0.1:${server.port}/v1/tunnel`,
+      ],
+      {
+        env: { ...process.env, HOME: home, KORTIX_AGENT_TUNNEL_NO_BROWSER: '1' },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      },
+    );
+    children.add(child);
+    let stdout = '';
+    child.stdout?.on('data', (chunk) => { stdout += String(chunk); });
+
+    try {
+      const exitCode = await new Promise<number | null>((r) => child.once('exit', r));
+      expect(exitCode).toBe(1);
+      expect(stdout).toContain('No capabilities were approved');
+      // An empty ceiling can only be widened by pairing again, so it must
+      // never reach disk in the first place.
+      await expect(readFile(join(home, '.agent-tunnel', 'config.json'), 'utf8')).rejects.toThrow();
+    } finally {
+      child.kill('SIGTERM');
+      server.stop(true);
+    }
+  }, 30_000);
+});
+
+describe('status output', () => {
+  test('reports an unpaired machine without inventing a connection', async () => {
+    const home = await mkdtemp(join(tmpdir(), 'agent-tunnel-status-'));
+    temporaryHomes.add(home);
+
+    const child = spawn(process.execPath, ['run', CLI_PATH, 'status', '--json'], {
+      env: { ...process.env, HOME: home },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    children.add(child);
+    let stdout = '';
+    child.stdout?.on('data', (chunk) => { stdout += String(chunk); });
+    await new Promise((r) => child.once('exit', r));
+
+    const status = JSON.parse(stdout) as { paired: boolean; tunnelId: string | null };
+    expect(status.paired).toBe(false);
+    expect(status.tunnelId).toBeNull();
+  }, 30_000);
+
+  test('reports the approved capability ceiling for a paired machine', async () => {
+    const home = await mkdtemp(join(tmpdir(), 'agent-tunnel-status-paired-'));
+    temporaryHomes.add(home);
+    await mkdir(join(home, '.agent-tunnel'), { recursive: true, mode: 0o700 });
+    await writeFile(
+      join(home, '.agent-tunnel', 'config.json'),
+      JSON.stringify({
+        tunnelId: '00000000-0000-4000-8000-000000000042',
+        token: 'kortix_tnl_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB',
+        apiUrl: 'https://api.kortix.com/v1/tunnel',
+        enabledCapabilities: ['filesystem', 'shell'],
+      }),
+      { mode: 0o600 },
+    );
+
+    const child = spawn(process.execPath, ['run', CLI_PATH, 'status', '--json'], {
+      env: { ...process.env, HOME: home },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    children.add(child);
+    let stdout = '';
+    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[] };
+    expect(status.paired).toBe(true);
+    expect(status.capabilities).toEqual(['filesystem', 'shell']);
+  }, 30_000);
+});

package/src/agent/service-paths.ts

@@ -0,0 +1,80 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export const SERVICE_LABEL = 'ai.kortix.agent-tunnel';
+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.
+ */
+export const TERMINAL_SERVICE_EXIT_CODE = 0;
+
+/** Supervised logs are appended to forever; launchd and systemd never rotate. */
+export const MAX_SERVICE_LOG_BYTES = 5 * 1024 * 1024;
+const RETAINED_LOG_LINES = 500;
+
+export interface ServicePaths {
+  configDir: string;
+  logDir: string;
+  binDir: string;
+  vendoredRunner: string;
+  launchdPlist: string;
+  systemdUnit: string;
+  windowsScript: string;
+}
+
+export function getServicePaths(): ServicePaths {
+  const home = homedir();
+  const configDir = join(home, '.agent-tunnel');
+  const binDir = join(configDir, 'bin');
+  return {
+    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`),
+    windowsScript: join(configDir, 'agent-tunnel-service.ps1'),
+  };
+}
+
+export function serviceLogFiles(paths: ServicePaths = getServicePaths()): string[] {
+  return [
+    join(paths.logDir, 'agent-tunnel.out.log'),
+    join(paths.logDir, 'agent-tunnel.err.log'),
+  ];
+}
+
+/**
+ * Trims oversized log files in place, keeping the most recent lines.
+ *
+ * A restart loop can produce megabytes of identical lines — 23 MB was observed
+ * on a real machine. Supervisors hold these files open in append mode, so
+ * rewriting the contents is safe while the service runs.
+ */
+export function rotateServiceLogs(
+  paths: ServicePaths = getServicePaths(),
+  maxBytes = MAX_SERVICE_LOG_BYTES,
+): string[] {
+  const rotated: string[] = [];
+  for (const file of serviceLogFiles(paths)) {
+    try {
+      // Read once and decide from the bytes in hand. Checking existence or size
+      // first and then reading is a race: the supervisor appends continuously,
+      // so the file examined need not be the file read.
+      const contents = readFileSync(file, 'utf8');
+      if (Buffer.byteLength(contents, 'utf8') <= maxBytes) continue;
+      const kept = contents.split(/\r?\n/).slice(-RETAINED_LOG_LINES).join('\n');
+      writeFileSync(file, `[agent-tunnel] earlier entries trimmed\n${kept}`, { mode: 0o600 });
+      rotated.push(file);
+    } catch {
+      // A missing or unreadable log must never stop the service from starting.
+    }
+  }
+  return rotated;
+}

package/src/agent/service-quoting.ts

@@ -0,0 +1,16 @@
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+export function powershellQuote(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+export function xmlEscape(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}