Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Fix process enumeration on busy hosts (#5155)

Nick Gomezc4adbe1fd9b8
diff --git a/.changeset/fix-process-enumeration.md b/.changeset/fix-process-enumeration.md
new file mode 100644
index 000000000..2a92f3af5
--- /dev/null
+++ b/.changeset/fix-process-enumeration.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Keep server detection working during removal and uninstall on machines with large process listings.
diff --git a/packages/cli/src/commands/removal-host-uncertainty.test.ts b/packages/cli/src/commands/removal-host-uncertainty.test.ts
index 1ee3c26f8..dea3d204d 100644
--- a/packages/cli/src/commands/removal-host-uncertainty.test.ts
+++ b/packages/cli/src/commands/removal-host-uncertainty.test.ts
@@ -5,7 +5,7 @@ import {
spawn,
spawnSync,
} from 'node:child_process';
-import { once } from 'node:events';
+import { EventEmitter, once } from 'node:events';
import {
chmodSync,
existsSync,
@@ -18,6 +18,7 @@ import {
} from 'node:fs';
import { hostname, tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
+import { Readable } from 'node:stream';
import { isProcessAlive } from '@inkeep/open-knowledge-server';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { startDefunctProcess } from './defunct-process.test-helper.ts';
@@ -26,11 +27,12 @@ import { stopServerForRemoval } from './stop-for-removal.ts';
vi.mock('node:child_process', async (importOriginal) => {
const actual = await importOriginal<typeof import('node:child_process')>();
- return { ...actual, spawnSync: vi.fn() };
+ return { ...actual, spawn: vi.fn(actual.spawn), spawnSync: vi.fn() };
});
+const spawnMock = vi.mocked(spawn);
const spawnSyncMock = vi.mocked(spawnSync);
-const { spawnSync: realSpawnSync } =
+const { spawn: realSpawn, spawnSync: realSpawnSync } =
await vi.importActual<typeof import('node:child_process')>('node:child_process');
interface HostProcess {
@@ -74,6 +76,7 @@ describe.skipIf(process.platform === 'win32')(
escapedSpawns = [];
write(join(project, '.ok', 'local', 'server.lock'), 'not json');
write(join(project, 'notes.md'), '# Keep');
+ spawnMock.mockReset().mockImplementation(realSpawn);
spawnSyncMock.mockReset();
});
@@ -84,6 +87,7 @@ describe.skipIf(process.platform === 'win32')(
child.kill('SIGKILL');
await exited;
}
+ spawnMock.mockReset().mockImplementation(realSpawn);
spawnSyncMock.mockReset();
rmSync(root, { recursive: true, force: true });
expect(escapedSpawns).toEqual([]);
@@ -96,15 +100,34 @@ describe.skipIf(process.platform === 'win32')(
function installHost(plan: HostPlan): void {
const scriptedCwds = new Map((plan.cwdQueries ?? []).map((q) => [q.pids, q.result]));
+ spawnMock.mockImplementation((...args: Parameters<typeof spawn>) => {
+ const processListing =
+ args[0] === 'ps' && (args[1]?.includes('-A') || args[1]?.includes('-axo'));
+ const listenerListing = args[0] === 'lsof' && args[1]?.includes('-iTCP');
+ if (!processListing && !listenerListing) {
+ if (args[0] !== 'ps' && args[0] !== 'lsof') return realSpawn(...args);
+ escapedSpawns.push(`${args[0]} ${args[1]?.join(' ')}`);
+ throw new Error(`unplanned ${args[0]} spawn`);
+ }
+ const rows = plan.processes.map((p) => `${p.pid} ${p.command}`);
+ const output = processListing ? ` PID COMMAND\n${rows.join('\n')}\n` : LSOF_HEADER;
+ const child = Object.assign(new EventEmitter(), {
+ stdout: Readable.from([output]),
+ stderr: Readable.from([]),
+ });
+ let closed = 0;
+ for (const stream of [child.stdout, child.stderr]) {
+ stream.once('close', () => {
+ if (++closed === 2) child.emit('close', 0);
+ });
+ }
+ return child as ChildProcess;
+ });
spawnSyncMock.mockImplementation(
(command: string, args: readonly string[] = [], options?: SpawnSyncOptions) => {
if (command === 'pgrep') {
return spawnResult({ stdout: plan.processes.map((p) => `${p.pid}\n`).join('') });
}
- if (command === 'ps' && args[0] === '-axo') {
- const rows = plan.processes.map((p) => `${p.pid} ${p.command}`);
- return spawnResult({ stdout: ` PID COMMAND\n${rows.join('\n')}\n` });
- }
if (command === 'lsof' && args[0] === '-iTCP') {
return spawnResult({ stdout: LSOF_HEADER });
}
diff --git a/packages/server/src/process-scan-collectors.test.ts b/packages/server/src/process-scan-collectors.test.ts
new file mode 100644
index 000000000..a62774bf7
--- /dev/null
+++ b/packages/server/src/process-scan-collectors.test.ts
@@ -0,0 +1,454 @@
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { spawnSync, spawn, execFileSync } = vi.hoisted(() => ({
+ spawnSync: vi.fn(),
+ spawn: vi.fn(),
+ execFileSync: vi.fn(),
+}));
+
+vi.mock('node:child_process', () => ({ spawnSync, spawn, execFileSync }));
+
+import {
+ fakeChildProcess,
+ type FakeChildProcessInput as Output,
+} from './process-scan.test-helper.ts';
+import { discoverLockDirs, findOkProcessPids, scanLockProcesses } from './process-scan.ts';
+
+const originalPlatform = process.platform;
+const fixturePid = 24680;
+const listenerHeader = 'COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME\n';
+const nodeDefaultMaxBuffer = 1024 * 1024;
+let directory: string;
+let project: string;
+let lockDir: string;
+
+function provideOutput(read: (program: string, args: string[]) => Output) {
+ spawn.mockImplementation((program: string, args: string[]) =>
+ fakeChildProcess(read(program, args)),
+ );
+ spawnSync.mockImplementation((program: string, args: string[]) => {
+ const result = read(program, args);
+ let stdout = '';
+ let bytes = 0;
+ for (const chunk of result.stdout as Iterable<string | Buffer>) {
+ stdout += chunk.toString();
+ bytes += Buffer.byteLength(chunk);
+ if (bytes > nodeDefaultMaxBuffer) {
+ return {
+ stdout,
+ stderr: '',
+ status: null,
+ error: Object.assign(new Error('spawnSync output exceeds buffer'), { code: 'ENOBUFS' }),
+ };
+ }
+ }
+ return {
+ ...result,
+ stdout,
+ stderr: result.stderr ?? '',
+ status: result.status === undefined ? 0 : result.status,
+ };
+ });
+}
+
+function emptyOutput(program: string): Output {
+ if (program === 'ps') return { stdout: ['PID COMMAND\n'] };
+ if (program === 'lsof' || program === 'pgrep') return { stdout: [], status: 1 };
+ throw new Error(`Unexpected subprocess: ${program}`);
+}
+
+beforeEach(() => {
+ directory = realpathSync(mkdtempSync(join(tmpdir(), 'ok-process-collectors-')));
+ project = join(directory, 'project');
+ lockDir = join(project, '.ok', 'local');
+ mkdirSync(lockDir, { recursive: true });
+ writeFileSync(join(lockDir, 'server.lock'), '{}');
+ const caller = join(directory, 'caller');
+ mkdirSync(caller);
+ vi.spyOn(process, 'cwd').mockReturnValue(caller);
+ vi.spyOn(process, 'kill').mockReturnValue(true);
+ Object.defineProperty(process, 'platform', { value: 'linux' });
+ spawn.mockReset();
+ spawnSync.mockReset();
+ execFileSync.mockReset().mockReturnValue('S\n');
+ provideOutput(emptyOutput);
+});
+
+afterEach(() => {
+ Object.defineProperty(process, 'platform', { value: originalPlatform });
+ vi.restoreAllMocks();
+ rmSync(directory, { recursive: true, force: true });
+});
+
+describe('process listing producers', () => {
+ it.each(['Toybox', 'procps'])('discovers marked processes with %s ps', async (producer) => {
+ const command = `node --ok-lock-dir-b64=${Buffer.from(lockDir).toString('base64url')}`;
+ provideOutput((program, args) => {
+ if (program === 'pgrep') return { stdout: [`${fixturePid} ${command}\n`] };
+ if (program !== 'ps') return emptyOutput(program);
+ if (producer === 'Toybox' && args.some((arg) => arg.startsWith('-') && arg.includes('x')))
+ return { stdout: [], status: 1, stderr: "ps: Unknown option 'xo' (see 'ps --help')\n" };
+ const format = args[args.indexOf('-o') + 1] ?? '';
+ if (producer === 'procps' && format.includes('cmdline'))
+ return {
+ stdout: [],
+ status: 1,
+ stderr: 'error: unknown user-defined format specifier "cmdline"\n',
+ };
+ const fullCommand =
+ producer === 'procps' || format.includes('args') || format.includes('cmdline');
+ const control =
+ producer === 'Toybox' && format.includes('args')
+ ? 'open-knowledge-server --fixture-control=notes'
+ : '/opt/open-knowledge-server --fixture-control=notes';
+ return {
+ stdout: [
+ 'PID COMMAND\n',
+ `13579 ${control}\n`,
+ `${fixturePid} ${fullCommand ? command : 'node'}\n`,
+ ],
+ };
+ });
+
+ expect(await scanLockProcesses()).toEqual({
+ candidates: [{ lockDir, pid: fixturePid, source: 'lock-dir-argument' }],
+ unavailable: [],
+ });
+ });
+
+ it('retains trailing command arguments with procps ps under a narrow display width', async () => {
+ const displayWidth = 20;
+ const row = `${fixturePid} node /srv/fixture.cjs --ok-lock-dir-b64=${Buffer.from(lockDir).toString('base64url')}`;
+ provideOutput((program, args) => {
+ if (program !== 'ps') return emptyOutput(program);
+ const format = args[args.indexOf('-o') + 1] ?? '';
+ if (format.includes('cmdline'))
+ return {
+ stdout: [],
+ status: 1,
+ stderr: 'error: unknown user-defined format specifier "cmdline"\n',
+ };
+ const wide = args.includes('-ww') || args.filter((arg) => arg === '-w').length === 2;
+ return { stdout: ['PID COMMAND\n', `${wide ? row : row.slice(0, displayWidth)}\n`] };
+ });
+
+ expect(await findOkProcessPids()).toEqual([fixturePid]);
+ expect(await scanLockProcesses()).toEqual({
+ candidates: [{ lockDir, pid: fixturePid, source: 'lock-dir-argument' }],
+ unavailable: [],
+ });
+ });
+});
+
+describe('BusyBox process listing', () => {
+ interface BusyBoxProcess {
+ pid: number;
+ comm: string;
+ exe: string;
+ cmdline: string;
+ }
+
+ const psColumns =
+ 'user,group,comm,args,pid,ppid,pgid,etime,nice,rgroup,ruser,time,tty,vsz,sid,stat,rss';
+ const psUsage =
+ 'BusyBox v1.37.0 (2026-01-10 15:38:28 UTC) multi-call binary.\n\nUsage: ps [-o COL1,COL2=HEADER] [-T]\n\nShow list of processes\n\n\t-o COL1,COL2=HEADER\tSelect columns for display\n\t-T\t\t\tShow threads\n';
+ const libcs = [
+ ['musl', (option: string) => `ps: unrecognized option: ${option}`],
+ ['glibc', (option: string) => `ps: invalid option -- '${option}'`],
+ ] as const;
+ const shell = { pid: 1, comm: 'sh', exe: '/bin/busybox', cmdline: '/bin/sh /srv/run.sh' };
+ const ordinary = {
+ pid: 11223,
+ comm: 'MainThread',
+ exe: '/usr/local/bin/node',
+ cmdline: 'node /srv/fixture.cjs --fixture-control=ordinary',
+ };
+ const lookalike = {
+ pid: 13579,
+ comm: 'MainThread',
+ exe: '/usr/local/bin/node',
+ cmdline: '/opt/open-knowledge-server /srv/fixture.cjs --fixture-control=notes',
+ };
+
+ function argsColumn({ comm, cmdline }: BusyBoxProcess): string {
+ const argv0 = cmdline.split(' ')[0] ?? '';
+ const base = cmdline.slice(argv0.lastIndexOf('/') + 1).replace(/^-/, '');
+ return base.startsWith(comm) ? cmdline : `{${comm}} ${cmdline}`;
+ }
+
+ function busyboxPs(
+ processes: BusyBoxProcess[],
+ args: string[],
+ reject: (option: string) => string,
+ ): Output {
+ const columns: string[] = [];
+ for (let index = 0; index < args.length; index++) {
+ const arg = args[index] ?? '';
+ if (!arg.startsWith('-')) throw new Error(`Unmodeled ps operand: ${arg}`);
+ for (let offset = 1; offset < arg.length; offset++) {
+ const option = arg[offset] ?? '';
+ if (option === 'o') {
+ columns.push(...(arg.slice(offset + 1) || args[++index] || '').split(','));
+ break;
+ }
+ if (option === 'T') throw new Error('Unmodeled ps option: T');
+ if (!'ZaAdefl'.includes(option))
+ return { stdout: [], status: 1, stderr: `${reject(option)}\n${psUsage}` };
+ }
+ }
+ const unknown = columns.find((column) => !psColumns.split(',').includes(column));
+ if (unknown !== undefined)
+ return {
+ stdout: [],
+ status: 1,
+ stderr: `ps: bad -o argument '${unknown}', supported arguments: ${psColumns}\n`,
+ };
+ if (columns.join(',') !== 'pid,args')
+ throw new Error(`Unmodeled ps columns: ${columns.join(',')}`);
+ return {
+ stdout: [
+ 'PID COMMAND\n',
+ ...processes.map((entry) => `${String(entry.pid).padStart(5)} ${argsColumn(entry)}\n`),
+ ],
+ };
+ }
+
+ function provideBusyBox(processes: BusyBoxProcess[], reject: (option: string) => string) {
+ const read = (program: string, args: string[]): Output => {
+ if (program === 'ps') return busyboxPs(processes, args, reject);
+ if (program === 'lsof')
+ return { stdout: processes.map((entry) => `${entry.pid}\t${entry.exe}\t0\t/dev/null\n`) };
+ throw new Error(`Unexpected subprocess: ${program}`);
+ };
+ provideOutput(read);
+ execFileSync.mockImplementation((program: string, args: string[]) => {
+ const result = read(program, args);
+ if (!result.status) return [...(result.stdout as Iterable<string>)].join('');
+ throw Object.assign(new Error(`Command failed: ${program} ${args.join(' ')}`), {
+ status: result.status,
+ stderr: result.stderr,
+ });
+ });
+ }
+
+ it.each(libcs)(
+ 'discovers a marked process and not its lookalike with %s BusyBox ps',
+ async (_libc, reject) => {
+ const marked = {
+ pid: fixturePid,
+ comm: 'MainThread',
+ exe: '/usr/local/bin/node',
+ cmdline: `node /srv/fixture.cjs --ok-lock-dir-b64=${Buffer.from(lockDir).toString('base64url')}`,
+ };
+ provideBusyBox([shell, ordinary, lookalike, marked], reject);
+
+ expect(await findOkProcessPids()).toEqual([fixturePid]);
+ expect(await discoverLockDirs()).toEqual([lockDir]);
+ expect(await scanLockProcesses(() => ({ onProbeFailure: () => {} }))).toEqual({
+ candidates: [{ lockDir, pid: fixturePid, source: 'lock-dir-argument' }],
+ unavailable: [],
+ });
+ },
+ );
+
+ it.each(libcs)(
+ 'reports a %s BusyBox host without OK processes as fully enumerated',
+ async (_libc, reject) => {
+ provideBusyBox([shell, ordinary], reject);
+
+ expect(await findOkProcessPids()).toEqual([]);
+ expect(await discoverLockDirs()).toEqual([]);
+ expect(await scanLockProcesses(() => ({ onProbeFailure: () => {} }))).toEqual({
+ candidates: [],
+ unavailable: [],
+ });
+ },
+ );
+});
+
+describe('process format failures', () => {
+ it('does not change command formats after an incomplete process table', async () => {
+ provideOutput((program, args) => {
+ if (program !== 'ps') return emptyOutput(program);
+ if (args.includes('pid,cmdline'))
+ return { stdout: ['PID CMDLINE\n'], status: 1, stderr: 'process table unreadable\n' };
+ return { stdout: ['PID ARGS\n13579 open-knowledge-server --fixture-control=notes\n'] };
+ });
+
+ expect(await findOkProcessPids()).toEqual([]);
+ const scan = await scanLockProcesses();
+ expect(scan.candidates).toEqual([]);
+ expect(scan.unavailable).toEqual([expect.stringContaining('process table unreadable')]);
+ });
+});
+
+describe('listener enumeration', () => {
+ function provideLargeListenerTable() {
+ const row = `node ${fixturePid} user 20u IPv4 device 0t0 TCP *:54321 (LISTEN)\n`;
+ const repeats = Math.ceil(nodeDefaultMaxBuffer / Buffer.byteLength(row));
+ provideOutput((program, args) => {
+ if (program === 'lsof' && args.includes('-iTCP')) {
+ return {
+ stdout: (function* () {
+ yield listenerHeader;
+ for (let index = 0; index < repeats; index++)
+ yield row.replace('20u', `${index + 20}u`);
+ })(),
+ };
+ }
+ if (program === 'lsof' && args.includes('cwd'))
+ return { stdout: [`p${fixturePid}\nn${project}\n`] };
+ return emptyOutput(program);
+ });
+ }
+
+ it('discovers lock directories from an oversized listener table', async () => {
+ provideLargeListenerTable();
+
+ expect(await discoverLockDirs()).toEqual([lockDir]);
+ });
+
+ it('attributes a listener once after an oversized listener table', async () => {
+ provideLargeListenerTable();
+
+ expect(await scanLockProcesses()).toEqual({
+ candidates: [
+ { lockDir, pid: fixturePid, source: 'listener-cwd' },
+ { lockDir: join(project, '.ok'), pid: fixturePid, source: 'listener-cwd' },
+ ],
+ unavailable: [],
+ });
+ });
+});
+
+describe('process listing diagnostics', () => {
+ it.each(['ENOENT', 'EACCES'] as const)('retains a ps startup error code %s', async (code) => {
+ provideOutput((program) =>
+ program === 'ps'
+ ? { stdout: [], error: Object.assign(new Error('could not start producer'), { code }) }
+ : emptyOutput(program),
+ );
+
+ const scan = await scanLockProcesses();
+ expect(scan.candidates).toEqual([]);
+ expect(scan.unavailable).toEqual([expect.stringContaining('ps')]);
+ expect(scan.unavailable[0]).toContain(code);
+ expect(scan.unavailable[0]).toContain('could not start producer');
+ expect(scan.unavailable[0]).not.toContain('pgrep');
+ expect(await findOkProcessPids()).toEqual([]);
+ });
+
+ it('retains the ps output read error after receiving a matching row', async () => {
+ spawn.mockImplementation(() =>
+ fakeChildProcess({
+ stdout: (async function* () {
+ yield `PID COMMAND\n${fixturePid} node --ok-project-path=${project}\n`;
+ throw Object.assign(new Error('output read failed'), { code: 'EIO' });
+ })(),
+ }),
+ );
+
+ const scan = await scanLockProcesses();
+ expect(scan.candidates).toEqual([]);
+ expect(scan.unavailable).toEqual([expect.stringMatching(/ps.*EIO/)]);
+ expect(scan.unavailable[0]).toContain('output read failed');
+ expect(scan.unavailable[0]).not.toContain('pgrep');
+ expect(await findOkProcessPids()).toEqual([]);
+ });
+
+ it('retains the ps exit status when enumeration fails', async () => {
+ provideOutput((program) =>
+ program === 'ps'
+ ? { stdout: ['PID COMMAND\n'], status: 7, stderr: 'ps: process data unavailable\n' }
+ : emptyOutput(program),
+ );
+
+ const scan = await scanLockProcesses();
+ expect(scan.candidates).toEqual([]);
+ expect(scan.unavailable).toEqual([expect.stringMatching(/ps.*(?:exit|status).*7/)]);
+ expect(scan.unavailable[0]).toContain('process data unavailable');
+ expect(scan.unavailable[0]).not.toContain('pgrep');
+ });
+
+ it('retains the diagnostic of every rejected ps listing', async () => {
+ const attempts: string[][] = [];
+ const rejection = (args: string[]) => `ps: rejected [${args.join(' ')}]`;
+ provideOutput((program, args) => {
+ if (program !== 'ps') return emptyOutput(program);
+ attempts.push(args);
+ return { stdout: [], status: 1, stderr: `${rejection(args)}\n` };
+ });
+
+ const scan = await scanLockProcesses();
+ expect(scan.candidates).toEqual([]);
+ expect(scan.unavailable).toHaveLength(1);
+ expect(attempts).not.toHaveLength(0);
+ for (const args of attempts) expect(scan.unavailable[0]).toContain(rejection(args));
+ expect(await findOkProcessPids()).toEqual([]);
+ });
+
+ it('retains the ps termination signal when enumeration stops', async () => {
+ provideOutput((program) =>
+ program === 'ps'
+ ? { stdout: ['PID COMMAND\n'], status: null, signal: 'SIGTERM' }
+ : emptyOutput(program),
+ );
+
+ const scan = await scanLockProcesses();
+ expect(scan.candidates).toEqual([]);
+ expect(scan.unavailable).toEqual([expect.stringMatching(/ps.*SIGTERM/)]);
+ expect(scan.unavailable[0]).not.toContain('pgrep');
+ expect(scan.unavailable[0]).not.toContain('timed out');
+ });
+
+ it.each(['ps', 'lsof'])(
+ 'reports the %s listing stopped by the scan time budget as a timeout',
+ async (producer) => {
+ provideOutput((program, args) =>
+ program === producer && (program === 'ps' || args.includes('-iTCP'))
+ ? { stdout: [], status: null, signal: 'SIGTERM', killed: true }
+ : emptyOutput(program),
+ );
+
+ const scan = await scanLockProcesses();
+ expect(scan.candidates).toEqual([]);
+ expect(scan.unavailable).toEqual([
+ expect.stringMatching(new RegExp(`${producer} .*timed out`)),
+ ]);
+ },
+ );
+
+ it('reports an lsof listing stopped by an outside signal as that signal', async () => {
+ provideOutput((program, args) =>
+ program === 'lsof' && args.includes('-iTCP')
+ ? { stdout: [], status: null, signal: 'SIGTERM' }
+ : emptyOutput(program),
+ );
+
+ const scan = await scanLockProcesses();
+ expect(scan.unavailable).toEqual([
+ expect.stringMatching(/TCP listeners.*lsof.*signal SIGTERM/),
+ ]);
+ expect(scan.unavailable[0]).not.toContain('timed out');
+ });
+
+ it.each(['ENOENT', 'EACCES'] as const)('retains an lsof startup error code %s', async (code) => {
+ provideOutput((program, args) =>
+ program === 'lsof' && args.includes('-iTCP')
+ ? {
+ stdout: [],
+ error: Object.assign(new Error('could not start listener producer'), { code }),
+ }
+ : emptyOutput(program),
+ );
+
+ const scan = await scanLockProcesses();
+ expect(scan.candidates).toEqual([]);
+ expect(scan.unavailable).toEqual([expect.stringMatching(/TCP listeners.*lsof/)]);
+ expect(scan.unavailable[0]).toContain(code);
+ expect(scan.unavailable[0]).toContain('could not start listener producer');
+ });
+});
diff --git a/packages/server/src/process-scan-enumeration.test.ts b/packages/server/src/process-scan-enumeration.test.ts
new file mode 100644
index 000000000..8e88f2f68
--- /dev/null
+++ b/packages/server/src/process-scan-enumeration.test.ts
@@ -0,0 +1,272 @@
+import { join, resolve } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { spawnSync, spawn, execFileSync } = vi.hoisted(() => ({
+ spawnSync: vi.fn(),
+ spawn: vi.fn(),
+ execFileSync: vi.fn(),
+}));
+
+vi.mock('node:child_process', () => ({ spawnSync, spawn, execFileSync }));
+
+import { fakeChildProcess } from './process-scan.test-helper.ts';
+import { findOkProcessPids, scanLockProcesses } from './process-scan.ts';
+
+const originalPlatform = process.platform;
+const fixturePid = 24680;
+const lockDir = resolve('/missing/notes-é/.ok/local');
+const command = `node --ok-lock-dir-b64=${Buffer.from(lockDir).toString('base64url')}`;
+const row = `${fixturePid} ${command}`;
+const enobufs = Object.assign(new Error('output exceeds the buffered reader'), { code: 'ENOBUFS' });
+const unavailable = Object.assign(new Error('command not found'), { code: 'ENOENT' });
+
+function providePsStream(read: (args: string[]) => ReturnType<typeof fakeChildProcess>) {
+ spawn.mockImplementation((program: string, args: string[]) =>
+ program === 'lsof' ? fakeChildProcess({ stdout: [], status: 1 }) : read(args),
+ );
+}
+
+function providePsOutput(chunks: readonly (string | Buffer)[], code: number | null = 0) {
+ const stdout = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))).toString('utf8');
+ const readSync = (program: string) => {
+ if (program === 'ps') return { status: code, stdout };
+ if (program === 'lsof') return { status: 1, stdout: '', stderr: '' };
+ return { status: null, error: unavailable };
+ };
+ spawnSync.mockImplementation(readSync);
+ providePsStream(() => fakeChildProcess({ stdout: chunks, status: code }));
+ return readSync;
+}
+
+beforeEach(() => {
+ spawn.mockReset().mockImplementation((program: string) => {
+ if (program === 'lsof') return fakeChildProcess({ stdout: [], status: 1 });
+ throw new Error('unexpected process enumeration');
+ });
+ spawnSync.mockReset().mockImplementation((program: string) => {
+ if (program === 'lsof') return { status: 1, stdout: '', stderr: '' };
+ return { status: null, error: unavailable };
+ });
+ execFileSync.mockReset().mockReturnValue('S\n');
+ vi.spyOn(process, 'kill').mockReturnValue(true);
+});
+
+afterEach(() => {
+ Object.defineProperty(process, 'platform', { value: originalPlatform });
+ vi.restoreAllMocks();
+});
+
+describe('process enumeration', () => {
+ it.each(['darwin', 'linux'] as const)('discovers matching commands on %s', async (platform) => {
+ Object.defineProperty(process, 'platform', { value: platform });
+ const readSync = providePsOutput(['PID COMMAND\n', `${row}\n`]);
+ spawnSync.mockImplementation((program: string, args: string[]) => {
+ if (program !== 'pgrep') return readSync(program);
+ const fullCommand =
+ args.includes('-f') &&
+ args.includes('-a') &&
+ (platform !== 'darwin' || args.includes('-l'));
+ return { status: 0, stdout: fullCommand ? `${row}\n` : `${fixturePid}\n` };
+ });
+
+ expect(await findOkProcessPids()).toEqual([fixturePid]);
+ });
+
+ it.each(['missing pgrep', 'PID-only pgrep', 'buffered pgrep overflow'])(
+ 'discovers marked processes after an oversized listing with %s',
+ async (mode) => {
+ const unrelated = ' 12345 /usr/bin/unrelated-service\n';
+ const nodeDefaultMaxBuffer = 1024 * 1024;
+ const repeats = Math.ceil(nodeDefaultMaxBuffer / Buffer.byteLength(unrelated));
+ spawnSync.mockImplementation((program: string) => {
+ if (program === 'pgrep') {
+ if (mode === 'PID-only pgrep') return { status: 0, stdout: `${fixturePid}\n` };
+ return { status: null, error: mode === 'missing pgrep' ? unavailable : enobufs };
+ }
+ if (program === 'ps')
+ return { status: 0, error: enobufs, stdout: unrelated.repeat(repeats) };
+ return { status: 1, stdout: '', stderr: '' };
+ });
+ providePsStream(() =>
+ fakeChildProcess({
+ stdout: (function* () {
+ yield 'PID COMMAND\n';
+ for (let index = 0; index < repeats; index++) yield unrelated;
+ yield row;
+ })(),
+ }),
+ );
+
+ expect(await scanLockProcesses()).toEqual({
+ candidates: [{ lockDir, pid: fixturePid, source: 'lock-dir-argument' }],
+ unavailable: [],
+ });
+ },
+ );
+
+ it('retains project paths split across byte chunks and an unterminated final row', async () => {
+ const project = resolve('/missing/notes-é');
+ const output = Buffer.from(
+ `PID COMMAND\n12345 /usr/bin/unrelated-service\n${fixturePid} node --ok-project-path=${project}`,
+ );
+ providePsOutput(Array.from(output, (byte) => Buffer.from([byte])));
+
+ expect(await scanLockProcesses()).toEqual({
+ candidates: [
+ { lockDir: join(project, '.ok', 'local'), pid: fixturePid, source: 'project-argument' },
+ { lockDir: join(project, '.ok'), pid: fixturePid, source: 'project-argument' },
+ ],
+ unavailable: [],
+ });
+ });
+
+ it('keeps carriage returns inside a process command', async () => {
+ providePsOutput(['PID COMMAND\n12345 unrelated\r97531 open-knowledge-server notes\n', row]);
+
+ expect(await scanLockProcesses()).toEqual({
+ candidates: [{ lockDir, pid: fixturePid, source: 'lock-dir-argument' }],
+ unavailable: [],
+ });
+ });
+
+ it.each([1, null])('discards an incomplete listing with exit status %s', async (code) => {
+ providePsOutput(['PID COMMAND\n', row], code);
+
+ expect(await scanLockProcesses()).toEqual({
+ candidates: [],
+ unavailable: [expect.stringContaining('Could not enumerate processes')],
+ });
+ expect(await findOkProcessPids()).toEqual([]);
+ });
+
+ it('keeps multiline command text within its owning process', async () => {
+ Object.defineProperty(process, 'platform', { value: 'darwin' });
+ const readSync = providePsOutput([
+ 'PID COMMAND\n',
+ '13579 unrelated\\01297531 open-knowledge-server notes\n',
+ `${row}\n`,
+ ]);
+ spawnSync.mockImplementation((program: string, args: string[]) => {
+ if (program !== 'pgrep') return readSync(program);
+ return {
+ status: 0,
+ stdout: args.includes('-l')
+ ? `13579 unrelated\n97531 open-knowledge-server notes\n${row}\n`
+ : `13579\n${fixturePid}\n`,
+ };
+ });
+
+ expect(await scanLockProcesses()).toEqual({
+ candidates: [{ lockDir, pid: fixturePid, source: 'lock-dir-argument' }],
+ unavailable: [],
+ });
+ });
+
+ it('discovers accepted dev commands alongside a matching server on Linux', async () => {
+ Object.defineProperty(process, 'platform', { value: 'linux' });
+ const project = resolve('/missing/dev-project');
+ const devPid = 13579;
+ const readSync = providePsOutput([
+ 'PID COMMAND\n',
+ `${row}\n`,
+ `${devPid} /usr/local/bin/bun run dev\n`,
+ ]);
+ spawnSync.mockImplementation((program: string, args: string[]) => {
+ if (program === 'pgrep') return { status: 0, stdout: `${row}\n` };
+ if (program === 'lsof' && args.includes('cwd'))
+ return { status: 0, stdout: `p${devPid}\nn${project}\n` };
+ return readSync(program);
+ });
+
+ expect(await scanLockProcesses()).toEqual({
+ candidates: [
+ { lockDir, pid: fixturePid, source: 'lock-dir-argument' },
+ { lockDir: join(project, '.ok', 'local'), pid: devPid, source: 'process-cwd' },
+ { lockDir: join(project, '.ok'), pid: devPid, source: 'process-cwd' },
+ ],
+ unavailable: [],
+ });
+ });
+
+ it('retains trailing command arguments under a narrow Linux display width', async () => {
+ Object.defineProperty(process, 'platform', { value: 'linux' });
+ const narrow = `PID COMMAND\n${fixturePid} /usr/local/node`;
+ const complete = `PID COMMAND\n${row}`;
+ const outputFor = (args: string[]) =>
+ args.includes('-ww') || args.filter((arg) => arg === '-w').length === 2 ? complete : narrow;
+ providePsStream((args) => fakeChildProcess({ stdout: [outputFor(args)] }));
+ spawnSync.mockImplementation((program: string, args: string[]) => {
+ if (program === 'ps') return { status: 0, stdout: outputFor(args) };
+ if (program === 'lsof') return { status: 1, stdout: '', stderr: '' };
+ return { status: null, error: unavailable };
+ });
+
+ expect(await scanLockProcesses()).toEqual({
+ candidates: [{ lockDir, pid: fixturePid, source: 'lock-dir-argument' }],
+ unavailable: [],
+ });
+ });
+
+ it('retains existing candidate discovery with Windows Unix tools', async () => {
+ Object.defineProperty(process, 'platform', { value: 'win32' });
+ spawnSync.mockImplementation((program: string) => {
+ if (program === 'pgrep') return { status: 0, stdout: `${row}\n` };
+ if (program === 'lsof') return { status: 1, stdout: '', stderr: '' };
+ return { status: null, error: unavailable };
+ });
+
+ expect(await scanLockProcesses(() => ({ onProbeFailure: () => {} }))).toEqual({
+ candidates: [{ lockDir, pid: fixturePid, source: 'lock-dir-argument' }],
+ unavailable: [],
+ });
+ });
+
+ it('reports a listing read failure even after receiving a matching row', async () => {
+ const readError = Object.assign(new Error('could not read output'), { code: 'EIO' });
+ spawnSync.mockImplementation((program: string) => {
+ if (program === 'ps') return { status: 0, stdout: `PID COMMAND\n${row}`, error: readError };
+ return { status: null, error: unavailable };
+ });
+ providePsStream(() =>
+ fakeChildProcess({
+ stdout: (async function* () {
+ yield `PID COMMAND\n${row}\n`;
+ throw readError;
+ })(),
+ }),
+ );
+
+ expect(await scanLockProcesses()).toEqual({
+ candidates: [],
+ unavailable: [expect.stringContaining('Could not enumerate processes')],
+ });
+ });
+
+ it('reports an empty response as unavailable', async () => {
+ providePsOutput([]);
+
+ expect(await scanLockProcesses()).toEqual({
+ candidates: [],
+ unavailable: [expect.stringContaining('Could not enumerate processes')],
+ });
+ });
+
+ it('accepts a complete listing without matching processes', async () => {
+ providePsOutput(['PID COMMAND\n12345 /usr/bin/unrelated-service\n']);
+
+ expect(await scanLockProcesses()).toEqual({ candidates: [], unavailable: [] });
+ });
+
+ it.each(['darwin', 'linux', 'win32'] as const)(
+ 'reports a process listing that cannot start on %s',
+ async (platform) => {
+ Object.defineProperty(process, 'platform', { value: platform });
+ providePsStream(() => fakeChildProcess({ stdout: [], status: null, error: unavailable }));
+
+ expect(await scanLockProcesses()).toEqual({
+ candidates: [],
+ unavailable: [expect.stringContaining('Could not enumerate processes')],
+ });
+ },
+ );
+});
diff --git a/packages/server/src/process-scan.test-helper.ts b/packages/server/src/process-scan.test-helper.ts
new file mode 100644
index 000000000..74dcfb4d4
--- /dev/null
+++ b/packages/server/src/process-scan.test-helper.ts
@@ -0,0 +1,29 @@
+import { EventEmitter } from 'node:events';
+import { Readable } from 'node:stream';
+
+export interface FakeChildProcessInput {
+ stdout: Iterable<string | Buffer> | AsyncIterable<string | Buffer>;
+ stderr?: string;
+ status?: number | null;
+ signal?: NodeJS.Signals | null;
+ killed?: boolean;
+ error?: Error;
+}
+
+export function fakeChildProcess(input: FakeChildProcessInput) {
+ const child = Object.assign(new EventEmitter(), {
+ stdout: Readable.from(input.stdout),
+ stderr: Readable.from(input.stderr === undefined ? [] : [input.stderr]),
+ killed: input.killed ?? false,
+ });
+ let open = 2;
+ for (const stream of [child.stdout, child.stderr]) {
+ stream.on('close', () => {
+ if (--open === 0)
+ child.emit('close', input.status === undefined ? 0 : input.status, input.signal ?? null);
+ });
+ }
+ const { error } = input;
+ if (error) process.nextTick(() => child.emit('error', error));
+ return child;
+}
diff --git a/packages/server/src/process-scan.test.ts b/packages/server/src/process-scan.test.ts
index 456facc18..7ce7db984 100644
--- a/packages/server/src/process-scan.test.ts
+++ b/packages/server/src/process-scan.test.ts
@@ -1,7 +1,10 @@
import type { SpawnSyncReturns } from 'node:child_process';
import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { fakeChildProcess } from './process-scan.test-helper.ts';
-const spawnSyncMock = vi.fn();
+const realPlatform = process.platform;
+const spawnSyncMock =
+ vi.fn<(command: string, args: readonly string[]) => SpawnSyncReturns<string>>();
const execFileSyncMock = vi.fn();
const existsSyncMock = vi.fn();
const readdirSyncMock = vi.fn();
@@ -20,10 +23,20 @@ let realFs: typeof import('node:fs');
beforeAll(async () => {
realCp = await vi.importActual<typeof import('node:child_process')>('node:child_process');
realFs = await vi.importActual<typeof import('node:fs')>('node:fs');
- execFileSyncMock.mockImplementation(realCp.execFileSync);
+ execFileSyncMock.mockReturnValue('S\n');
vi.doMock('node:child_process', () => ({
...realCp,
spawnSync: spawnSyncMock,
+ spawn: (command: string, args: string[]) => {
+ const result = spawnSyncMock(command, args);
+ return fakeChildProcess({
+ stdout: [result.stdout ?? ''],
+ stderr: result.stderr,
+ status: result.status,
+ signal: result.signal,
+ error: result.error,
+ });
+ },
execFileSync: execFileSyncMock,
}));
vi.doMock('node:fs', () => ({
@@ -43,6 +56,16 @@ beforeAll(async () => {
} = await import('./process-scan.ts'));
});
+beforeEach(() => {
+ Object.defineProperty(process, 'platform', { value: 'darwin', configurable: true });
+ vi.spyOn(process, 'kill').mockReturnValue(true);
+});
+
+afterEach(() => {
+ Object.defineProperty(process, 'platform', { value: realPlatform, configurable: true });
+ vi.restoreAllMocks();
+});
+
function refuseUnmockedSpawn(command: string, args: readonly string[] = []): never {
throw new Error(`unmocked spawnSync escaped to the host: ${command} ${args.join(' ')}`);
}
@@ -60,10 +83,11 @@ function makeSpawnResult(overrides: Partial<SpawnSyncReturns<string>>): SpawnSyn
};
}
-describe('findOkProcessPids', () => {
+describe('findOkProcessPids with Windows Unix tools', () => {
let spawnSyncSpy: typeof spawnSyncMock;
beforeEach(() => {
+ Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
spawnSyncMock.mockReset().mockImplementation(refuseUnmockedSpawn);
spawnSyncSpy = spawnSyncMock;
});
@@ -148,8 +172,7 @@ describe('findOkProcessPids', () => {
.mockReturnValueOnce(
makeSpawnResult({
stdout:
- 'PID COMMAND\n' +
- ' 99999 /usr/local/bin/open-knowledge start\n' +
+ 'PID COMMAND\n 99999 /usr/local/bin/open-knowledge start\n' +
' 123 some-other-process\n',
status: 0,
}),
@@ -339,7 +362,7 @@ describe('discoverLockDirs', () => {
spawnSyncSpy
.mockReturnValueOnce(
makeSpawnResult({
- stdout: '111 /usr/local/bin/bun /path/packages/cli/dist/cli.mjs start\n',
+ stdout: 'PID COMMAND\n111 /usr/local/bin/bun /path/packages/cli/dist/cli.mjs start\n',
status: 0,
}),
)
@@ -366,14 +389,14 @@ describe('discoverLockDirs', () => {
expect(dirs[0]).toContain('.ok/local');
const calls = spawnSyncSpy.mock.calls as [string, string[]][];
- expect(calls[0]?.[0]).toBe('pgrep');
+ expect(calls[0]?.[0]).toBe('ps');
expect(calls[1]?.[0]).toBe('lsof');
expect(calls[2]?.[0]).toBe('lsof');
});
it('returns empty array when no ok processes and no lock dirs exist', async () => {
spawnSyncSpy
- .mockReturnValueOnce(makeSpawnResult({ stdout: '', status: 1 }))
+ .mockReturnValueOnce(makeSpawnResult({ stdout: 'PID COMMAND\n', status: 0 }))
.mockReturnValueOnce(makeSpawnResult({ stdout: 'COMMAND PID USER\n', status: 0 }));
existsSyncSpy.mockReturnValue(false);
@@ -388,7 +411,7 @@ describe('discoverLockDirs', () => {
spawnSyncSpy
.mockReturnValueOnce(
makeSpawnResult({
- stdout: `77 /Applications/OpenKnowledge.app/Contents/Frameworks/OpenKnowledge Helper --type=utility --ok-lock-dir-b64=${encoded}\n`,
+ stdout: `PID COMMAND\n77 /Applications/OpenKnowledge.app/Contents/Frameworks/OpenKnowledge Helper --type=utility --ok-lock-dir-b64=${encoded}\n`,
status: 0,
}),
)
@@ -406,7 +429,7 @@ describe('discoverLockDirs', () => {
expect(dirs).toEqual([lockDir]);
const calls = spawnSyncSpy.mock.calls as [string, string[]][];
- expect(calls[0]?.[0]).toBe('pgrep');
+ expect(calls[0]?.[0]).toBe('ps');
expect(calls[1]?.[0]).toBe('lsof');
expect(calls[2]?.[0]).toBe('lsof');
});
@@ -418,7 +441,7 @@ describe('discoverLockDirs', () => {
spawnSyncSpy
.mockReturnValueOnce(
makeSpawnResult({
- stdout: `93943 /Applications/OpenKnowledge.app/Contents/Frameworks/OpenKnowledge Helper (Renderer).app/Contents/MacOS/OpenKnowledge Helper (Renderer) --type=renderer --ok-collab-url=ws://localhost:51473/collab --ok-project-path=${projectPath} --ok-project-name=garth_nix --seatbelt-client=53\n`,
+ stdout: `PID COMMAND\n93943 /Applications/OpenKnowledge.app/Contents/Frameworks/OpenKnowledge Helper (Renderer).app/Contents/MacOS/OpenKnowledge Helper (Renderer) --type=renderer --ok-collab-url=ws://localhost:51473/collab --ok-project-path=${projectPath} --ok-project-name=garth_nix --seatbelt-client=53\n`,
status: 0,
}),
)
@@ -438,7 +461,7 @@ describe('discoverLockDirs', () => {
.mockReturnValueOnce(
makeSpawnResult({
stdout:
- '93943 /Applications/OpenKnowledge Helper (Renderer) --type=renderer --ok-project-path=relative/notes --ok-project-name=notes\n',
+ 'PID COMMAND\n93943 /Applications/OpenKnowledge Helper (Renderer) --type=renderer --ok-project-path=relative/notes --ok-project-name=notes\n',
status: 0,
}),
)
@@ -458,7 +481,7 @@ describe('discoverLockDirs', () => {
spawnSyncSpy
.mockReturnValueOnce(
makeSpawnResult({
- stdout: '77 /usr/local/bin/ok ui\n',
+ stdout: 'PID COMMAND\n77 /usr/local/bin/ok ui\n',
status: 0,
}),
)
@@ -476,7 +499,7 @@ describe('discoverLockDirs', () => {
.mockReturnValueOnce(
makeSpawnResult({
stdout:
- '42 /Applications/OpenKnowledge.app/Contents/Frameworks/Helper --ok-lock-dir-b64=\n',
+ 'PID COMMAND\n42 /Applications/OpenKnowledge.app/Contents/Frameworks/Helper --ok-lock-dir-b64=\n',
status: 0,
}),
)
@@ -496,7 +519,7 @@ describe('discoverLockDirs', () => {
spawnSyncSpy
.mockReturnValueOnce(
makeSpawnResult({
- stdout: `42 /Applications/Helper --ok-lock-dir-b64=${encoded}\n`,
+ stdout: `PID COMMAND\n42 /Applications/Helper --ok-lock-dir-b64=${encoded}\n`,
status: 0,
}),
)
@@ -521,7 +544,7 @@ describe('discoverLockDirs', () => {
.mockReturnValueOnce(
makeSpawnResult({
stdout:
- '5816 /Applications/OpenKnowledge.app/Contents/Frameworks/OpenKnowledge Helper.app/Contents/MacOS/OpenKnowledge Helper --type=utility --utility-sub-type=node.mojom.NodeService\n',
+ 'PID COMMAND\n5816 /Applications/OpenKnowledge.app/Contents/Frameworks/OpenKnowledge Helper.app/Contents/MacOS/OpenKnowledge Helper --type=utility --utility-sub-type=node.mojom.NodeService\n',
status: 0,
}),
)
@@ -559,7 +582,7 @@ describe('discoverLockDirs', () => {
.mockReturnValueOnce(
makeSpawnResult({
stdout:
- '11 /usr/local/bin/ok start\n' +
+ 'PID COMMAND\n11 /usr/local/bin/ok start\n' +
'22 /Applications/OpenKnowledge.app/Contents/Frameworks/OpenKnowledge Helper.app/Contents/MacOS/OpenKnowledge Helper --type=utility --utility-sub-type=node.mojom.NodeService\n',
status: 0,
}),
@@ -603,7 +626,7 @@ describe('discoverLockDirs', () => {
.mockImplementation(() => makeSpawnResult({ error: enoent as NodeJS.ErrnoException }))
.mockReturnValueOnce(
makeSpawnResult({
- stdout: '55 /usr/local/bin/ok start\n',
+ stdout: 'PID COMMAND\n55 /usr/local/bin/ok start\n',
status: 0,
}),
);
@@ -624,7 +647,7 @@ describe('lock recovery process evidence', () => {
let stderrWrites: string[];
beforeEach(() => {
spawnSyncMock.mockReset();
- execFileSyncMock.mockReset().mockImplementation(realCp.execFileSync);
+ execFileSyncMock.mockReset().mockReturnValue('S\n');
stderrWrites = [];
vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array) => {
stderrWrites.push(String(chunk));
@@ -634,36 +657,44 @@ describe('lock recovery process evidence', () => {
afterEach(() => {
vi.restoreAllMocks();
spawnSyncMock.mockReset();
- execFileSyncMock.mockReset().mockImplementation(realCp.execFileSync);
+ execFileSyncMock.mockReset().mockReturnValue('S\n');
});
it('does not mistake failed process enumeration for evidence of absence', async () => {
- spawnSyncMock.mockReturnValue(makeSpawnResult({ status: 2, stderr: 'permission denied' }));
+ spawnSyncMock.mockReturnValue(
+ makeSpawnResult({ stdout: 'PID COMMAND\n', status: 2, stderr: 'permission denied' }),
+ );
const scan = await scanLockProcesses();
expect(scan.candidates).toEqual([]);
- expect(scan.unavailable).toEqual(['Could not enumerate processes with pgrep or ps']);
+ expect(scan.unavailable).toEqual([
+ expect.stringMatching(/ps.*exit status 2.*permission denied/),
+ ]);
});
it('accepts a successful empty process and listener scan', async () => {
- spawnSyncMock.mockReturnValue(makeSpawnResult({ status: 1 }));
+ spawnSyncMock
+ .mockReturnValueOnce(makeSpawnResult({ stdout: 'PID COMMAND\n' }))
+ .mockReturnValue(makeSpawnResult({ status: 1 }));
expect(await scanLockProcesses()).toEqual({ candidates: [], unavailable: [] });
});
it('retains listener inspection failures', async () => {
spawnSyncMock
- .mockReturnValueOnce(makeSpawnResult({ status: 1 }))
+ .mockReturnValueOnce(makeSpawnResult({ stdout: 'PID COMMAND\n', status: 0 }))
.mockReturnValueOnce(makeSpawnResult({ status: 1, stderr: 'permission denied' }));
expect((await scanLockProcesses()).unavailable).toEqual([
- 'Could not enumerate TCP listeners with lsof',
+ expect.stringMatching(/TCP listeners.*lsof.*exit status 1.*permission denied/),
]);
});
it('treats a listener query that exits non-zero with a table as incomplete enumeration', async () => {
- spawnSyncMock.mockReturnValueOnce(makeSpawnResult({ status: 1 })).mockReturnValueOnce(
- makeSpawnResult({
- status: 1,
- stdout: `COMMAND PID USER\nnode ${process.pid} user\n`,
- }),
- );
+ spawnSyncMock
+ .mockReturnValueOnce(makeSpawnResult({ stdout: 'PID COMMAND\n', status: 0 }))
+ .mockReturnValueOnce(
+ makeSpawnResult({
+ status: 1,
+ stdout: `COMMAND PID USER\nnode ${process.pid} user\n`,
+ }),
+ );
expect((await scanLockProcesses()).unavailable).toEqual([
- 'Could not enumerate TCP listeners with lsof',
+ expect.stringMatching(/TCP listeners.*lsof.*exit status 1/),
]);
});
it('keeps explicit process provenance even without a lock file on disk', async () => {
@@ -671,7 +702,7 @@ describe('lock recovery process evidence', () => {
spawnSyncMock
.mockReturnValueOnce(
makeSpawnResult({
- stdout: `${process.pid} node --ok-lock-dir-b64=${Buffer.from(lockDir).toString('base64url')}\n`,
+ stdout: `PID COMMAND\n${process.pid} node --ok-lock-dir-b64=${Buffer.from(lockDir).toString('base64url')}\n`,
}),
)
.mockReturnValueOnce(makeSpawnResult({ status: 1 }));
@@ -683,7 +714,9 @@ describe('lock recovery process evidence', () => {
it('recognizes the production server process title and its working directory', async () => {
spawnSyncMock
.mockReturnValueOnce(
- makeSpawnResult({ stdout: `${process.pid} open-knowledge-server notes\n` }),
+ makeSpawnResult({
+ stdout: `PID COMMAND\n${process.pid} open-knowledge-server notes\n`,
+ }),
)
.mockReturnValueOnce(makeSpawnResult({ status: 1 }))
.mockReturnValueOnce(makeSpawnResult({ stdout: `p${process.pid}\nfcwd\nn/notes\n` }));
@@ -696,7 +729,9 @@ describe('lock recovery process evidence', () => {
it('retains a live candidate with an unreadable working directory as uncertainty', async () => {
spawnSyncMock
.mockReturnValueOnce(
- makeSpawnResult({ stdout: `${process.pid} open-knowledge-server notes\n` }),
+ makeSpawnResult({
+ stdout: `PID COMMAND\n${process.pid} open-knowledge-server notes\n`,
+ }),
)
.mockReturnValueOnce(makeSpawnResult({ status: 1 }))
.mockReturnValueOnce(makeSpawnResult({ status: 1 }));
@@ -711,7 +746,9 @@ describe('lock recovery process evidence', () => {
});
spawnSyncMock
.mockReturnValueOnce(
- makeSpawnResult({ stdout: `${process.pid} open-knowledge-server notes\n` }),
+ makeSpawnResult({
+ stdout: `PID COMMAND\n${process.pid} open-knowledge-server notes\n`,
+ }),
)
.mockReturnValueOnce(makeSpawnResult({ status: 1 }))
.mockReturnValueOnce(makeSpawnResult({ status: 1 }));
@@ -738,7 +775,9 @@ describe('lock recovery process evidence', () => {
});
spawnSyncMock
.mockReturnValueOnce(
- makeSpawnResult({ stdout: `${process.pid} open-knowledge-server notes\n` }),
+ makeSpawnResult({
+ stdout: `PID COMMAND\n${process.pid} open-knowledge-server notes\n`,
+ }),
)
.mockReturnValueOnce(makeSpawnResult({ status: 1 }))
.mockReturnValueOnce(makeSpawnResult({ status: 1 }));
@@ -762,7 +801,9 @@ describe('lock recovery process evidence', () => {
});
spawnSyncMock
.mockReturnValueOnce(
- makeSpawnResult({ stdout: `${process.pid} open-knowledge-server notes\n` }),
+ makeSpawnResult({
+ stdout: `PID COMMAND\n${process.pid} open-knowledge-server notes\n`,
+ }),
)
.mockReturnValueOnce(makeSpawnResult({ status: 1 }))
.mockReturnValueOnce(makeSpawnResult({ status: 1 }));
@@ -786,7 +827,9 @@ describe('lock recovery process evidence', () => {
});
spawnSyncMock
.mockReturnValueOnce(
- makeSpawnResult({ stdout: `${process.pid} open-knowledge-server notes\n` }),
+ makeSpawnResult({
+ stdout: `PID COMMAND\n${process.pid} open-knowledge-server notes\n`,
+ }),
)
.mockReturnValueOnce(makeSpawnResult({ status: 1 }))
.mockReturnValueOnce(makeSpawnResult({ status: 1 }));
@@ -806,7 +849,9 @@ describe('lock recovery process evidence', () => {
});
spawnSyncMock
.mockReturnValueOnce(
- makeSpawnResult({ stdout: `${process.pid} open-knowledge-server notes\n` }),
+ makeSpawnResult({
+ stdout: `PID COMMAND\n${process.pid} open-knowledge-server notes\n`,
+ }),
)
.mockReturnValueOnce(makeSpawnResult({ status: 1 }))
.mockReturnValueOnce(makeSpawnResult({ status: 1 }));
@@ -828,7 +873,7 @@ describe('lock recovery process evidence', () => {
spawnSyncMock
.mockReturnValueOnce(
makeSpawnResult({
- stdout: `${process.pid} open-knowledge-server notes\n${process.pid} node cli.mjs --ok-project-path=/notes\n`,
+ stdout: `PID COMMAND\n${process.pid} open-knowledge-server notes\n${process.pid} node cli.mjs --ok-project-path=/notes\n`,
}),
)
.mockReturnValueOnce(makeSpawnResult({ status: 1 }))
@@ -850,7 +895,9 @@ describe('lock recovery process evidence', () => {
it('retains a live candidate the batched query could not answer for', async () => {
spawnSyncMock
.mockReturnValueOnce(
- makeSpawnResult({ stdout: `${process.pid} open-knowledge-server notes\n` }),
+ makeSpawnResult({
+ stdout: `PID COMMAND\n${process.pid} open-knowledge-server notes\n`,
+ }),
)
.mockReturnValueOnce(makeSpawnResult({ status: 1 }))
.mockReturnValueOnce(makeSpawnResult({ stdout: 'p1\nfcwd\nn/other\n', status: 0 }));
@@ -863,7 +910,7 @@ describe('lock recovery process evidence', () => {
spawnSyncMock
.mockReturnValueOnce(
makeSpawnResult({
- stdout: pids.map((pid) => `${pid} open-knowledge-server notes`).join('\n'),
+ stdout: `PID COMMAND\n${pids.map((pid) => `${pid} open-knowledge-server notes`).join('\n')}`,
}),
)
.mockReturnValueOnce(makeSpawnResult({ status: 1 }))
@@ -888,7 +935,7 @@ describe('lock recovery process evidence', () => {
});
it('keeps listener provenance without asserting the process is an OpenKnowledge server', async () => {
spawnSyncMock
- .mockReturnValueOnce(makeSpawnResult({ status: 1 }))
+ .mockReturnValueOnce(makeSpawnResult({ stdout: 'PID COMMAND\n', status: 0 }))
.mockReturnValueOnce(
makeSpawnResult({ stdout: `COMMAND PID USER\nnode ${process.pid} user\n` }),
)
@@ -915,7 +962,7 @@ describe('isDefunctProcess', () => {
afterEach(() => {
Object.defineProperty(process, 'platform', { value: realPlatform, configurable: true });
vi.restoreAllMocks();
- execFileSyncMock.mockReset().mockImplementation(realCp.execFileSync);
+ execFileSyncMock.mockReset().mockReturnValue('S\n');
});
it('skips the probe entirely on an unsupported platform', () => {
@@ -964,7 +1011,7 @@ describe('readProcessState', () => {
afterEach(() => {
Object.defineProperty(process, 'platform', { value: realPlatform, configurable: true });
vi.restoreAllMocks();
- execFileSyncMock.mockReset().mockImplementation(realCp.execFileSync);
+ execFileSyncMock.mockReset().mockReturnValue('S\n');
});
it('tells a confirmed absence apart from a confirmed live process', () => {
@@ -1002,7 +1049,7 @@ describe('isLockProcessRunning', () => {
afterEach(() => {
Object.defineProperty(process, 'platform', { value: realPlatform, configurable: true });
vi.restoreAllMocks();
- execFileSyncMock.mockReset().mockImplementation(realCp.execFileSync);
+ execFileSyncMock.mockReset().mockReturnValue('S\n');
});
it('lets a probe-confirmed absence override a process that was alive a moment earlier', () => {
diff --git a/packages/server/src/process-scan.ts b/packages/server/src/process-scan.ts
index 129d7e472..9b14fc1e9 100644
--- a/packages/server/src/process-scan.ts
+++ b/packages/server/src/process-scan.ts
@@ -1,7 +1,8 @@
-import { execFileSync, spawnSync } from 'node:child_process';
+import { execFileSync, spawn, spawnSync } from 'node:child_process';
import { existsSync, lstatSync, readdirSync } from 'node:fs';
import { realpath } from 'node:fs/promises';
import { basename, isAbsolute, join, resolve } from 'node:path';
+import type { Readable } from 'node:stream';
import {
LOCAL_OP_PIPE_STDIO_OPTIONS,
withHiddenWindowsConsole,
@@ -13,6 +14,7 @@ const LOCK_SCAN_MAX_DEPTH = 3;
const LOCK_SCAN_MAX_ENTRIES = 2000;
const OK_LOCK_DIR_ARG_PREFIX = '--ok-lock-dir-b64=';
const OK_PROJECT_PATH_ARG_PREFIX = '--ok-project-path=';
+const LISTENER_QUERY_ARGS = ['-iTCP', '-sTCP:LISTEN', '-nP'];
const OK_PROCESS_PGREP_QUERY =
'cli\\.mjs|open-knowledge|Open ?Knowledge(\\.app| Helper)|--ok-lock-dir-b64=|--ok-project-path=|(^|[ /])ok[ ]+(start|mcp|ui)([ ]|$)|packages/(cli|app)|hocuspocus|vite';
@@ -80,62 +82,165 @@ function parsePgrepOutput(output: string): OkProcessEntry[] {
return entries;
}
-function parsePsOutput(output: string): OkProcessEntry[] {
+interface ListingResult {
+ code: number | null;
+ signal: NodeJS.Signals | null;
+ timedOut: boolean;
+ hasStdout: boolean;
+ hasStderr: boolean;
+ diagnostic: string;
+}
+
+function readCommandLines(
+ program: string,
+ args: string[],
+ onLine: (line: string) => void,
+): Promise<ListingResult> {
+ return new Promise((resolveResult, reject) => {
+ const child = spawn(
+ program,
+ args,
+ withHiddenWindowsConsole({
+ ...LOCAL_OP_PIPE_STDIO_OPTIONS,
+ timeout: SPAWN_TIMEOUT_MS,
+ env: {
+ ...process.env,
+ LC_CTYPE: process.env.LC_ALL || process.env.LC_CTYPE,
+ LC_ALL: undefined,
+ LC_MESSAGES: 'C',
+ },
+ }),
+ );
+ let hasStdout = false;
+ let hasStderr = false;
+ let diagnostic = '';
+ child.once('error', reject);
+ const readLines = (stream: Readable, visit: (line: string) => void) => {
+ let pending = '';
+ stream.once('error', reject);
+ stream.setEncoding('utf8');
+ stream.on('data', (chunk: string) => {
+ pending += chunk;
+ let newline = pending.indexOf('\n');
+ while (newline !== -1) {
+ visit(pending.slice(0, newline));
+ pending = pending.slice(newline + 1);
+ newline = pending.indexOf('\n');
+ }
+ });
+ stream.once('end', () => {
+ if (pending) visit(pending);
+ });
+ };
+ readLines(child.stdout, (line) => {
+ hasStdout = true;
+ onLine(line);
+ });
+ readLines(child.stderr, (line) => {
+ hasStderr = true;
+ diagnostic ||= line.trim();
+ });
+ child.once('close', (code, signal) => {
+ resolveResult({ code, signal, timedOut: child.killed, hasStdout, hasStderr, diagnostic });
+ });
+ });
+}
+
+function describeListingError(error: unknown): string {
+ if (!(error instanceof Error)) return String(error);
+ const code = (error as NodeJS.ErrnoException).code;
+ return code ? `${code}: ${error.message}` : error.message;
+}
+
+function describeListingResult(result: ListingResult): string {
+ const completion = result.signal ? `signal ${result.signal}` : `exit status ${result.code}`;
+ const ending = result.timedOut
+ ? `timed out after ${SPAWN_TIMEOUT_MS} ms (${completion})`
+ : completion;
+ return `${ending}${result.diagnostic ? `: ${result.diagnostic}` : ''}`;
+}
+
+class PsListingError extends Error {
+ readonly result: ListingResult;
+
+ constructor(result: ListingResult) {
+ super(describeListingResult(result));
+ this.result = result;
+ }
+}
+
+async function readPsEntries(args: string[]): Promise<OkProcessEntry[]> {
const entries: OkProcessEntry[] = [];
- const lines = output.split('\n');
- for (let i = 1; i < lines.length; i++) {
- const line = lines[i]?.trim();
- if (!line) continue;
- const spaceIdx = line.indexOf(' ');
- if (spaceIdx === -1) continue;
- const pidStr = line.slice(0, spaceIdx);
- const command = line.slice(spaceIdx + 1).trim();
- const pid = Number.parseInt(pidStr, 10);
- if (!Number.isNaN(pid) && isOkProcess(command)) {
- entries.push({ pid, command });
+ let header = true;
+ const result = await readCommandLines('ps', args, (line) => {
+ if (header) {
+ header = false;
+ return;
}
+ const trimmed = line.trim();
+ const spaceIdx = trimmed.indexOf(' ');
+ if (spaceIdx === -1) return;
+ const pid = Number.parseInt(trimmed.slice(0, spaceIdx), 10);
+ const command = trimmed.slice(spaceIdx + 1).trim();
+ if (!Number.isNaN(pid) && isOkProcess(command)) entries.push({ pid, command });
+ });
+ if (result.code !== 0 || result.signal) {
+ throw new PsListingError(result);
}
+ if (header) throw new Error('no process table returned');
return entries;
}
async function findOkProcessEntries(strict = false): Promise<OkProcessEntry[]> {
- const pgrepResult = spawnSync(
- 'pgrep',
- ['-a', '-f', OK_PROCESS_PGREP_QUERY],
- withHiddenWindowsConsole({
- encoding: 'utf-8',
- timeout: SPAWN_TIMEOUT_MS,
- }),
- );
+ const failures: string[] = [];
+ const unix = process.platform === 'darwin' || process.platform === 'linux';
+ if (!unix) {
+ const pgrepResult = spawnSync(
+ 'pgrep',
+ ['-a', '-f', OK_PROCESS_PGREP_QUERY],
+ withHiddenWindowsConsole({
+ encoding: 'utf-8',
+ timeout: SPAWN_TIMEOUT_MS,
+ }),
+ );
- const pgrepUnavailable =
- pgrepResult.error != null && (pgrepResult.error as NodeJS.ErrnoException).code === 'ENOENT';
-
- if (
- !pgrepUnavailable &&
- !pgrepResult.error &&
- (pgrepResult.status === 0 || pgrepResult.status === 1)
- ) {
- const output = pgrepResult.stdout ?? '';
- const entries = parsePgrepOutput(output);
- if (entries.length > 0 || output.trim() === '') return entries;
+ if (!pgrepResult.error && (pgrepResult.status === 0 || pgrepResult.status === 1)) {
+ const output = pgrepResult.stdout ?? '';
+ const entries = parsePgrepOutput(output);
+ if (entries.length > 0 || output.trim() === '') return entries;
+ failures.push('pgrep: no command rows returned');
+ } else {
+ failures.push(
+ `pgrep: ${pgrepResult.error ? describeListingError(pgrepResult.error) : `exit status ${pgrepResult.status}`}`,
+ );
+ }
}
- const psResult = spawnSync(
- 'ps',
- ['-axo', 'pid,command'],
- withHiddenWindowsConsole({
- encoding: 'utf-8',
- timeout: SPAWN_TIMEOUT_MS,
- }),
- );
-
- if (psResult.error != null || psResult.status !== 0 || !psResult.stdout) {
- if (strict) throw new Error('Could not enumerate processes with pgrep or ps');
- return [];
+ const formats =
+ process.platform === 'linux'
+ ? [
+ ['-ww', '-A', '-o', 'pid,cmdline'],
+ ['-ww', '-A', '-o', 'pid,args'],
+ ['-A', '-o', 'pid,args'],
+ ]
+ : unix
+ ? [['-ww', '-A', '-o', 'pid,args']]
+ : [['-axo', 'pid,command']];
+ for (const args of formats) {
+ try {
+ return await readPsEntries(args);
+ } catch (error) {
+ failures.push(`ps (${args.join(' ')}): ${describeListingError(error)}`);
+ const unsupportedFormat =
+ error instanceof PsListingError &&
+ error.result.code === 1 &&
+ !error.result.signal &&
+ !error.result.hasStdout;
+ if (!unsupportedFormat) break;
+ }
}
-
- return parsePsOutput(psResult.stdout);
+ if (strict) throw new Error(`Could not enumerate processes: ${failures.join('; ')}`);
+ return [];
}
export async function findOkProcessPids(): Promise<number[]> {
@@ -322,20 +427,23 @@ export function readPidCwds(pids: readonly number[]): Map<number, string> {
return cwds;
}
-function parseListeningPids(output: string): number[] {
- const pids: number[] = [];
- const lines = output.split('\n');
- for (let i = 1; i < lines.length; i++) {
- const line = lines[i]?.trim();
- if (!line) continue;
- const parts = line.split(/\s+/);
- if (parts.length < 2) continue;
- const pid = Number.parseInt(parts[1] ?? '', 10);
- if (!Number.isNaN(pid)) {
- pids.push(pid);
+async function readListeningPids(strict = false): Promise<number[]> {
+ const pids = new Set<number>();
+ let header = true;
+ const result = await readCommandLines('lsof', LISTENER_QUERY_ARGS, (line) => {
+ if (header) {
+ header = false;
+ return;
}
+ const parts = line.trim().split(/\s+/);
+ const pid = Number.parseInt(parts[1] ?? '', 10);
+ if (!Number.isNaN(pid)) pids.add(pid);
+ });
+ const noListeners = result.code === 1 && !result.hasStdout && !result.hasStderr;
+ if (result.signal || result.code === null || (strict && result.code !== 0 && !noListeners)) {
+ throw new Error(describeListingResult(result));
}
- return [...new Set(pids)];
+ return [...pids];
}
function hasLockFile(lockDir: string): boolean {
@@ -410,17 +518,8 @@ export async function discoverLockDirs(): Promise<string[]> {
addLockDirsForCwd(candidateDirs, cwd);
}
- const lsofResult = spawnSync(
- 'lsof',
- ['-iTCP', '-sTCP:LISTEN', '-nP'],
- withHiddenWindowsConsole({
- encoding: 'utf-8',
- timeout: SPAWN_TIMEOUT_MS,
- }),
- );
-
- if (lsofResult.error == null && lsofResult.stdout) {
- const listeningPids = parseListeningPids(lsofResult.stdout);
+ const listeningPids = await readListeningPids().catch(() => null);
+ if (listeningPids !== null) {
const knownPidSet = new Set(okEntries.map((e) => e.pid));
const newPids = listeningPids.filter((p) => !knownPidSet.has(p));
const portCwdsByPid = readPidCwds(newPids);
@@ -505,22 +604,16 @@ export async function scanLockProcesses(
else if (project) await addProject(project, entry.pid, 'project-argument');
else pendingCwd.push({ pid: entry.pid, source: 'process-cwd' });
}
- const listeners = spawnSync(
- 'lsof',
- ['-iTCP', '-sTCP:LISTEN', '-nP'],
- withHiddenWindowsConsole({
- encoding: 'utf-8',
- timeout: SPAWN_TIMEOUT_MS,
- }),
- );
- const listenersUnavailable =
- listeners.error != null ||
- (listeners.status !== 0 && !(listeners.status === 1 && !listeners.stdout && !listeners.stderr));
- if (!listenersUnavailable) {
- const known = new Set(entries.map((entry) => entry.pid));
- for (const pid of parseListeningPids(listeners.stdout ?? '')) {
- if (isValidLockPid(pid) && !known.has(pid)) pendingCwd.push({ pid, source: 'listener-cwd' });
- }
+ let listeners: number[] = [];
+ let listenerFailure = '';
+ try {
+ listeners = await readListeningPids(true);
+ } catch (error) {
+ listenerFailure = `Could not enumerate TCP listeners: lsof (${LISTENER_QUERY_ARGS.join(' ')}): ${describeListingError(error)}`;
+ }
+ const known = new Set(entries.map((entry) => entry.pid));
+ for (const pid of listeners) {
+ if (isValidLockPid(pid) && !known.has(pid)) pendingCwd.push({ pid, source: 'listener-cwd' });
}
const cwds = readPidCwds(pendingCwd.map(({ pid }) => pid));
for (const { pid, source } of pendingCwd) {
@@ -529,7 +622,7 @@ export async function scanLockProcesses(
else if (isLockProcessRunning(pid, probeOptions(pid)))
scan.unavailable.push(`Could not read the working directory of process ${pid}`);
}
- if (listenersUnavailable) scan.unavailable.push('Could not enumerate TCP listeners with lsof');
+ if (listenerFailure) scan.unavailable.push(listenerFailure);
const defunctCandidates = new Set<number>();
for (const pid of new Set(scan.candidates.map((candidate) => candidate.pid))) {
if (isDefunctProcess(pid, probeOptions(pid))) defunctCandidates.add(pid);
diff --git a/packages/server/src/test-helper-caller-typecheck-coverage.test.ts b/packages/server/src/test-helper-caller-typecheck-coverage.test.ts
index a0e94a9c4..1efdd1f84 100644
--- a/packages/server/src/test-helper-caller-typecheck-coverage.test.ts
+++ b/packages/server/src/test-helper-caller-typecheck-coverage.test.ts
@@ -13,6 +13,7 @@ const HELPERS = [
'wait-within-test-budget.test-helper.ts',
'expect-stable.test-helper.ts',
'forked-watcher-process.test-helper.ts',
+ 'process-scan.test-helper.ts',
];
const UNSCANNED_DIRS = new Set(['node_modules', 'dist', '.turbo']);
diff --git a/packages/server/tsconfig.test-helper-callers.json b/packages/server/tsconfig.test-helper-callers.json
index 4d178fcca..348233549 100644
--- a/packages/server/tsconfig.test-helper-callers.json
+++ b/packages/server/tsconfig.test-helper-callers.json
@@ -11,6 +11,9 @@
"src/persistence-tripwire-block.test.ts",
"src/persistence-tripwire-paste.test.ts",
"src/polled-watcher-contract.test.ts",
+ "src/process-scan-collectors.test.ts",
+ "src/process-scan-enumeration.test.ts",
+ "src/process-scan.test.ts",
"src/serialize-doc-vs-git-show-byte-equality.test.ts",
"src/serialize-doc-ytext.test.ts",
"src/wait-within-test-budget.test.ts"