@vibelet/cli 0.1.34 → 0.1.36

package/src/logger.ts

@@ -0,0 +1,112 @@
+import { appendFileSync, mkdirSync } from 'fs';
+import {
+  DAEMON_STDERR_LOG_PATH,
+  DAEMON_STDOUT_LOG_PATH,
+  VIBELET_LOG_DIR,
+} from './paths.js';
+import { writeStderrSafe, writeStdoutSafe } from './safe-stdio.js';
+
+/**
+ * Structured logger for the Vibelet daemon.
+ *
+ * Outputs one JSON object per line (JSONL) to stdout/stderr.
+ * Each entry includes: level, ts, msg, and any extra context fields.
+ *
+ * Usage:
+ *   import { logger } from './logger.js';
+ *   logger.info({ sessionId, agent }, 'session created');
+ *   const child = logger.child({ sessionId, agent });
+ *   child.info('driver started');
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LEVEL_VALUE: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40 };
+
+let minLevel: LogLevel = (process.env.VIBE_LOG_LEVEL as LogLevel) || 'info';
+
+export function setLogLevel(level: LogLevel): void {
+  minLevel = level;
+}
+
+interface LogContext {
+  [key: string]: unknown;
+}
+
+function isTestRuntime(): boolean {
+  return process.env.VIBE_TEST === '1' || process.argv.includes('--test');
+}
+
+// Skip appendFileSync when launchd/systemd already redirects stdout/stderr
+// to the log files — writing to both causes every line to appear twice.
+function stdoutAlreadyRedirected(): boolean {
+  try {
+    const { fstatSync } = require('fs') as typeof import('fs');
+    const stat = fstatSync(1);
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+const PERSIST_LOG_FILE = !isTestRuntime() && !stdoutAlreadyRedirected();
+
+if (PERSIST_LOG_FILE) {
+  try { mkdirSync(VIBELET_LOG_DIR, { recursive: true }); } catch {}
+}
+
+function write(level: LogLevel, ctx: LogContext, msg: string): void {
+  if (LEVEL_VALUE[level] < LEVEL_VALUE[minLevel]) return;
+
+  const entry = {
+    level,
+    ts: new Date().toISOString(),
+    msg,
+    ...ctx,
+  };
+
+  const line = JSON.stringify(entry);
+  if (level === 'error' || level === 'warn') {
+    writeStderrSafe(line + '\n');
+  } else {
+    writeStdoutSafe(line + '\n');
+  }
+  if (PERSIST_LOG_FILE) {
+    const logFile = level === 'error' || level === 'warn'
+      ? DAEMON_STDERR_LOG_PATH
+      : DAEMON_STDOUT_LOG_PATH;
+    try { appendFileSync(logFile, line + '\n'); } catch {}
+  }
+}
+
+export interface Logger {
+  debug(msg: string): void;
+  debug(ctx: LogContext, msg: string): void;
+  info(msg: string): void;
+  info(ctx: LogContext, msg: string): void;
+  warn(msg: string): void;
+  warn(ctx: LogContext, msg: string): void;
+  error(msg: string): void;
+  error(ctx: LogContext, msg: string): void;
+  child(defaultCtx: LogContext): Logger;
+}
+
+function createLogger(defaultCtx: LogContext = {}): Logger {
+  function log(level: LogLevel, ctxOrMsg: LogContext | string, maybeMsg?: string): void {
+    if (typeof ctxOrMsg === 'string') {
+      write(level, defaultCtx, ctxOrMsg);
+    } else {
+      write(level, { ...defaultCtx, ...ctxOrMsg }, maybeMsg!);
+    }
+  }
+
+  return {
+    debug: (ctxOrMsg: LogContext | string, maybeMsg?: string) => log('debug', ctxOrMsg, maybeMsg),
+    info: (ctxOrMsg: LogContext | string, maybeMsg?: string) => log('info', ctxOrMsg, maybeMsg),
+    warn: (ctxOrMsg: LogContext | string, maybeMsg?: string) => log('warn', ctxOrMsg, maybeMsg),
+    error: (ctxOrMsg: LogContext | string, maybeMsg?: string) => log('error', ctxOrMsg, maybeMsg),
+    child: (childCtx: LogContext) => createLogger({ ...defaultCtx, ...childCtx }),
+  } as Logger;
+}
+
+export const logger = createLogger({ module: 'daemon' });

package/src/metrics.ts

@@ -0,0 +1,117 @@
+/**
+ * Lightweight in-memory metrics for the Vibelet daemon.
+ *
+ * Provides counters and timers. No external dependencies.
+ * Metrics are exposed via the /health endpoint and periodically logged.
+ *
+ * Usage:
+ *   import { metrics } from './metrics.js';
+ *   metrics.increment('session.create', { agent: 'claude' });
+ *   const end = metrics.startTimer('driver.spawn');
+ *   // ... work ...
+ *   end();  // records duration in ms
+ */
+
+import { logger } from './logger.js';
+
+interface CounterEntry {
+  value: number;
+  labels: Record<string, string>;
+}
+
+interface TimerEntry {
+  count: number;
+  totalMs: number;
+  minMs: number;
+  maxMs: number;
+  lastMs: number;
+}
+
+class MetricsRegistry {
+  private counters = new Map<string, CounterEntry[]>();
+  private timers = new Map<string, TimerEntry>();
+  private gauges = new Map<string, number>();
+  private startTime = Date.now();
+  private logInterval: ReturnType<typeof setInterval> | null = null;
+
+  /** Increment a counter, optionally with labels. */
+  increment(name: string, labels: Record<string, string> = {}): void {
+    if (!this.counters.has(name)) this.counters.set(name, []);
+    const entries = this.counters.get(name)!;
+    const key = JSON.stringify(labels);
+    const existing = entries.find(e => JSON.stringify(e.labels) === key);
+    if (existing) {
+      existing.value++;
+    } else {
+      entries.push({ value: 1, labels });
+    }
+  }
+
+  /** Set a gauge value (for current-state metrics). */
+  gauge(name: string, value: number): void {
+    this.gauges.set(name, value);
+  }
+
+  /** Start a timer, returns a function to call when done. */
+  startTimer(name: string): () => number {
+    const start = performance.now();
+    return () => {
+      const durationMs = Math.round(performance.now() - start);
+      const entry = this.timers.get(name) ?? { count: 0, totalMs: 0, minMs: Infinity, maxMs: 0, lastMs: 0 };
+      entry.count++;
+      entry.totalMs += durationMs;
+      entry.minMs = Math.min(entry.minMs, durationMs);
+      entry.maxMs = Math.max(entry.maxMs, durationMs);
+      entry.lastMs = durationMs;
+      this.timers.set(name, entry);
+      return durationMs;
+    };
+  }
+
+  /** Get a snapshot of all metrics. */
+  snapshot(): MetricsSnapshot {
+    const counters: Record<string, CounterEntry[]> = {};
+    for (const [name, entries] of this.counters) {
+      counters[name] = entries.map(e => ({ ...e }));
+    }
+
+    const timers: Record<string, TimerEntry> = {};
+    for (const [name, entry] of this.timers) {
+      timers[name] = { ...entry, minMs: entry.minMs === Infinity ? 0 : entry.minMs };
+    }
+
+    const gauges: Record<string, number> = {};
+    for (const [name, value] of this.gauges) {
+      gauges[name] = value;
+    }
+
+    return { uptimeMs: Date.now() - this.startTime, counters, timers, gauges };
+  }
+
+  /** Start periodic metrics logging (default: every 60s). */
+  startPeriodicLog(intervalMs = 60_000): void {
+    if (this.logInterval) return;
+    this.logInterval = setInterval(() => {
+      const snap = this.snapshot();
+      logger.info({ metrics: snap }, 'periodic metrics snapshot');
+    }, intervalMs);
+    this.logInterval.unref();
+  }
+
+  /** Stop periodic logging. */
+  stopPeriodicLog(): void {
+    if (this.logInterval) {
+      clearInterval(this.logInterval);
+      this.logInterval = null;
+    }
+  }
+}
+
+export interface MetricsSnapshot {
+  uptimeMs: number;
+  counters: Record<string, CounterEntry[]>;
+  timers: Record<string, TimerEntry>;
+  gauges: Record<string, number>;
+}
+
+export const metrics = new MetricsRegistry();

package/src/pairing-store.test.ts

@@ -0,0 +1,53 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { PairingStore } from './pairing-store.js';
+
+test('PairingStore issues stable per-device tokens and validates them', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'vibelet-pairing-'));
+  const pairingsPath = join(dir, 'pairings.json');
+
+  try {
+    const store = new PairingStore(pairingsPath);
+    const token = store.issuePairToken('device-1', 'Leyang iPhone');
+
+    assert.equal(store.pairedCount(), 1);
+    assert.equal(store.validatePairToken('device-1', token), true);
+    assert.equal(store.validateAnyPairToken(token)?.deviceId, 'device-1');
+
+    const persisted = JSON.parse(await readFile(pairingsPath, 'utf8'));
+    assert.equal(persisted.length, 1);
+    assert.equal(persisted[0].deviceId, 'device-1');
+    assert.notEqual(persisted[0].tokenHash, token);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('PairingStore expires one-time pairing windows and can revoke/reset pairings', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'vibelet-pairing-'));
+  const pairingsPath = join(dir, 'pairings.json');
+
+  try {
+    const store = new PairingStore(pairingsPath);
+    const expired = store.openWindow(-1);
+    const fresh = store.openWindow();
+    const token = store.issuePairToken('device-2', 'Office iPhone');
+
+    assert.equal(store.consumeWindow(expired.pairNonce), null);
+    assert.ok(store.consumeWindow(fresh.pairNonce));
+    assert.equal(store.consumeWindow(fresh.pairNonce), null);
+
+    assert.equal(store.revoke('device-2'), true);
+    assert.equal(store.validatePairToken('device-2', token, false), false);
+    assert.equal(store.pairedCount(), 0);
+
+    store.reset();
+    const persisted = JSON.parse(await readFile(pairingsPath, 'utf8'));
+    assert.deepEqual(persisted, []);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/pairing-store.ts

@@ -0,0 +1,154 @@
+import { createHash, randomBytes, timingSafeEqual } from 'crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+import { PAIRINGS_PATH } from './paths.js';
+
+export interface PairingRecord {
+  deviceId: string;
+  deviceName: string;
+  tokenHash: string;
+  createdAt: string;
+  lastSeenAt: string;
+  revokedAt: string | null;
+}
+
+export interface PairingWindow {
+  pairingId: string;
+  pairNonce: string;
+  expiresAt: string;
+}
+
+function base64Url(bytes: number): string {
+  return randomBytes(bytes).toString('base64url');
+}
+
+function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+function sameHash(left: string, right: string): boolean {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  if (leftBuffer.length !== rightBuffer.length) return false;
+  return timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+function readRecords(pairingsPath: string): PairingRecord[] {
+  try {
+    const raw = readFileSync(pairingsPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((entry): entry is PairingRecord => (
+      entry &&
+      typeof entry.deviceId === 'string' &&
+      typeof entry.deviceName === 'string' &&
+      typeof entry.tokenHash === 'string' &&
+      typeof entry.createdAt === 'string' &&
+      typeof entry.lastSeenAt === 'string' &&
+      (typeof entry.revokedAt === 'string' || entry.revokedAt === null)
+    ));
+  } catch {
+    return [];
+  }
+}
+
+function writeRecords(pairingsPath: string, records: PairingRecord[]): void {
+  mkdirSync(dirname(pairingsPath), { recursive: true });
+  writeFileSync(pairingsPath, JSON.stringify(records, null, 2) + '\n', 'utf8');
+}
+
+export class PairingStore {
+  private records: PairingRecord[];
+  private windows = new Map<string, PairingWindow>();
+
+  constructor(private readonly pairingsPath = PAIRINGS_PATH) {
+    this.records = readRecords(pairingsPath);
+  }
+
+  list(): PairingRecord[] {
+    return this.records.slice();
+  }
+
+  pairedCount(): number {
+    return this.records.filter((record) => !record.revokedAt).length;
+  }
+
+  openWindow(windowMs = 5 * 60_000): PairingWindow {
+    const pairingId = `pair_${base64Url(8)}`;
+    const pairNonce = base64Url(24);
+    const expiresAt = new Date(Date.now() + windowMs).toISOString();
+    const window: PairingWindow = { pairingId, pairNonce, expiresAt };
+    this.windows.set(pairNonce, window);
+    return window;
+  }
+
+  consumeWindow(pairNonce: string): PairingWindow | null {
+    const window = this.windows.get(pairNonce);
+    if (!window) return null;
+    this.windows.delete(pairNonce);
+    if (new Date(window.expiresAt).getTime() < Date.now()) {
+      return null;
+    }
+    return window;
+  }
+
+  issuePairToken(deviceId: string, deviceName: string): string {
+    const now = new Date().toISOString();
+    const pairToken = base64Url(32);
+    const nextRecord: PairingRecord = {
+      deviceId,
+      deviceName,
+      tokenHash: hashToken(pairToken),
+      createdAt: now,
+      lastSeenAt: now,
+      revokedAt: null,
+    };
+
+    const existingIndex = this.records.findIndex((record) => record.deviceId === deviceId);
+    if (existingIndex >= 0) {
+      this.records[existingIndex] = nextRecord;
+    } else {
+      this.records.unshift(nextRecord);
+    }
+
+    writeRecords(this.pairingsPath, this.records);
+    return pairToken;
+  }
+
+  validatePairToken(deviceId: string, token: string, touch = true): boolean {
+    const record = this.records.find((entry) => entry.deviceId === deviceId && !entry.revokedAt);
+    if (!record) return false;
+    const tokenDigest = hashToken(token);
+    if (!sameHash(record.tokenHash, tokenDigest)) return false;
+    if (touch) {
+      record.lastSeenAt = new Date().toISOString();
+      writeRecords(this.pairingsPath, this.records);
+    }
+    return true;
+  }
+
+  validateAnyPairToken(token: string, touch = true): PairingRecord | null {
+    const tokenDigest = hashToken(token);
+    const record = this.records.find((entry) => !entry.revokedAt && sameHash(entry.tokenHash, tokenDigest));
+    if (!record) return null;
+    if (touch) {
+      record.lastSeenAt = new Date().toISOString();
+      writeRecords(this.pairingsPath, this.records);
+    }
+    return record;
+  }
+
+  revoke(deviceId: string): boolean {
+    const record = this.records.find((entry) => entry.deviceId === deviceId && !entry.revokedAt);
+    if (!record) return false;
+    record.revokedAt = new Date().toISOString();
+    writeRecords(this.pairingsPath, this.records);
+    return true;
+  }
+
+  reset(): void {
+    this.records = [];
+    this.windows.clear();
+    writeRecords(this.pairingsPath, this.records);
+  }
+}

package/src/paths.ts

@@ -0,0 +1,19 @@
+import { homedir } from 'os';
+import { join } from 'path';
+
+export const VIBELET_DIR = join(homedir(), '.vibelet');
+export const VIBELET_LOG_DIR = join(VIBELET_DIR, 'logs');
+export const VIBELET_DATA_DIR = join(VIBELET_DIR, 'data');
+export const VIBELET_RUNTIME_DIR = join(VIBELET_DIR, 'runtime');
+export const VIBELET_RUNTIME_CURRENT_DIR = join(VIBELET_RUNTIME_DIR, 'current');
+
+export const IDENTITY_PATH = join(VIBELET_DIR, 'identity.json');
+export const PAIRINGS_PATH = join(VIBELET_DIR, 'pairings.json');
+export const PUSH_SUBSCRIPTIONS_PATH = join(VIBELET_DATA_DIR, 'push-subscriptions.json');
+export const SESSION_STORE_PATH = join(VIBELET_DATA_DIR, 'sessions.json');
+export const AUDIT_PATH = join(VIBELET_DATA_DIR, 'audit.jsonl');
+export const VIBELET_UPLOADS_DIR = join(VIBELET_DATA_DIR, 'uploads');
+export const DAEMON_STDOUT_LOG_PATH = join(VIBELET_LOG_DIR, 'daemon.stdout.log');
+export const DAEMON_STDERR_LOG_PATH = join(VIBELET_LOG_DIR, 'daemon.stderr.log');
+export const UPDATE_CHECK_PATH = join(VIBELET_DIR, 'update-check.json');
+export const PAIRING_QR_PNG_PATH = join(VIBELET_DIR, 'pairing-qr.png');

package/src/perf-compare.ts

@@ -0,0 +1,164 @@
+/**
+ * Compare two perf baselines and report regressions.
+ *
+ * Usage:
+ *   tsx src/perf-compare.ts                           # compare perf-baseline.json vs perf-baseline.prev.json
+ *   tsx src/perf-compare.ts <current> <previous>      # compare two specific files
+ *
+ * Exit code:
+ *   0 = no regressions
+ *   1 = regressions detected (>20% slower)
+ */
+
+import { readFileSync, existsSync } from 'fs';
+
+interface PerfEntry {
+  test: string;
+  suite: string;
+  durationMs: number;
+  passed: boolean;
+  metrics: Record<string, number>;
+}
+
+interface PerfBaseline {
+  timestamp: string;
+  nodeVersion: string;
+  platform: string;
+  arch: string;
+  results: PerfEntry[];
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+    totalDurationMs: number;
+  };
+}
+
+const REGRESSION_THRESHOLD = 0.20; // 20% slower = regression
+
+function loadBaseline(path: string): PerfBaseline | null {
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf-8'));
+}
+
+function formatDelta(current: number, previous: number): string {
+  if (previous === 0) return 'N/A';
+  const pct = ((current - previous) / previous) * 100;
+  const sign = pct >= 0 ? '+' : '';
+  return `${sign}${pct.toFixed(1)}%`;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const currentPath = args[0] || 'perf-baseline.json';
+  const previousPath = args[1] || 'perf-baseline.prev.json';
+
+  const current = loadBaseline(currentPath);
+  if (!current) {
+    console.error(`Current baseline not found: ${currentPath}`);
+    console.error('Run "pnpm test:perf:baseline" to generate it.');
+    process.exit(1);
+  }
+
+  const previous = loadBaseline(previousPath);
+  if (!previous) {
+    console.log(`No previous baseline found at ${previousPath}.`);
+    console.log(`Current baseline: ${current.summary.total} tests, ${current.summary.totalDurationMs.toFixed(0)}ms total`);
+    console.log('To compare, save the current baseline as the previous:');
+    console.log(`  cp ${currentPath} ${previousPath}`);
+    process.exit(0);
+  }
+
+  console.log('Performance Comparison');
+  console.log('='.repeat(90));
+  console.log(`Previous: ${previous.timestamp} (Node ${previous.nodeVersion})`);
+  console.log(`Current:  ${current.timestamp} (Node ${current.nodeVersion})`);
+  console.log('');
+
+  // Build lookup for previous results
+  const prevMap = new Map<string, PerfEntry>();
+  for (const entry of previous.results) {
+    prevMap.set(`${entry.suite}::${entry.test}`, entry);
+  }
+
+  const regressions: string[] = [];
+  const improvements: string[] = [];
+  const newTests: string[] = [];
+
+  console.log(`${'Test'.padEnd(55)} ${'Prev'.padStart(10)} ${'Curr'.padStart(10)} ${'Delta'.padStart(10)}`);
+  console.log('-'.repeat(90));
+
+  for (const entry of current.results) {
+    const key = `${entry.suite}::${entry.test}`;
+    const prev = prevMap.get(key);
+
+    // Use the most representative metric for comparison
+    const currentMs = entry.metrics.totalMs ?? entry.metrics.coldMs ?? entry.durationMs;
+
+    if (!prev) {
+      newTests.push(entry.test);
+      const label = truncate(`${entry.suite} > ${entry.test}`, 55);
+      console.log(`${label.padEnd(55)} ${'new'.padStart(10)} ${fmt(currentMs).padStart(10)} ${''.padStart(10)}`);
+      continue;
+    }
+
+    const prevMs = prev.metrics.totalMs ?? prev.metrics.coldMs ?? prev.durationMs;
+    const delta = formatDelta(currentMs, prevMs);
+    const ratio = prevMs > 0 ? (currentMs - prevMs) / prevMs : 0;
+
+    const label = truncate(`${entry.suite} > ${entry.test}`, 55);
+    const marker = ratio > REGRESSION_THRESHOLD ? ' ⚠️' : ratio < -REGRESSION_THRESHOLD ? ' ✨' : '';
+
+    console.log(`${label.padEnd(55)} ${fmt(prevMs).padStart(10)} ${fmt(currentMs).padStart(10)} ${delta.padStart(10)}${marker}`);
+
+    if (ratio > REGRESSION_THRESHOLD) {
+      regressions.push(`${entry.suite} > ${entry.test}: ${fmt(prevMs)} → ${fmt(currentMs)} (${delta})`);
+    } else if (ratio < -REGRESSION_THRESHOLD) {
+      improvements.push(`${entry.suite} > ${entry.test}: ${fmt(prevMs)} → ${fmt(currentMs)} (${delta})`);
+    }
+
+    prevMap.delete(key);
+  }
+
+  // Removed tests
+  const removedTests = [...prevMap.keys()];
+
+  console.log('');
+  console.log('='.repeat(90));
+  console.log(`Summary: ${current.summary.total} tests | ${fmt(current.summary.totalDurationMs)} total`);
+
+  if (improvements.length > 0) {
+    console.log(`\n✨ Improvements (>${REGRESSION_THRESHOLD * 100}% faster): ${improvements.length}`);
+    for (const imp of improvements) console.log(`  ${imp}`);
+  }
+
+  if (newTests.length > 0) {
+    console.log(`\n🆕 New tests: ${newTests.length}`);
+    for (const t of newTests) console.log(`  ${t}`);
+  }
+
+  if (removedTests.length > 0) {
+    console.log(`\n🗑️  Removed tests: ${removedTests.length}`);
+    for (const t of removedTests) console.log(`  ${t}`);
+  }
+
+  if (regressions.length > 0) {
+    console.log(`\n⚠️  Regressions (>${REGRESSION_THRESHOLD * 100}% slower): ${regressions.length}`);
+    for (const reg of regressions) console.log(`  ${reg}`);
+    process.exit(1);
+  } else {
+    console.log('\n✅ No performance regressions detected.');
+  }
+}
+
+function fmt(ms: number): string {
+  if (ms < 1) return `${(ms * 1000).toFixed(0)}µs`;
+  if (ms < 1000) return `${ms.toFixed(2)}ms`;
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+
+function truncate(str: string, maxLen: number): string {
+  return str.length <= maxLen ? str : str.slice(0, maxLen - 3) + '...';
+}
+
+main();

package/src/port-conflict.test.ts

@@ -0,0 +1,45 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { collectPortOccupants, parsePidList } from './port-conflict.js';
+
+test('parsePidList keeps only valid positive numeric pids', () => {
+  assert.deepEqual(
+    parsePidList('123\nabc\n\n0\n456\n123\n'),
+    [123, 456],
+  );
+});
+
+test('collectPortOccupants includes command details when available', () => {
+  const occupants = collectPortOccupants(9876, (file, args) => {
+    if (file === 'lsof') {
+      assert.deepEqual(args, ['-ti', 'tcp:9876']);
+      return '123\n456';
+    }
+    if (file === 'ps' && args[1] === '123') {
+      return 'node dist/index.js';
+    }
+    if (file === 'ps' && args[1] === '456') {
+      return 'python -m http.server';
+    }
+    throw new Error(`Unexpected command: ${file} ${args.join(' ')}`);
+  });
+
+  assert.deepEqual(occupants, [
+    { pid: 123, command: 'node dist/index.js' },
+    { pid: 456, command: 'python -m http.server' },
+  ]);
+});
+
+test('collectPortOccupants falls back to pid-only entries when ps lookup fails', () => {
+  const occupants = collectPortOccupants(9876, (file, args) => {
+    if (file === 'lsof') {
+      return '123';
+    }
+    if (file === 'ps' && args[1] === '123') {
+      throw new Error('ps failed');
+    }
+    throw new Error(`Unexpected command: ${file} ${args.join(' ')}`);
+  });
+
+  assert.deepEqual(occupants, [{ pid: 123 }]);
+});