Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

40.2 KB
Raw Blame
import { type ExecFileSyncOptionsWithStringEncoding, execFileSync } from 'node:child_process';
import { hostname } from 'node:os';
import { afterEach, describe, expect, test, vi } from 'vitest';
import {
  processStartTokenFromOs,
  readProcessStartFromOs,
} from '../../../test-support/os-process-start.test-helper.ts';
import {
  lockWrittenBeforeProcessStarted,
  lockWrittenByRunningProcess,
  type OwnedProcess,
  startOwnedProcess,
  stopOwnedProcess,
} from '../../../test-support/owned-process.test-helper.ts';
import { getLogger } from './logger.ts';
import { getMachineId } from './machine-id.ts';
import {
  assessLockHolder,
  classifyLockHolder,
  createRecentProcessStartReader,
  isLockFromThisMachine,
  type LockHolderIdentity,
  type LockHolderVerdict,
  type ProcessStart,
  parseProcessStartToken,
  processStartToken,
  readBootStartedAtMs,
  readProcessStart,
  readPsProcessStart,
  registerNativeProcessStartReader,
  type UnverifiedLockHolderCause,
} from './process-identity.ts';

const WRITTEN_AT = '2026-10-01T12:00:00.000Z';
const WRITTEN_AT_MS = Date.parse(WRITTEN_AT);
const THIRTY_SIX_HOURS_MS = 36 * 60 * 60 * 1000;
const HOLDER_PID = 4242;
const THIRTY_SIX_HOURS_BEFORE_WRITTEN_AT = new Date(
  WRITTEN_AT_MS - THIRTY_SIX_HOURS_MS,
).toISOString();

function lockWrittenAt(extra: Partial<LockHolderIdentity> = {}): LockHolderIdentity {
  return { pid: HOLDER_PID, startedAt: WRITTEN_AT, ...extra };
}

function creationStart(offsetFromWrittenMs: number): ProcessStart {
  return { startedAtMs: WRITTEN_AT_MS + offsetFromWrittenMs, clock: 'creation' };
}

function bootedAt(offsetFromWrittenMs: number): () => number {
  return () => WRITTEN_AT_MS + offsetFromWrittenMs;
}

const BOOTED_BEFORE_LOCK = bootedAt(-THIRTY_SIX_HOURS_MS);

function bootDerivedStart(
  offsetFromWrittenMs: number,
  pair?: { bootId: string; startTicks: number },
): ProcessStart {
  return { startedAtMs: WRITTEN_AT_MS + offsetFromWrittenMs, clock: 'boot-derived', ...pair };
}

interface ComparatorRow {
  name: string;
  lock: LockHolderIdentity;
  live: ProcessStart | null;
  expected: Exclude<LockHolderVerdict, 'gone'>;
  cause?: UnverifiedLockHolderCause;
  refuseHolderStartedAfterLock?: boolean;
}

const BOOT_PAIR_TOKEN = { bootId: 'boot-a', startTicks: 5_000 };

const comparatorRows: ComparatorRow[] = [
  {
    name: 'no reading of the holder is unverified',
    lock: lockWrittenAt(),
    live: null,
    expected: 'unverified',
    cause: 'process-start-unreadable',
  },
  {
    name: 'a boot pair from another boot is replaced',
    lock: lockWrittenAt({ processStart: BOOT_PAIR_TOKEN }),
    live: bootDerivedStart(0, { bootId: 'boot-b', startTicks: 5_000 }),
    expected: 'replaced',
  },
  {
    name: 'equal ticks on the same boot are the writer even when startedAt is 36 h old',
    lock: lockWrittenAt({ processStart: BOOT_PAIR_TOKEN }),
    live: bootDerivedStart(THIRTY_SIX_HOURS_MS, { bootId: 'boot-a', startTicks: 5_000 }),
    expected: 'writer',
  },
  {
    name: 'later ticks on the same boot are replaced even when startedAt looks current',
    lock: lockWrittenAt({ processStart: BOOT_PAIR_TOKEN }),
    live: bootDerivedStart(0, { bootId: 'boot-a', startTicks: 5_001 }),
    expected: 'replaced',
  },
  {
    name: 'earlier ticks on the same boot are unverified',
    lock: lockWrittenAt({ processStart: BOOT_PAIR_TOKEN }),
    live: bootDerivedStart(0, { bootId: 'boot-a', startTicks: 4_999 }),
    expected: 'unverified',
    cause: 'process-start-mismatch',
  },
  {
    name: 'a creation start 1000 ms after the token is the writer even when startedAt is 36 h old',
    lock: lockWrittenAt({
      startedAt: THIRTY_SIX_HOURS_BEFORE_WRITTEN_AT,
      processStart: { startedAtMs: WRITTEN_AT_MS },
    }),
    live: creationStart(1_000),
    expected: 'writer',
  },
  {
    name: 'a creation start 1000 ms before the token is the writer even when startedAt is 36 h old',
    lock: lockWrittenAt({
      startedAt: THIRTY_SIX_HOURS_BEFORE_WRITTEN_AT,
      processStart: { startedAtMs: WRITTEN_AT_MS },
    }),
    live: creationStart(-1_000),
    expected: 'writer',
  },
  {
    name: 'a creation start 1001 ms after the token is replaced even when startedAt looks current',
    lock: lockWrittenAt({ processStart: { startedAtMs: WRITTEN_AT_MS - 2_000 } }),
    live: creationStart(-2_000 + 1_001),
    expected: 'replaced',
  },
  {
    name: 'a creation start 1001 ms before the token is unverified',
    lock: lockWrittenAt({ processStart: { startedAtMs: WRITTEN_AT_MS } }),
    live: creationStart(-1_001),
    expected: 'unverified',
    cause: 'process-start-mismatch',
  },
  {
    name: 'a legacy lock whose creation-clock holder started 9999 ms later is the writer',
    lock: lockWrittenAt(),
    live: creationStart(9_999),
    expected: 'writer',
  },
  {
    name: 'a legacy lock whose creation-clock holder started 10000 ms later is the writer',
    lock: lockWrittenAt(),
    live: creationStart(10_000),
    expected: 'writer',
  },
  {
    name: 'a legacy lock whose creation-clock holder started 10001 ms later is replaced',
    lock: lockWrittenAt(),
    live: creationStart(10_001),
    expected: 'replaced',
  },
  {
    name: 'a legacy lock whose boot-derived holder started 299999 ms later is the writer',
    lock: lockWrittenAt(),
    live: bootDerivedStart(299_999),
    expected: 'writer',
  },
  {
    name: 'a legacy lock whose boot-derived holder started 300001 ms later is replaced',
    lock: lockWrittenAt(),
    live: bootDerivedStart(300_001),
    expected: 'replaced',
  },
  {
    name: 'a legacy lock whose holder started before it was written is the writer',
    lock: lockWrittenAt(),
    live: creationStart(-60_000),
    expected: 'writer',
  },
  {
    name: 'refusing later holders, a legacy lock whose creation-clock holder started 1 ms later is unverified',
    lock: lockWrittenAt(),
    live: creationStart(1),
    expected: 'unverified',
    cause: 'process-started-after-lock',
    refuseHolderStartedAfterLock: true,
  },
  {
    name: 'refusing later holders, a legacy lock whose creation-clock holder started 9999 ms later is unverified',
    lock: lockWrittenAt(),
    live: creationStart(9_999),
    expected: 'unverified',
    cause: 'process-started-after-lock',
    refuseHolderStartedAfterLock: true,
  },
  {
    name: 'refusing later holders, a legacy lock whose creation-clock holder started 10001 ms later is replaced',
    lock: lockWrittenAt(),
    live: creationStart(10_001),
    expected: 'replaced',
    refuseHolderStartedAfterLock: true,
  },
  {
    name: 'refusing later holders, a legacy lock whose creation-clock holder started as it was written is the writer',
    lock: lockWrittenAt(),
    live: creationStart(0),
    expected: 'writer',
    refuseHolderStartedAfterLock: true,
  },
  {
    name: 'refusing later holders, a legacy lock whose boot-derived holder started 1 ms later is unverified',
    lock: lockWrittenAt(),
    live: bootDerivedStart(1),
    expected: 'unverified',
    cause: 'process-started-after-lock',
    refuseHolderStartedAfterLock: true,
  },
  {
    name: 'refusing later holders, a legacy lock whose boot-derived holder started 299999 ms later is unverified',
    lock: lockWrittenAt(),
    live: bootDerivedStart(299_999),
    expected: 'unverified',
    cause: 'process-started-after-lock',
    refuseHolderStartedAfterLock: true,
  },
  {
    name: 'refusing later holders, a legacy lock whose boot-derived holder started 300001 ms later is replaced',
    lock: lockWrittenAt(),
    live: bootDerivedStart(300_001),
    expected: 'replaced',
    refuseHolderStartedAfterLock: true,
  },
  {
    name: 'refusing later holders, a legacy lock whose boot-derived holder started before it was written is the writer',
    lock: lockWrittenAt(),
    live: bootDerivedStart(-60_000),
    expected: 'writer',
    refuseHolderStartedAfterLock: true,
  },
  {
    name: 'refusing later holders, a lock with a creation token is judged by the token alone even when its holder started after startedAt',
    lock: lockWrittenAt({ processStart: { startedAtMs: WRITTEN_AT_MS } }),
    live: creationStart(1_000),
    expected: 'writer',
    refuseHolderStartedAfterLock: true,
  },
  {
    name: 'a legacy lock with an unparseable startedAt is unverified',
    lock: lockWrittenAt({ startedAt: 'not a date' }),
    live: creationStart(THIRTY_SIX_HOURS_MS),
    expected: 'unverified',
    cause: 'process-start-incomparable',
  },
  {
    name: 'a legacy lock without startedAt is unverified',
    lock: { pid: HOLDER_PID },
    live: creationStart(THIRTY_SIX_HOURS_MS),
    expected: 'unverified',
    cause: 'process-start-incomparable',
  },
  {
    name: 'a millisecond token read against a boot-derived clock is unverified',
    lock: lockWrittenAt({ processStart: { startedAtMs: WRITTEN_AT_MS - THIRTY_SIX_HOURS_MS } }),
    live: bootDerivedStart(1_000),
    expected: 'unverified',
    cause: 'process-start-incomparable',
  },
  {
    name: 'a boot pair token read against a creation reading is unverified',
    lock: lockWrittenAt({ processStart: BOOT_PAIR_TOKEN }),
    live: creationStart(1_000),
    expected: 'unverified',
    cause: 'process-start-incomparable',
  },
  {
    name: 'a boot pair token read against a boot-derived reading without a boot id is unverified',
    lock: lockWrittenAt({ processStart: BOOT_PAIR_TOKEN }),
    live: bootDerivedStart(1_000),
    expected: 'unverified',
    cause: 'process-start-incomparable',
  },
  {
    name: 'a malformed token falls back to startedAt',
    lock: lockWrittenAt({ processStart: { startedAtMs: 'soon' } }),
    live: creationStart(10_001),
    expected: 'replaced',
  },
  {
    name: 'a token carrying both shapes is read as its boot pair',
    lock: lockWrittenAt({
      processStart: { startedAtMs: WRITTEN_AT_MS + 10_001, ...BOOT_PAIR_TOKEN },
    }),
    live: creationStart(10_001),
    expected: 'unverified',
    cause: 'process-start-incomparable',
  },
];

describe('assessLockHolder', () => {
  test.each(comparatorRows)(
    '$name, naming the comparison that decided it',
    ({ lock, live, expected, cause, refuseHolderStartedAfterLock }) => {
      expect(
        assessLockHolder(
          { machineId: getMachineId(), ...lock },
          {
            isAlive: () => true,
            readProcessStart: () => live,
            readBootInstant: BOOTED_BEFORE_LOCK,
            sameMachine: true,
            refuseHolderStartedAfterLock,
          },
        ),
      ).toEqual(expected === 'unverified' ? { verdict: expected, cause } : { verdict: expected });
    },
  );

  test('names another machine for its lock when the local start cannot be read either', () => {
    expect(
      assessLockHolder(lockWrittenAt({ machineId: 'another-machine-0000' }), {
        isAlive: () => true,
        readProcessStart: () => null,
      }),
    ).toEqual({ verdict: 'unverified', cause: 'foreign-host' });
  });

  test('names another machine for its lock when the recorded start contradicts the holder', () => {
    expect(
      assessLockHolder(
        lockWrittenAt({
          machineId: 'another-machine-0000',
          processStart: { startedAtMs: WRITTEN_AT_MS },
        }),
        { isAlive: () => true, readProcessStart: () => creationStart(-60_000) },
      ),
    ).toEqual({ verdict: 'unverified', cause: 'foreign-host' });
  });

  test('does not read the start of a holder named by a lock that records no owner', () => {
    const readPids: number[] = [];
    expect(
      assessLockHolder(lockWrittenAt(), {
        isAlive: () => true,
        readProcessStart: (pid) => {
          readPids.push(pid);
          return creationStart(-60_000);
        },
      }),
    ).toEqual({ verdict: 'unverified', cause: 'unverified-owner' });
    expect(readPids).toEqual([]);
  });

  test('a lock naming only another hostname with a startedAt in the future vouches for no holder', () => {
    expect(
      assessLockHolder(
        { pid: HOLDER_PID, hostname: 'elsewhere.invalid', startedAt: '2099-01-01T00:00:00.000Z' },
        {
          isAlive: () => true,
          readProcessStart: () => ({ startedAtMs: Date.now() - 60_000, clock: 'creation' }),
        },
      ),
    ).toEqual({ verdict: 'unverified', cause: 'foreign-host' });
  });

  test('a lock from this machine with a startedAt ahead of the clock is refused for that reason', () => {
    expect(
      assessLockHolder(
        { pid: HOLDER_PID, machineId: getMachineId(), startedAt: '2099-01-01T00:00:00.000Z' },
        {
          isAlive: () => true,
          readProcessStart: () => ({ startedAtMs: Date.now() - 60_000, clock: 'creation' }),
        },
      ),
    ).toEqual({ verdict: 'unverified', cause: 'recorded-start-in-future' });
  });

  test('a lock naming only this hostname cannot confirm an earlier-started holder', () => {
    expect(
      assessLockHolder(lockWrittenAt({ hostname: hostname() }), {
        isAlive: () => true,
        readProcessStart: () => creationStart(-60_000),
      }),
    ).toEqual({ verdict: 'unverified', cause: 'writer-identity-unrecorded' });
  });

  test('a lock whose format has no machine ID confirms an earlier-started holder on this hostname', () => {
    expect(
      assessLockHolder(lockWrittenAt({ hostname: hostname() }), {
        isAlive: () => true,
        readProcessStart: () => creationStart(-60_000),
        sameMachine: true,
        formatRecordsMachineId: false,
      }),
    ).toEqual({ verdict: 'writer' });
  });

  test('a lock naming only this hostname whose pid now belongs to a later process is replaced', () => {
    expect(
      assessLockHolder(lockWrittenAt({ hostname: hostname() }), {
        isAlive: () => true,
        readProcessStart: () => creationStart(THIRTY_SIX_HOURS_MS),
      }),
    ).toEqual({ verdict: 'replaced' });
  });

  test('a holder that exits while its start is read is gone', () => {
    const liveness = [true, false];
    expect(
      assessLockHolder(lockWrittenAt({ machineId: getMachineId() }), {
        isAlive: () => liveness.shift() ?? false,
        readProcessStart: () => null,
      }),
    ).toEqual({ verdict: 'gone' });
  });

  test('an unreadable holder of a lock written before this machine booted is replaced', () => {
    expect(
      assessLockHolder(lockWrittenAt({ machineId: getMachineId() }), {
        isAlive: () => true,
        readProcessStart: () => null,
        platform: 'win32',
        readBootInstant: bootedAt(THIRTY_SIX_HOURS_MS),
      }),
    ).toEqual({ verdict: 'replaced' });
  });

  test('an unreadable holder of a lock naming only this hostname written before boot is replaced', () => {
    expect(
      assessLockHolder(lockWrittenAt({ hostname: hostname() }), {
        isAlive: () => true,
        readProcessStart: () => null,
        platform: 'win32',
        readBootInstant: bootedAt(THIRTY_SIX_HOURS_MS),
      }),
    ).toEqual({ verdict: 'replaced' });
  });

  test('a lock whose recorded process start is after boot is not dated by an earlier startedAt', () => {
    expect(
      assessLockHolder(
        lockWrittenAt({
          machineId: getMachineId(),
          processStart: { startedAtMs: WRITTEN_AT_MS + 2 * THIRTY_SIX_HOURS_MS },
        }),
        {
          isAlive: () => true,
          readProcessStart: () => null,
          platform: 'win32',
          readBootInstant: bootedAt(THIRTY_SIX_HOURS_MS),
        },
      ),
    ).toEqual({ verdict: 'unverified', cause: 'process-start-unreadable' });
  });

  test('an unreadable holder of a lock written minutes before boot stays unverified', () => {
    expect(
      assessLockHolder(lockWrittenAt({ machineId: getMachineId() }), {
        isAlive: () => true,
        readProcessStart: () => null,
        platform: 'win32',
        readBootInstant: bootedAt(60_000),
      }),
    ).toEqual({ verdict: 'unverified', cause: 'process-start-unreadable' });
  });

  test('an unreadable holder of a lock that records no write time stays unverified', () => {
    expect(
      assessLockHolder(
        { pid: HOLDER_PID, machineId: getMachineId() },
        {
          isAlive: () => true,
          readProcessStart: () => null,
          platform: 'win32',
          readBootInstant: bootedAt(THIRTY_SIX_HOURS_MS),
        },
      ),
    ).toEqual({ verdict: 'unverified', cause: 'process-start-unreadable' });
  });

  test('an unreadable holder stays unverified when the boot time cannot be read', () => {
    expect(
      assessLockHolder(lockWrittenAt({ machineId: getMachineId() }), {
        isAlive: () => true,
        readProcessStart: () => null,
        platform: 'win32',
        readBootInstant: () => null,
      }),
    ).toEqual({ verdict: 'unverified', cause: 'process-start-unreadable' });
  });

  test('a lock from another machine written before this machine booted still names that machine', () => {
    expect(
      assessLockHolder(lockWrittenAt({ machineId: 'another-machine-0000' }), {
        isAlive: () => true,
        readProcessStart: () => null,
        platform: 'win32',
        readBootInstant: bootedAt(THIRTY_SIX_HOURS_MS),
      }),
    ).toEqual({ verdict: 'unverified', cause: 'foreign-host' });
  });

  test.each(['linux', 'darwin'] as const)(
    'on %s an unreadable holder of a lock written before this machine booted stays unverified',
    (platform) => {
      expect(
        assessLockHolder(lockWrittenAt({ machineId: getMachineId() }), {
          isAlive: () => true,
          readProcessStart: () => null,
          platform,
          readBootInstant: bootedAt(THIRTY_SIX_HOURS_MS),
        }),
      ).toEqual({ verdict: 'unverified', cause: 'process-start-unreadable' });
    },
  );
});

describe('readBootStartedAtMs', () => {
  test('dates the boot by subtracting uptime from now', () => {
    expect(readBootStartedAtMs(1_000_000_000, () => 120.4)).toBe(1_000_000_000 - 120_400);
  });

  test('an unusable uptime fails open to null rather than throwing', () => {
    expect(readBootStartedAtMs(1_000_000_000, () => 0)).toBeNull();
    expect(readBootStartedAtMs(1_000_000_000, () => Number.NaN)).toBeNull();
    expect(
      readBootStartedAtMs(1_000_000_000, () => {
        throw new Error('uptime unavailable');
      }),
    ).toBeNull();
  });

  test('the live boot instant precedes now', () => {
    const now = Date.now();
    const bootStartedAtMs = readBootStartedAtMs(now);
    expect(bootStartedAtMs).not.toBeNull();
    expect(bootStartedAtMs).toBeLessThan(now);
  });
});

describe('classifyLockHolder', () => {
  test('a holder that is no longer running is gone without reading its start', () => {
    const readPids: number[] = [];
    const verdict = classifyLockHolder(lockWrittenAt({ machineId: getMachineId() }), {
      isAlive: () => false,
      readProcessStart: (pid) => {
        readPids.push(pid);
        return creationStart(0);
      },
    });
    expect({ verdict, readPids }).toEqual({ verdict: 'gone', readPids: [] });
  });

  test('a running holder whose start cannot be read is unverified', () => {
    expect(
      classifyLockHolder(lockWrittenAt({ machineId: getMachineId() }), {
        isAlive: () => true,
        readProcessStart: () => null,
        readBootInstant: BOOTED_BEFORE_LOCK,
      }),
    ).toBe('unverified');
  });

  test('a later-started holder of a lock from this machine is replaced', () => {
    expect(
      classifyLockHolder(lockWrittenAt({ machineId: getMachineId() }), {
        isAlive: () => true,
        readProcessStart: () => creationStart(THIRTY_SIX_HOURS_MS),
      }),
    ).toBe('replaced');
  });

  test('a later-started holder of a lock from another machine is unverified', () => {
    expect(
      classifyLockHolder(lockWrittenAt({ machineId: 'another-machine-0000' }), {
        isAlive: () => true,
        readProcessStart: () => creationStart(THIRTY_SIX_HOURS_MS),
      }),
    ).toBe('unverified');
  });

  test('a caller that has established the lock is local keeps the replaced verdict', () => {
    expect(
      classifyLockHolder(lockWrittenAt({ machineId: 'another-machine-0000' }), {
        isAlive: () => true,
        readProcessStart: () => creationStart(THIRTY_SIX_HOURS_MS),
        sameMachine: true,
      }),
    ).toBe('replaced');
  });

  test('a caller that has established the lock is foreign downgrades replaced to unverified', () => {
    expect(
      classifyLockHolder(lockWrittenAt({ machineId: getMachineId() }), {
        isAlive: () => true,
        readProcessStart: () => creationStart(THIRTY_SIX_HOURS_MS),
        sameMachine: false,
      }),
    ).toBe('unverified');
  });

  test('an earlier-started holder of a lock from another machine id is unverified without a recorded start', () => {
    expect(
      classifyLockHolder(lockWrittenAt({ machineId: 'another-machine-0000' }), {
        isAlive: () => true,
        readProcessStart: () => creationStart(-60_000),
      }),
    ).toBe('unverified');
  });

  test('a holder matching the recorded start is the writer of a lock from another machine id', () => {
    expect(
      classifyLockHolder(
        lockWrittenAt({
          machineId: 'another-machine-0000',
          processStart: { startedAtMs: WRITTEN_AT_MS - 60_000 },
        }),
        { isAlive: () => true, readProcessStart: () => creationStart(-60_000) },
      ),
    ).toBe('writer');
  });

  test('an earlier-started holder of a lock naming only another hostname is unverified', () => {
    expect(
      classifyLockHolder(lockWrittenAt({ hostname: 'elsewhere.invalid' }), {
        isAlive: () => true,
        readProcessStart: () => creationStart(-60_000),
      }),
    ).toBe('unverified');
  });

  test('an earlier-started holder of a lock that records no owner is unverified', () => {
    expect(
      classifyLockHolder(lockWrittenAt(), {
        isAlive: () => true,
        readProcessStart: () => creationStart(-60_000),
      }),
    ).toBe('unverified');
  });

  test('a reader that has established the lock is local judges an ownerless lock by its start', () => {
    expect(
      classifyLockHolder(lockWrittenAt(), {
        isAlive: () => true,
        readProcessStart: () => creationStart(THIRTY_SIX_HOURS_MS),
        sameMachine: true,
      }),
    ).toBe('replaced');
  });
});

describe('createRecentProcessStartReader', () => {
  function recentReader(readings: Array<ProcessStart | null>, readTakesMs = 0) {
    let nowMs = 0;
    const readPids: number[] = [];
    const read = createRecentProcessStartReader({
      maxAgeMs: 1_000,
      read: (pid) => {
        readPids.push(pid);
        nowMs += readTakesMs;
        return readings.shift() ?? null;
      },
      now: () => nowMs,
    });
    return {
      read,
      readPids,
      advance: (ms: number) => {
        nowMs += ms;
      },
    };
  }

  test('answers a repeated read of a pid inside the maximum age without reading it again', () => {
    const recent = recentReader([creationStart(0), creationStart(THIRTY_SIX_HOURS_MS)]);
    expect(recent.read(HOLDER_PID)).toEqual(creationStart(0));
    recent.advance(999);
    expect(recent.read(HOLDER_PID)).toEqual(creationStart(0));
    expect(recent.readPids).toEqual([HOLDER_PID]);
  });

  test('reads the pid again once its reading reaches the maximum age', () => {
    const recent = recentReader([creationStart(0), creationStart(THIRTY_SIX_HOURS_MS)]);
    recent.read(HOLDER_PID);
    recent.advance(1_000);
    expect(recent.read(HOLDER_PID)).toEqual(creationStart(THIRTY_SIX_HOURS_MS));
    expect(recent.readPids).toEqual([HOLDER_PID, HOLDER_PID]);
  });

  test('does not retry a failed read inside the maximum age', () => {
    const recent = recentReader([null, creationStart(0)]);
    expect(recent.read(HOLDER_PID)).toBeNull();
    recent.advance(500);
    expect(recent.read(HOLDER_PID)).toBeNull();
    expect(recent.readPids).toEqual([HOLDER_PID]);
  });

  test('counts the age of a reading from when its read returned, however long the read took', () => {
    const recent = recentReader([creationStart(0), creationStart(THIRTY_SIX_HOURS_MS)], 1_500);
    expect(recent.read(HOLDER_PID)).toEqual(creationStart(0));
    recent.advance(999);
    expect(recent.read(HOLDER_PID)).toEqual(creationStart(0));
    expect(recent.readPids).toEqual([HOLDER_PID]);
  });

  test('holds a failed reading for as long as a timed-out ps read can block', () => {
    const recent = recentReader([null, creationStart(0)], 5_000);
    expect(recent.read(HOLDER_PID)).toBeNull();
    recent.advance(4_999);
    expect(recent.read(HOLDER_PID)).toBeNull();
    expect(recent.readPids).toEqual([HOLDER_PID]);
    recent.advance(1);
    expect(recent.read(HOLDER_PID)).toEqual(creationStart(0));
    expect(recent.readPids).toEqual([HOLDER_PID, HOLDER_PID]);
  });

  test('reads each pid on its own', () => {
    const recent = recentReader([creationStart(0), creationStart(1)]);
    recent.read(HOLDER_PID);
    expect(recent.read(HOLDER_PID + 1)).toEqual(creationStart(1));
    expect(recent.readPids).toEqual([HOLDER_PID, HOLDER_PID + 1]);
  });
});

describe('isLockFromThisMachine', () => {
  test('a matching machine id is this machine even when the hostname differs', () => {
    expect(
      isLockFromThisMachine({ machineId: getMachineId(), hostname: 'elsewhere.invalid' }),
    ).toBe(true);
  });

  test('a different machine id is another machine even when the hostname matches', () => {
    expect(isLockFromThisMachine({ machineId: 'another-machine-0000', hostname: hostname() })).toBe(
      false,
    );
  });

  test('without a machine id a matching hostname is this machine', () => {
    expect(isLockFromThisMachine({ hostname: hostname() })).toBe(true);
  });

  test('without a machine id a different hostname is another machine', () => {
    expect(isLockFromThisMachine({ hostname: 'elsewhere.invalid' })).toBe(false);
  });
});

describe('processStartToken', () => {
  test('a reading with a boot pair records the pair', () => {
    expect(
      processStartToken({
        startedAtMs: WRITTEN_AT_MS,
        clock: 'boot-derived',
        startTicks: 7_311,
        bootId: 'boot-a',
      }),
    ).toEqual({ bootId: 'boot-a', startTicks: 7_311 });
  });

  test('a creation reading records its milliseconds', () => {
    expect(processStartToken(creationStart(0))).toEqual({ startedAtMs: WRITTEN_AT_MS });
  });

  test('a boot-derived reading without a boot id records nothing', () => {
    expect(
      processStartToken({ startedAtMs: WRITTEN_AT_MS, clock: 'boot-derived', startTicks: 7_311 }),
    ).toBeUndefined();
    expect(processStartToken(bootDerivedStart(0))).toBeUndefined();
  });

  test('no reading records nothing', () => {
    expect(processStartToken(null)).toBeUndefined();
  });
});

describe('parseProcessStartToken', () => {
  test.each([
    { name: 'a boot pair', value: { bootId: 'boot-a', startTicks: 7_311 } },
    { name: 'a boot pair at tick zero', value: { bootId: 'boot-a', startTicks: 0 } },
    { name: 'a creation time', value: { startedAtMs: WRITTEN_AT_MS } },
    { name: 'a creation time at the epoch', value: { startedAtMs: 0 } },
  ])('accepts $name', ({ value }) => {
    expect(parseProcessStartToken(value)).toEqual(value);
  });

  test.each([
    { name: 'null', value: null },
    { name: 'a string', value: '{"startedAtMs":1}' },
    { name: 'a number', value: WRITTEN_AT_MS },
    { name: 'an array', value: [WRITTEN_AT_MS] },
    { name: 'an empty object', value: {} },
    { name: 'an empty boot id', value: { bootId: '', startTicks: 1 } },
    { name: 'an overlong boot id', value: { bootId: 'b'.repeat(65), startTicks: 1 } },
    { name: 'a non-string boot id', value: { bootId: 42, startTicks: 1 } },
    { name: 'negative ticks', value: { bootId: 'boot-a', startTicks: -1 } },
    { name: 'fractional ticks', value: { bootId: 'boot-a', startTicks: 1.5 } },
    { name: 'a boot id without ticks', value: { bootId: 'boot-a' } },
    { name: 'ticks without a boot id', value: { startTicks: 1 } },
    { name: 'negative milliseconds', value: { startedAtMs: -1 } },
    { name: 'unsafe milliseconds', value: { startedAtMs: 2 ** 53 } },
    { name: 'string milliseconds', value: { startedAtMs: String(WRITTEN_AT_MS) } },
    { name: 'only unknown fields', value: { pid: 1, creationTicks: 9 } },
  ])('rejects $name', ({ value }) => {
    expect(parseProcessStartToken(value)).toBeUndefined();
  });

  test.each([
    {
      name: 'a creation time with an extra field',
      value: { startedAtMs: WRITTEN_AT_MS, pid: 1 },
      token: { startedAtMs: WRITTEN_AT_MS },
    },
    {
      name: 'a boot pair with an extra field',
      value: { bootId: 'boot-a', startTicks: 7_311, namespace: 'pid:[4026531836]' },
      token: { bootId: 'boot-a', startTicks: 7_311 },
    },
    {
      name: 'both shapes at once, preferring the boot pair',
      value: { startedAtMs: WRITTEN_AT_MS, bootId: 'boot-a', startTicks: 1 },
      token: { bootId: 'boot-a', startTicks: 1 },
    },
    {
      name: 'both shapes with an invalid boot pair, falling back to the creation time',
      value: { startedAtMs: WRITTEN_AT_MS, bootId: '', startTicks: 1 },
      token: { startedAtMs: WRITTEN_AT_MS },
    },
  ])('reads $name and drops what it does not know', ({ value, token }) => {
    expect(parseProcessStartToken(value)).toEqual(token);
  });

  test('every token a writer records parses back to itself', () => {
    const readings: ProcessStart[] = [
      creationStart(0),
      { startedAtMs: WRITTEN_AT_MS, clock: 'boot-derived', startTicks: 0, bootId: 'boot-a' },
      {
        startedAtMs: WRITTEN_AT_MS,
        clock: 'boot-derived',
        startTicks: 7_311,
        bootId: 'b'.repeat(64),
      },
    ];
    for (const reading of readings) {
      const token = processStartToken(reading);
      expect(token).toBeDefined();
      expect(parseProcessStartToken(token)).toEqual(token);
    }
  });
});

const FIXTURE_PID = 4242;
const FIXTURE_START_TICKS = 98_765_432;
const FIXTURE_BTIME_SECONDS = 1_760_000_000;
const FIXTURE_BOOT_ID = '6f1c2a3b-0000-4000-8000-0123456789ab';
const FIXTURE_STAT_WITH_AWKWARD_COMM = `${FIXTURE_PID} (w) x (y) z) S 1 ${FIXTURE_PID} ${FIXTURE_PID} 0 -1 4194560 120 0 0 0 3 1 0 0 20 0 1 0 ${FIXTURE_START_TICKS} 1060864 220 18446744073709551615 1 1 0 0 0 0 0 0 0 0 0 0 17 3 0 0 0 0 0\n`;
const FIXTURE_PROC_STAT = `cpu  10 0 10 1000 0 0 0 0 0 0\ncpu0 10 0 10 1000 0 0 0 0 0 0\nintr 1 0\nctxt 123\nbtime ${FIXTURE_BTIME_SECONDS}\nprocesses 99\nprocs_running 1\n`;

function procFiles(files: Record<string, string>): (path: string) => string {
  return (path) => {
    const content = files[path];
    if (content === undefined) {
      throw Object.assign(new Error(`ENOENT: no such file or directory, open '${path}'`), {
        code: 'ENOENT',
      });
    }
    return content;
  };
}

function linuxProcFor(pid: number, overrides: Record<string, string | undefined> = {}) {
  const files: Record<string, string> = {
    [`/proc/${pid}/stat`]: FIXTURE_STAT_WITH_AWKWARD_COMM,
    '/proc/stat': FIXTURE_PROC_STAT,
    '/proc/sys/kernel/random/boot_id': `${FIXTURE_BOOT_ID}\n`,
  };
  for (const [path, content] of Object.entries(overrides)) {
    if (content === undefined) delete files[path];
    else files[path] = content;
  }
  return procFiles(files);
}

describe('readProcessStart on Linux', () => {
  test('reads start ticks after the last parenthesis of a comm containing spaces and parentheses', () => {
    expect(
      readProcessStart(FIXTURE_PID, { platform: 'linux', readFile: linuxProcFor(FIXTURE_PID) }),
    ).toEqual({
      startedAtMs: FIXTURE_BTIME_SECONDS * 1000 + FIXTURE_START_TICKS * 10,
      clock: 'boot-derived',
      startTicks: FIXTURE_START_TICKS,
      bootId: FIXTURE_BOOT_ID,
    });
  });

  test('a host whose boot id cannot be read yields a reading that records no token', () => {
    const start = readProcessStart(FIXTURE_PID, {
      platform: 'linux',
      readFile: linuxProcFor(FIXTURE_PID, { '/proc/sys/kernel/random/boot_id': undefined }),
    });
    expect(start).toEqual({
      startedAtMs: FIXTURE_BTIME_SECONDS * 1000 + FIXTURE_START_TICKS * 10,
      clock: 'boot-derived',
      startTicks: FIXTURE_START_TICKS,
    });
    expect(processStartToken(start)).toBeUndefined();
  });

  test('a pid without a /proc entry has no reading', () => {
    expect(
      readProcessStart(FIXTURE_PID + 1, {
        platform: 'linux',
        readFile: linuxProcFor(FIXTURE_PID),
      }),
    ).toBeNull();
  });

  test('a truncated stat line has no reading', () => {
    expect(
      readProcessStart(FIXTURE_PID, {
        platform: 'linux',
        readFile: linuxProcFor(FIXTURE_PID, {
          [`/proc/${FIXTURE_PID}/stat`]: `${FIXTURE_PID} (w) x (y) z) S 1 ${FIXTURE_PID}\n`,
        }),
      }),
    ).toBeNull();
  });

  test('a /proc/stat without btime has no reading', () => {
    expect(
      readProcessStart(FIXTURE_PID, {
        platform: 'linux',
        readFile: linuxProcFor(FIXTURE_PID, { '/proc/stat': 'cpu  10 0 10 1000\nctxt 123\n' }),
      }),
    ).toBeNull();
  });

  test.each([0, -1, 1.5, Number.NaN, 0x1_0000_0000])(
    'pid %s is not a process id and has no reading',
    (pid) => {
      const readFile = (path: string) =>
        path.endsWith('/stat') && path !== '/proc/stat'
          ? FIXTURE_STAT_WITH_AWKWARD_COMM
          : linuxProcFor(FIXTURE_PID)(path);
      expect(readProcessStart(pid, { platform: 'linux', readFile })).toBeNull();
    },
  );
});

describe('the registered native process-start reader', () => {
  const unregisters: Array<() => void> = [];

  afterEach(() => {
    for (const unregister of unregisters.splice(0)) unregister();
  });

  function register(read: (pid: number) => number | null): void {
    unregisters.push(registerNativeProcessStartReader(read));
  }

  test('is the Windows reading for the pid it is asked about', () => {
    const askedPids: number[] = [];
    register((pid) => {
      askedPids.push(pid);
      return 1_700_000_000_123;
    });
    expect(readProcessStart(FIXTURE_PID, { platform: 'win32' })).toEqual({
      startedAtMs: 1_700_000_000_123,
      clock: 'creation',
    });
    expect(askedPids).toEqual([FIXTURE_PID]);
  });

  test('is not consulted on Linux or on an unsupported platform', () => {
    const askedPids: number[] = [];
    register((pid) => {
      askedPids.push(pid);
      return 1_700_000_000_123;
    });
    expect(
      readProcessStart(FIXTURE_PID, { platform: 'linux', readFile: linuxProcFor(FIXTURE_PID) }),
    ).toMatchObject({ clock: 'boot-derived', startTicks: FIXTURE_START_TICKS });
    expect(readProcessStart(FIXTURE_PID, { platform: 'aix' })).toBeNull();
    expect(askedPids).toEqual([]);
  });

  test('leaves Windows without a reading once unregistered', () => {
    const unregister = registerNativeProcessStartReader(() => 1_700_000_000_123);
    expect(readProcessStart(FIXTURE_PID, { platform: 'win32' })).not.toBeNull();
    unregister();
    expect(readProcessStart(FIXTURE_PID, { platform: 'win32' })).toBeNull();
  });

  test('a reader that cannot identify the process leaves Windows without a reading', () => {
    register(() => null);
    expect(readProcessStart(FIXTURE_PID, { platform: 'win32' })).toBeNull();
  });

  test('gives way to a reader passed for the read', () => {
    register(() => 1_700_000_000_123);
    expect(
      readProcessStart(FIXTURE_PID, { platform: 'win32', readNative: () => 1_700_000_000_456 }),
    ).toEqual({ startedAtMs: 1_700_000_000_456, clock: 'creation' });
  });

  test('warns once while Windows has no reader to ask', () => {
    registerNativeProcessStartReader(() => null)();
    const warn = vi.spyOn(getLogger('process-identity'), 'warn');
    try {
      expect(readProcessStart(FIXTURE_PID, { platform: 'win32' })).toBeNull();
      expect(readProcessStart(FIXTURE_PID + 1, { platform: 'win32' })).toBeNull();
      expect(warn).toHaveBeenCalledTimes(1);
      expect(warn).toHaveBeenCalledWith(
        { event: 'process-start-reader-missing' },
        expect.any(String),
      );
    } finally {
      warn.mockRestore();
    }
  });

  test('warns again when a withdrawn reader leaves Windows without one', () => {
    registerNativeProcessStartReader(() => null)();
    const warn = vi.spyOn(getLogger('process-identity'), 'warn');
    try {
      expect(readProcessStart(FIXTURE_PID, { platform: 'win32' })).toBeNull();
      const unregister = registerNativeProcessStartReader(() => 1_700_000_000_123);
      expect(readProcessStart(FIXTURE_PID, { platform: 'win32' })).not.toBeNull();
      unregister();
      expect(readProcessStart(FIXTURE_PID, { platform: 'win32' })).toBeNull();
      expect(warn).toHaveBeenCalledTimes(2);
    } finally {
      warn.mockRestore();
    }
  });
});

describe('readPsProcessStart', () => {
  test('queries ps in the C locale at UTC and parses lstart as UTC', () => {
    const calls: Array<{
      command: string;
      args: string[];
      options: ExecFileSyncOptionsWithStringEncoding;
    }> = [];
    const startedAtMs = readPsProcessStart(FIXTURE_PID, {
      env: { PATH: '/usr/bin', LC_ALL: 'de_DE.UTF-8', TZ: 'Europe/Berlin' },
      run: (command, args, options) => {
        calls.push({ command, args, options });
        return 'Tue Oct 13 17:27:40 2026\n';
      },
    });
    expect(startedAtMs).toBe(Date.UTC(2026, 9, 13, 17, 27, 40));
    expect(calls).toHaveLength(1);
    expect(calls[0]).toMatchObject({
      command: 'ps',
      args: ['-p', String(FIXTURE_PID), '-o', 'lstart='],
      options: {
        encoding: 'utf8',
        timeout: 5000,
        windowsHide: true,
        env: { PATH: '/usr/bin', LC_ALL: 'C', TZ: 'UTC0' },
      },
    });
  });

  test.each([
    '  PID TTY\n',
    '',
    'permission denied',
    'Tue Sep  8 20:21:34 2026\nTue Sep  8 20:21:34 2026',
  ])('output %j that is not one lstart date has no reading', (output) => {
    expect(readPsProcessStart(FIXTURE_PID, { run: () => output })).toBeNull();
  });

  test('a ps that cannot run or times out has no reading', () => {
    expect(
      readPsProcessStart(FIXTURE_PID, {
        run: () => {
          throw Object.assign(new Error('spawnSync ps ETIMEDOUT'), { code: 'ETIMEDOUT' });
        },
      }),
    ).toBeNull();
  });

  test('a ps that exits unsuccessfully has no reading', () => {
    expect(
      readPsProcessStart(FIXTURE_PID, {
        run: (_command, _args, options) =>
          execFileSync(process.execPath, ['-e', 'process.exit(1)'], options),
      }),
    ).toBeNull();
  });

  test.each([0, -1, Number.NaN, 12.5, 0x1_0000_0000])(
    'an invalid pid %j has no reading and runs nothing',
    (pid) => {
      const commands: string[] = [];
      expect(
        readPsProcessStart(pid, {
          run: (command) => {
            commands.push(command);
            return 'Tue Oct 13 17:27:40 2026\n';
          },
        }),
      ).toBeNull();
      expect(commands).toEqual([]);
    },
  );
});

const SECOND_TRUNCATION_PLUS_ONE_TICK_MS = 1_010;

describe.skipIf(process.platform === 'win32')('readProcessStart on this host', () => {
  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;
  }

  test('reads this process the way the operating system records it', () => {
    expect(readProcessStart(process.pid)).toEqual(readProcessStartFromOs(process.pid));
  });

  test('reads a child inside the window in which it was spawned', async () => {
    const holder = await startHolder();
    const start = readProcessStart(holder.pid);
    expect(start).toEqual(readProcessStartFromOs(holder.pid));
    expect(start?.startedAtMs).toBeGreaterThanOrEqual(
      holder.spawnRequestedAtMs - SECOND_TRUNCATION_PLUS_ONE_TICK_MS,
    );
    expect(start?.startedAtMs).toBeLessThanOrEqual(holder.readyAtMs);
  });

  test('classifies a child holding a lock written before it started as replaced', async () => {
    const holder = await startHolder();
    expect(
      classifyLockHolder({
        pid: holder.pid,
        startedAt: lockWrittenBeforeProcessStarted(holder),
        machineId: getMachineId(),
      }),
    ).toBe('replaced');
  });

  test('classifies a child holding the lock it wrote as the writer', async () => {
    const holder = await startHolder();
    expect(
      classifyLockHolder({
        pid: holder.pid,
        startedAt: lockWrittenByRunningProcess(holder),
        machineId: getMachineId(),
      }),
    ).toBe('writer');
  });

  test('classifies a child as the writer when its recorded start matches, whatever startedAt says', async () => {
    const holder = await startHolder();
    const recorded = processStartTokenFromOs(holder.pid);
    expect(
      classifyLockHolder({
        pid: holder.pid,
        startedAt: lockWrittenBeforeProcessStarted(holder),
        machineId: getMachineId(),
        processStart: recorded,
      }),
    ).toBe('writer');
  });
});