Skip to content
Merged
Original file line number Diff line number Diff line change
Expand Up @@ -382,9 +382,13 @@ test('daemon acquisition reclaims a proven reused owner before publication', asy
const paths = resolveDaemonPaths(stateDir);
const daemon = await startHttpDaemonFixture({ via: 'fresh-daemon' });
vi.stubEnv('AGENT_DEVICE_STATE_DIR', stateDir);
const staleStartTime =
process.platform === 'linux'
? 'linux:00000000-0000-0000-0000-000000000000:0'
: 'stale-start-time';
const stale = tryAcquireProcessLock({
lockDirPath: paths.lockPath,
owner: { pid: process.pid, startTime: 'stale-start-time', acquiredAtMs: Date.now() },
owner: { pid: process.pid, startTime: staleStartTime, acquiredAtMs: Date.now() },
});
assert.equal(stale.status, 'acquired');
installSpawnedHttpDaemon(paths, daemon.port);
Expand All @@ -402,7 +406,7 @@ test('daemon acquisition reclaims a proven reused owner before publication', asy
assert.deepEqual(response, { ok: true, data: { via: 'fresh-daemon' } });
assert.equal(mockRunCmdDetached.mock.calls.length, 1);
assert.equal(freshLock.state, 'held');
if (freshLock.state === 'held') assert.notEqual(freshLock.owner.startTime, 'stale-start-time');
if (freshLock.state === 'held') assert.notEqual(freshLock.owner.startTime, staleStartTime);
assert.deepEqual(daemon.seenPaths, ['GET /health', 'POST /rpc']);
} finally {
if (stale.status === 'acquired') await stale.acquisition.release();
Expand Down
3 changes: 2 additions & 1 deletion packages/daemon-contracts/src/daemon-process.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import {
isProcessAlive,
processStartTimesDiffer,
isProcessPid,
readHostProcessIdentityObservations,
readProcessCommand,
Expand Down Expand Up @@ -83,7 +84,7 @@ export async function waitForDaemonExit(
return (
Comment thread
thymikee marked this conversation as resolved.
Resolved
Boolean(
observed?.state.startsWith('Z') ||
(observed?.startTime && observed.startTime !== identity.startTime),
processStartTimesDiffer(observed?.startTime, identity.startTime),
) || !isProcessAlive(identity.pid)
);
};
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,10 @@ test('a record whose process is gone or was replaced is not a running daemon', (
token: 't',
port: 1,
pid: owner.pid,
processStartTime: 'Thu Jan 1 00:00:00 1970',
processStartTime:
process.platform === 'linux'
? 'linux:00000000-0000-0000-0000-000000000000:0'
: 'Thu Jan 1 00:00:00 1970',
plugins: [ACTIVE],
});
expect(readDaemonStatus(resolveDaemonPaths(stateDir)).state).toBe('stopped');
Expand Down
95 changes: 95 additions & 0 deletions packages/host-kit/src/internal/host-process-liveness.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ import {
isProcessZombie,
readHostProcessIdentityObservations,
readHostProcessIdentityObservationsAsync,
readProcessStartTime,
readProcessIdentities,
readProcessIdentityFacts,
} from './host-process.ts';
Expand Down Expand Up @@ -266,3 +267,97 @@ test('a host with both pinned ps binaries keeps running /bin/ps', () => {
assert.equal(isProcessZombie(4242), false);
assert.equal(mockRunCmdSync.mock.calls[0]?.[0], '/bin/ps');
});

for (const probe of ['single', 'sync', 'async'] as const) {
test.skipIf(process.platform !== 'linux')(
`Linux ${probe} identity survives a wall-clock step`,
async () => {
vi.spyOn(fs, 'readFileSync').mockImplementation((path) => {
if (String(path) === '/proc/sys/kernel/random/boot_id') return 'test-boot\n';
if (String(path) === '/proc/4242/stat') {
return `4242 (a) b) S ${Array(18).fill('0').join(' ')} 5371442 0`;
}
throw new Error('ENOENT');
});
const read = async () => {
if (probe === 'single') return readProcessStartTime(4242);
const rows =
probe === 'sync'
? readHostProcessIdentityObservations([4242])
: await readHostProcessIdentityObservationsAsync([4242]);
return rows.get(4242)?.startTime;
};
for (const time of ['Mon Nov 9 23:54:54 2026', 'Mon Nov 9 23:54:58 2026']) {
const stdout = probe === 'single' ? time : `4242 Ss ${time}`;
psReturns(stdout);
mockRunCmd.mockResolvedValue({ stdout, stderr: '', exitCode: 0 });
assert.equal(await read(), 'linux:test-boot:5371442');
}
},
);
}

for (const [psState, procState, zombie] of [
['Z', 'S', false],
['S', 'Z', true],
] as const) {
test.skipIf(process.platform !== 'linux')(
`Linux state follows the /proc read that gave the start token (ps ${psState}, /proc ${procState})`,
async () => {
// A pid reused between the ps snapshot and the /proc read must not pair one lifetime's
// start token with the other lifetime's state.
vi.spyOn(fs, 'readFileSync').mockImplementation((path) => {
if (String(path) === '/proc/sys/kernel/random/boot_id') return 'test-boot\n';
if (String(path) === '/proc/4242/stat') {
return `4242 (a) ${procState} ${Array(18).fill('0').join(' ')} 5371442 0`;
}
throw new Error('ENOENT');
});
const row = `4242 ${psState} Mon Nov 9 23:54:54 2026\n`;
psReturns(row);
psAnswersIdentity({ identity: row, command: '4242 y\n' });
const expected = { state: procState, startTime: 'linux:test-boot:5371442' };

assert.deepEqual(readHostProcessIdentityObservations([4242]).get(4242), expected);
assert.deepEqual(
(await readHostProcessIdentityObservationsAsync([4242])).get(4242),
expected,
);
assert.deepEqual(await readProcessIdentityFacts(4242), {
startTime: 'linux:test-boot:5371442',
command: 'y',
zombie,
});
},
);
}

test.skipIf(process.platform !== 'linux')(
'Linux identities fall back to lstart when proc is unreadable or malformed',
async () => {
for (const stat of [
null,
'4242 (broken) S 0',
`4242 (broken) S ${Array(18).fill('0').join(' ')} nope`,
]) {
vi.spyOn(fs, 'readFileSync').mockImplementation((path) => {
if (String(path) === '/proc/sys/kernel/random/boot_id') return 'test-boot\n';
if (stat === null) throw new Error('ENOENT');
return stat;
});
psReturns('original lstart');
assert.equal(readProcessStartTime(4242), 'original lstart');
psReturns('4242 Ss original lstart');
mockRunCmd.mockResolvedValue({ stdout: '4242 Ss original lstart', stderr: '', exitCode: 0 });
assert.equal(
readHostProcessIdentityObservations([4242]).get(4242)?.startTime,
'original lstart',
);
assert.equal(
(await readHostProcessIdentityObservationsAsync([4242])).get(4242)?.startTime,
'original lstart',
);
vi.restoreAllMocks();
}
},
);
42 changes: 40 additions & 2 deletions packages/host-kit/src/internal/host-process.ts
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,38 @@ function parseHostProcessCommandRows(stdout: string): Array<{ pid: number; comma
}));
}

/** State and start token from one `/proc/<pid>/stat` read, so a reused pid cannot mix lifetimes. */
function readLinuxProcessStat(pid: number): { state: string; startTime: string } | null {
if (process.platform !== 'linux') return null;
try {
const bootId = fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
Comment thread
thymikee marked this conversation as resolved.
Resolved
// comm can contain spaces and closing parentheses; field 3 follows the last one.
const end = stat.lastIndexOf(')');
if (end < 0) return null;
const fields = stat
.slice(end + 1)
.trim()
.split(/\s+/);
const state = fields[0];
const startTime = fields[19];
if (!bootId || !state || !startTime || !/^\d+$/.test(startTime)) return null;
return { state, startTime: `linux:${bootId}:${startTime}` };
} catch {
return null;
}
}

/** Positive proof of different lifetimes; unreadable or mixed-format records prove nothing. */
export function processStartTimesDiffer(
left: string | null | undefined,
right: string | null | undefined,
): boolean {
if (!left || !right) return false;
if (left.startsWith('linux:') !== right.startsWith('linux:')) return false;
return left !== right;
}

export function readProcessStartTime(pid: number): string | null {
return readProcessField(pid, 'lstart=');
}
Expand Down Expand Up @@ -333,7 +365,9 @@ function parseHostProcessIdentityRows(stdout: string): HostProcessIdentityRow[]
if (!match) continue;
const pid = Number.parseInt(match[1]!, 10);
if (!Number.isInteger(pid) || pid <= 0) continue;
rows.push({ pid, state: match[2]!, startTime: match[3]! });
// On Linux both facts come from one /proc read; the ps row is the fallback when /proc is unreadable.
const linux = readLinuxProcessStat(pid);
rows.push(linux ? { pid, ...linux } : { pid, state: match[2]!, startTime: match[3]! });
}
return rows;
}
Expand All @@ -353,6 +387,10 @@ type HostProcessField = 'lstart=' | 'command=' | 'state=';
function readProcessField(pid: number, field: HostProcessField): string | null {
if (!Number.isInteger(pid) || pid <= 0) return null;
if (isWindowsHostPlatform()) return readWindowsProcessField(pid, field);
if (field === 'lstart=') {
const token = readLinuxProcessStat(pid)?.startTime;
if (token !== undefined) return token;
}
try {
const result = runCmdSync(hostPsCommand(), ['-p', String(pid), '-o', field], {
allowFailure: true,
Expand Down Expand Up @@ -744,7 +782,7 @@ export function judgeProcessIdentity(
): ProcessIdentityVerdict {
if (facts.zombie) return 'exited';
const { startTime, matches } = expected;
if (startTime && facts.startTime && facts.startTime !== startTime) return 'reassigned';
if (processStartTimesDiffer(startTime, facts.startTime)) return 'reassigned';
const commandMatches = facts.command === null || !matches ? undefined : matches(facts.command);
if (!startTime && commandMatches === false) return 'reassigned';
if (!startTime && !matches) return 'unverified';
Expand Down
11 changes: 10 additions & 1 deletion packages/host-kit/src/internal/owner-identity-liveness.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@ const { mockIsProcessAlive, mockIsProcessZombie, mockReadProcessStartTime } = vi
mockReadProcessStartTime: vi.fn(),
}));

vi.mock('./host-process.ts', () => ({
vi.mock('./host-process.ts', async (importOriginal) => ({
...(await importOriginal<typeof import('./host-process.ts')>()),
isProcessAlive: mockIsProcessAlive,
isProcessZombie: mockIsProcessZombie,
readProcessStartTime: mockReadProcessStartTime,
Expand Down Expand Up @@ -59,6 +60,14 @@ test('a definite start-time mismatch classifies as owner-process-reused', () =>
);
});

test.each([
['Mon Aug 10 20:00:00 2026', 'linux:11111111-1111-4111-8111-111111111111:12345'],
['linux:11111111-1111-4111-8111-111111111111:12345', 'Mon Aug 10 20:00:00 2026'],
])('an owner with an incomparable start-time format retains its resource', (recorded, observed) => {
mockReadProcessStartTime.mockReturnValue(observed);
assert.equal(classifyOwnerLiveness({ owner: { pid: OWNER_PID, startTime: recorded } }), 'live');
});

test('a null-start-time owner stays fail-closed while its pid is alive', () => {
// No same-clock-domain proof of birth order exists for a null-start owner:
// a clock step could make a live owner look like it started after the
Expand Down
44 changes: 42 additions & 2 deletions packages/host-kit/src/internal/owner-identity.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,12 @@ import {
ownerIdentityMatches,
type OwnerIdentity,
} from './owner-identity.ts';
import { readProcessStartTime } from './host-process.ts';
import {
readProcessStartTime,
readHostProcessIdentityObservations,
readHostProcessIdentityObservationsAsync,
readProcessIdentityFacts,
} from './host-process.ts';
import { mkdtempForTestSync } from './tmp-dir.fixtures.ts';

afterEach(() => {
Expand All @@ -22,7 +27,14 @@ test('distinguishes dead and PID-reused owners', () => {
'owner-process-dead',
);
assert.equal(
classifyOwnerLiveness({ owner: { pid: process.pid, startTime: 'not-this-process' } }),
classifyOwnerLiveness({
owner: {
pid: process.pid,
startTime: readProcessStartTime(process.pid)?.startsWith('linux:')
? 'linux:other-boot:1'
: 'not-this-process',
},
}),
'owner-process-reused',
);
});
Expand Down Expand Up @@ -54,6 +66,17 @@ test('proves two owners differ only when the evidence is there', () => {
assert.equal(differs({ pid: 1, startTime: 'a' }, { pid: 2, startTime: 'a' }), true);
assert.equal(differs({ pid: 1, startTime: 'a' }, { pid: 1, startTime: 'b' }), true);
assert.equal(differs({ pid: 1, startTime: 'a' }, { pid: 1, startTime: 'a' }), false);
assert.equal(
differs(
{ pid: 1, startTime: 'Mon Aug 10 20:00:00 2026' },
{ pid: 1, startTime: 'linux:boot:1' },
),
false,
);
assert.equal(
differs({ pid: 1, startTime: 'linux:boot:1' }, { pid: 1, startTime: 'linux:boot:2' }),
true,
);
// An unreadable start time on either side leaves equal pids unproven, never
// different — the inverse mistake would hand a held resource to a second owner.
assert.equal(differs({ pid: 1, startTime: null }, { pid: 1, startTime: 'b' }), false);
Expand All @@ -63,3 +86,20 @@ test('proves two owners differ only when the evidence is there', () => {
false,
);
});

test.skipIf(process.platform !== 'linux')(
'real Linux process reads share the kernel lifetime token',
async () => {
const token = readProcessStartTime(process.pid);
assert.match(token ?? '', /^linux:[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}:\d+$/);
assert.equal(
readHostProcessIdentityObservations([process.pid]).get(process.pid)?.startTime,
token,
);
assert.equal(
(await readHostProcessIdentityObservationsAsync([process.pid])).get(process.pid)?.startTime,
token,
);
assert.equal((await readProcessIdentityFacts(process.pid)).startTime, token);
},
);
5 changes: 3 additions & 2 deletions packages/host-kit/src/internal/owner-identity.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import fs from 'node:fs';
import {
isProcessAlive,
processStartTimesDiffer,
isProcessZombie,
readHostProcessIdentityObservations,
readHostProcessIdentityObservationsAsync,
Expand Down Expand Up @@ -74,7 +75,7 @@ export function ownerIdentityDiffers(
right: Pick<OwnerIdentity, 'pid' | 'startTime'>,
): boolean {
if (left.pid !== right.pid) return true;
return Boolean(left.startTime && right.startTime && left.startTime !== right.startTime);
return processStartTimesDiffer(left.startTime, right.startTime);
}

/**
Expand Down Expand Up @@ -183,7 +184,7 @@ function provesPidReused(
): boolean {
const currentStartTime =
observation === undefined ? readProcessStartTime(owner.pid) : (observation?.startTime ?? null);
return currentStartTime !== null && currentStartTime !== owner.startTime;
return processStartTimesDiffer(currentStartTime, owner.startTime);
}

function classifyOwnerStateDirectory(stateDir: string): OwnerLiveness {
Expand Down
5 changes: 4 additions & 1 deletion packages/host-kit/src/internal/process-lock-guard.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,10 @@ test('a long-standing guard whose holder pid now has another start time is recla
const reusedHolder = {
...DEAD_GUARD_HOLDER,
pid: process.ppid,
startTime: 'Thu Jan 1 00:00:00 1970',
startTime:
process.platform === 'linux'
? 'linux:00000000-0000-0000-0000-000000000000:0'
: 'Thu Jan 1 00:00:00 1970',
};
fs.writeFileSync(mutexPath, JSON.stringify(reusedHolder));
stampDirectoryAbandoned(mutexPath);
Expand Down
1 change: 1 addition & 0 deletions packages/host-kit/src/process.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ export {
readProcessIdentities,
readProcessIdentityFacts,
readProcessStartTime,
processStartTimesDiffer,
signalPidsBestEffort,
stopProcessAndConfirmExit,
uniquePositivePids,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -243,3 +243,17 @@ test('an empty or undecodable record is not dead and needs no probe', async () =
);
assert.equal(mockObservations.mock.calls.length, 0);
});

test.each([
['Mon Aug 10 20:00:00 2026', 'linux:11111111-1111-4111-8111-111111111111:12345'],
['linux:11111111-1111-4111-8111-111111111111:12345', 'Mon Aug 10 20:00:00 2026'],
])(
'incomparable process lifetimes (recorded %s, observed %s) prove neither a live nor a dead browser fleet',
async (recorded, observed) => {
mockIsProcessAlive.mockReturnValue(true);
mockObservations.mockResolvedValue(new Map([[11, { state: 'Ss', startTime: observed }]]));
const store = storeReturning([daemonEntry([record(11, recorded)])]);
assert.equal(await managedWebBrowserProcessRecordIsLive(store), false);
assert.equal(await managedWebBrowserProcessRecordIsDead(store), false);
},
);
Loading
Loading