@kortix/agent-tunnel 0.12.7 → 0.13.0

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 { join } from 'node:path';
 import {
   DEFAULT_INSTALL_BACKGROUND_SERVICE,
   SERVICE_LABEL,
   buildServiceShellCommand,
   getServicePaths,
+  isEphemeralRunnerPath,
   renderLaunchdPlist,
   renderSystemdUnit,
   renderWindowsPowerShellScript,
+  vendorRunner,
 } from './service';
 
 describe('agent tunnel service definitions', () => {
@@ -31,10 +36,12 @@ describe('agent tunnel service definitions', () => {
     expect(plist).toContain('agent-tunnel.err.log');
   });
 
-  test('systemd unit restarts forever', () => {
+  test('systemd unit restarts on failure but not after a terminal exit', () => {
     const unit = renderSystemdUnit('exec /bin/echo tunnel');
     expect(unit).toContain('Description=Kortix Agent Tunnel');
-    expect(unit).toContain('Restart=always');
+    // Restart=always respawned the agent forever when the credential was
+    // missing or revoked, which no restart can fix.
+    expect(unit).toContain('Restart=on-failure');
     expect(unit).toContain('UMask=0077');
     expect(unit).toContain('WantedBy=default.target');
     expect(unit).toContain('agent-tunnel.out.log');
@@ -52,6 +59,49 @@ describe('agent tunnel service definitions', () => {
     expect(script).toContain('Start-Sleep -Seconds 5');
   });
 
+  test('treats package-manager caches as ephemeral runner locations', () => {
+    expect(
+      isEphemeralRunnerPath(
+        '/Users/x/.npm/_npx/d2c324008dde6a9b/node_modules/@kortix/agent-tunnel/dist/agent-cli.js',
+      ),
+    ).toBe(true);
+    expect(isEphemeralRunnerPath('/Users/x/.npm/_cacache/content-v2/sha512/ab/cd')).toBe(true);
+    expect(isEphemeralRunnerPath('/usr/local/lib/node_modules/@kortix/agent-tunnel/dist/agent-cli.js')).toBe(false);
+    expect(isEphemeralRunnerPath('/opt/homebrew/bin/agent-tunnel')).toBe(false);
+  });
+
+  test('vendors an npx-cached runner into the config directory', () => {
+    const home = mkdtempSync(join(tmpdir(), 'agent-tunnel-vendor-'));
+    try {
+      const paths = {
+        ...getServicePaths(),
+        binDir: join(home, 'bin'),
+        vendoredRunner: join(home, 'bin', 'agent-cli.js'),
+      };
+
+      // A stable install location is used as-is.
+      const stable = join(home, 'agent-cli.js');
+      writeFileSync(stable, '// bundle\n');
+      expect(vendorRunner(stable, paths)).toBe(stable);
+
+      // An npx cache path is copied out to the stable location instead.
+      const cacheDir = join(home, '_npx', 'abc');
+      mkdirSync(cacheDir, { recursive: true });
+      const cached = join(cacheDir, 'agent-cli.js');
+      writeFileSync(cached, '// cached bundle\n');
+      const copied = vendorRunner(cached, paths);
+      expect(copied).toBe(paths.vendoredRunner);
+      expect(readFileSync(copied, 'utf8')).toBe('// cached bundle\n');
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test('resolves the interpreter at start instead of pinning one absolute path', () => {
+    const command = buildServiceShellCommand();
+    expect(command).toContain('command -v node');
+  });
+
   test('service paths are under the user home', () => {
     const paths = getServicePaths();
     expect(paths.configDir).toContain('.agent-tunnel');

package/src/agent/service.ts

@@ -1,18 +1,34 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
-import { homedir, platform, userInfo } from 'os';
-import { dirname, join } from 'path';
-import { spawnSync } from 'child_process';
-
-export const SERVICE_LABEL = 'ai.kortix.agent-tunnel';
-export const DEFAULT_INSTALL_BACKGROUND_SERVICE = true;
-
-export interface ServicePaths {
-  configDir: string;
-  logDir: string;
-  launchdPlist: string;
-  systemdUnit: string;
-  windowsScript: string;
-}
+import { chmodSync, copyFileSync, existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from 'fs';
+import { platform } from 'os';
+import { join } from 'path';
+
+import {
+  SUPPORTED_PLATFORMS_MESSAGE,
+  type RunnerParts,
+  posixShellCommand,
+  serviceDriver,
+} from './service-drivers';
+import {
+  type ServicePaths,
+  getServicePaths,
+  rotateServiceLogs,
+} from './service-paths';
+
+export {
+  DEFAULT_INSTALL_BACKGROUND_SERVICE,
+  MAX_SERVICE_LOG_BYTES,
+  SERVICE_LABEL,
+  TERMINAL_SERVICE_EXIT_CODE,
+  type ServicePaths,
+  getServicePaths,
+  rotateServiceLogs,
+  serviceLogFiles,
+} from './service-paths';
+export {
+  renderLaunchdPlist,
+  renderSystemdUnit,
+  renderWindowsPowerShellScript,
+} from './service-drivers';
 
 export interface ServiceStatus {
   platform: NodeJS.Platform;
@@ -22,338 +38,129 @@ export interface ServiceStatus {
   detail?: string;
 }
 
-export function getServicePaths(): ServicePaths {
-  const home = homedir();
-  const configDir = join(home, '.agent-tunnel');
-  return {
-    configDir,
-    logDir: join(configDir, 'logs'),
-    launchdPlist: join(home, 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`),
-    systemdUnit: join(home, '.config', 'systemd', 'user', `${SERVICE_LABEL}.service`),
-    windowsScript: join(configDir, 'agent-tunnel-service.ps1'),
-  };
-}
-
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-
-function powershellQuote(value: string): string {
-  return `'${value.replace(/'/g, "''")}'`;
+/**
+ * True for locations a package manager may delete without warning.
+ *
+ * `npx` extracts the package into a content-addressed cache directory and
+ * garbage-collects it. A background service pointed at that path starts fine and
+ * then dies permanently the first time the cache is pruned, leaving only a
+ * MODULE_NOT_FOUND in a log file nobody reads.
+ */
+export function isEphemeralRunnerPath(path: string): boolean {
+  const normalized = path.replace(/\\/g, '/');
+  return (
+    normalized.includes('/_npx/') ||
+    normalized.includes('/_cacache/') ||
+    normalized.includes('/.pnpm-store/') ||
+    normalized.includes('/.yarn/$$virtual/')
+  );
 }
 
-function xmlEscape(value: string): string {
-  return value
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&apos;');
+/**
+ * Copies the running CLI bundle into ~/.agent-tunnel/bin so the installed
+ * service owns its executable. The bundle is a single self-contained file that
+ * imports only Node builtins, so a plain copy is sufficient.
+ */
+export function vendorRunner(scriptPath: string, paths: ServicePaths = getServicePaths()): string {
+  if (!isEphemeralRunnerPath(scriptPath)) return scriptPath;
+
+  mkdirSync(paths.binDir, { recursive: true, mode: 0o700 });
+  const source = realpathSync(scriptPath);
+  copyFileSync(source, paths.vendoredRunner);
+  try { chmodSync(paths.vendoredRunner, 0o700); } catch {}
+  writeFileSync(
+    join(paths.binDir, 'agent-cli.source.json'),
+    JSON.stringify({ source, vendoredFrom: scriptPath }, null, 2),
+    { mode: 0o600 },
+  );
+  return paths.vendoredRunner;
 }
 
-function currentRunnerParts(): { command: string; args: string[] } {
-  const exec = process.execPath;
+function currentRunnerParts(): RunnerParts {
   const script = process.argv[1];
   if (script && existsSync(script)) {
-    return { command: exec, args: [script, 'run', '--service'] };
+    return { command: process.execPath, args: [vendorRunner(script), 'run', '--service'] };
   }
   throw new Error(
     'Cannot install the background service because the current Agent Tunnel executable was not found',
   );
 }
 
-function currentRunnerCommand(): string {
-  const runner = currentRunnerParts();
-  return [runner.command, ...runner.args].map(shellQuote).join(' ');
-}
-
 export function buildServiceShellCommand(): string {
-  return `exec ${currentRunnerCommand()}`;
-}
-
-export function renderWindowsPowerShellScript(
-  runner = currentRunnerParts(),
-): string {
-  const command = powershellQuote(runner.command);
-  const args = runner.args.map(powershellQuote).join(' ');
-
-  return `$ErrorActionPreference = 'Continue'
-while ($true) {
-  & ${command}${args ? ` ${args}` : ''}
-  Start-Sleep -Seconds 5
-}
-`;
-}
-
-function windowsTaskCommand(paths: ServicePaths): string {
-  return `powershell.exe -NoProfile -ExecutionPolicy Bypass -File "${paths.windowsScript}"`;
-}
-
-export function renderLaunchdPlist(command: string, paths: ServicePaths = getServicePaths()): string {
-  const stdout = join(paths.logDir, 'agent-tunnel.out.log');
-  const stderr = join(paths.logDir, 'agent-tunnel.err.log');
-  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>
-  <true/>
-  <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 = join(paths.logDir, 'agent-tunnel.out.log');
-  const stderr = join(paths.logDir, 'agent-tunnel.err.log');
-  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=always
-RestartSec=5
-WorkingDirectory=${homedir()}
-Environment=PATH=/usr/local/bin:/usr/bin:/bin
-StandardOutput=append:${stdout}
-StandardError=append:${stderr}
+  return posixShellCommand(currentRunnerParts());
+}
+
+/**
+ * Runs one driver operation and normalises it into a ServiceStatus.
+ *
+ * Every public verb below shares this shape, which is why the per-platform
+ * branching lives in the driver table rather than in six near-identical
+ * functions.
+ */
+function withDriver(
+  operate: (driver: NonNullable<ReturnType<typeof serviceDriver>>, paths: ServicePaths, installed: boolean) => {
+    active?: boolean | null;
+    installed?: boolean;
+    detail?: string;
+  },
+  fallback: { installed: boolean; active: boolean | null },
+): ServiceStatus {
+  const driver = serviceDriver();
+  const paths = getServicePaths();
 
-[Install]
-WantedBy=default.target
-`;
-}
+  // Mutating verbs must fail loudly on an unsupported platform. Reporting a
+  // successful-looking status would make the CLI claim it installed a service
+  // that does not exist.
+  if (!driver) throw new Error(SUPPORTED_PLATFORMS_MESSAGE);
 
-function run(command: string, args: string[]): { ok: boolean; detail: string } {
-  const result = spawnSync(command, args, { encoding: 'utf8' });
-  const detail = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
-  return { ok: result.status === 0, detail };
-}
+  const path = driver.unitPath(paths);
+  const installed = existsSync(path);
+  const outcome = operate(driver, paths, installed);
 
-function launchdTarget(): string {
-  const uid = typeof process.getuid === 'function' ? process.getuid() : userInfo().uid;
-  return `gui/${uid}`;
+  return {
+    platform: platform(),
+    installed: outcome.installed ?? installed,
+    active: outcome.active ?? fallback.active,
+    path,
+    detail: outcome.detail,
+  };
 }
 
 export function installService(): ServiceStatus {
   const paths = getServicePaths();
   mkdirSync(paths.configDir, { recursive: true, mode: 0o700 });
   mkdirSync(paths.logDir, { recursive: true, mode: 0o700 });
+  rotateServiceLogs(paths);
 
-  const command = buildServiceShellCommand();
-
-  if (platform() === 'darwin') {
-    mkdirSync(dirname(paths.launchdPlist), { recursive: true });
-    writeFileSync(paths.launchdPlist, renderLaunchdPlist(command, 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 {
-      platform: platform(),
-      installed: true,
-      active: boot.ok || kick.ok ? true : null,
-      path: paths.launchdPlist,
-      detail: [boot.detail, kick.detail].filter(Boolean).join('\n'),
-    };
-  }
-
-  if (platform() === 'linux') {
-    mkdirSync(dirname(paths.systemdUnit), { recursive: true });
-    writeFileSync(paths.systemdUnit, renderSystemdUnit(command, paths), { mode: 0o600 });
-    const reload = run('systemctl', ['--user', 'daemon-reload']);
-    const enable = run('systemctl', ['--user', 'enable', '--now', `${SERVICE_LABEL}.service`]);
-    return {
-      platform: platform(),
-      installed: true,
-      active: enable.ok ? true : null,
-      path: paths.systemdUnit,
-      detail: [reload.detail, enable.detail].filter(Boolean).join('\n'),
-    };
-  }
-
-  if (platform() === 'win32') {
-    writeFileSync(paths.windowsScript, renderWindowsPowerShellScript(), { mode: 0o600 });
-    const create = run('schtasks.exe', [
-      '/Create',
-      '/TN',
-      SERVICE_LABEL,
-      '/TR',
-      windowsTaskCommand(paths),
-      '/SC',
-      'ONLOGON',
-      '/F',
-      '/RL',
-      'LIMITED',
-    ]);
-    const start = run('schtasks.exe', ['/Run', '/TN', SERVICE_LABEL]);
-    return {
-      platform: platform(),
-      installed: create.ok,
-      active: start.ok ? true : null,
-      path: paths.windowsScript,
-      detail: [create.detail, start.detail].filter(Boolean).join('\n'),
-    };
-  }
-
-  throw new Error('Background service install is currently supported on macOS launchd, Linux systemd user services, and Windows Scheduled Tasks.');
+  const runner = currentRunnerParts();
+  return withDriver(
+    (driver, servicePaths) => driver.install(servicePaths, runner),
+    { installed: false, active: null },
+  );
 }
 
 export function uninstallService(): ServiceStatus {
-  const paths = getServicePaths();
-
-  if (platform() === 'darwin') {
-    const existed = existsSync(paths.launchdPlist);
-    const stop = run('launchctl', ['bootout', launchdTarget(), paths.launchdPlist]);
-    if (existed) rmSync(paths.launchdPlist, { force: true });
-    return {
-      platform: platform(),
-      installed: false,
-      active: false,
-      path: paths.launchdPlist,
-      detail: stop.detail,
-    };
-  }
-
-  if (platform() === 'linux') {
-    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 {
-      platform: platform(),
-      installed: false,
-      active: false,
-      path: paths.systemdUnit,
-      detail: disable.detail,
-    };
-  }
-
-  if (platform() === 'win32') {
-    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 {
-      platform: platform(),
-      installed: false,
-      active: false,
-      path: paths.windowsScript,
-      detail: [stop.detail, del.detail].filter(Boolean).join('\n'),
-    };
-  }
-
-  throw new Error('Background service uninstall is currently supported on macOS launchd, Linux systemd user services, and Windows Scheduled Tasks.');
+  // Remove the vendored executable too, so uninstall leaves no residue a later
+  // install would silently reuse.
+  rmSync(getServicePaths().binDir, { recursive: true, force: true });
+  return withDriver(
+    (driver, paths) => ({ ...driver.uninstall(paths), installed: false, active: false }),
+    { installed: false, active: false },
+  );
 }
 
 export function startService(): ServiceStatus {
-  const paths = getServicePaths();
-
-  if (platform() === 'darwin') {
-    const installed = existsSync(paths.launchdPlist);
-    const boot = installed ? run('launchctl', ['bootstrap', launchdTarget(), paths.launchdPlist]) : { ok: false, detail: 'LaunchAgent is not installed.' };
-    const kick = run('launchctl', ['kickstart', '-k', `${launchdTarget()}/${SERVICE_LABEL}`]);
-    return {
-      platform: platform(),
-      installed,
-      active: boot.ok || kick.ok ? true : null,
-      path: paths.launchdPlist,
-      detail: [boot.detail, kick.detail].filter(Boolean).join('\n'),
-    };
-  }
-
-  if (platform() === 'linux') {
-    const installed = existsSync(paths.systemdUnit);
-    const start = installed ? run('systemctl', ['--user', 'start', `${SERVICE_LABEL}.service`]) : { ok: false, detail: 'systemd unit is not installed.' };
-    return {
-      platform: platform(),
-      installed,
-      active: start.ok ? true : null,
-      path: paths.systemdUnit,
-      detail: start.detail,
-    };
-  }
-
-  if (platform() === 'win32') {
-    const installed = existsSync(paths.windowsScript);
-    const start = installed ? run('schtasks.exe', ['/Run', '/TN', SERVICE_LABEL]) : { ok: false, detail: 'Scheduled Task is not installed.' };
-    return {
-      platform: platform(),
-      installed,
-      active: start.ok ? true : null,
-      path: paths.windowsScript,
-      detail: start.detail,
-    };
-  }
-
-  throw new Error('Background service start is currently supported on macOS, Linux, and Windows.');
+  return withDriver(
+    (driver, paths, installed) => driver.start(paths, installed),
+    { installed: false, active: null },
+  );
 }
 
 export function stopService(): ServiceStatus {
-  const paths = getServicePaths();
-
-  if (platform() === 'darwin') {
-    const installed = existsSync(paths.launchdPlist);
-    const stop = installed ? run('launchctl', ['bootout', launchdTarget(), paths.launchdPlist]) : { ok: false, detail: 'LaunchAgent is not installed.' };
-    return {
-      platform: platform(),
-      installed,
-      active: false,
-      path: paths.launchdPlist,
-      detail: stop.detail,
-    };
-  }
-
-  if (platform() === 'linux') {
-    const installed = existsSync(paths.systemdUnit);
-    const stop = installed ? run('systemctl', ['--user', 'stop', `${SERVICE_LABEL}.service`]) : { ok: false, detail: 'systemd unit is not installed.' };
-    return {
-      platform: platform(),
-      installed,
-      active: false,
-      path: paths.systemdUnit,
-      detail: stop.detail,
-    };
-  }
-
-  if (platform() === 'win32') {
-    const installed = existsSync(paths.windowsScript);
-    const stop = installed ? run('schtasks.exe', ['/End', '/TN', SERVICE_LABEL]) : { ok: false, detail: 'Scheduled Task is not installed.' };
-    return {
-      platform: platform(),
-      installed,
-      active: false,
-      path: paths.windowsScript,
-      detail: stop.detail,
-    };
-  }
-
-  throw new Error('Background service stop is currently supported on macOS, Linux, and Windows.');
+  return withDriver(
+    (driver, paths, installed) => ({ ...driver.stop(paths, installed), active: false }),
+    { installed: false, active: false },
+  );
 }
 
 export function restartService(): ServiceStatus {
@@ -362,49 +169,18 @@ export function restartService(): ServiceStatus {
 }
 
 export function getServiceStatus(): ServiceStatus {
-  const paths = getServicePaths();
-
-  if (platform() === 'darwin') {
-    const installed = existsSync(paths.launchdPlist);
-    const status = run('launchctl', ['print', `${launchdTarget()}/${SERVICE_LABEL}`]);
+  // Status is the one verb that must answer on every platform: callers use it
+  // to decide whether a service exists at all.
+  if (!serviceDriver()) {
     return {
       platform: platform(),
-      installed,
-      active: status.ok,
-      path: paths.launchdPlist,
-      detail: status.detail || (installed ? readFileSync(paths.launchdPlist, 'utf8') : undefined),
-    };
-  }
-
-  if (platform() === 'linux') {
-    const installed = existsSync(paths.systemdUnit);
-    const status = run('systemctl', ['--user', 'is-active', `${SERVICE_LABEL}.service`]);
-    return {
-      platform: platform(),
-      installed,
-      active: status.ok,
-      path: paths.systemdUnit,
-      detail: status.detail,
-    };
-  }
-
-  if (platform() === 'win32') {
-    const installed = existsSync(paths.windowsScript);
-    const status = run('schtasks.exe', ['/Query', '/TN', SERVICE_LABEL, '/FO', 'LIST', '/V']);
-    const detail = status.detail || (installed ? readFileSync(paths.windowsScript, 'utf8') : undefined);
-    return {
-      platform: platform(),
-      installed,
-      active: status.ok ? /Status:\s*Running/i.test(detail ?? '') : false,
-      path: paths.windowsScript,
-      detail,
+      installed: false,
+      active: null,
+      detail: SUPPORTED_PLATFORMS_MESSAGE,
     };
   }
-
-  return {
-    platform: platform(),
-    installed: false,
-    active: null,
-    detail: 'Background service status is currently supported on macOS launchd, Linux systemd user services, and Windows Scheduled Tasks.',
-  };
+  return withDriver(
+    (driver, paths, installed) => driver.status(paths, installed),
+    { installed: false, active: null },
+  );
 }

package/src/agent/terminal.ts

@@ -0,0 +1,53 @@
+/**
+ * Terminal rendering primitives.
+ *
+ * The colour table used to be copy-pasted into agent.ts and cli.ts, which drifted
+ * (one carried keys the other did not). One table, one place.
+ */
+export const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  white: '\x1b[97m',
+  gray: '\x1b[90m',
+} as const;
+
+const ANSI = /\x1b\[[0-9;]*m/g;
+
+export function stripAnsi(value: string): string {
+  return value.replace(ANSI, '');
+}
+
+/** Printable width, ignoring colour escapes. Needed to pad boxed layouts. */
+export function visibleLength(value: string): number {
+  return stripAnsi(value).length;
+}
+
+export function clearScreen(): void {
+  process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+}
+
+export const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Status glyphs. Kept together so "on/off/warn" reads the same everywhere. */
+export const glyph = {
+  on: `${c.green}●${c.reset}`,
+  off: `${c.gray}○${c.reset}`,
+  warn: `${c.yellow}!${c.reset}`,
+  bad: `${c.red}✗${c.reset}`,
+  mark: `${c.cyan}◆${c.reset}`,
+} as const;
+
+/** `  label      value` — the two-column layout shared by status and summaries. */
+export function field(label: string, value: string, width = 14): void {
+  console.log(`  ${c.dim}${label.padEnd(width)}${c.reset}${value}`);
+}
+
+export function blankLine(): void {
+  console.log('');
+}