Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Fix Windows desktop crash attribution (PRD-8779) (#4841)

Andrew Mikofalvy4c5b9ce7ea3f
diff --git a/.changeset/spicy-cycles-smell.md b/.changeset/spicy-cycles-smell.md
new file mode 100644
index 000000000..668e9492d
--- /dev/null
+++ b/.changeset/spicy-cycles-smell.md
@@ -0,0 +1,6 @@
+---
+"@inkeep/open-knowledge": patch
+"@inkeep/open-knowledge-desktop": patch
+---
+
+Make renderer and Utility-process crashes diagnosable from a bug report bundle. Desktop logs now retain low-rate process memory and CPU samples, per-window liveness and lifecycle events, and the last pre-crash plus live process snapshots on each crash breadcrumb.
diff --git a/packages/desktop/src/main/crash-detection.test.ts b/packages/desktop/src/main/crash-detection.test.ts
index 66d22ed63..bdbb0cdf4 100644
--- a/packages/desktop/src/main/crash-detection.test.ts
+++ b/packages/desktop/src/main/crash-detection.test.ts
@@ -264,6 +264,65 @@ describe('runtime process-gone invitations', () => {
}
});
+ test('runtime crash breadcrumbs retain the pre-crash and live process snapshots', () => {
+ const rig = makeRig();
+ const detection = createCrashDetection(rig.deps);
+ const processSnapshot = {
+ affectedRenderer: { contentsId: 17, rendererPid: 222 },
+ lastSampleAgeMs: 4_000,
+ lastSample: {
+ capturedAt: '2026-09-22T19:25:47.000Z',
+ processCount: 0,
+ processesTruncated: 0,
+ processes: [],
+ windowCount: 0,
+ windowsTruncated: 0,
+ windows: [],
+ },
+ liveSample: {
+ capturedAt: '2026-09-22T19:25:51.000Z',
+ processCount: 0,
+ processesTruncated: 0,
+ processes: [],
+ windowCount: 0,
+ windowsTruncated: 0,
+ windows: [],
+ },
+ };
+
+ detection.handleRenderProcessGone({
+ reason: 'crashed',
+ exitCode: -1,
+ processSnapshot,
+ });
+ const first = rig.emitted[0];
+ if (!first) throw new Error('expected a report invitation');
+ detection.ack(first.eventId);
+ detection.handleChildProcessGone({
+ type: 'Utility',
+ reason: 'crashed',
+ exitCode: -1,
+ name: 'OpenKnowledge Terminal Host 7',
+ serviceName: 'node.mojom.NodeService',
+ processSnapshot,
+ });
+
+ expect(
+ rig.warnings.find((line) => line.event === 'crash-detection.render-process-gone'),
+ ).toMatchObject({ processSnapshot });
+ expect(
+ rig.warnings.find((line) => line.event === 'crash-detection.child-process-gone'),
+ ).toMatchObject({
+ name: 'OpenKnowledge Terminal Host 7',
+ processSnapshot,
+ });
+ expect(
+ rig.warnings.find((line) => line.event === 'crash-detection.child-process-gone'),
+ ).not.toHaveProperty('serviceName');
+ expect(rig.emitted[0]).not.toHaveProperty('processSnapshot');
+ expect(rig.emitted[1]).not.toHaveProperty('processSnapshot');
+ });
+
test('a second crash stays silent while one invitation is unanswered, and invites again after ack', () => {
const rig = makeRig();
const detection = createCrashDetection(rig.deps);
diff --git a/packages/desktop/src/main/crash-detection.ts b/packages/desktop/src/main/crash-detection.ts
index b76ef81cf..331e60970 100644
--- a/packages/desktop/src/main/crash-detection.ts
+++ b/packages/desktop/src/main/crash-detection.ts
@@ -10,6 +10,7 @@ import {
import { dirname, join } from 'node:path';
import type { OkBugReportCrashDetectedEvent } from '@inkeep/open-knowledge-core';
import { asReportableAppVersion } from './crashed-app-version.ts';
+import type { DesktopCrashProcessSnapshot } from './desktop-process-observability.ts';
import {
classifyPreviousLiveness,
isFileMissingError,
@@ -29,6 +30,10 @@ import {
const CRASH_REASONS = new Set(['crashed', 'oom', 'launch-failed', 'integrity-failure']);
+export function isProcessCrashReason(reason: string): boolean {
+ return CRASH_REASONS.has(reason);
+}
+
const GPU_PROCESS_TYPE = 'GPU';
const GPU_DUMP_PROCESS_TYPE = 'gpu-process';
@@ -127,12 +132,18 @@ export interface CrashDetection {
noteOsShutdown(reasons?: readonly string[]): void;
noteSuspend(): void;
noteResume(): void;
- handleRenderProcessGone(details: { reason: string; exitCode?: number }): void;
+ handleRenderProcessGone(details: {
+ reason: string;
+ exitCode?: number;
+ processSnapshot?: DesktopCrashProcessSnapshot;
+ }): void;
handleChildProcessGone(details: {
type: string;
reason: string;
exitCode?: number;
name?: string;
+ serviceName?: string;
+ processSnapshot?: DesktopCrashProcessSnapshot;
}): void;
notifyRendererReady(): void;
ack(eventId: string): void;
@@ -812,7 +823,7 @@ export function createCrashDetection(deps: CrashDetectionDeps): CrashDetection {
},
handleRenderProcessGone(details): void {
- if (!CRASH_REASONS.has(details.reason)) return;
+ if (!isProcessCrashReason(details.reason)) return;
const owned = newestOwnedMinidump();
deps.logger.warn(
{
@@ -822,6 +833,9 @@ export function createCrashDetection(deps: CrashDetectionDeps): CrashDetection {
foreignDumpsIgnored: owned.foreignSkipped,
unreadableDumpsSkipped: owned.unknownSkipped,
nonCrashDumpsSkipped: owned.nonCrashSkipped,
+ ...(details.processSnapshot === undefined
+ ? {}
+ : { processSnapshot: details.processSnapshot }),
},
'renderer process died abnormally',
);
@@ -841,7 +855,7 @@ export function createCrashDetection(deps: CrashDetectionDeps): CrashDetection {
},
handleChildProcessGone(details): void {
- if (!CRASH_REASONS.has(details.reason)) return;
+ if (!isProcessCrashReason(details.reason)) return;
const owned = newestOwnedMinidump();
const gpu = details.type === GPU_PROCESS_TYPE ? noteGpuCrash() : null;
deps.logger.warn(
@@ -850,9 +864,13 @@ export function createCrashDetection(deps: CrashDetectionDeps): CrashDetection {
processType: details.type,
reason: details.reason,
exitCode: details.exitCode,
+ ...(details.name === undefined ? {} : { name: details.name }),
foreignDumpsIgnored: owned.foreignSkipped,
unreadableDumpsSkipped: owned.unknownSkipped,
nonCrashDumpsSkipped: owned.nonCrashSkipped,
+ ...(details.processSnapshot === undefined
+ ? {}
+ : { processSnapshot: details.processSnapshot }),
...(gpu === null ? {} : { gpuCrashesInWindow: gpu.countInWindow }),
...(gpu?.suppressInvite === true ? { invitationSuppressed: 'gpu-recoverable' } : {}),
},
diff --git a/packages/desktop/src/main/desktop-process-observability.test.ts b/packages/desktop/src/main/desktop-process-observability.test.ts
new file mode 100644
index 000000000..ce10bf0b2
--- /dev/null
+++ b/packages/desktop/src/main/desktop-process-observability.test.ts
@@ -0,0 +1,429 @@
+import { describe, expect, test } from 'vitest';
+import {
+ createDesktopProcessObservability,
+ DESKTOP_PROCESS_SAMPLE_INTERVAL_MS,
+ MAX_DESKTOP_PROCESS_SAMPLE_ROWS,
+ MAX_DESKTOP_WINDOW_SAMPLE_ROWS,
+ type ObservedBrowserWindow,
+ type ProcessMetricLike,
+} from './desktop-process-observability.ts';
+
+interface TestWindow extends ObservedBrowserWindow {
+ emit(event: 'closed' | 'show' | 'hide' | 'minimize' | 'restore'): void;
+ setState(
+ state: Partial<{
+ destroyed: boolean;
+ visible: boolean;
+ minimized: boolean;
+ crashed: boolean;
+ loading: boolean;
+ rendererPid: number;
+ }>,
+ ): void;
+}
+
+function makeWindow(input: {
+ id: number;
+ contentsId: number;
+ rendererPid: number;
+ visible?: boolean;
+ minimized?: boolean;
+ throwIdentityWhenDestroyed?: boolean;
+}): TestWindow {
+ const listeners = new Map<string, Array<() => void>>();
+ let destroyed = false;
+ let visible = input.visible ?? true;
+ let minimized = input.minimized ?? false;
+ let crashed = false;
+ let loading = false;
+ let rendererPid = input.rendererPid;
+ const contents = {
+ id: input.contentsId,
+ getOSProcessId: () => rendererPid,
+ isCrashed: () => crashed,
+ isDestroyed: () => destroyed,
+ isLoading: () => loading,
+ };
+ return {
+ get id() {
+ if (destroyed && input.throwIdentityWhenDestroyed === true) {
+ throw new Error('window identity unavailable after close');
+ }
+ return input.id;
+ },
+ get webContents() {
+ if (destroyed && input.throwIdentityWhenDestroyed === true) {
+ throw new Error('webContents unavailable after close');
+ }
+ return contents;
+ },
+ isDestroyed: () => destroyed,
+ isVisible: () => visible,
+ isMinimized: () => minimized,
+ isFocused: () => visible && !minimized,
+ on: (event, listener) => {
+ listeners.set(event, [...(listeners.get(event) ?? []), listener]);
+ },
+ emit: (event) => {
+ for (const listener of listeners.get(event) ?? []) listener();
+ },
+ setState: (state) => {
+ destroyed = state.destroyed ?? destroyed;
+ visible = state.visible ?? visible;
+ minimized = state.minimized ?? minimized;
+ crashed = state.crashed ?? crashed;
+ loading = state.loading ?? loading;
+ rendererPid = state.rendererPid ?? rendererPid;
+ },
+ };
+}
+
+function processMetric(input: {
+ pid: number;
+ type: string;
+ workingSetSize: number;
+ name?: string;
+}): ProcessMetricLike {
+ return {
+ pid: input.pid,
+ type: input.type,
+ name: input.name,
+ serviceName: input.name === undefined ? undefined : 'node.mojom.NodeService',
+ creationTime: 1_790_000_000_000 + input.pid,
+ cpu: {
+ percentCPUUsage: 12.5,
+ cumulativeCPUUsage: 42,
+ idleWakeupsPerSecond: 0,
+ },
+ memory: {
+ workingSetSize: input.workingSetSize,
+ peakWorkingSetSize: input.workingSetSize + 100,
+ privateBytes: input.workingSetSize - 100,
+ },
+ sandboxed: true,
+ integrityLevel: 'low',
+ };
+}
+
+function harness() {
+ let nowMs = Date.parse('2026-09-22T19:25:00.000Z');
+ let metrics: ProcessMetricLike[] = [
+ processMetric({ pid: 100, type: 'Browser', workingSetSize: 50_000 }),
+ processMetric({ pid: 200, type: 'Tab', workingSetSize: 125_000 }),
+ ];
+ const windows: TestWindow[] = [
+ makeWindow({
+ id: 7,
+ contentsId: 11,
+ rendererPid: 200,
+ throwIdentityWhenDestroyed: true,
+ }),
+ ];
+ const info: Array<Record<string, unknown>> = [];
+ const warn: Array<Record<string, unknown>> = [];
+ const intervals: Array<{ callback: () => void; ms: number; cleared: boolean }> = [];
+ const observability = createDesktopProcessObservability({
+ now: () => new Date(nowMs),
+ getAppMetrics: () => metrics,
+ getAllWindows: () => windows,
+ logger: {
+ info: (payload) => info.push(payload),
+ warn: (payload) => warn.push(payload),
+ },
+ setInterval: (callback, ms) => {
+ const interval = { callback, ms, cleared: false };
+ intervals.push(interval);
+ return interval;
+ },
+ clearInterval: (handle) => {
+ (handle as { cleared: boolean }).cleared = true;
+ },
+ });
+ return {
+ observability,
+ info,
+ warn,
+ intervals,
+ windows,
+ setMetrics: (next: ProcessMetricLike[]) => {
+ metrics = next;
+ },
+ advance: (ms: number) => {
+ nowMs += ms;
+ },
+ };
+}
+
+describe('desktop process observability', () => {
+ test('samples every app process and window once per minute from main-process dependencies', () => {
+ const rig = harness();
+
+ rig.observability.start();
+
+ expect(DESKTOP_PROCESS_SAMPLE_INTERVAL_MS).toBe(60_000);
+ expect(rig.intervals[0]?.ms).toBe(60_000);
+ expect(rig.info[0]).toMatchObject({
+ event: 'desktop-process-observability.sample',
+ trigger: 'startup',
+ capturedAt: '2026-09-22T19:25:00.000Z',
+ processes: [
+ {
+ pid: 200,
+ type: 'Tab',
+ workingSetSizeKb: 125_000,
+ privateBytesKb: 124_900,
+ },
+ { pid: 100, type: 'Browser', workingSetSizeKb: 50_000 },
+ ],
+ windows: [
+ {
+ windowId: 7,
+ contentsId: 11,
+ rendererPid: 200,
+ state: 'alive',
+ visible: true,
+ minimized: false,
+ focused: true,
+ },
+ ],
+ });
+
+ rig.advance(DESKTOP_PROCESS_SAMPLE_INTERVAL_MS);
+ rig.intervals[0]?.callback();
+ expect(rig.info[1]).toMatchObject({
+ event: 'desktop-process-observability.sample',
+ trigger: 'interval',
+ capturedAt: '2026-09-22T19:26:00.000Z',
+ });
+
+ rig.advance(1_000);
+ rig.observability.sampleNow('renderer-ready');
+ expect(rig.info[2]).toMatchObject({
+ event: 'desktop-process-observability.sample',
+ trigger: 'renderer-ready',
+ capturedAt: '2026-09-22T19:26:01.000Z',
+ });
+ });
+
+ test('keeps the last pre-crash sample beside a live post-crash snapshot', () => {
+ const rig = harness();
+ rig.observability.start();
+ rig.advance(5_000);
+ rig.setMetrics([processMetric({ pid: 100, type: 'Browser', workingSetSize: 51_000 })]);
+
+ const snapshot = rig.observability.snapshotForCrash({ contentsId: 11, rendererPid: null });
+
+ expect(snapshot).toMatchObject({
+ affectedRenderer: { contentsId: 11, rendererPid: 200 },
+ lastSampleAgeMs: 5_000,
+ lastSample: {
+ capturedAt: '2026-09-22T19:25:00.000Z',
+ processes: [{ pid: 200, type: 'Tab' }, { pid: 100 }],
+ },
+ liveSample: {
+ capturedAt: '2026-09-22T19:25:05.000Z',
+ processes: [{ pid: 100 }],
+ },
+ });
+ expect(snapshot.liveSample?.processes).not.toContainEqual(
+ expect.objectContaining({ pid: 200 }),
+ );
+ });
+
+ test('records complete window lifecycle with the remaining live-window count', () => {
+ const rig = harness();
+ const window = rig.windows[0];
+ if (!window) throw new Error('missing test window');
+
+ rig.observability.observeWindow(window);
+ window.setState({ visible: false, minimized: true });
+ window.emit('hide');
+ window.emit('minimize');
+ window.setState({ visible: true, minimized: false });
+ window.emit('show');
+ window.emit('restore');
+ window.setState({ destroyed: true });
+ expect(() => window.emit('closed')).not.toThrow();
+
+ const lifecycle = rig.info.filter(
+ (line) => line.event === 'desktop-process-observability.window-lifecycle',
+ );
+ expect(lifecycle.map((line) => line.action)).toEqual([
+ 'created',
+ 'hidden',
+ 'minimized',
+ 'shown',
+ 'restored',
+ 'closed',
+ ]);
+ expect(lifecycle[0]).toMatchObject({
+ windowId: 7,
+ contentsId: 11,
+ rendererPid: 200,
+ liveWindowCount: 1,
+ });
+ expect(lifecycle.at(-1)).toMatchObject({ liveWindowCount: 0, state: 'destroyed' });
+ });
+
+ test('keeps crash handling alive when Electron refuses a process sample', () => {
+ const rig = harness();
+ rig.observability.start();
+ rig.observability.stop();
+ const failing = createDesktopProcessObservability({
+ now: () => new Date('2026-09-22T19:25:30.000Z'),
+ getAppMetrics: () => {
+ throw new Error('metrics unavailable');
+ },
+ getAllWindows: () => rig.windows,
+ logger: {
+ info: (payload) => rig.info.push(payload),
+ warn: (payload) => rig.warn.push(payload),
+ },
+ setInterval: () => 1,
+ clearInterval: () => {},
+ });
+
+ failing.start();
+ const snapshot = failing.snapshotForCrash({ contentsId: 11, rendererPid: 200 });
+
+ expect(snapshot.lastSample).toBeNull();
+ expect(snapshot.liveSample).toBeNull();
+ expect(rig.warn).toContainEqual(
+ expect.objectContaining({ event: 'desktop-process-observability.sample-failed' }),
+ );
+ });
+
+ test('preserves the last renderer PID after the live contents becomes unavailable', () => {
+ const rig = harness();
+ const window = rig.windows[0];
+ if (!window) throw new Error('missing test window');
+ window.setState({ rendererPid: 0 });
+ rig.observability.observeWindow(window);
+ window.setState({ rendererPid: 200 });
+ rig.observability.sampleNow('renderer-ready');
+ window.setState({ destroyed: true });
+
+ expect(() => window.emit('closed')).not.toThrow();
+
+ const closed = rig.info.find(
+ (line) =>
+ line.event === 'desktop-process-observability.window-lifecycle' && line.action === 'closed',
+ );
+ expect(closed).toMatchObject({
+ windowId: 7,
+ contentsId: 11,
+ rendererPid: 200,
+ state: 'destroyed',
+ });
+ });
+
+ test('distinguishes alive, loading, crashed and destroyed window states', () => {
+ const rig = harness();
+ const window = rig.windows[0];
+ if (!window) throw new Error('missing test window');
+ rig.observability.start();
+
+ window.setState({ crashed: true, rendererPid: 0 });
+ rig.observability.sampleNow('renderer-ready');
+ window.setState({ loading: true, crashed: false });
+ rig.observability.sampleNow('renderer-ready');
+ window.setState({ loading: false });
+ rig.observability.sampleNow('renderer-ready');
+ window.setState({ crashed: true });
+ rig.observability.sampleNow('renderer-ready');
+ window.setState({ destroyed: true });
+ rig.observability.sampleNow('renderer-ready');
+
+ const samples = rig.info.filter(
+ (line) => line.event === 'desktop-process-observability.sample',
+ ) as Array<{ windows: Array<{ state: string; rendererPid: number | null }> }>;
+ expect(samples[0]?.windows).toEqual([
+ expect.objectContaining({ state: 'alive', rendererPid: 200 }),
+ ]);
+ expect(samples[1]?.windows).toEqual([
+ expect.objectContaining({ state: 'crashed', rendererPid: 200 }),
+ ]);
+ expect(samples[2]?.windows).toEqual([
+ expect.objectContaining({ state: 'loading', rendererPid: null }),
+ ]);
+ expect(samples[3]?.windows).toEqual([
+ expect.objectContaining({ state: 'alive', rendererPid: null }),
+ ]);
+ expect(samples[4]?.windows).toEqual([
+ expect.objectContaining({ state: 'crashed', rendererPid: null }),
+ ]);
+ expect(samples[5]?.windows).toEqual([]);
+ });
+
+ test('starts only one interval and floors clock rollback at a zero sample age', () => {
+ const rig = harness();
+ rig.observability.start();
+ rig.observability.start();
+ rig.advance(-5_000);
+
+ const snapshot = rig.observability.snapshotForCrash();
+
+ expect(rig.intervals).toHaveLength(1);
+ expect(snapshot.lastSampleAgeMs).toBe(0);
+ });
+
+ test('bounds each log line while retaining counts and the highest-memory processes', () => {
+ const rig = harness();
+ rig.setMetrics(
+ Array.from({ length: 40 }, (_, index) =>
+ processMetric({
+ pid: 1_000 + index,
+ type: index === 0 ? 'Browser' : 'Tab',
+ workingSetSize: 10_000 + Math.min(index, 38) * 1_000,
+ name: 'process-name'.repeat(50),
+ }),
+ ),
+ );
+ for (let index = 0; index < 20; index += 1) {
+ rig.windows.push(
+ makeWindow({
+ id: 100 + index,
+ contentsId: 200 + index,
+ rendererPid: 1_000 + index,
+ }),
+ );
+ }
+ rig.windows.reverse();
+
+ rig.observability.start();
+
+ const sample = rig.info[0] as {
+ processCount: number;
+ processesTruncated: number;
+ processes: Array<{ pid: number }>;
+ windowCount: number;
+ windowsTruncated: number;
+ windows: unknown[];
+ };
+ expect(sample.processCount).toBe(40);
+ expect(sample.processesTruncated).toBe(40 - MAX_DESKTOP_PROCESS_SAMPLE_ROWS);
+ expect(sample.processes).toHaveLength(MAX_DESKTOP_PROCESS_SAMPLE_ROWS);
+ expect(sample.processes[0]?.pid).toBe(1_038);
+ expect((sample.processes[0] as { name?: string }).name).toHaveLength(96);
+ expect(sample.processes[0]).not.toHaveProperty('serviceName');
+ expect(sample.windowCount).toBe(21);
+ 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);
+ 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);
+ expect(sampleBytes).toBeLessThan(5 * 1_024);
+ expect(sampleBytes * samplesPerDay).toBeLessThan(6 * 1024 * 1024);
+ });
+
+ test('stop is idempotent', () => {
+ const rig = harness();
+ rig.observability.start();
+
+ rig.observability.stop();
+ rig.observability.stop();
+
+ expect(rig.intervals[0]?.cleared).toBe(true);
+ });
+});
diff --git a/packages/desktop/src/main/desktop-process-observability.ts b/packages/desktop/src/main/desktop-process-observability.ts
new file mode 100644
index 000000000..9cb8cc0d2
--- /dev/null
+++ b/packages/desktop/src/main/desktop-process-observability.ts
@@ -0,0 +1,337 @@
+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;
+
+export interface ProcessMetricLike {
+ pid: number;
+ type: string;
+ name?: string;
+ serviceName?: string;
+ creationTime: number;
+ cpu: {
+ percentCPUUsage: number;
+ cumulativeCPUUsage?: number;
+ idleWakeupsPerSecond: number;
+ };
+ memory: {
+ workingSetSize: number;
+ peakWorkingSetSize: number;
+ privateBytes?: number;
+ };
+ sandboxed?: boolean;
+ integrityLevel?: string;
+}
+
+interface ObservedWebContents {
+ readonly id: number;
+ getOSProcessId(): number;
+ isCrashed(): boolean;
+ isDestroyed(): boolean;
+ isLoading(): boolean;
+}
+
+type WindowLifecycleEvent = 'closed' | 'show' | 'hide' | 'minimize' | 'restore';
+
+export interface ObservedBrowserWindow {
+ readonly id: number;
+ readonly webContents: ObservedWebContents;
+ isDestroyed(): boolean;
+ isVisible(): boolean;
+ isMinimized(): boolean;
+ isFocused(): boolean;
+ on(event: WindowLifecycleEvent, listener: () => void): void;
+}
+
+interface ProcessSample {
+ pid: number;
+ type: string;
+ creationTime: number;
+ name?: string;
+ cumulativeCpuSeconds?: number;
+ workingSetSizeKb: number;
+ privateBytesKb?: number;
+}
+
+interface WindowSample {
+ windowId: number | null;
+ contentsId: number | null;
+ rendererPid: number | null;
+ state: 'alive' | 'loading' | 'crashed' | 'destroyed';
+ visible: boolean;
+ minimized: boolean;
+ focused: boolean;
+}
+
+interface DesktopProcessSample {
+ capturedAt: string;
+ processCount: number;
+ processesTruncated: number;
+ processes: ProcessSample[];
+ windowCount: number;
+ windowsTruncated: number;
+ windows: WindowSample[];
+}
+
+export interface DesktopCrashProcessSnapshot {
+ affectedRenderer: { contentsId: number; rendererPid: number | null } | null;
+ lastSampleAgeMs: number | null;
+ lastSample: DesktopProcessSample | null;
+ liveSample: DesktopProcessSample | null;
+}
+
+interface WindowIdentity {
+ windowId: number | null;
+ contentsId: number | null;
+}
+
+interface DesktopProcessLogger {
+ info(payload: Record<string, unknown>, message: string): void;
+ warn(payload: Record<string, unknown>, message: string): void;
+}
+
+export interface DesktopProcessObservabilityDeps<IntervalHandle> {
+ now(): Date;
+ getAppMetrics(): readonly ProcessMetricLike[];
+ getAllWindows(): readonly ObservedBrowserWindow[];
+ logger: DesktopProcessLogger;
+ setInterval(callback: () => void, ms: number): IntervalHandle;
+ clearInterval(handle: IntervalHandle): void;
+}
+
+export interface DesktopProcessObservability {
+ start(): void;
+ stop(): void;
+ sampleNow(trigger: 'renderer-ready'): void;
+ observeWindow(window: ObservedBrowserWindow): void;
+ snapshotForCrash(affectedRenderer?: {
+ contentsId: number;
+ rendererPid: number | null;
+ }): DesktopCrashProcessSnapshot;
+}
+
+function readBoolean(fn: () => boolean, fallback: boolean): boolean {
+ try {
+ return fn();
+ } catch {
+ return fallback;
+ }
+}
+
+export function readRendererPid(contents: ObservedWebContents | null): number | null {
+ if (contents === null) return null;
+ try {
+ const pid = contents.getOSProcessId();
+ return Number.isInteger(pid) && pid > 0 ? pid : null;
+ } catch {
+ return null;
+ }
+}
+
+function boundedLabel(value: string | undefined): string | undefined {
+ return value?.slice(0, 96);
+}
+
+function normalizeProcess(metric: ProcessMetricLike): ProcessSample {
+ const name = boundedLabel(metric.name);
+ return {
+ pid: metric.pid,
+ type: metric.type,
+ creationTime: metric.creationTime,
+ ...(name === undefined ? {} : { name }),
+ ...(metric.cpu.cumulativeCPUUsage === undefined
+ ? {}
+ : { cumulativeCpuSeconds: metric.cpu.cumulativeCPUUsage }),
+ workingSetSizeKb: metric.memory.workingSetSize,
+ ...(metric.memory.privateBytes === undefined
+ ? {}
+ : { privateBytesKb: metric.memory.privateBytes }),
+ };
+}
+
+function readWebContents(window: ObservedBrowserWindow): ObservedWebContents | null {
+ try {
+ return window.webContents;
+ } catch {
+ return null;
+ }
+}
+
+function readWindowIdentity(window: ObservedBrowserWindow): WindowIdentity {
+ let windowId: number | null = null;
+ let contentsId: number | null = null;
+ try {
+ windowId = window.id;
+ } catch {}
+ const contents = readWebContents(window);
+ if (contents !== null) {
+ try {
+ contentsId = contents.id;
+ } catch {}
+ }
+ return { windowId, contentsId };
+}
+
+function inspectWindow(
+ window: ObservedBrowserWindow,
+ identity: WindowIdentity = readWindowIdentity(window),
+): WindowSample {
+ const destroyed = readBoolean(() => window.isDestroyed(), true);
+ const contents = readWebContents(window);
+ const contentsDestroyed =
+ destroyed || contents === null || readBoolean(() => contents.isDestroyed(), true);
+ const crashed = !contentsDestroyed && readBoolean(() => contents.isCrashed(), false);
+ const loading = !contentsDestroyed && !crashed && readBoolean(() => contents.isLoading(), false);
+ return {
+ ...identity,
+ rendererPid: contentsDestroyed ? null : readRendererPid(contents),
+ state: contentsDestroyed ? 'destroyed' : crashed ? 'crashed' : loading ? 'loading' : 'alive',
+ visible: !destroyed && readBoolean(() => window.isVisible(), false),
+ minimized: !destroyed && readBoolean(() => window.isMinimized(), false),
+ focused: !destroyed && readBoolean(() => window.isFocused(), false),
+ };
+}
+
+export function createDesktopProcessObservability<IntervalHandle>(
+ deps: DesktopProcessObservabilityDeps<IntervalHandle>,
+): DesktopProcessObservability {
+ let interval: IntervalHandle | undefined;
+ let lastSample: DesktopProcessSample | null = null;
+ const lastKnownRendererPids = new WeakMap<ObservedBrowserWindow, number>();
+
+ const inspectTrackedWindow = (
+ window: ObservedBrowserWindow,
+ identity?: WindowIdentity,
+ ): WindowSample => {
+ const details = inspectWindow(window, identity);
+ if (details.rendererPid !== null) {
+ lastKnownRendererPids.set(window, details.rendererPid);
+ } else if (details.state === 'crashed' || details.state === 'destroyed') {
+ details.rendererPid = lastKnownRendererPids.get(window) ?? null;
+ } else {
+ lastKnownRendererPids.delete(window);
+ }
+ return details;
+ };
+
+ const capture = (): DesktopProcessSample | null => {
+ try {
+ const processes = deps
+ .getAppMetrics()
+ .map(normalizeProcess)
+ .sort(
+ (left, right) => right.workingSetSizeKb - left.workingSetSizeKb || left.pid - right.pid,
+ );
+ const windows = deps
+ .getAllWindows()
+ .map((window) => inspectTrackedWindow(window))
+ .filter((window) => window.state !== 'destroyed')
+ .sort(
+ (left, right) =>
+ (left.windowId ?? Number.MAX_SAFE_INTEGER) -
+ (right.windowId ?? Number.MAX_SAFE_INTEGER),
+ );
+ return {
+ capturedAt: deps.now().toISOString(),
+ processCount: processes.length,
+ processesTruncated: Math.max(0, processes.length - MAX_DESKTOP_PROCESS_SAMPLE_ROWS),
+ processes: processes.slice(0, MAX_DESKTOP_PROCESS_SAMPLE_ROWS),
+ windowCount: windows.length,
+ windowsTruncated: Math.max(0, windows.length - MAX_DESKTOP_WINDOW_SAMPLE_ROWS),
+ windows: windows.slice(0, MAX_DESKTOP_WINDOW_SAMPLE_ROWS),
+ };
+ } catch (err) {
+ deps.logger.warn(
+ { event: 'desktop-process-observability.sample-failed', err },
+ 'desktop process sample failed',
+ );
+ return null;
+ }
+ };
+
+ const sample = (trigger: 'startup' | 'interval' | 'renderer-ready'): void => {
+ const captured = capture();
+ if (captured === null) return;
+ lastSample = captured;
+ deps.logger.info(
+ { event: 'desktop-process-observability.sample', trigger, ...captured },
+ 'desktop process and window sample',
+ );
+ };
+
+ const lifecycle = (
+ window: ObservedBrowserWindow,
+ action: 'created' | 'shown' | 'hidden' | 'minimized' | 'restored' | 'closed',
+ identity: WindowIdentity,
+ ): void => {
+ const details = inspectTrackedWindow(window, identity);
+ let liveWindowCount: number | null = null;
+ try {
+ liveWindowCount = deps
+ .getAllWindows()
+ .map((candidate) => inspectTrackedWindow(candidate))
+ .filter((entry) => entry.state !== 'destroyed').length;
+ } catch (err) {
+ deps.logger.warn(
+ { event: 'desktop-process-observability.window-count-failed', err },
+ 'desktop live-window count failed',
+ );
+ }
+ deps.logger.info(
+ {
+ event: 'desktop-process-observability.window-lifecycle',
+ action,
+ liveWindowCount,
+ ...details,
+ },
+ 'desktop window lifecycle changed',
+ );
+ };
+
+ return {
+ start() {
+ if (interval !== undefined) return;
+ sample('startup');
+ interval = deps.setInterval(() => sample('interval'), DESKTOP_PROCESS_SAMPLE_INTERVAL_MS);
+ },
+ stop() {
+ if (interval === undefined) return;
+ deps.clearInterval(interval);
+ interval = undefined;
+ },
+ sampleNow(trigger) {
+ sample(trigger);
+ },
+ observeWindow(window) {
+ const identity = readWindowIdentity(window);
+ lifecycle(window, 'created', identity);
+ window.on('show', () => lifecycle(window, 'shown', identity));
+ window.on('hide', () => lifecycle(window, 'hidden', identity));
+ window.on('minimize', () => lifecycle(window, 'minimized', identity));
+ window.on('restore', () => lifecycle(window, 'restored', identity));
+ window.on('closed', () => lifecycle(window, 'closed', identity));
+ },
+ snapshotForCrash(affectedRenderer) {
+ const now = deps.now();
+ const sampleAge =
+ lastSample === null ? null : Math.max(0, now.getTime() - Date.parse(lastSample.capturedAt));
+ const liveSample = capture();
+ const lastAffectedWindow =
+ affectedRenderer === undefined
+ ? undefined
+ : lastSample?.windows.find((window) => window.contentsId === affectedRenderer.contentsId);
+ return {
+ affectedRenderer:
+ affectedRenderer === undefined
+ ? null
+ : {
+ ...affectedRenderer,
+ rendererPid:
+ affectedRenderer.rendererPid ?? lastAffectedWindow?.rendererPid ?? null,
+ },
+ lastSampleAgeMs: sampleAge,
+ lastSample,
+ liveSample,
+ };
+ },
+ };
+}
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index 9b4d15504..16b2ebbfd 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -227,6 +227,7 @@ import { copyImageToClipboard } from './copy-image-clipboard.ts';
import {
type CrashDetection,
createCrashDetection,
+ isProcessCrashReason,
SENTINEL_HEARTBEAT_INTERVAL_MS,
startLocalCrashReporter,
} from './crash-detection.ts';
@@ -238,6 +239,11 @@ import {
} from './create-new-project.ts';
import { createDebugIpc, type DebugIpcHandle } from './debug-ipc.ts';
import { flushDesktopLogger, getLogger, getRootDesktopLogger } from './desktop-logger.ts';
+import {
+ createDesktopProcessObservability,
+ type DesktopProcessObservability,
+ readRendererPid,
+} from './desktop-process-observability.ts';
import {
collectDesktopUninstallProjectCandidates,
confirmDesktopUninstall,
@@ -1145,6 +1151,7 @@ let mcpWiringHandle: RunMcpWiringHandle | null = null;
let rendererReadySink: RendererReadySink | null = null;
let crashDetection: CrashDetection | null = null;
let rendererRecovery: RendererRecovery | null = null;
+let desktopProcessObservability: DesktopProcessObservability | null = null;
let crashSentinelHeartbeat: NodeJS.Timeout | null = null;
let osShutdownNoted = false;
@@ -1207,7 +1214,10 @@ function resolveLocalOpCli(): LocalOpCliInvocation {
function runDriverBootSmokeInProduction(): void {
runDriverBootSmoke({
- fork: (entry) => utilityProcess.fork(entry, [], {}) as unknown as DriverUtilityLike,
+ fork: (entry) =>
+ utilityProcess.fork(entry, [], {
+ serviceName: 'OpenKnowledge Driver Boot',
+ }) as unknown as DriverUtilityLike,
quit: () => {
try {
app.quit();
@@ -3788,8 +3798,10 @@ function registerIpcHandlers() {
};
const terminalManager = createTerminalManager({
- forkPtyHost: () =>
- utilityProcess.fork(join(__dirname, 'utility/pty-host.js')) as unknown as PtyUtilityLike,
+ forkPtyHost: (windowId) =>
+ utilityProcess.fork(join(__dirname, 'utility/pty-host.js'), [], {
+ serviceName: `OpenKnowledge Terminal Host ${windowId}`,
+ }) as unknown as PtyUtilityLike,
sendData: (wc, payload) => sendToRenderer(wc, 'ok:pty:data', payload),
sendExit: (wc, payload) => sendToRenderer(wc, 'ok:pty:exit', payload),
sendNotice: (wc, payload) => sendToRenderer(wc, 'ok:pty:notice', payload),
@@ -5851,6 +5863,14 @@ function bootPrimaryInstance(): void {
);
startLocalCrashReporter(crashReporter);
+ desktopProcessObservability = createDesktopProcessObservability({
+ now: () => new Date(),
+ getAppMetrics: () => app.getAppMetrics(),
+ getAllWindows: () => BrowserWindow.getAllWindows(),
+ logger: getLogger('desktop-process-observability'),
+ setInterval: (callback, ms) => setInterval(callback, ms).unref(),
+ clearInterval: (handle) => clearInterval(handle),
+ });
crashDetection = createCrashDetection({
sentinelPath: join(app.getPath('userData'), 'bug-report-dirty-shutdown.json'),
ackStorePath: join(app.getPath('userData'), 'bug-report-crash-acks.json'),
@@ -5935,6 +5955,7 @@ function bootPrimaryInstance(): void {
powerMonitor.on('suspend', () => crashDetection?.noteSuspend());
powerMonitor.on('resume', () => crashDetection?.noteResume());
app.on('browser-window-created', (_event, win) => {
+ desktopProcessObservability?.observeWindow(win);
win.on('session-end', (event) => {
if (crashDetection === null || osShutdownNoted) return;
osShutdownNoted = true;
@@ -5957,20 +5978,46 @@ function bootPrimaryInstance(): void {
if (details.type === 'Utility') {
getServerExitRecorder().noteGoneReason(details.reason);
}
- crashDetection?.handleChildProcessGone(details);
+ const crashReason = isProcessCrashReason(details.reason);
+ const processSnapshot = crashReason
+ ? desktopProcessObservability?.snapshotForCrash()
+ : undefined;
+ crashDetection?.handleChildProcessGone({
+ ...details,
+ processSnapshot,
+ });
+ if (crashReason) flushDesktopLogger();
});
app.on('web-contents-created', (_event, contents) => {
attachRendererConsoleCapture(contents);
contents.on('render-process-gone', (_e, details) => {
- crashDetection?.handleRenderProcessGone(details);
+ let rendererPid: number | null = null;
+ const crashReason = isProcessCrashReason(details.reason);
+ if (crashReason) {
+ rendererPid = readRendererPid(contents);
+ }
+ const processSnapshot = crashReason
+ ? desktopProcessObservability?.snapshotForCrash({
+ contentsId: contents.id,
+ rendererPid,
+ })
+ : undefined;
+ crashDetection?.handleRenderProcessGone({
+ ...details,
+ processSnapshot,
+ });
rendererRecovery?.handleRenderProcessGone(contents, details);
+ if (crashReason) flushDesktopLogger();
});
contents.once('destroyed', () => {
rendererRecovery?.dispose(contents);
});
const retryDelivery = () => crashDetection?.notifyRendererReady();
- contents.on('did-finish-load', retryDelivery);
+ contents.on('did-finish-load', () => {
+ retryDelivery();
+ desktopProcessObservability?.sampleNow('renderer-ready');
+ });
contents.on('did-stop-loading', retryDelivery);
});
@@ -6130,6 +6177,7 @@ function bootPrimaryInstance(): void {
.then(async () => {
startupWaterfall.mark('appReady');
startupWaterfall.otelEnabled = beginRoot();
+ desktopProcessObservability?.start();
logBootAccessibilityPosture();
const shellEnvLogger = {
event: (payload: Record<string, unknown> & { event: string }) =>
@@ -6632,6 +6680,8 @@ function bootPrimaryInstance(): void {
crashSentinelHeartbeat = null;
}
rendererRecovery = null;
+ desktopProcessObservability?.stop();
+ desktopProcessObservability = null;
dockVisibleForWindow.clear();
agentPanelVisibleForWindow.clear();
dockOrderForWindow.clear();
diff --git a/packages/desktop/src/main/terminal-manager.ts b/packages/desktop/src/main/terminal-manager.ts
index ffaada45b..3b3480ff8 100644
--- a/packages/desktop/src/main/terminal-manager.ts
+++ b/packages/desktop/src/main/terminal-manager.ts
@@ -33,7 +33,7 @@ export interface PtyUtilityLike {
type TimerToken = unknown;
export interface TerminalManagerDeps {
- forkPtyHost: () => PtyUtilityLike;
+ forkPtyHost: (windowId: number) => PtyUtilityLike;
sendData: (webContents: SendableWebContents, payload: { ptyId: string; data: string }) => void;
sendExit: (webContents: SendableWebContents, payload: OkPtyExit) => void;
sendNotice?: (webContents: SendableWebContents, payload: OkPtyNotice) => void;
@@ -490,7 +490,7 @@ export function createTerminalManager(deps: TerminalManagerDeps): TerminalManage
existing.webContents = req.webContents;
return existing;
}
- const utility = deps.forkPtyHost();
+ const utility = deps.forkPtyHost(req.windowId);
const handle: PtyWindowHandle = {
webContents: req.webContents,
utility,
diff --git a/packages/desktop/src/main/window-manager.ts b/packages/desktop/src/main/window-manager.ts
index 915463831..e82f7cf71 100644
--- a/packages/desktop/src/main/window-manager.ts
+++ b/packages/desktop/src/main/window-manager.ts
@@ -229,7 +229,7 @@ export interface WindowManagerDeps {
forkUtility(
entry: string,
args: string[],
- opts: { windowLifecycleBound?: boolean },
+ opts: { windowLifecycleBound?: boolean; serviceName: string },
): UtilityProcessLike;
utilityEntryPath: string;
spawnDetachedServer?(opts: {
@@ -353,6 +353,8 @@ export class WindowManager {
private readonly keepalives = new Map<string, KeepaliveHandle>();
+ private projectServerSequence = 0;
+
private readonly deps: WindowManagerDeps;
constructor(deps: WindowManagerDeps) {
@@ -1209,12 +1211,22 @@ export class WindowManager {
? resolveLocalOpCliArgsForUtilityFork(opts.localOpCliInvocation)
: null;
+ const serviceName = `OpenKnowledge Project Server ${++this.projectServerSequence}`;
const utility = this.deps.forkUtility(
this.deps.utilityEntryPath,
[`--ok-lock-dir-b64=${Buffer.from(lockDir, 'utf8').toString('base64url')}`],
{
windowLifecycleBound: true,
+ serviceName,
+ },
+ );
+ this.deps.log?.info(
+ {
+ event: 'desktop-project-server-forked',
+ name: serviceName,
+ projectPath,
},
+ '[window-manager] project server utility forked',
);
const utilityRef = utility;
const stopUtilityWaitHeartbeat = startBootHeartbeat(
diff --git a/packages/desktop/tests/main/terminal-manager.test.ts b/packages/desktop/tests/main/terminal-manager.test.ts
index af65d5eaf..2d58b0856 100644
--- a/packages/desktop/tests/main/terminal-manager.test.ts
+++ b/packages/desktop/tests/main/terminal-manager.test.ts
@@ -70,10 +70,12 @@ function makeManager(over?: Partial<TerminalManagerDeps>) {
const timerDelays: number[] = [];
const warns: Array<Record<string, unknown>> = [];
const infos: Array<Record<string, unknown>> = [];
+ const forkedWindowIds: number[] = [];
let idn = 0;
const mgr = createTerminalManager({
canSpawnAt: () => true,
- forkPtyHost: () => {
+ forkPtyHost: (windowId) => {
+ forkedWindowIds.push(windowId);
const u = new FakeUtility();
forked.push(u);
return u as unknown as PtyUtilityLike;
@@ -128,6 +130,7 @@ function makeManager(over?: Partial<TerminalManagerDeps>) {
forked,
warns,
infos,
+ forkedWindowIds,
runTimers,
dataPayloads,
exits,
@@ -454,6 +457,7 @@ describe('createTerminalManager — create', () => {
rows: 24,
});
expect(r).toEqual({ ok: true, ptyId: 'pty-1' });
+ expect(h.forkedWindowIds).toEqual([1]);
expect(h.forked).toHaveLength(1);
expect(h.forked[0]?.posted).toEqual([
{ type: 'create', ptyId: 'pty-1', cwd: PROJECT, cols: 80, rows: 24 },
@@ -725,6 +729,7 @@ describe('createTerminalManager — create', () => {
rows: 24,
});
expect(h.forked).toHaveLength(2);
+ expect(h.forkedWindowIds).toEqual([1, 2]);
});
});
diff --git a/packages/desktop/tests/main/window-manager.test.ts b/packages/desktop/tests/main/window-manager.test.ts
index 4229cc593..cb46b3e9e 100644
--- a/packages/desktop/tests/main/window-manager.test.ts
+++ b/packages/desktop/tests/main/window-manager.test.ts
@@ -115,6 +115,8 @@ interface TestEnv {
projectPath?: string;
}>;
forkUtilityArgs: string[][];
+ forkUtilityOpts: Array<{ windowLifecycleBound?: boolean; serviceName: string }>;
+ logEntries: Array<{ payload: object; message: string }>;
timers: Array<{ cb: () => void; ms: number }>;
killProbe: ReturnType<typeof vi.fn>;
activateApp: ReturnType<typeof vi.fn>;
@@ -131,6 +133,8 @@ function buildEnv(): TestEnv {
projectPath?: string;
}> = [];
const forkUtilityArgs: string[][] = [];
+ const forkUtilityOpts: Array<{ windowLifecycleBound?: boolean; serviceName: string }> = [];
+ const logEntries: Array<{ payload: object; message: string }> = [];
const timers: Array<{ cb: () => void; ms: number }> = [];
const killProbe = vi.fn(() => {});
const activateApp = vi.fn(() => {});
@@ -155,6 +159,8 @@ function buildEnv(): TestEnv {
windows,
createWindowOpts,
forkUtilityArgs,
+ forkUtilityOpts,
+ logEntries,
timers,
killProbe,
activateApp,
@@ -166,8 +172,9 @@ function buildEnv(): TestEnv {
windows.push(w);
return w;
},
- forkUtility: (_entry, args) => {
+ forkUtility: (_entry, args, opts) => {
forkUtilityArgs.push(args);
+ forkUtilityOpts.push(opts);
const u = makeUtility(++pidCounter);
utilities.push(u);
return u;
@@ -182,6 +189,11 @@ function buildEnv(): TestEnv {
killProbe,
activateApp,
showGate,
+ log: {
+ info: (payload, message) => logEntries.push({ payload, message }),
+ warn: (payload, message) => logEntries.push({ payload, message }),
+ error: (payload, message) => logEntries.push({ payload, message }),
+ },
},
};
}
@@ -232,6 +244,17 @@ describe('WindowManager', () => {
const promise = wm.createProjectWindow({ projectPath: '/tmp/test-project' });
expect(env.utilities.length).toBe(1);
+ expect(env.forkUtilityOpts).toEqual([
+ { windowLifecycleBound: true, serviceName: 'OpenKnowledge Project Server 1' },
+ ]);
+ expect(env.logEntries).toContainEqual({
+ payload: {
+ event: 'desktop-project-server-forked',
+ name: 'OpenKnowledge Project Server 1',
+ projectPath: '/tmp/test-project',
+ },
+ message: '[window-manager] project server utility forked',
+ });
const marker = env.forkUtilityArgs[0]?.find((arg) => arg.startsWith('--ok-lock-dir-b64='));
expect(marker).toBeDefined();
expect(
@@ -261,6 +284,18 @@ describe('WindowManager', () => {
expect(env.windows.length).toBe(1);
expect(env.windows[0]?.loadFile).toHaveBeenCalledWith('/fake/renderer/index.html');
+
+ const secondPromise = wm.createProjectWindow({ projectPath: '/tmp/second-project' });
+ expect(env.forkUtilityOpts[1]).toEqual({
+ windowLifecycleBound: true,
+ serviceName: 'OpenKnowledge Project Server 2',
+ });
+ env.utilities[1]?.fire({
+ type: 'ready',
+ port: 51235,
+ apiOrigin: 'http://localhost:51235',
+ });
+ await secondPromise;
});
test('createProjectWindow binds the utility server to numeric IPv4 loopback, never a hostname', async () => {
diff --git a/packages/desktop/tests/smoke/liveness-watchdog.e2e.ts b/packages/desktop/tests/smoke/liveness-watchdog.e2e.ts
index 9df3f07fc..4edb7c417 100644
--- a/packages/desktop/tests/smoke/liveness-watchdog.e2e.ts
+++ b/packages/desktop/tests/smoke/liveness-watchdog.e2e.ts
@@ -1,5 +1,5 @@
import { spawnSync } from 'node:child_process';
-import { existsSync, mkdtempSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { type ElectronApplication, _electron as electron } from '@playwright/test';
@@ -43,6 +43,22 @@ function readBootBreadcrumbs(tmpHome: string): BootBreadcrumb[] {
return out.sort((a, b) => Date.parse(a.time) - Date.parse(b.time));
}
+function readDesktopEvents(tmpHome: string): Array<Record<string, unknown>> {
+ const logsDir = join(tmpHome, '.ok', 'logs');
+ if (!existsSync(logsDir)) return [];
+ const lines = readdirSync(logsDir)
+ .filter((name) => name.startsWith('desktop.') && name.endsWith('.log'))
+ .flatMap((name) => readFileSync(join(logsDir, name), 'utf8').split('\n'));
+ const out: Array<Record<string, unknown>> = [];
+ for (const line of lines) {
+ try {
+ const parsed = JSON.parse(line) as Record<string, unknown>;
+ if (typeof parsed.event === 'string') out.push(parsed);
+ } catch {}
+ }
+ return out;
+}
+
function readWitness(tmpHome: string): WitnessRecord | null {
const path = join(userDataDirFor(tmpHome), 'bug-report-main-thread-liveness.json');
try {
@@ -154,4 +170,127 @@ test.describe('liveness watchdog separates a frozen main thread from a dead one
expect(breadcrumb.dirtyShutdown).toBe(true);
expect(breadcrumb.livenessVerdict).toBe('died');
});
+
+ test('Utility and renderer crashes remain recoverable before an external process-tree kill (PRD-8779)', async ({
+ captureStderrFor,
+ }) => {
+ test.setTimeout(200_000);
+ const tmpHome = mkdtempSync(join(tmpdir(), 'ok-process-crash-chain-'));
+ const utilityEntry = join(tmpHome, 'crash-utility.mjs');
+ writeFileSync(
+ utilityEntry,
+ `setTimeout(() => typeof process.crash === 'function' ? process.crash() : process.abort(), 100)\n`,
+ );
+ const app = await launchIsolated(tmpHome);
+ captureStderrFor(app, { cleanupDirs: [tmpHome] });
+ await expect
+ .poll(
+ () =>
+ readDesktopEvents(tmpHome).some(
+ (event) =>
+ event.event === 'desktop-process-observability.sample' &&
+ event.trigger === 'renderer-ready',
+ ),
+ { timeout: 30_000 },
+ )
+ .toBe(true);
+ await waitForWitnessPings(tmpHome, 2);
+
+ const utilityExit = await app.evaluate(async ({ utilityProcess }, entry) => {
+ return await new Promise<{ code: number | null; timedOut: boolean }>((resolve) => {
+ const child = utilityProcess.fork(entry, [], { serviceName: 'PRD-8779 crash probe' });
+ const timer = setTimeout(() => {
+ child.kill();
+ resolve({ code: null, timedOut: true });
+ }, 10_000);
+ child.once('exit', (code) => {
+ clearTimeout(timer);
+ resolve({ code, timedOut: false });
+ });
+ });
+ }, utilityEntry);
+ expect(utilityExit.timedOut).toBe(false);
+ await expect
+ .poll(
+ () =>
+ readDesktopEvents(tmpHome).some(
+ (event) => event.event === 'crash-detection.child-process-gone',
+ ),
+ { timeout: 20_000 },
+ )
+ .toBe(true);
+
+ const renderer = await app.evaluate(async ({ BrowserWindow }) => {
+ const window = BrowserWindow.getAllWindows().find((candidate) => !candidate.isDestroyed());
+ if (window === undefined) throw new Error('no live window to crash');
+ const target = {
+ contentsId: window.webContents.id,
+ rendererPid: window.webContents.getOSProcessId(),
+ };
+ window.webContents.debugger.attach('1.3');
+ try {
+ await window.webContents.debugger.sendCommand('Page.crash');
+ } catch {}
+ return target;
+ });
+ await expect
+ .poll(
+ () =>
+ readDesktopEvents(tmpHome).some(
+ (event) => event.event === 'crash-detection.render-process-gone',
+ ),
+ { timeout: 20_000 },
+ )
+ .toBe(true);
+ await expect
+ .poll(
+ () =>
+ app.evaluate(({ BrowserWindow }) => {
+ const window = BrowserWindow.getAllWindows().find(
+ (candidate) => !candidate.isDestroyed(),
+ );
+ return (
+ window !== undefined &&
+ !window.webContents.isCrashed() &&
+ !window.webContents.isLoading()
+ );
+ }),
+ { timeout: 30_000 },
+ )
+ .toBe(true);
+
+ const events = readDesktopEvents(tmpHome);
+ const childCrash = events.find((event) => event.event === 'crash-detection.child-process-gone');
+ const rendererCrash = events.find(
+ (event) => event.event === 'crash-detection.render-process-gone',
+ );
+ expect(childCrash).toMatchObject({
+ processType: 'Utility',
+ reason: 'crashed',
+ name: 'PRD-8779 crash probe',
+ processSnapshot: {
+ lastSample: { processes: expect.any(Array), windows: expect.any(Array) },
+ liveSample: { processes: expect.any(Array), windows: expect.any(Array) },
+ },
+ });
+ expect(rendererCrash).toMatchObject({
+ reason: 'crashed',
+ processSnapshot: {
+ affectedRenderer: renderer,
+ lastSample: {
+ processes: expect.arrayContaining([
+ expect.objectContaining({ pid: renderer.rendererPid, type: 'Tab' }),
+ ]),
+ },
+ liveSample: { processes: expect.any(Array), windows: expect.any(Array) },
+ },
+ });
+ expect(app.process().exitCode).toBeNull();
+
+ await killProcessTree(app);
+ const breadcrumb = await relaunchAndReadBreadcrumb(tmpHome, captureStderrFor);
+ console.log('[process-crash-chain] breadcrumb', JSON.stringify(breadcrumb));
+ expect(breadcrumb.dirtyShutdown).toBe(true);
+ expect(breadcrumb.livenessVerdict).toBe('died');
+ });
});