Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Fix process enumeration on busy hosts (#5155)
Nick Gomezc4adbe1fd9b8
diff --git a/.changeset/fix-process-enumeration.md b/.changeset/fix-process-enumeration.mdnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.jsonindex 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"