Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Collect unattributed macOS exit evidence (PRD-9658) (#7562)

Andrew Mikofalvycee01c9bb146
diff --git a/.changeset/prd-9658-unattributed-exit-evidence.md b/.changeset/prd-9658-unattributed-exit-evidence.md
new file mode 100644
index 000000000..7389f1652
--- /dev/null
+++ b/.changeset/prd-9658-unattributed-exit-evidence.md
@@ -0,0 +1,7 @@
+---
+'@inkeep/open-knowledge': patch
+'@inkeep/open-knowledge-server': patch
+'@inkeep/open-knowledge-desktop': patch
+---
+
+Bug reports now include the newest macOS update-installer logs, the machine's memory pressure before an unexpected exit, and which signal stopped the local server.
diff --git a/packages/cli/src/commands/bug-report-bundle.test.ts b/packages/cli/src/commands/bug-report-bundle.test.ts
index fee430b00..bbe96fa55 100644
--- a/packages/cli/src/commands/bug-report-bundle.test.ts
+++ b/packages/cli/src/commands/bug-report-bundle.test.ts
@@ -7,6 +7,7 @@ import {
readFileSync,
realpathSync,
rmSync,
+ utimesSync,
writeFileSync,
} from 'node:fs';
import { homedir, tmpdir } from 'node:os';
@@ -619,6 +620,49 @@ describe('collectShipItLogFiles — Squirrel.Mac install logs', () => {
expect(names).toEqual(['ShipIt_stderr.log', 'ShipIt_stderr.log.1', 'ShipIt_stdout.log.2']);
});
+ test('keeps the newest fallback logs when Squirrel has left more than four', () => {
+ const cachesDir = makeTmpDir();
+ const names = ['', '.1', '.2', '.3', '.4', '.5'].map((suffix) => `ShipIt_stderr.log${suffix}`);
+ names.forEach((name, index) => {
+ writeAt(cachesDir, `${DESKTOP_BUNDLE_ID}.ShipIt/${name}`, `run ${index}\n`);
+ const at = new Date(Date.UTC(2026, 9, 1 + index));
+ utimesSync(join(cachesDir, `${DESKTOP_BUNDLE_ID}.ShipIt`, name), at, at);
+ });
+
+ const collected = collectShipItLogFiles(cachesDir)
+ .map((f) => basename(f))
+ .sort();
+
+ expect(collected).toEqual([
+ 'ShipIt_stderr.log.2',
+ 'ShipIt_stderr.log.3',
+ 'ShipIt_stderr.log.4',
+ 'ShipIt_stderr.log.5',
+ ]);
+ });
+
+ test('orders fallback logs by when they were written, not by suffix', () => {
+ const cachesDir = makeTmpDir();
+ const writtenOldestFirst = ['.1', '.2', '.3', '.4', '.5', ''];
+ writtenOldestFirst.forEach((suffix, index) => {
+ const name = `ShipIt_stderr.log${suffix}`;
+ writeAt(cachesDir, `${DESKTOP_BUNDLE_ID}.ShipIt/${name}`, `run ${index}\n`);
+ const at = new Date(Date.UTC(2026, 9, 1 + index));
+ utimesSync(join(cachesDir, `${DESKTOP_BUNDLE_ID}.ShipIt`, name), at, at);
+ });
+
+ const collected = collectShipItLogFiles(cachesDir)
+ .map((f) => basename(f))
+ .sort();
+
+ expect(collected).toEqual([
+ 'ShipIt_stderr.log',
+ 'ShipIt_stderr.log.3',
+ 'ShipIt_stderr.log.4',
+ 'ShipIt_stderr.log.5',
+ ]);
+ });
+
test('ignores neighbours that merely start with a ShipIt log name', () => {
const cachesDir = makeTmpDir();
writeAt(cachesDir, `${DESKTOP_BUNDLE_ID}.ShipIt/ShipIt_stderr.log.1`, 'ours\n');
@@ -641,10 +685,10 @@ describe('collectShipItLogFiles — Squirrel.Mac install logs', () => {
const names = collectShipItLogFiles(cachesDir).map((f) => basename(f));
expect(names).toEqual([
- 'ShipIt_stderr.log',
- 'ShipIt_stderr.log.1',
- 'ShipIt_stderr.log.2',
- 'ShipIt_stderr.log.3',
+ 'ShipIt_stderr.log.12',
+ 'ShipIt_stderr.log.11',
+ 'ShipIt_stderr.log.10',
+ 'ShipIt_stderr.log.9',
]);
});
diff --git a/packages/cli/src/commands/bug-report-bundle.ts b/packages/cli/src/commands/bug-report-bundle.ts
index d9403f0be..9f981d059 100644
--- a/packages/cli/src/commands/bug-report-bundle.ts
+++ b/packages/cli/src/commands/bug-report-bundle.ts
@@ -1,6 +1,13 @@
import { execSync } from 'node:child_process';
import { createHash } from 'node:crypto';
-import { createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import {
+ createWriteStream,
+ existsSync,
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ statSync,
+} from 'node:fs';
import { freemem, type as osType, platform, release, totalmem, uptime } from 'node:os';
import { basename, dirname, join, resolve } from 'node:path';
import {
@@ -196,12 +203,24 @@ export function collectShipItLogFiles(
return /^\d+$/.test(suffix) ? { entry, suffix: Number(suffix) } : null;
})
.filter((match) => match !== null)
- .sort((a, b) => a.suffix - b.suffix)
+ .map((match) => {
+ const path = join(shipItDir, match.entry);
+ return { path, suffix: match.suffix, mtimeMs: readMtimeMs(path) };
+ })
+ .sort((a, b) => b.mtimeMs - a.mtimeMs || b.suffix - a.suffix)
.slice(0, SHIPIT_LOG_FILES_PER_STREAM)
- .map((match) => join(shipItDir, match.entry)),
+ .map((match) => match.path),
);
}
+function readMtimeMs(path: string): number {
+ try {
+ return statSync(path).mtimeMs;
+ } catch {
+ return 0;
+ }
+}
+
export const MAX_BUNDLED_LEDGER_REPORTS = 25;
export function collectBugReportLedgerFiles(bugReportsDir: string): string[] {
diff --git a/packages/cli/src/commands/single-file-open.ts b/packages/cli/src/commands/single-file-open.ts
index b220ceeff..f279076dd 100644
--- a/packages/cli/src/commands/single-file-open.ts
+++ b/packages/cli/src/commands/single-file-open.ts
@@ -124,19 +124,19 @@ async function runSingleFileBrowserOpen(
let tornDown = false;
let booted: Awaited<ReturnType<typeof bootStartServer>> | undefined;
- const teardown = async (): Promise<void> => {
+ const teardown = async (signal?: NodeJS.Signals): Promise<void> => {
if (tornDown) return;
tornDown = true;
try {
- await booted?.destroy('external-signal');
+ await booted?.destroy('external-signal', { signal });
} catch {}
try {
await rm(projectDir, { recursive: true, force: true });
} catch {}
};
- const onSignal = (): void => {
- void teardown().then(() => process.exit(0));
+ const onSignal = (signal: NodeJS.Signals): void => {
+ void teardown(signal).then(() => process.exit(0));
};
process.once('SIGINT', onSignal);
process.once('SIGTERM', onSignal);
diff --git a/packages/cli/src/commands/start.test.ts b/packages/cli/src/commands/start.test.ts
index 7ae7fc7ab..665efc329 100644
--- a/packages/cli/src/commands/start.test.ts
+++ b/packages/cli/src/commands/start.test.ts
@@ -947,6 +947,44 @@ describe('bootStartServer (integration)', () => {
}
});
+ test('--single-file ephemeral teardown records the signal that stopped it', async () => {
+ const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));
+ const shutdownRecords: Array<Record<string, unknown>> = [];
+ const record = (data: unknown, message?: string): void => {
+ if (message?.includes('shutdown initiated') === true) {
+ shutdownRecords.push(data as Record<string, unknown>);
+ }
+ };
+ const log = {
+ info: record,
+ warn: record,
+ error: record,
+ debug: record,
+ trace: record,
+ fatal: record,
+ } as unknown as NonNullable<Parameters<typeof bootStartServer>[0]['log']>;
+ try {
+ writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');
+ booted = await bootStartServer({
+ config: makeTestConfig(),
+ cwd: tmpDir,
+ host: TEST_HOST,
+ skipAutoInit: true,
+ singleFile: join(looseDir, 'note.md'),
+ log,
+ });
+ await booted.ready;
+
+ await booted.destroy('external-signal', { signal: 'SIGINT' });
+ booted = null;
+ expect(shutdownRecords).toEqual([
+ expect.objectContaining({ reason: 'external-signal', signal: 'SIGINT' }),
+ ]);
+ } finally {
+ await rm(looseDir, { recursive: true, force: true });
+ }
+ });
+
test('--single-file with a provided empty --project-dir seeds the synthesized config and boots', async () => {
const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));
const providedDir = await mkdtemp(resolve(tmpdir(), 'ok-ephemeral-'));
diff --git a/packages/cli/src/commands/start.ts b/packages/cli/src/commands/start.ts
index dfc56d597..ee6a64057 100644
--- a/packages/cli/src/commands/start.ts
+++ b/packages/cli/src/commands/start.ts
@@ -27,6 +27,7 @@ import {
lockAdvertisesUi,
type PinoLogger,
prepareSingleFileOpen,
+ type ServerExitDetail,
type ServerExitReason,
} from '@inkeep/open-knowledge-server';
import { Command, InvalidArgumentError, Option } from 'commander';
@@ -320,7 +321,7 @@ interface BootStartServerOptions {
export interface BootedStartServer {
httpServer: HttpServer;
- destroy: (reason?: ServerExitReason) => Promise<void>;
+ destroy: (reason?: ServerExitReason, detail?: ServerExitDetail) => Promise<void>;
lockDir: string;
contentDir: string;
port: number;
@@ -524,9 +525,9 @@ export async function bootStartServer(opts: BootStartServerOptions): Promise<Boo
const innerDestroy = booted.destroy;
const destroy = ownsEphemeralProjectDir
- ? async (): Promise<void> => {
+ ? async (...args: Parameters<typeof innerDestroy>): Promise<void> => {
try {
- await innerDestroy();
+ await innerDestroy(...args);
} finally {
await reapOwnedEphemeralDir();
}
@@ -804,7 +805,7 @@ export async function runStartCommand(configArg: Config, opts: StartCommandOptio
console.log(dim(` ${line}`));
}
try {
- await booted.destroy('external-signal');
+ await booted.destroy('external-signal', { signal });
} catch (err) {
console.error(
`${error('destroy() failed:')} ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`,
diff --git a/packages/desktop/src/main/desktop-process-observability.test.ts b/packages/desktop/src/main/desktop-process-observability.test.ts
index 288e654a7..7e1bc4362 100644
--- a/packages/desktop/src/main/desktop-process-observability.test.ts
+++ b/packages/desktop/src/main/desktop-process-observability.test.ts
@@ -7,6 +7,7 @@ import {
type ObservedBrowserWindow,
type ProcessMetricLike,
} from './desktop-process-observability.ts';
+import type { SystemMemorySample } from './system-memory-sample.ts';
interface TestWindow extends ObservedBrowserWindow {
emit(
@@ -107,7 +108,7 @@ function processMetric(input: {
};
}
-function harness() {
+function harness(options: { readSystemMemory?: () => SystemMemorySample } = {}) {
let nowMs = Date.parse('2026-09-22T19:25:00.000Z');
let metrics: ProcessMetricLike[] = [
processMetric({ pid: 100, type: 'Browser', workingSetSize: 50_000 }),
@@ -128,6 +129,7 @@ function harness() {
now: () => new Date(nowMs),
getAppMetrics: () => metrics,
getAllWindows: () => windows,
+ ...options,
logger: {
info: (payload) => info.push(payload),
warn: (payload) => warn.push(payload),
@@ -399,7 +401,18 @@ describe('desktop process observability', () => {
});
test('bounds each log line while retaining counts and the highest-memory processes', () => {
- const rig = harness();
+ const rig = harness({
+ readSystemMemory: () => ({
+ totalKb: 137_438_953_472,
+ freeKb: 137_438_953_472,
+ swapTotalKb: 137_438_953_472,
+ swapFreeKb: 137_438_953_472,
+ swapUsedKb: 137_438_953_472,
+ pressure: 'unreadable',
+ pressureReadAt: '2026-09-22T19:24:59.999Z',
+ pressureUnreadableCause: 'unparsed',
+ }),
+ });
rig.setMetrics(
Array.from({ length: 40 }, (_, index) =>
processMetric({
@@ -441,6 +454,7 @@ describe('desktop process observability', () => {
expect(sample.windowsTruncated).toBe(21 - MAX_DESKTOP_WINDOW_SAMPLE_ROWS);
expect(sample.windows).toHaveLength(MAX_DESKTOP_WINDOW_SAMPLE_ROWS);
expect((sample.windows[0] as { windowId?: number }).windowId).toBe(7);
+ expect(sample).toHaveProperty('systemMemory.pressure', 'unreadable');
const sampleBytes = Buffer.byteLength(JSON.stringify(sample));
const samplesPerDay = (24 * 60 * 60 * 1_000) / DESKTOP_PROCESS_SAMPLE_INTERVAL_MS;
expect(Number.isInteger(samplesPerDay)).toBe(true);
@@ -448,6 +462,43 @@ describe('desktop process observability', () => {
expect(sampleBytes * samplesPerDay).toBeLessThan(6 * 1024 * 1024);
});
+ test('records the machine memory state beside the app processes, and samples without it when unreadable', () => {
+ const info: Array<Record<string, unknown>> = [];
+ const warn: Array<Record<string, unknown>> = [];
+ let readSystemMemory = () => ({
+ totalKb: 16_777_216,
+ freeKb: 102_400,
+ swapUsedKb: 6_291_456,
+ pressure: 'critical' as const,
+ pressureReadAt: '2026-10-19T09:17:58.000Z',
+ });
+ const observability = createDesktopProcessObservability({
+ now: () => new Date('2026-10-19T09:17:59.000Z'),
+ getAppMetrics: () => [processMetric({ pid: 100, type: 'Browser', workingSetSize: 50_000 })],
+ getAllWindows: () => [],
+ readSystemMemory: () => readSystemMemory(),
+ logger: { info: (payload) => info.push(payload), warn: (payload) => warn.push(payload) },
+ setInterval: () => 1,
+ clearInterval: () => {},
+ });
+
+ observability.start();
+ readSystemMemory = () => {
+ throw new Error('sysinfo unavailable');
+ };
+ observability.sampleNow('renderer-ready');
+
+ expect(info[0]).toMatchObject({
+ event: 'desktop-process-observability.sample',
+ systemMemory: { freeKb: 102_400, swapUsedKb: 6_291_456, pressure: 'critical' },
+ });
+ expect(info[1]).toMatchObject({ trigger: 'renderer-ready', processes: [{ pid: 100 }] });
+ expect(info[1]).not.toHaveProperty('systemMemory');
+ expect(warn).toEqual([
+ expect.objectContaining({ event: 'desktop-process-observability.system-memory-failed' }),
+ ]);
+ });
+
test('stop is idempotent', () => {
const rig = harness();
rig.observability.start();
diff --git a/packages/desktop/src/main/desktop-process-observability.ts b/packages/desktop/src/main/desktop-process-observability.ts
index 67aaa7580..850242b51 100644
--- a/packages/desktop/src/main/desktop-process-observability.ts
+++ b/packages/desktop/src/main/desktop-process-observability.ts
@@ -1,3 +1,5 @@
+import type { SystemMemorySample } from './system-memory-sample.ts';
+
export const DESKTOP_PROCESS_SAMPLE_INTERVAL_MS = 60_000;
export const MAX_DESKTOP_PROCESS_SAMPLE_ROWS = 12;
export const MAX_DESKTOP_WINDOW_SAMPLE_ROWS = 8;
@@ -71,6 +73,7 @@ interface WindowSample {
interface DesktopProcessSample {
capturedAt: string;
+ systemMemory?: SystemMemorySample;
processCount: number;
processesTruncated: number;
processes: ProcessSample[];
@@ -100,6 +103,7 @@ export interface DesktopProcessObservabilityDeps<IntervalHandle> {
now(): Date;
getAppMetrics(): readonly ProcessMetricLike[];
getAllWindows(): readonly ObservedBrowserWindow[];
+ readSystemMemory?(): SystemMemorySample | null;
logger: DesktopProcessLogger;
setInterval(callback: () => void, ms: number): IntervalHandle;
clearInterval(handle: IntervalHandle): void;
@@ -220,6 +224,18 @@ export function createDesktopProcessObservability<IntervalHandle>(
return details;
};
+ const readSystemMemory = (): SystemMemorySample | null => {
+ try {
+ return deps.readSystemMemory?.() ?? null;
+ } catch (err) {
+ deps.logger.warn(
+ { event: 'desktop-process-observability.system-memory-failed', err },
+ 'desktop system memory read failed',
+ );
+ return null;
+ }
+ };
+
const capture = (): DesktopProcessSample | null => {
try {
const processes = deps
@@ -237,8 +253,10 @@ export function createDesktopProcessObservability<IntervalHandle>(
(left.windowId ?? Number.MAX_SAFE_INTEGER) -
(right.windowId ?? Number.MAX_SAFE_INTEGER),
);
+ const systemMemory = readSystemMemory();
return {
capturedAt: deps.now().toISOString(),
+ ...(systemMemory === null ? {} : { systemMemory }),
processCount: processes.length,
processesTruncated: Math.max(0, processes.length - MAX_DESKTOP_PROCESS_SAMPLE_ROWS),
processes: processes.slice(0, MAX_DESKTOP_PROCESS_SAMPLE_ROWS),
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index 203d03d09..cdc1b63a7 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -515,6 +515,7 @@ import {
windowRestoreKey,
} from './state-store.ts';
import { stopCommandLine } from './stop-command.ts';
+import { createMacMemoryPressureProbe, readSystemMemorySample } from './system-memory-sample.ts';
import { isTerminalAvailable, withTerminalCapabilityArg } from './terminal-capability.ts';
import {
isTerminalConsented,
@@ -6225,10 +6226,21 @@ function bootPrimaryInstance(): void {
);
startLocalCrashReporter(crashReporter);
+ const macMemoryPressure =
+ process.platform === 'darwin' ? createMacMemoryPressureProbe({ now: () => new Date() }) : null;
+ macMemoryPressure?.refresh();
desktopProcessObservability = createDesktopProcessObservability({
now: () => new Date(),
getAppMetrics: () => app.getAppMetrics(),
getAllWindows: () => BrowserWindow.getAllWindows(),
+ readSystemMemory: () => {
+ const sample = readSystemMemorySample(
+ process.getSystemMemoryInfo(),
+ macMemoryPressure?.latest() ?? null,
+ );
+ macMemoryPressure?.refresh();
+ return sample;
+ },
logger: getLogger('desktop-process-observability'),
setInterval: (callback, ms) => setInterval(callback, ms).unref(),
clearInterval: (handle) => clearInterval(handle),
diff --git a/packages/desktop/src/main/system-memory-sample.test.ts b/packages/desktop/src/main/system-memory-sample.test.ts
new file mode 100644
index 000000000..48428be18
--- /dev/null
+++ b/packages/desktop/src/main/system-memory-sample.test.ts
@@ -0,0 +1,136 @@
+import { describe, expect, test, vi } from 'vitest';
+import {
+ createMacMemoryPressureProbe,
+ parseMacMemorySysctl,
+ readSystemMemorySample,
+} from './system-memory-sample.ts';
+
+describe('parseMacMemorySysctl', () => {
+ test.each([
+ ['1', 'normal'],
+ ['2', 'warn'],
+ ['4', 'critical'],
+ ] as const)('maps pressure level %s to %s', (level, pressure) => {
+ expect(
+ parseMacMemorySysctl(
+ `${level}\ntotal = 2048.00M used = 1186.25M free = 861.75M (encrypted)\n`,
+ ),
+ ).toEqual({ pressure, swapUsedKb: 1_214_720 });
+ });
+
+ test('reads gigabyte swap figures', () => {
+ expect(
+ parseMacMemorySysctl('4\ntotal = 8192.00M used = 6.50G free = 1.50G (encrypted)')
+ .swapUsedKb,
+ ).toBe(6_815_744);
+ });
+
+ test('reports an unknown level and missing swap line as unreadable rather than guessing', () => {
+ expect(parseMacMemorySysctl('3\n')).toEqual({
+ pressure: 'unreadable',
+ swapUsedKb: null,
+ unreadableCause: 'unparsed',
+ });
+ expect(parseMacMemorySysctl('')).toEqual({
+ pressure: 'unreadable',
+ swapUsedKb: null,
+ unreadableCause: 'unparsed',
+ });
+ });
+});
+
+describe('createMacMemoryPressureProbe', () => {
+ test('caches the latest reading with the time it was taken', async () => {
+ let calls = 0;
+ const probe = createMacMemoryPressureProbe({
+ runSysctl: async () => {
+ calls++;
+ return '2\ntotal = 1024.00M used = 512.00M free = 512.00M (encrypted)';
+ },
+ now: () => new Date('2026-10-19T09:17:59.000Z'),
+ });
+ expect(probe.latest()).toBeNull();
+ probe.refresh();
+ probe.refresh();
+ await vi.waitFor(() => expect(probe.latest()).not.toBeNull());
+ expect(calls).toBe(1);
+ expect(probe.latest()).toEqual({
+ pressure: 'warn',
+ swapUsedKb: 524_288,
+ readAt: '2026-10-19T09:17:59.000Z',
+ });
+ });
+
+ test('takes a fresh reading on every refresh once the previous one settles', async () => {
+ const levels = ['1', '4'];
+ const probe = createMacMemoryPressureProbe({
+ runSysctl: async () => `${levels.shift() ?? '2'}\n`,
+ now: () => new Date('2026-10-19T09:17:59.000Z'),
+ });
+ probe.refresh();
+ await vi.waitFor(() => expect(probe.latest()?.pressure).toBe('normal'));
+ probe.refresh();
+ await vi.waitFor(() => expect(probe.latest()?.pressure).toBe('critical'));
+ });
+
+ test.each([
+ [
+ 'a timeout',
+ Object.assign(new Error('Command failed'), { killed: true, signal: 'SIGTERM' }),
+ 'timeout',
+ ],
+ [
+ 'a signal the probe did not send',
+ Object.assign(new Error('Command failed'), { killed: false, code: null, signal: 'SIGKILL' }),
+ 'signal',
+ ],
+ ['a non-zero exit', Object.assign(new Error('Command failed'), { code: 1 }), 'exit'],
+ ['a spawn failure', Object.assign(new Error('spawn EAGAIN'), { code: 'EAGAIN' }), 'spawn'],
+ ] as const)('records %s as unreadable with its cause', async (_label, failure, cause) => {
+ const probe = createMacMemoryPressureProbe({
+ runSysctl: async () => {
+ throw failure;
+ },
+ now: () => new Date('2026-10-19T09:17:59.000Z'),
+ });
+ probe.refresh();
+ await vi.waitFor(() => expect(probe.latest()?.unreadableCause).toBe(cause));
+ expect(probe.latest()?.pressure).toBe('unreadable');
+ expect(readSystemMemorySample({ total: 1, free: 1 }, probe.latest())).toMatchObject({
+ pressure: 'unreadable',
+ pressureUnreadableCause: cause,
+ });
+ });
+});
+
+describe('readSystemMemorySample', () => {
+ test('combines Electron memory figures with the macOS pressure reading', () => {
+ expect(
+ readSystemMemorySample(
+ { total: 16_777_216, free: 204_800 },
+ { pressure: 'critical', swapUsedKb: 3_145_728, readAt: '2026-10-19T09:17:59.000Z' },
+ ),
+ ).toEqual({
+ totalKb: 16_777_216,
+ freeKb: 204_800,
+ swapUsedKb: 3_145_728,
+ pressure: 'critical',
+ pressureReadAt: '2026-10-19T09:17:59.000Z',
+ });
+ });
+
+ test('derives swap use from Electron swap figures where the platform reports them', () => {
+ expect(
+ readSystemMemorySample(
+ { total: 8_000_000, free: 1_000_000, swapTotal: 2_000_000, swapFree: 500_000 },
+ null,
+ ),
+ ).toEqual({
+ totalKb: 8_000_000,
+ freeKb: 1_000_000,
+ swapTotalKb: 2_000_000,
+ swapFreeKb: 500_000,
+ swapUsedKb: 1_500_000,
+ });
+ });
+});
diff --git a/packages/desktop/src/main/system-memory-sample.ts b/packages/desktop/src/main/system-memory-sample.ts
new file mode 100644
index 000000000..9a170091d
--- /dev/null
+++ b/packages/desktop/src/main/system-memory-sample.ts
@@ -0,0 +1,131 @@
+import { execFile } from 'node:child_process';
+
+type MemoryPressureLevel = 'normal' | 'warn' | 'critical';
+
+type PressureUnreadableCause = 'timeout' | 'signal' | 'exit' | 'spawn' | 'unparsed';
+
+export interface SystemMemorySample {
+ totalKb: number;
+ freeKb: number;
+ swapTotalKb?: number;
+ swapFreeKb?: number;
+ swapUsedKb?: number;
+ pressure?: MemoryPressureLevel | 'unreadable';
+ pressureReadAt?: string;
+ pressureUnreadableCause?: PressureUnreadableCause;
+}
+
+export interface ElectronSystemMemoryInfo {
+ total: number;
+ free: number;
+ swapTotal?: number;
+ swapFree?: number;
+}
+
+interface MacMemoryReading {
+ pressure: MemoryPressureLevel | 'unreadable';
+ swapUsedKb: number | null;
+ unreadableCause?: PressureUnreadableCause;
+ readAt: string;
+}
+
+export interface MacMemoryPressureProbe {
+ latest(): MacMemoryReading | null;
+ refresh(): void;
+}
+
+const PRESSURE_LEVELS: Readonly<Record<string, MemoryPressureLevel>> = {
+ '1': 'normal',
+ '2': 'warn',
+ '4': 'critical',
+};
+
+const SWAP_UNIT_KB: Readonly<Record<string, number>> = { K: 1, M: 1024, G: 1024 * 1024 };
+
+const MAC_MEMORY_SYSCTL_ARGS = ['-n', 'kern.memorystatus_vm_pressure_level', 'vm.swapusage'];
+
+const MAC_MEMORY_SYSCTL_TIMEOUT_MS = 2_000;
+
+function runMacMemorySysctl(): Promise<string> {
+ return new Promise((resolve, reject) => {
+ execFile(
+ '/usr/sbin/sysctl',
+ MAC_MEMORY_SYSCTL_ARGS,
+ { timeout: MAC_MEMORY_SYSCTL_TIMEOUT_MS, windowsHide: true },
+ (err, stdout) => (err ? reject(err) : resolve(stdout)),
+ );
+ });
+}
+
+export function parseMacMemorySysctl(stdout: string): Omit<MacMemoryReading, 'readAt'> {
+ const [levelLine = '', swapLine = ''] = stdout.split('\n');
+ const used = /\bused = ([\d.]+)([KMG])\b/.exec(swapLine);
+ const swapUsedKb =
+ used === null
+ ? null
+ : Math.round(Number(used[1]) * (SWAP_UNIT_KB[used[2] ?? ''] ?? Number.NaN));
+ const pressure = PRESSURE_LEVELS[levelLine.trim()];
+ return {
+ pressure: pressure ?? 'unreadable',
+ swapUsedKb: swapUsedKb !== null && Number.isFinite(swapUsedKb) ? swapUsedKb : null,
+ ...(pressure === undefined ? { unreadableCause: 'unparsed' as const } : {}),
+ };
+}
+
+function classifySysctlFailure(err: unknown): PressureUnreadableCause {
+ const failure = err as { killed?: unknown; code?: unknown; signal?: unknown } | null;
+ if (failure?.killed === true) return 'timeout';
+ if (typeof failure?.code === 'number') return 'exit';
+ return typeof failure?.signal === 'string' ? 'signal' : 'spawn';
+}
+
+export function createMacMemoryPressureProbe(deps: {
+ runSysctl?(): Promise<string>;
+ now(): Date;
+}): MacMemoryPressureProbe {
+ const runSysctl = deps.runSysctl ?? runMacMemorySysctl;
+ let latest: MacMemoryReading | null = null;
+ let inFlight = false;
+ return {
+ latest: () => latest,
+ refresh() {
+ if (inFlight) return;
+ inFlight = true;
+ runSysctl()
+ .then(
+ (stdout) => parseMacMemorySysctl(stdout),
+ (err: unknown) => ({
+ pressure: 'unreadable' as const,
+ swapUsedKb: null,
+ unreadableCause: classifySysctlFailure(err),
+ }),
+ )
+ .then((reading) => {
+ latest = { ...reading, readAt: deps.now().toISOString() };
+ })
+ .finally(() => {
+ inFlight = false;
+ });
+ },
+ };
+}
+
+export function readSystemMemorySample(
+ info: ElectronSystemMemoryInfo,
+ mac: MacMemoryReading | null,
+): SystemMemorySample {
+ const swapUsedKb =
+ mac?.swapUsedKb ??
+ (info.swapTotal !== undefined && info.swapFree !== undefined
+ ? info.swapTotal - info.swapFree
+ : undefined);
+ return {
+ totalKb: info.total,
+ freeKb: info.free,
+ ...(info.swapTotal === undefined ? {} : { swapTotalKb: info.swapTotal }),
+ ...(info.swapFree === undefined ? {} : { swapFreeKb: info.swapFree }),
+ ...(swapUsedKb === undefined ? {} : { swapUsedKb }),
+ ...(mac === null ? {} : { pressure: mac.pressure, pressureReadAt: mac.readAt }),
+ ...(mac?.unreadableCause === undefined ? {} : { pressureUnreadableCause: mac.unreadableCause }),
+ };
+}
diff --git a/packages/desktop/src/utility/server-entry.test.ts b/packages/desktop/src/utility/server-entry.test.ts
index 7200124e1..f2d8cda29 100644
--- a/packages/desktop/src/utility/server-entry.test.ts
+++ b/packages/desktop/src/utility/server-entry.test.ts
@@ -123,6 +123,7 @@ interface DriveResult {
readyErr?: Error;
handle: UtilityHandle;
destroyReasons: Array<string | undefined>;
+ destroySignals: Array<string | undefined>;
}
async function driveInit(opts: {
@@ -133,6 +134,7 @@ async function driveInit(opts: {
const posted: Array<Record<string, unknown>> = [];
const bootPorts: Array<number | undefined> = [];
const destroyReasons: Array<string | undefined> = [];
+ const destroySignals: Array<string | undefined> = [];
let messageHandler: ((e: { data: unknown }) => void) | undefined;
const fakeBootServer = async (o: BootServerOptions): Promise<BootedServer> => {
@@ -141,8 +143,9 @@ async function driveInit(opts: {
return {
port: res.port,
degraded: [],
- destroy: async (reason?: string) => {
+ destroy: async (reason?: string, detail?: { signal?: string }) => {
destroyReasons.push(reason);
+ destroySignals.push(detail?.signal);
},
} as unknown as BootedServer;
};
@@ -183,9 +186,9 @@ async function driveInit(opts: {
});
try {
const ready = await handle.readyPromise;
- return { posted, bootPorts, ready, handle, destroyReasons };
+ return { posted, bootPorts, ready, handle, destroyReasons, destroySignals };
} catch (err) {
- return { posted, bootPorts, readyErr: err as Error, handle, destroyReasons };
+ return { posted, bootPorts, readyErr: err as Error, handle, destroyReasons, destroySignals };
}
}
@@ -264,9 +267,10 @@ describe('shutdown exit reason', () => {
}
test('a dead parent drains the server as parent-exit', async () => {
- const { handle, destroyReasons } = await drive();
+ const { handle, destroyReasons, destroySignals } = await drive();
await handle.shutdown('parent-died');
expect(destroyReasons).toEqual(['parent-exit']);
+ expect(destroySignals).toEqual([undefined]);
});
test('window-close IPC drains as parent-exit too — the host is going away', async () => {
@@ -276,8 +280,9 @@ describe('shutdown exit reason', () => {
});
test('a signal drains as external-signal', async () => {
- const { handle, destroyReasons } = await drive();
+ const { handle, destroyReasons, destroySignals } = await drive();
await handle.shutdown('SIGTERM');
expect(destroyReasons).toEqual(['external-signal']);
+ expect(destroySignals).toEqual(['SIGTERM']);
});
});
diff --git a/packages/desktop/src/utility/server-entry.ts b/packages/desktop/src/utility/server-entry.ts
index 33d6a2e14..5c158849f 100644
--- a/packages/desktop/src/utility/server-entry.ts
+++ b/packages/desktop/src/utility/server-entry.ts
@@ -200,7 +200,10 @@ export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
let drainOk = true;
if (booted) {
try {
- await booted.destroy(SERVER_EXIT_REASONS[reason]);
+ await booted.destroy(
+ SERVER_EXIT_REASONS[reason],
+ reason === 'SIGTERM' || reason === 'SIGINT' ? { signal: reason } : undefined,
+ );
} catch (err) {
drainOk = false;
deps.parentPort?.postMessage({
diff --git a/packages/server/src/boot.ts b/packages/server/src/boot.ts
index b558da8d1..5c204139d 100644
--- a/packages/server/src/boot.ts
+++ b/packages/server/src/boot.ts
@@ -184,9 +184,13 @@ export interface BootServerOptions
export type ServerExitReason = 'external-signal' | 'idle-shutdown' | 'parent-exit' | 'unspecified';
+export interface ServerExitDetail {
+ signal?: NodeJS.Signals;
+}
+
export interface BootedServer {
httpServer: HttpServer;
- destroy: (reason?: ServerExitReason) => Promise<void>;
+ destroy: (reason?: ServerExitReason, detail?: ServerExitDetail) => Promise<void>;
lockDir: string;
contentDir: string;
port: number;
@@ -264,9 +268,9 @@ export async function bootServer(opts: BootServerOptions): Promise<BootedServer>
throw err;
}
const innerDestroy = booted.destroy;
- booted.destroy = async (reason) => {
+ booted.destroy = async (reason, detail) => {
try {
- await innerDestroy(reason);
+ await innerDestroy(reason, detail);
} finally {
crashCapture.uninstall();
}
@@ -565,7 +569,7 @@ async function bootServerInner(
acpThreadManager,
});
- let destroy: (reason?: ServerExitReason) => Promise<void> = async () => {
+ let destroy: BootedServer['destroy'] = async () => {
throw new Error('bootServer: destroy() invoked before initialization — boot did not complete');
};
@@ -700,7 +704,10 @@ async function bootServerInner(
if (timer !== undefined) clearTimeout(timer);
}
};
- destroy = async (reason: ServerExitReason = 'unspecified'): Promise<void> => {
+ destroy = async (
+ reason: ServerExitReason = 'unspecified',
+ detail: ServerExitDetail = {},
+ ): Promise<void> => {
if (destroyed) return;
destroyed = true;
try {
@@ -710,7 +717,10 @@ async function bootServerInner(
tracedUtimesSync(projectLogsDir, now, now);
}
} catch {}
- log.info({ reason, pid: process.pid, lockDir }, `[server] shutdown initiated (${reason})`);
+ log.info(
+ { reason, signal: detail.signal ?? null, pid: process.pid, lockDir },
+ `[server] shutdown initiated (${reason})`,
+ );
readinessState = 'draining';
const errors: unknown[] = [];
const runStep = async (
diff --git a/packages/server/src/composition-rig.test-helper.ts b/packages/server/src/composition-rig.test-helper.ts
index 7f364e498..d99ea73e0 100644
--- a/packages/server/src/composition-rig.test-helper.ts
+++ b/packages/server/src/composition-rig.test-helper.ts
@@ -57,9 +57,9 @@ export async function bootCompositionRig(
}
if (overrides.configHomedirOverride === undefined) {
const inner = booted.destroy;
- booted.destroy = async (reason) => {
+ booted.destroy = async (...args) => {
try {
- await inner(reason);
+ await inner(...args);
} finally {
rmSync(ownedHome, { recursive: true, force: true });
}
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index 46d87b012..0a1ff5b99 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -85,6 +85,7 @@ export {
type BootedServer,
type BootServerOptions,
bootServer,
+ type ServerExitDetail,
type ServerExitReason,
} from './boot.ts';
export {
diff --git a/packages/server/src/server-exit-reason.test.ts b/packages/server/src/server-exit-reason.test.ts
index 844431d88..951cc43e5 100644
--- a/packages/server/src/server-exit-reason.test.ts
+++ b/packages/server/src/server-exit-reason.test.ts
@@ -40,10 +40,11 @@ describe('server exit reason', () => {
const booted = await bootCompositionRig(dir, { log });
await booted.ready;
try {
- await booted.destroy('external-signal');
+ await booted.destroy('external-signal', { signal: 'SIGTERM' });
const record = entries.find((e) => e.msg.includes('shutdown initiated'));
expect(record).toBeDefined();
expect(record?.payload.reason).toBe('external-signal');
+ expect(record?.payload.signal).toBe('SIGTERM');
expect(record?.payload.pid).toBe(process.pid);
} finally {
await rm(dir, { recursive: true, force: true });