Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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<Booconst 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: StartCommandOptioconsole.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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex b558da8d1..5c204139d 100644--- a/packages/server/src/boot.ts+++ b/packages/server/src/boot.ts@@ -184,9 +184,13 @@ export interface BootServerOptionsexport 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.tsindex 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.tsindex 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.tsindex 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 });