Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

54.4 KB
Raw Blame
import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { hostname, tmpdir } from 'node:os';
import { resolve } from 'node:path';
import { LOCAL_DIR } from '@inkeep/open-knowledge-core';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { processStartTokenFromOs } from '../../../test-support/os-process-start.test-helper.ts';
import {
  legacyServerLock,
  lockWrittenBeforeProcessStarted,
  lockWrittenByRunningProcess,
  type OwnedProcess,
  ownedProcessHasExited,
  startOwnedProcess,
  stopOwnedProcess,
} from '../../../test-support/owned-process.test-helper.ts';
import { getLogger } from './logger';
import { getMachineId } from './machine-id';
import {
  acquireProcessLock,
  type LockName,
  lockBaseUrl,
  lockFilePath,
  markProcessLockDraining,
  ProcessLockCollisionError,
  type ProcessLockHandle,
  type ProcessLockMetadata,
  readProcessLock,
  readProcessLockDetailed,
  releaseProcessLock,
  updateProcessLockPort,
  waitForProcessLockDrain,
} from './process-lock';
import { PROTOCOL_VERSION, RUNTIME_VERSION } from './version-constants';

const LOCK_NAME: LockName = 'server';

function aliveForeignPid(): number {
  if (process.ppid > 1 && process.ppid !== process.pid) return process.ppid;
  for (let candidate = process.pid + 1; candidate < process.pid + 5000; candidate++) {
    try {
      process.kill(candidate, 0);
      return candidate;
    } catch (err) {
      const code = (err as NodeJS.ErrnoException).code;
      if (code === 'EPERM') return candidate;
    }
  }
  throw new Error('aliveForeignPid: could not find a live foreign pid for the test');
}

let tmpDir: string;
let lockDir: string;
let lockPath: string;

beforeEach(async () => {
  tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-process-lock-test-'));
  lockDir = resolve(tmpDir, '.ok', LOCAL_DIR);
  lockPath = lockFilePath(lockDir, LOCK_NAME);
});

afterEach(async () => {
  await rm(tmpDir, { recursive: true, force: true });
});

describe('acquireProcessLock', () => {
  test('creates lock file at <lockDir>/<lockName>.lock with correct metadata', () => {
    const handle = acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3000, worktreeRoot: '/my/wt' },
    });

    expect(handle.lockPath).toBe(lockPath);
    expect(existsSync(lockPath)).toBe(true);
    expect(lockPath.endsWith('server.lock')).toBe(true);

    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.pid).toBe(process.pid);
    expect(md.hostname).toBe(hostname());
    expect(md.port).toBe(3000);
    expect(md.worktreeRoot).toBe('/my/wt');
    expect(Number.isNaN(Date.parse(md.startedAt))).toBe(false);
  });

  test('creates lockDir when missing', () => {
    expect(existsSync(lockDir)).toBe(false);
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/wt' },
    });
    expect(existsSync(lockDir)).toBe(true);
  });

  test('accepts port=0 sentinel (process starting)', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/wt' },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.port).toBe(0);
  });

  test('replaces stale lock from dead process', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 1, worktreeRoot: '/old' },
    });
    const stale: ProcessLockMetadata = {
      pid: 99999999,
      hostname: hostname(),
      port: 1234,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/old',
    };
    writeFileSync(lockPath, JSON.stringify(stale), 'utf-8');

    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3000, worktreeRoot: '/new' },
    });

    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.pid).toBe(process.pid);
    expect(md.port).toBe(3000);
    expect(md.worktreeRoot).toBe('/new');
  });

  test('records the replaced holder as lockPid, apart from the logger pid binding', () => {
    const stale: ProcessLockMetadata = {
      pid: 99999999,
      hostname: hostname(),
      port: 1234,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/old',
    };
    mkdirSync(lockDir, { recursive: true });
    writeFileSync(lockPath, JSON.stringify(stale), 'utf-8');
    const warn = vi.spyOn(getLogger('process-lock'), 'warn');
    try {
      acquireProcessLock({
        lockName: LOCK_NAME,
        lockDir,
        metadata: { port: 3000, worktreeRoot: '/new' },
      });
      expect(warn).toHaveBeenCalledWith(
        { lockPid: 99999999, host: hostname(), holder: 'gone' },
        expect.stringContaining('Stale lock detected (pid=99999999'),
      );
    } finally {
      warn.mockRestore();
    }
  });

  test('throws ProcessLockCollisionError when lock owner is alive', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/seed' },
    });
    const livePid = aliveForeignPid();
    const live: ProcessLockMetadata = {
      pid: livePid,
      hostname: hostname(),
      port: 9000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/other',
    };
    writeFileSync(lockPath, JSON.stringify(live), 'utf-8');

    const tryAgain = () =>
      acquireProcessLock({
        lockName: LOCK_NAME,
        lockDir,
        metadata: { port: 3000, worktreeRoot: '/me' },
      });
    expect(tryAgain).toThrow(ProcessLockCollisionError);
    try {
      tryAgain();
    } catch (err) {
      expect(err).toBeInstanceOf(ProcessLockCollisionError);
      if (err instanceof ProcessLockCollisionError) {
        expect(err.existing.pid).toBe(livePid);
        expect(err.existing.port).toBe(9000);
        expect(err.lockName).toBe(LOCK_NAME);
        expect(err.lockPath).toBe(lockPath);
        expect(err.message).toContain('already running at port 9000');
        expect(err.message).toContain(LOCK_NAME);
      }
    }
  });

  test('replaces corrupt lock file', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/wt' },
    });
    writeFileSync(lockPath, 'not valid json', 'utf-8');

    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3000, worktreeRoot: '/me' },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.pid).toBe(process.pid);
    expect(md.port).toBe(3000);
  });

  test('is idempotent for same process (refreshes port/startedAt)', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 1111, worktreeRoot: '/wt1' },
    });
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 2222, worktreeRoot: '/wt2' },
    });

    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.pid).toBe(process.pid);
    expect(md.port).toBe(2222);
    expect(md.worktreeRoot).toBe('/wt2');
  });

  test('replaces lock from different hostname', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/tmp' },
    });
    const remote: ProcessLockMetadata = {
      pid: 1,
      hostname: 'some-other-host',
      port: 3000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/remote',
    };
    writeFileSync(lockPath, JSON.stringify(remote), 'utf-8');

    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3001, worktreeRoot: '/me' },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.pid).toBe(process.pid);
    expect(md.port).toBe(3001);
  });

  test('handle.release removes the lock we just acquired', () => {
    const handle = acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3000, worktreeRoot: '/me' },
    });
    expect(existsSync(lockPath)).toBe(true);
    handle.release();
    expect(existsSync(lockPath)).toBe(false);
  });

  test('round-trips kind/parentPid/capabilities when provided', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: {
        port: 4242,
        worktreeRoot: '/wt',
        kind: 'mcp-spawned',
        parentPid: 99999,
        capabilities: ['http', 'ws'],
      },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.kind).toBe('mcp-spawned');
    expect(md.parentPid).toBe(99999);
    expect(md.capabilities).toEqual(['http', 'ws']);
  });

  test('omits kind/parentPid/capabilities when not provided (legacy lock shape)', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 1, worktreeRoot: '/wt' },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.kind).toBeUndefined();
    expect(md.parentPid).toBeUndefined();
    expect(md.capabilities).toBeUndefined();
  });

  test('updatePort preserves new optional fields', () => {
    const handle = acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: {
        port: 0,
        worktreeRoot: '/wt',
        kind: 'interactive',
        parentPid: 12345,
        capabilities: ['http', 'ws'],
      },
    });
    handle.updatePort(8080);
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.port).toBe(8080);
    expect(md.kind).toBe('interactive');
    expect(md.parentPid).toBe(12345);
    expect(md.capabilities).toEqual(['http', 'ws']);
  });

  test('handle.updatePort updates only port, preserving other fields', () => {
    const handle = acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/me' },
    });
    const before: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    handle.updatePort(3000);
    const after: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(after.port).toBe(3000);
    expect(after.pid).toBe(before.pid);
    expect(after.startedAt).toBe(before.startedAt);
    expect(after.worktreeRoot).toBe(before.worktreeRoot);
  });
});

describe('a lock that cannot be removed from a read-only lock directory', () => {
  const canRestrictWrites = process.platform !== 'win32' && process.getuid?.() !== 0;

  function writeLockInReadOnlyDir(text: string): void {
    mkdirSync(lockDir, { recursive: true });
    writeFileSync(lockPath, text, 'utf-8');
    chmodSync(lockDir, 0o500);
  }

  afterEach(() => {
    if (existsSync(lockDir)) chmodSync(lockDir, 0o700);
  });

  const exitedHolderLock = JSON.stringify({
    pid: 99999999,
    hostname: hostname(),
    machineId: getMachineId(),
    port: 1234,
    startedAt: new Date().toISOString(),
    worktreeRoot: '/old',
  });

  test.runIf(canRestrictWrites)(
    'acquireProcessLock names the stale lock and the unlink error instead of reporting contention',
    () => {
      writeLockInReadOnlyDir(exitedHolderLock);

      expect(() =>
        acquireProcessLock({
          lockName: LOCK_NAME,
          lockDir,
          metadata: { port: 0, worktreeRoot: '/new' },
        }),
      ).toThrow(
        `[server-lock] Could not remove the stale lock at ${lockPath}: EACCES: permission denied, unlink '${lockPath}'. Restore file and parent-directory access, then retry.`,
      );
      expect(readFileSync(lockPath, 'utf-8')).toBe(exitedHolderLock);
    },
  );

  test.runIf(canRestrictWrites)(
    'acquireProcessLock names the corrupt lock and the unlink error instead of reporting contention',
    () => {
      writeLockInReadOnlyDir('{ not json');

      expect(() =>
        acquireProcessLock({
          lockName: LOCK_NAME,
          lockDir,
          metadata: { port: 0, worktreeRoot: '/new' },
        }),
      ).toThrow(
        `[server-lock] Could not remove the corrupt lock at ${lockPath}: EACCES: permission denied, unlink '${lockPath}'. Restore file and parent-directory access, then retry.`,
      );
      expect(readFileSync(lockPath, 'utf-8')).toBe('{ not json');
    },
  );

  test.runIf(canRestrictWrites)('readProcessLock still reports no live server', () => {
    writeLockInReadOnlyDir(exitedHolderLock);

    expect(readProcessLock({ lockName: LOCK_NAME, lockDir })).toBeNull();
    expect(readFileSync(lockPath, 'utf-8')).toBe(exitedHolderLock);
  });

  test.runIf(canRestrictWrites)('readProcessLockDetailed still reports the lock stale', () => {
    writeLockInReadOnlyDir(exitedHolderLock);

    expect(readProcessLockDetailed({ lockName: LOCK_NAME, lockDir })).toMatchObject({
      status: 'stale',
      lock: { pid: 99999999 },
    });
    expect(readFileSync(lockPath, 'utf-8')).toBe(exitedHolderLock);
  });
});

describe('a lock acquire cannot read', () => {
  const canRestrictReads = process.platform !== 'win32' && process.getuid?.() !== 0;

  afterEach(() => {
    if (existsSync(lockPath)) chmodSync(lockPath, 0o600);
  });

  test.runIf(canRestrictReads)(
    'acquireProcessLock keeps an unreadable lock naming a live process and reports the read error',
    () => {
      const text = JSON.stringify({
        pid: aliveForeignPid(),
        hostname: hostname(),
        machineId: getMachineId(),
        port: 1234,
        startedAt: new Date().toISOString(),
        worktreeRoot: '/live',
      });
      mkdirSync(lockDir, { recursive: true });
      writeFileSync(lockPath, text, 'utf-8');
      chmodSync(lockPath, 0o000);

      expect(() =>
        acquireProcessLock({
          lockName: LOCK_NAME,
          lockDir,
          metadata: { port: 0, worktreeRoot: '/new' },
        }),
      ).toThrow(
        `[server-lock] Could not read the lock at ${lockPath}: EACCES: permission denied, open '${lockPath}'. Restore file and parent-directory access, then retry.`,
      );
      chmodSync(lockPath, 0o600);
      expect(readFileSync(lockPath, 'utf-8')).toBe(text);
    },
  );
});

describe('one-URL contract (url field + lockBaseUrl)', () => {
  test('acquire omits url by default; updatePort(port, url) writes both in agreement', () => {
    const handle = acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/wt' },
    });
    const before: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(before.url).toBeUndefined();

    handle.updatePort(8080, 'http://127.0.0.1:8080');
    const after: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(after.port).toBe(8080);
    expect(after.url).toBe('http://127.0.0.1:8080');
    expect(new URL(after.url as string).port).toBe(String(after.port));
  });

  test('acquire round-trips an explicit url', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 4242, url: 'http://127.0.0.1:4242', worktreeRoot: '/wt' },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.url).toBe('http://127.0.0.1:4242');
  });

  test('updatePort WITHOUT url drops a previously advertised url (stale-origin guard)', () => {
    const handle = acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/wt' },
    });
    handle.updatePort(8080, 'http://127.0.0.1:8080');
    handle.updatePort(9090);
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.port).toBe(9090);
    expect(md.url).toBeUndefined();
  });

  test('readProcessLockDetailed carries url + capabilities through its reconstruction', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: {
        port: 4242,
        url: 'http://127.0.0.1:4242',
        worktreeRoot: '/wt',
        capabilities: ['http', 'ws', 'ui'],
      },
    });
    const result = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
    expect(result.status).toBe('live');
    if (result.status !== 'live') return;
    expect(result.lock.url).toBe('http://127.0.0.1:4242');
    expect(result.lock.capabilities).toEqual(['http', 'ws', 'ui']);
  });

  test('lockBaseUrl prefers url over port and strips trailing slashes', () => {
    expect(lockBaseUrl({ port: 1111, url: 'http://127.0.0.1:2222/' })).toBe(
      'http://127.0.0.1:2222',
    );
  });

  test('lockBaseUrl falls back to port with localhost by default', () => {
    expect(lockBaseUrl({ port: 3333 })).toBe('http://localhost:3333');
  });

  test('lockBaseUrl honors fallbackHost for numeric-loopback dialers', () => {
    expect(lockBaseUrl({ port: 3333 }, { fallbackHost: '127.0.0.1' })).toBe(
      'http://127.0.0.1:3333',
    );
  });

  test('lockBaseUrl returns null when nothing is dialable (port 0, no url)', () => {
    expect(lockBaseUrl({ port: 0 })).toBeNull();
  });

  test('lockBaseUrl normalizes wildcard fallback hosts to localhost', () => {
    expect(lockBaseUrl({ port: 3000 }, { fallbackHost: '0.0.0.0' })).toBe('http://localhost:3000');
    expect(lockBaseUrl({ port: 3000 }, { fallbackHost: '::' })).toBe('http://localhost:3000');
  });

  test('lockBaseUrl brackets a bare IPv6 fallback host', () => {
    expect(lockBaseUrl({ port: 3000 }, { fallbackHost: '::1' })).toBe('http://[::1]:3000');
  });

  test('lockBaseUrl rejects a corrupt url and falls back to the port', () => {
    expect(lockBaseUrl({ port: 3000, url: 'not a url' })).toBe('http://localhost:3000');
  });

  test('lockBaseUrl rejects a non-loopback url and falls back to the port', () => {
    expect(lockBaseUrl({ port: 3000, url: 'http://evil.example.com:9999' })).toBe(
      'http://localhost:3000',
    );
    expect(lockBaseUrl({ port: 3000, url: 'http://10.0.0.1:9999' })).toBe('http://localhost:3000');
  });

  test('lockBaseUrl rejects a non-http scheme and falls back to the port', () => {
    expect(lockBaseUrl({ port: 3000, url: 'ftp://127.0.0.1:9999' })).toBe('http://localhost:3000');
  });

  test('lockBaseUrl accepts https and IPv6 loopback origins, normalizing stray paths', () => {
    expect(lockBaseUrl({ port: 3000, url: 'https://127.0.0.1:9999' })).toBe(
      'https://127.0.0.1:9999',
    );
    expect(lockBaseUrl({ port: 3000, url: 'http://[::1]:9999' })).toBe('http://[::1]:9999');
    expect(lockBaseUrl({ port: 3000, url: 'http://127.0.0.1:9999/some/path' })).toBe(
      'http://127.0.0.1:9999',
    );
  });

  test('lockBaseUrl rejection of a corrupt url beats port 0 (still null)', () => {
    expect(lockBaseUrl({ port: 0, url: 'not a url' })).toBeNull();
  });

  test('collision error surfaces the advertised url when the holder has one', () => {
    const live: ProcessLockMetadata = {
      pid: aliveForeignPid(),
      hostname: hostname(),
      port: 9000,
      url: 'http://127.0.0.1:9000',
      startedAt: new Date().toISOString(),
      worktreeRoot: '/other',
    };
    mkdirSync(lockDir, { recursive: true });
    writeFileSync(lockPath, JSON.stringify(live), 'utf-8');

    expect(() =>
      acquireProcessLock({
        lockName: LOCK_NAME,
        lockDir,
        metadata: { port: 3000, worktreeRoot: '/me' },
      }),
    ).toThrow(/already running at http:\/\/127\.0\.0\.1:9000/);
  });
});

describe('updateProcessLockPort', () => {
  test('no-op when lock file is missing', () => {
    updateProcessLockPort({ lockName: LOCK_NAME, lockDir, port: 3000 });
    expect(existsSync(lockPath)).toBe(false);
  });

  test('refuses to overwrite a lock owned by a different pid', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/me' },
    });
    const foreign: ProcessLockMetadata = {
      pid: 1,
      hostname: hostname(),
      port: 1234,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/other',
    };
    writeFileSync(lockPath, JSON.stringify(foreign), 'utf-8');

    updateProcessLockPort({ lockName: LOCK_NAME, lockDir, port: 9999 });

    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.pid).toBe(1);
    expect(md.port).toBe(1234);
  });

  test('ignores corrupt lock file', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/wt' },
    });
    writeFileSync(lockPath, 'garbage', 'utf-8');
    updateProcessLockPort({ lockName: LOCK_NAME, lockDir, port: 3000 });
    expect(readFileSync(lockPath, 'utf-8')).toBe('garbage');
  });
});

describe('readProcessLock', () => {
  test('returns metadata when live lock exists on this host', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3000, worktreeRoot: '/me' },
    });
    const md = readProcessLock({ lockName: LOCK_NAME, lockDir });
    expect(md).not.toBeNull();
    expect(md?.pid).toBe(process.pid);
    expect(md?.port).toBe(3000);
  });

  test('returns null + unlinks stale lock (dead pid)', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/wt' },
    });
    const stale: ProcessLockMetadata = {
      pid: 99999999,
      hostname: hostname(),
      port: 3000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/old',
    };
    writeFileSync(lockPath, JSON.stringify(stale), 'utf-8');

    expect(readProcessLock({ lockName: LOCK_NAME, lockDir })).toBeNull();
    expect(existsSync(lockPath)).toBe(false);
  });

  test('returns null for cross-host lock (does not unlink)', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/wt' },
    });
    const remote: ProcessLockMetadata = {
      pid: 1,
      hostname: 'other-host',
      port: 3000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/remote',
    };
    writeFileSync(lockPath, JSON.stringify(remote), 'utf-8');

    expect(readProcessLock({ lockName: LOCK_NAME, lockDir })).toBeNull();
    expect(existsSync(lockPath)).toBe(true);
  });

  test('returns null when lock is missing', () => {
    expect(readProcessLock({ lockName: LOCK_NAME, lockDir })).toBeNull();
  });

  test('returns null for corrupt lock', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/wt' },
    });
    writeFileSync(lockPath, 'garbage', 'utf-8');
    expect(readProcessLock({ lockName: LOCK_NAME, lockDir })).toBeNull();
  });

  test('reads are scoped to (lockName, lockDir) — a sibling lockDir reads null', () => {
    acquireProcessLock({
      lockName: 'server',
      lockDir,
      metadata: { port: 1111, worktreeRoot: '/wt' },
    });
    expect(readProcessLock({ lockName: 'server', lockDir })?.port).toBe(1111);
    expect(readProcessLock({ lockName: 'server', lockDir: `${lockDir}/other` })).toBeNull();
  });
});

describe('releaseProcessLock', () => {
  test('removes lock owned by this process', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3000, worktreeRoot: '/me' },
    });
    expect(existsSync(lockPath)).toBe(true);
    releaseProcessLock({ lockName: LOCK_NAME, lockDir });
    expect(existsSync(lockPath)).toBe(false);
  });

  test('is safe to call multiple times', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3000, worktreeRoot: '/me' },
    });
    releaseProcessLock({ lockName: LOCK_NAME, lockDir });
    releaseProcessLock({ lockName: LOCK_NAME, lockDir });
    expect(existsSync(lockPath)).toBe(false);
  });

  test('no-op if lock does not exist', () => {
    expect(() => releaseProcessLock({ lockName: LOCK_NAME, lockDir })).not.toThrow();
    expect(existsSync(lockPath)).toBe(false);
  });

  test('refuses to remove a lock owned by a different pid', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/me' },
    });
    const foreign: ProcessLockMetadata = {
      pid: 1,
      hostname: hostname(),
      port: 9000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/other',
    };
    writeFileSync(lockPath, JSON.stringify(foreign), 'utf-8');

    releaseProcessLock({ lockName: LOCK_NAME, lockDir });

    expect(existsSync(lockPath)).toBe(true);
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.pid).toBe(1);
  });

  test('double acquire then single release keeps lock file in place', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 1111, worktreeRoot: '/wt1' },
    });
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 2222, worktreeRoot: '/wt2' },
    });
    expect(existsSync(lockPath)).toBe(true);

    releaseProcessLock({ lockName: LOCK_NAME, lockDir });

    expect(existsSync(lockPath)).toBe(true);
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.pid).toBe(process.pid);
    expect(md.port).toBe(2222);
  });

  test('double acquire then double release removes lock file', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 1111, worktreeRoot: '/wt1' },
    });
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 2222, worktreeRoot: '/wt2' },
    });
    releaseProcessLock({ lockName: LOCK_NAME, lockDir });
    expect(existsSync(lockPath)).toBe(true);
    releaseProcessLock({ lockName: LOCK_NAME, lockDir });
    expect(existsSync(lockPath)).toBe(false);
  });

  test('release without prior acquire is a no-op (untracked release path)', () => {
    expect(existsSync(lockPath)).toBe(false);
    releaseProcessLock({ lockName: LOCK_NAME, lockDir });
    expect(existsSync(lockPath)).toBe(false);
  });

  test('refcount drains correctly across an acquire-release-acquire-release cycle', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 1111, worktreeRoot: '/wt1' },
    });
    releaseProcessLock({ lockName: LOCK_NAME, lockDir });
    expect(existsSync(lockPath)).toBe(false);

    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 2222, worktreeRoot: '/wt2' },
    });
    expect(existsSync(lockPath)).toBe(true);
    releaseProcessLock({ lockName: LOCK_NAME, lockDir });
    expect(existsSync(lockPath)).toBe(false);
  });
});

describe('version metadata (protocolVersion + runtimeVersion)', () => {
  test('acquireProcessLock auto-populates protocolVersion + runtimeVersion from constants', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3000, worktreeRoot: '/me' },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.protocolVersion).toBe(PROTOCOL_VERSION);
    expect(md.runtimeVersion).toBe(RUNTIME_VERSION);
    expect(typeof md.runtimeVersion).toBe('string');
    expect(md.runtimeVersion?.length).toBeGreaterThan(0);
  });

  test('acquireProcessLock honors explicit overrides on the metadata input', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: {
        port: 3000,
        worktreeRoot: '/me',
        protocolVersion: 99,
        runtimeVersion: 'test-1.2.3',
      },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.protocolVersion).toBe(99);
    expect(md.runtimeVersion).toBe('test-1.2.3');
  });

  test('updateProcessLockPort preserves the version fields', () => {
    const handle = acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: {
        port: 0,
        worktreeRoot: '/me',
        protocolVersion: 7,
        runtimeVersion: 'preserve-test',
      },
    });
    handle.updatePort(4000);
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.port).toBe(4000);
    expect(md.protocolVersion).toBe(7);
    expect(md.runtimeVersion).toBe('preserve-test');
  });
});

describe('channel metadata (one writer per project across channels)', () => {
  afterEach(() => {
    vi.unstubAllEnvs();
  });

  test('the lock names the channel that wrote it, and both readers return it', () => {
    vi.stubEnv('OK_CHANNEL', 'beta');
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3000, worktreeRoot: '/me' },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.channel).toBe('beta');
    expect(readProcessLock({ lockName: LOCK_NAME, lockDir })?.channel).toBe('beta');
    const detailed = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
    expect(detailed.status === 'live' ? detailed.lock.channel : null).toBe('beta');
  });

  test('a dev build records the dev channel, not Stable', () => {
    vi.stubEnv('OK_CHANNEL', 'dev');
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3000, worktreeRoot: '/me' },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.channel).toBe('dev');
  });

  test('a lock with no channel reads back without one, and a channel this build does not know is kept', () => {
    mkdirSync(lockDir, { recursive: true });
    for (const channel of [undefined, 'cloud']) {
      writeFileSync(
        lockPath,
        JSON.stringify({
          pid: process.pid,
          hostname: hostname(),
          port: 3000,
          startedAt: new Date().toISOString(),
          worktreeRoot: '/me',
          machineId: getMachineId(),
          protocolVersion: PROTOCOL_VERSION,
          runtimeVersion: RUNTIME_VERSION,
          ...(channel === undefined ? {} : { channel }),
        }),
      );
      const detailed = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
      expect(detailed.status).toBe('live');
      expect(detailed.status === 'live' ? detailed.lock.channel : 'unread').toBe(channel);
    }
  });

  test('both readers treat a channel that is not a non-empty string as absent', () => {
    mkdirSync(lockDir, { recursive: true });
    for (const channel of ['', 42, null]) {
      writeFileSync(
        lockPath,
        JSON.stringify({
          pid: process.pid,
          hostname: hostname(),
          port: 3000,
          startedAt: new Date().toISOString(),
          worktreeRoot: '/me',
          machineId: getMachineId(),
          protocolVersion: PROTOCOL_VERSION,
          runtimeVersion: RUNTIME_VERSION,
          channel,
        }),
      );
      const plain = readProcessLock({ lockName: LOCK_NAME, lockDir });
      const detailed = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
      expect({
        plain: plain === null ? 'unread' : plain.channel,
        detailed: detailed.status === 'live' ? detailed.lock.channel : 'unread',
      }).toEqual({ plain: undefined, detailed: undefined });
    }
  });

  test('an unsupported OK_CHANNEL still acquires the lock, without a channel', () => {
    vi.stubEnv('OK_CHANNEL', 'cloud');
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3000, worktreeRoot: '/me' },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.pid).toBe(process.pid);
    expect('channel' in md).toBe(false);
  });
});

describe('readProcessLockDetailed', () => {
  test('returns absent when no lock file exists', () => {
    const result = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
    expect(result.status).toBe('absent');
  });

  test('returns live with the parsed lock when fields are complete', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 5000, worktreeRoot: '/me' },
    });
    const result = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
    expect(result.status).toBe('live');
    if (result.status !== 'live') throw new Error('expected live');
    expect(result.lock.port).toBe(5000);
    expect(result.lock.protocolVersion).toBe(PROTOCOL_VERSION);
    expect(result.lock.runtimeVersion).toBe(RUNTIME_VERSION);
  });

  test('returns incompatible.missing-fields for a live lock missing protocolVersion', () => {
    const versionless = {
      pid: aliveForeignPid(),
      hostname: hostname(),
      port: 6000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/legacy',
    };
    mkdirSync(lockDir, { recursive: true });
    writeFileSync(lockPath, JSON.stringify(versionless), 'utf-8');

    const result = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
    expect(result.status).toBe('incompatible');
    if (result.status !== 'incompatible') throw new Error('expected incompatible');
    expect(result.reason).toBe('missing-fields');
  });

  test('returns incompatible.missing-fields for a live lock missing runtimeVersion only', () => {
    const partial = {
      pid: aliveForeignPid(),
      hostname: hostname(),
      port: 6500,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/legacy',
      protocolVersion: 1,
    };
    mkdirSync(lockDir, { recursive: true });
    writeFileSync(lockPath, JSON.stringify(partial), 'utf-8');

    const result = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
    expect(result.status).toBe('incompatible');
  });

  test('returns incompatible.corrupt for unparseable JSON', () => {
    mkdirSync(lockDir, { recursive: true });
    writeFileSync(lockPath, '{not json', 'utf-8');
    const result = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
    expect(result.status).toBe('incompatible');
    if (result.status !== 'incompatible') throw new Error('expected incompatible');
    expect(result.reason).toBe('corrupt');
  });

  test('returns incompatible.corrupt for shape violation (missing pid)', () => {
    mkdirSync(lockDir, { recursive: true });
    writeFileSync(lockPath, JSON.stringify({ port: 1234 }), 'utf-8');
    const result = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
    expect(result.status).toBe('incompatible');
    if (result.status !== 'incompatible') throw new Error('expected incompatible');
    expect(result.reason).toBe('corrupt');
  });

  test('returns stale + cleans up on dead pid', () => {
    const stale: ProcessLockMetadata = {
      pid: 99999999,
      hostname: hostname(),
      port: 7000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/old',
      protocolVersion: 1,
      runtimeVersion: '0.1.0',
    };
    mkdirSync(lockDir, { recursive: true });
    writeFileSync(lockPath, JSON.stringify(stale), 'utf-8');

    const result = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
    expect(result.status).toBe('stale');
    expect(existsSync(lockPath)).toBe(false);
  });

  test('returns stale (without cleanup) on cross-host lock', () => {
    const remote: ProcessLockMetadata = {
      pid: aliveForeignPid(),
      hostname: 'some-other-host',
      port: 7100,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/remote',
      protocolVersion: 1,
      runtimeVersion: '0.1.0',
    };
    mkdirSync(lockDir, { recursive: true });
    writeFileSync(lockPath, JSON.stringify(remote), 'utf-8');

    const result = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
    expect(result.status).toBe('stale');
    expect(existsSync(lockPath)).toBe(true);
  });
});

describe('lock-pid security validation', () => {
  const HOSTILE_PIDS: ReadonlyArray<{ pid: unknown; label: string }> = [
    { pid: 0, label: 'PID 0 (process group)' },
    { pid: 1, label: 'PID 1 (init/launchd)' },
    { pid: -42, label: 'negative PID (process group syntax)' },
    { pid: 1.5, label: 'non-integer PID' },
    { pid: Number.NaN, label: 'NaN PID' },
    { pid: Number.POSITIVE_INFINITY, label: 'Infinity PID' },
    { pid: 0x80000000, label: 'PID above 2^31-1 (corrupt or tampered)' },
    { pid: '12345', label: 'string PID (not a number)' },
    { pid: null, label: 'null PID' },
  ];

  for (const { pid, label } of HOSTILE_PIDS) {
    test(`acquireProcessLock replaces hostile lock with ${label}`, () => {
      acquireProcessLock({
        lockName: LOCK_NAME,
        lockDir,
        metadata: { port: 0, worktreeRoot: '/seed' },
      });
      const hostile = {
        pid,
        hostname: hostname(),
        port: 9000,
        startedAt: new Date().toISOString(),
        worktreeRoot: '/attacker',
      };
      writeFileSync(lockPath, JSON.stringify(hostile), 'utf-8');

      acquireProcessLock({
        lockName: LOCK_NAME,
        lockDir,
        metadata: { port: 4242, worktreeRoot: '/me' },
      });
      const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
      expect(md.pid).toBe(process.pid);
      expect(md.port).toBe(4242);
    });

    test(`readProcessLock returns null for hostile lock with ${label}`, () => {
      const hostile = {
        pid,
        hostname: hostname(),
        port: 9000,
        startedAt: new Date().toISOString(),
        worktreeRoot: '/attacker',
      };
      mkdirSync(lockDir, { recursive: true });
      writeFileSync(lockPath, JSON.stringify(hostile), 'utf-8');

      expect(readProcessLock({ lockName: LOCK_NAME, lockDir })).toBeNull();
    });

    test(`readProcessLockDetailed returns incompatible.corrupt for hostile lock with ${label}`, () => {
      const hostile = {
        pid,
        hostname: hostname(),
        port: 9000,
        startedAt: new Date().toISOString(),
        worktreeRoot: '/attacker',
        protocolVersion: 1,
        runtimeVersion: '1.0.0',
      };
      mkdirSync(lockDir, { recursive: true });
      writeFileSync(lockPath, JSON.stringify(hostile), 'utf-8');

      const result = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
      expect(result.status).toBe('incompatible');
      if (result.status !== 'incompatible') throw new Error('expected incompatible');
      expect(result.reason).toBe('corrupt');
    });
  }

  test('isValidLockPid rejects hostile sentinels', async () => {
    const { isValidLockPid } = await import('./process-alive.ts');
    expect(isValidLockPid(0)).toBe(false);
    expect(isValidLockPid(1)).toBe(false);
    expect(isValidLockPid(-1)).toBe(false);
    expect(isValidLockPid(1.5)).toBe(false);
    expect(isValidLockPid(Number.NaN)).toBe(false);
    expect(isValidLockPid(Number.POSITIVE_INFINITY)).toBe(false);
    expect(isValidLockPid(0x80000000)).toBe(false);
    expect(isValidLockPid('123')).toBe(false);
    expect(isValidLockPid(null)).toBe(false);
    expect(isValidLockPid(process.pid)).toBe(true);
    expect(isValidLockPid(process.ppid > 1 ? process.ppid : 12345)).toBe(true);
  });
});

describe('machine identity + fail-closed liveness (duplicate-server regression)', () => {
  test('stamps machineId into the lock on acquire', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3000, worktreeRoot: '/wt' },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.machineId).toBe(getMachineId());
  });

  test('collides on a live local pid even when hostname AND machineId look foreign (hostname-flap regression)', () => {
    const livePid = aliveForeignPid();
    mkdirSync(lockDir, { recursive: true });
    const flapped: ProcessLockMetadata = {
      pid: livePid,
      hostname: `${hostname()}-before-rename`,
      port: 9000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/other',
      machineId: 'some-other-machine-id',
    };
    writeFileSync(lockPath, JSON.stringify(flapped), 'utf-8');

    expect(() =>
      acquireProcessLock({
        lockName: LOCK_NAME,
        lockDir,
        metadata: { port: 3000, worktreeRoot: '/me' },
      }),
    ).toThrow(ProcessLockCollisionError);
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.pid).toBe(livePid);
  });

  test('replaces a foreign-machine lock whose pid is dead locally', () => {
    mkdirSync(lockDir, { recursive: true });
    const remote: ProcessLockMetadata = {
      pid: 99999999,
      hostname: 'some-other-host',
      port: 9000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/remote',
      machineId: 'some-other-machine-id',
    };
    writeFileSync(lockPath, JSON.stringify(remote), 'utf-8');

    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 3001, worktreeRoot: '/me' },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.pid).toBe(process.pid);
  });

  test('readProcessLock returns null for a foreign-machine lock WITHOUT unlinking it', () => {
    mkdirSync(lockDir, { recursive: true });
    const livePid = aliveForeignPid();
    const foreign: ProcessLockMetadata = {
      pid: livePid,
      hostname: hostname(),
      port: 9000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/other',
      machineId: 'some-other-machine-id',
    };
    writeFileSync(lockPath, JSON.stringify(foreign), 'utf-8');

    expect(readProcessLock({ lockName: LOCK_NAME, lockDir })).toBeNull();
    expect(existsSync(lockPath)).toBe(true);
  });

  test('same-machine lock with a drifted hostname still reads as ours via machineId', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 4000, worktreeRoot: '/wt' },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    md.hostname = `${hostname()}-renamed-since`;
    writeFileSync(lockPath, JSON.stringify(md), 'utf-8');

    const read = readProcessLock({ lockName: LOCK_NAME, lockDir });
    expect(read?.pid).toBe(process.pid);
    expect(read?.port).toBe(4000);
  });
});

describe('draining lifecycle (lock held until process exit)', () => {
  test('markProcessLockDraining sets the flag and preserves every other field', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 5000, worktreeRoot: '/wt' },
    });
    markProcessLockDraining({ lockName: LOCK_NAME, lockDir });

    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.draining).toBe(true);
    expect(md.pid).toBe(process.pid);
    expect(md.port).toBe(5000);
    expect(md.worktreeRoot).toBe('/wt');
    expect(md.machineId).toBe(getMachineId());
  });

  test('markProcessLockDraining refuses locks we do not own', () => {
    mkdirSync(lockDir, { recursive: true });
    const livePid = aliveForeignPid();
    const foreign: ProcessLockMetadata = {
      pid: livePid,
      hostname: hostname(),
      port: 9000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/other',
    };
    writeFileSync(lockPath, JSON.stringify(foreign), 'utf-8');
    markProcessLockDraining({ lockName: LOCK_NAME, lockDir });

    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.draining).toBeUndefined();
  });

  test('markProcessLockDraining no-ops while another in-process acquire is active (Vite restart)', () => {
    acquireProcessLock({ lockName: LOCK_NAME, lockDir, metadata: { port: 1, worktreeRoot: '/a' } });
    acquireProcessLock({ lockName: LOCK_NAME, lockDir, metadata: { port: 2, worktreeRoot: '/b' } });

    markProcessLockDraining({ lockName: LOCK_NAME, lockDir });
    let md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.draining).toBeUndefined();

    releaseProcessLock({ lockName: LOCK_NAME, lockDir });
    markProcessLockDraining({ lockName: LOCK_NAME, lockDir });
    md = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.draining).toBe(true);
  });

  test('release with deferUnlinkToExit keeps the file on disk, marked draining', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 5000, worktreeRoot: '/wt' },
    });
    releaseProcessLock({ lockName: LOCK_NAME, lockDir, deferUnlinkToExit: true });

    expect(existsSync(lockPath)).toBe(true);
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.pid).toBe(process.pid);
    expect(md.draining).toBe(true);
  });

  test('plain release still unlinks immediately (error-path contract)', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 5000, worktreeRoot: '/wt' },
    });
    releaseProcessLock({ lockName: LOCK_NAME, lockDir });
    expect(existsSync(lockPath)).toBe(false);
  });

  test('same-pid re-acquire after a deferred release clears the draining flag', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 5000, worktreeRoot: '/wt' },
    });
    releaseProcessLock({ lockName: LOCK_NAME, lockDir, deferUnlinkToExit: true });

    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 6000, worktreeRoot: '/wt' },
    });
    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.draining).toBeUndefined();
    expect(md.port).toBe(6000);
    releaseProcessLock({ lockName: LOCK_NAME, lockDir });
  });

  test('updateProcessLockPort preserves the draining flag', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/wt' },
    });
    markProcessLockDraining({ lockName: LOCK_NAME, lockDir });
    updateProcessLockPort({ lockName: LOCK_NAME, lockDir, port: 7777 });

    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.port).toBe(7777);
    expect(md.draining).toBe(true);
  });

  test('readProcessLockDetailed propagates draining and machineId (desktop attach guard depends on both)', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 8100, worktreeRoot: '/wt' },
    });
    markProcessLockDraining({ lockName: LOCK_NAME, lockDir });

    const result = readProcessLockDetailed({ lockName: LOCK_NAME, lockDir });
    expect(result.status).toBe('live');
    if (result.status === 'live') {
      expect(result.lock.draining).toBe(true);
      expect(result.lock.machineId).toBe(getMachineId());
    }
  });

  test('readProcessLock surfaces the draining flag on a live same-machine holder', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 8000, worktreeRoot: '/wt' },
    });
    markProcessLockDraining({ lockName: LOCK_NAME, lockDir });

    const read = readProcessLock({ lockName: LOCK_NAME, lockDir });
    expect(read?.draining).toBe(true);
    expect(read?.port).toBe(8000);
  });
});

describe('waitForProcessLockDrain', () => {
  const immediateSleep = async () => {};

  test('returns no-drain when no lock exists', async () => {
    const outcome = await waitForProcessLockDrain({
      lockName: LOCK_NAME,
      lockDir,
      readLock: () => null,
      sleep: immediateSleep,
    });
    expect(outcome).toBe('no-drain');
  });

  test('returns no-drain for a live non-draining holder', async () => {
    const live: ProcessLockMetadata = {
      pid: process.pid,
      hostname: hostname(),
      port: 9000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/wt',
    };
    const outcome = await waitForProcessLockDrain({
      lockName: LOCK_NAME,
      lockDir,
      readLock: () => live,
      sleep: immediateSleep,
    });
    expect(outcome).toBe('no-drain');
  });

  test('returns released once the draining holder exits', async () => {
    const draining: ProcessLockMetadata = {
      pid: process.pid,
      hostname: hostname(),
      port: 9000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/wt',
      draining: true,
    };
    let reads = 0;
    const outcome = await waitForProcessLockDrain({
      lockName: LOCK_NAME,
      lockDir,
      readLock: () => {
        reads += 1;
        return reads >= 4 ? null : draining;
      },
      sleep: immediateSleep,
    });
    expect(outcome).toBe('released');
  });

  test('returns no-drain when a live non-draining successor replaces the draining holder mid-wait', async () => {
    const draining: ProcessLockMetadata = {
      pid: process.pid,
      hostname: hostname(),
      port: 9000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/wt',
      draining: true,
    };
    const successor: ProcessLockMetadata = {
      ...draining,
      pid: process.pid,
      draining: undefined,
      port: 9100,
    };
    let reads = 0;
    const outcome = await waitForProcessLockDrain({
      lockName: LOCK_NAME,
      lockDir,
      readLock: () => {
        reads += 1;
        return reads >= 3 ? successor : draining;
      },
      sleep: immediateSleep,
    });
    expect(outcome).toBe('no-drain');
  });

  test('returns timeout when the draining holder outlives the budget', async () => {
    const draining: ProcessLockMetadata = {
      pid: process.pid,
      hostname: hostname(),
      port: 9000,
      startedAt: new Date().toISOString(),
      worktreeRoot: '/wt',
      draining: true,
    };
    const outcome = await waitForProcessLockDrain({
      lockName: LOCK_NAME,
      lockDir,
      timeoutMs: 20,
      pollIntervalMs: 1,
      readLock: () => draining,
    });
    expect(outcome).toBe('timeout');
  });
});

describe('a lock whose pid is still running', () => {
  const owned: OwnedProcess[] = [];

  afterEach(async () => {
    for (const holder of owned.splice(0)) await stopOwnedProcess(holder);
  });

  async function startHolder(): Promise<OwnedProcess> {
    const holder = await startOwnedProcess();
    owned.push(holder);
    return holder;
  }

  function writeLegacyLock(holder: OwnedProcess, startedAt: string): void {
    mkdirSync(lockDir, { recursive: true });
    writeFileSync(
      lockPath,
      JSON.stringify(
        legacyServerLock({
          pid: holder.pid,
          startedAt,
          machineId: getMachineId(),
          worktreeRoot: '/previous/boot',
        }),
      ),
      'utf-8',
    );
  }

  function acquireForNewServer(): ProcessLockHandle {
    return acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/new/boot', kind: 'interactive' },
    });
  }

  describe('by a process that started after the lock was written (pid reused)', () => {
    test('acquireProcessLock replaces the lock instead of colliding', async () => {
      const holder = await startHolder();
      writeLegacyLock(holder, lockWrittenBeforeProcessStarted(holder));

      expect(acquireForNewServer).not.toThrow();
      const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
      expect(md.pid).toBe(process.pid);
      expect(md.worktreeRoot).toBe('/new/boot');
      expect(ownedProcessHasExited(holder)).toBe(false);
    });

    test('readProcessLock reports no live server', async () => {
      const holder = await startHolder();
      writeLegacyLock(holder, lockWrittenBeforeProcessStarted(holder));

      expect(readProcessLock({ lockName: LOCK_NAME, lockDir })).toBeNull();
    });

    test('readProcessLockDetailed reports the lock stale', async () => {
      const holder = await startHolder();
      writeLegacyLock(holder, lockWrittenBeforeProcessStarted(holder));

      expect(readProcessLockDetailed({ lockName: LOCK_NAME, lockDir })).toMatchObject({
        status: 'stale',
        lock: { pid: holder.pid },
      });
    });
  });

  describe('by the process that wrote it', () => {
    test('acquireProcessLock still collides', async () => {
      const holder = await startHolder();
      writeLegacyLock(holder, lockWrittenByRunningProcess(holder));

      expect(acquireForNewServer).toThrow(ProcessLockCollisionError);
      const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
      expect(md.pid).toBe(holder.pid);
    });

    test('readProcessLock returns the live lock', async () => {
      const holder = await startHolder();
      writeLegacyLock(holder, lockWrittenByRunningProcess(holder));

      expect(readProcessLock({ lockName: LOCK_NAME, lockDir })).toMatchObject({ pid: holder.pid });
    });

    test('readProcessLockDetailed reports the lock live', async () => {
      const holder = await startHolder();
      writeLegacyLock(holder, lockWrittenByRunningProcess(holder));

      expect(readProcessLockDetailed({ lockName: LOCK_NAME, lockDir })).toMatchObject({
        status: 'live',
        lock: { pid: holder.pid },
      });
    });
  });

  describe('by a process that does not match the recorded process start', () => {
    const BOOT_ID_PATH = '/proc/sys/kernel/random/boot_id';
    const PREVIOUS_BOOT_ID = '00000000-0000-4000-8000-000000000000';

    function processStartOfPreviousWriter(holder: OwnedProcess): Record<string, number | string> {
      if (process.platform === 'linux') {
        expect(existsSync(BOOT_ID_PATH)).toBe(true);
        const bootId = readFileSync(BOOT_ID_PATH, 'utf-8').trim();
        expect(bootId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
        expect(bootId).not.toBe(PREVIOUS_BOOT_ID);
        return { bootId: PREVIOUS_BOOT_ID, startTicks: 4_096 };
      }
      return { startedAtMs: Date.parse(lockWrittenBeforeProcessStarted(holder)) };
    }

    function writeLockRecordingPreviousWriter(holder: OwnedProcess): void {
      mkdirSync(lockDir, { recursive: true });
      writeFileSync(
        lockPath,
        JSON.stringify({
          ...legacyServerLock({
            pid: holder.pid,
            startedAt: lockWrittenByRunningProcess(holder),
            machineId: getMachineId(),
            worktreeRoot: '/previous/boot',
          }),
          processStart: processStartOfPreviousWriter(holder),
        }),
        'utf-8',
      );
    }

    test('acquireProcessLock replaces the lock instead of colliding', async () => {
      const holder = await startHolder();
      writeLockRecordingPreviousWriter(holder);

      expect(acquireForNewServer).not.toThrow();
      const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
      expect(md.pid).toBe(process.pid);
      expect(md.worktreeRoot).toBe('/new/boot');
      expect(ownedProcessHasExited(holder)).toBe(false);
    });

    test('readProcessLock reports no live server', async () => {
      const holder = await startHolder();
      writeLockRecordingPreviousWriter(holder);

      expect(readProcessLock({ lockName: LOCK_NAME, lockDir })).toBeNull();
    });

    test('readProcessLockDetailed reports the lock stale', async () => {
      const holder = await startHolder();
      writeLockRecordingPreviousWriter(holder);

      expect(readProcessLockDetailed({ lockName: LOCK_NAME, lockDir })).toMatchObject({
        status: 'stale',
        lock: { pid: holder.pid },
      });
    });
  });
});

describe('the process start a lock records for its writer', () => {
  test('acquireProcessLock records the start the operating system holds for the writer', () => {
    acquireProcessLock({
      lockName: LOCK_NAME,
      lockDir,
      metadata: { port: 0, worktreeRoot: '/wt' },
    });

    const md: ProcessLockMetadata = JSON.parse(readFileSync(lockPath, 'utf-8'));
    expect(md.processStart).toEqual(processStartTokenFromOs(process.pid));
  });
});