Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Capture packaged Windows terminal startup evidence (#5746)

Nick Gomez0f83483ed510
diff --git a/packages/desktop/scripts/pty-phase-evidence.mjs b/packages/desktop/scripts/pty-phase-evidence.mjs
new file mode 100644
index 000000000..b3aed948e
--- /dev/null
+++ b/packages/desktop/scripts/pty-phase-evidence.mjs
@@ -0,0 +1,246 @@
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function readPtyPhaseRecords(text) {
+ const records = [];
+ for (const line of text.split(/\r?\n/u)) {
+ let entry;
+ try {
+ entry = JSON.parse(line);
+ } catch {
+ continue;
+ }
+ const candidates = entry?.event === 'pty-phase-trace' ? entry.records : [entry];
+ if (!Array.isArray(candidates)) continue;
+ for (const record of candidates) {
+ if (
+ record?.event === 'pty-phase' &&
+ typeof record.producer === 'string' &&
+ typeof record.phase === 'string' &&
+ ['begin', 'end', 'error', 'point'].includes(record.edge) &&
+ Number.isFinite(record.atMs) &&
+ Number.isInteger(record.sequence)
+ )
+ records.push(record);
+ }
+ }
+ return records;
+}
+
+function measurePtyIntervals(records) {
+ const spawnEnds = new Map();
+ const firstOutputs = new Map();
+ const intervals = [];
+ const interval = (from, to) => ({
+ producer: to.producer,
+ pid: to.pid,
+ ptyId: to.ptyId,
+ from: from.phase,
+ to: to.phase,
+ durationMs: to.atMs - from.atMs,
+ fromSequence: from.sequence,
+ toSequence: to.sequence,
+ });
+ for (const record of records) {
+ const key = JSON.stringify([record.producer, record.pid, record.timeOriginMs, record.ptyId]);
+ if (record.phase === 'pty-spawn' && record.edge === 'end') spawnEnds.set(key, record);
+ else if (record.phase === 'pty-first-output' && record.currentSession === true) {
+ const spawnEnd = spawnEnds.get(key);
+ if (spawnEnd) intervals.push(interval(spawnEnd, record));
+ firstOutputs.set(key, record);
+ } else if (record.phase === 'pty-first-forward') {
+ const firstOutput = firstOutputs.get(key);
+ if (firstOutput) intervals.push(interval(firstOutput, record));
+ }
+ }
+ return intervals;
+}
+
+const isOutcomeWait = (span) => span.producer === 'renderer' && span.phase === 'evaluation';
+
+export function summarizePtyPhases(records) {
+ const pending = new Map();
+ const completed = [];
+ const incomplete = [];
+ for (const record of records) {
+ const key = JSON.stringify([
+ record.producer,
+ record.pid,
+ record.timeOriginMs,
+ record.phase,
+ record.scope ?? record.ptyId,
+ ]);
+ if (record.edge === 'begin') {
+ if (pending.has(key)) incomplete.push(pending.get(key));
+ pending.set(key, record);
+ } else if (record.edge === 'end' || record.edge === 'error') {
+ const begin = pending.get(key);
+ if (begin) {
+ completed.push({
+ producer: record.producer,
+ pid: record.pid,
+ phase: record.phase,
+ scope: record.scope,
+ ptyId: record.ptyId,
+ outcome: record.edge,
+ durationMs: record.atMs - begin.atMs,
+ beginSequence: begin.sequence,
+ endSequence: record.sequence,
+ });
+ pending.delete(key);
+ } else incomplete.push(record);
+ }
+ }
+ incomplete.push(...pending.values());
+ return {
+ completed,
+ incomplete,
+ longestCompleted: completed
+ .filter((span) => !isOutcomeWait(span))
+ .reduce(
+ (longest, span) => (!longest || span.durationMs > longest.durationMs ? span : longest),
+ null,
+ ),
+ intervals: measurePtyIntervals(records),
+ missingProducers: ['renderer', 'main', 'utility'].filter(
+ (producer) => !records.some((record) => record.producer === producer),
+ ),
+ limited: records.some((record) => record.phase === 'trace-limit'),
+ droppedWrites: records.filter((record) => record.droppedWrites > 0),
+ clockScope:
+ 'Durations compare marks within one process only; wall/time-origin anchors across processes are approximate.',
+ };
+}
+
+const INCIDENT_FILES = ['bug-report-main-thread-stall.json', 'bug-report-main-exit.json'];
+const WATCHDOG_FILES = [
+ 'bug-report-main-thread-liveness.json',
+ 'bug-report-dirty-shutdown.json',
+ ...INCIDENT_FILES,
+];
+
+export function preservePtyEvidence({
+ diagnosticsDir,
+ logPath,
+ logDir,
+ userDataDir,
+ launchedAt,
+ appPid,
+ driver,
+}) {
+ mkdirSync(diagnosticsDir, { recursive: true });
+ const destination = mkdtempSync(join(diagnosticsDir, 'run-'));
+ const files = [];
+ const capture = (source, target) => {
+ try {
+ const bytes = readFileSync(source);
+ writeFileSync(join(destination, target), bytes);
+ files.push({ source, target, status: 'copied', bytes: bytes.length });
+ return bytes.toString('utf8');
+ } catch (error) {
+ files.push({
+ source,
+ target,
+ status: error.code === 'ENOENT' ? 'missing' : 'unavailable',
+ error: error.message,
+ });
+ return '';
+ }
+ };
+ const appOutput = capture(logPath, 'app-stdio.log');
+ writeFileSync(join(destination, 'driver.stdout.log'), driver?.stdout ?? '');
+ writeFileSync(join(destination, 'driver.stderr.log'), driver?.stderr ?? '');
+ const observed = [
+ ...readPtyPhaseRecords(appOutput),
+ ...readPtyPhaseRecords(driver?.stdout ?? ''),
+ ...readPtyPhaseRecords(driver?.stderr ?? ''),
+ ];
+ const ownPaths = (records) =>
+ records.findLast(
+ (record) =>
+ record.producer === 'main' &&
+ record.pid === appPid &&
+ record.phase === 'paths' &&
+ record.wallTimeMs >= launchedAt,
+ );
+ const stdioPaths = ownPaths(observed);
+ const actualLogDir = typeof stdioPaths?.logDir === 'string' ? stdioPaths.logDir : logDir;
+ mkdirSync(join(destination, 'desktop-logs'));
+ try {
+ const names = readdirSync(actualLogDir).filter((name) =>
+ /^desktop.*\.log(?:\.\d+)?$/u.test(name),
+ );
+ if (names.length === 0) {
+ files.push({
+ source: actualLogDir,
+ target: 'desktop-logs',
+ status: 'missing',
+ error: 'no file matching desktop*.log',
+ });
+ }
+ for (const name of names) {
+ const text = capture(join(actualLogDir, name), join('desktop-logs', name));
+ observed.push(
+ ...readPtyPhaseRecords(text).filter((record) => record.wallTimeMs >= launchedAt),
+ );
+ }
+ } catch (error) {
+ files.push({
+ source: actualLogDir,
+ target: 'desktop-logs',
+ status: 'unavailable',
+ error: error.message,
+ });
+ }
+ const paths = ownPaths(observed);
+ const actualUserData = typeof paths?.userDataDir === 'string' ? paths.userDataDir : userDataDir;
+ mkdirSync(join(destination, 'user-data'));
+ for (const name of WATCHDOG_FILES) capture(join(actualUserData, name), join('user-data', name));
+ const incidentSources = new Set(INCIDENT_FILES.map((name) => join(actualUserData, name)));
+ const unique = new Map(
+ observed.map((record) => [
+ JSON.stringify([record.producer, record.pid, record.timeOriginMs, record.sequence]),
+ record,
+ ]),
+ );
+ const records = [...unique.values()].sort(
+ (a, b) =>
+ a.producer.localeCompare(b.producer) ||
+ String(a.pid).localeCompare(String(b.pid)) ||
+ (a.timeOriginMs ?? 0) - (b.timeOriginMs ?? 0) ||
+ a.sequence - b.sequence,
+ );
+ writeFileSync(
+ join(destination, 'phase-trace.jsonl'),
+ records.map((record) => JSON.stringify(record)).join('\n'),
+ );
+ writeFileSync(
+ join(destination, 'phase-summary.json'),
+ JSON.stringify(summarizePtyPhases(records), null, 2),
+ );
+ const manifest = {
+ launchedAt,
+ appPid,
+ logDir: actualLogDir,
+ userDataDir: actualUserData,
+ userDataSource: paths ? 'app-record' : 'requested-unconfirmed',
+ driver: driver
+ ? { status: driver.status, signal: driver.signal, error: driver.error?.message }
+ : { status: null, observation: 'not-returned' },
+ collection: files.some(
+ (file) =>
+ file.status === 'unavailable' ||
+ (file.status === 'missing' && !incidentSources.has(file.source)),
+ )
+ ? 'partial'
+ : 'copied',
+ files,
+ phaseRecords: records.length,
+ duplicatePhaseRecords: observed.length - records.length,
+ rendererCollectionUnavailable: (driver?.stderr ?? '').includes(
+ '"event": "pty-phase-trace-unavailable"',
+ ),
+ };
+ writeFileSync(join(destination, 'manifest.json'), JSON.stringify(manifest, null, 2));
+ return destination;
+}
diff --git a/packages/desktop/scripts/pty-phase-evidence.test.ts b/packages/desktop/scripts/pty-phase-evidence.test.ts
new file mode 100644
index 000000000..da1bac9d1
--- /dev/null
+++ b/packages/desktop/scripts/pty-phase-evidence.test.ts
@@ -0,0 +1,418 @@
+import {
+ appendFileSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, expect, test, vi } from 'vitest';
+import { createPtyPhaseTrace } from '../src/shared/pty-phase-trace.ts';
+import { type PtyProcessLike, setupPtyHost } from '../src/utility/pty-host.ts';
+import {
+ preservePtyEvidence,
+ readPtyPhaseRecords,
+ summarizePtyPhases,
+} from './pty-phase-evidence.mjs';
+
+const fixtures: string[] = [];
+afterEach(() => {
+ vi.restoreAllMocks();
+ for (const path of fixtures.splice(0)) rmSync(path, { recursive: true, force: true });
+});
+
+test('the retained artifact attributes a controlled host delay without inferring missing phases', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-phase-artifact-'));
+ fixtures.push(root);
+ const logDir = join(root, 'logs');
+ mkdirSync(logDir);
+ const logPath = join(root, 'stdio.log');
+ const SHELL_LOOKUP_DELAY_MS = 1000;
+ let clock = 0;
+ vi.spyOn(performance, 'now').mockImplementation(() => clock);
+ let receive = (_event: { data: unknown }) => {};
+ const pty: PtyProcessLike = {
+ pid: 12345,
+ onData() {},
+ onExit() {},
+ write() {},
+ resize() {},
+ kill() {},
+ pause() {},
+ resume() {},
+ };
+ setupPtyHost({
+ phaseTrace: createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: '1' }, 'utility', (record) =>
+ appendFileSync(logPath, `${JSON.stringify(record)}\n`),
+ ),
+ env: {},
+ platform: 'win32',
+ parentPort: {
+ on(_event, callback) {
+ receive = callback;
+ },
+ postMessage() {},
+ },
+ shellExists: () => {
+ clock += SHELL_LOOKUP_DELAY_MS;
+ return true;
+ },
+ spawn: () => pty,
+ });
+ receive({
+ data: {
+ type: 'create',
+ ptyId: 'retained-session',
+ cwd: 'C:\\project',
+ cols: 80,
+ rows: 24,
+ shell: 'C:\\Windows\\System32\\cmd.exe',
+ },
+ });
+ const destination = preservePtyEvidence({
+ diagnosticsDir: join(root, 'retained'),
+ logPath,
+ logDir,
+ userDataDir: join(root, 'profile'),
+ launchedAt: 0,
+ appPid: process.pid,
+ driver: { status: 1, stdout: '', stderr: 'echo failed' },
+ });
+ rmSync(logDir, { recursive: true });
+ rmSync(logPath);
+ const summary = JSON.parse(readFileSync(join(destination, 'phase-summary.json'), 'utf8'));
+ expect(summary.longestCompleted).toMatchObject({
+ producer: 'utility',
+ phase: 'shell-resolution',
+ ptyId: 'retained-session',
+ outcome: 'end',
+ durationMs: SHELL_LOOKUP_DELAY_MS,
+ });
+ expect(summary.incomplete).toEqual([]);
+ expect(summary.missingProducers).toEqual(['renderer', 'main']);
+ expect(
+ readPtyPhaseRecords(readFileSync(join(destination, 'phase-trace.jsonl'), 'utf8')).some(
+ (record: { phase: string }) => record.phase === 'shell-resolution',
+ ),
+ ).toBe(true);
+ const manifest = JSON.parse(readFileSync(join(destination, 'manifest.json'), 'utf8'));
+ expect(manifest.driver.status).toBe(1);
+ expect(manifest.userDataSource).toBe('requested-unconfirmed');
+ expect(manifest.files.some((file: { status: string }) => file.status === 'missing')).toBe(true);
+});
+
+test('the retained summary measures the wait from native spawn to first output and on to first forward', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-phase-interval-'));
+ fixtures.push(root);
+ const logDir = join(root, 'logs');
+ mkdirSync(logDir);
+ const logPath = join(root, 'stdio.log');
+ const SPAWN_TO_OUTPUT_DELAY_MS = 3000;
+ const FORWARD_DELAY_MS = 40;
+ let clock = 0;
+ vi.spyOn(performance, 'now').mockImplementation(() => clock);
+ let receive = (_event: { data: unknown }) => {};
+ let output = (_data: string) => {};
+ const pty: PtyProcessLike = {
+ pid: 12345,
+ onData(listener) {
+ output = listener;
+ },
+ onExit() {},
+ write() {},
+ resize() {},
+ kill() {},
+ pause() {},
+ resume() {},
+ };
+ setupPtyHost({
+ phaseTrace: createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: '1' }, 'utility', (record) =>
+ appendFileSync(logPath, `${JSON.stringify(record)}\n`),
+ ),
+ env: {},
+ platform: 'win32',
+ parentPort: {
+ on(_event, callback) {
+ receive = callback;
+ },
+ postMessage(message) {
+ if (message.type === 'data') clock += FORWARD_DELAY_MS;
+ },
+ },
+ shellExists: () => true,
+ spawn: () => pty,
+ });
+ receive({
+ data: {
+ type: 'create',
+ ptyId: 'late-output',
+ cwd: 'C:\\project',
+ cols: 80,
+ rows: 24,
+ shell: 'C:\\Windows\\System32\\cmd.exe',
+ },
+ });
+ clock += SPAWN_TO_OUTPUT_DELAY_MS;
+ output('Microsoft Windows\r\n');
+ const destination = preservePtyEvidence({
+ diagnosticsDir: join(root, 'retained'),
+ logPath,
+ logDir,
+ userDataDir: join(root, 'profile'),
+ launchedAt: 0,
+ appPid: process.pid,
+ driver: { status: 1, stdout: '', stderr: 'echo failed' },
+ });
+ const summary = JSON.parse(readFileSync(join(destination, 'phase-summary.json'), 'utf8'));
+ expect(summary.intervals).toEqual([
+ expect.objectContaining({
+ producer: 'utility',
+ ptyId: 'late-output',
+ from: 'pty-spawn',
+ to: 'pty-first-output',
+ durationMs: SPAWN_TO_OUTPUT_DELAY_MS,
+ }),
+ expect.objectContaining({
+ producer: 'utility',
+ ptyId: 'late-output',
+ from: 'pty-first-output',
+ to: 'pty-first-forward',
+ durationMs: FORWARD_DELAY_MS,
+ }),
+ ]);
+});
+
+test('pairs first output only with the successful spawn of the current session, and first forward with that output', () => {
+ const PTY_ID = 'replaced-session';
+ let sequence = 0;
+ const mark = (
+ phase: string,
+ edge: string,
+ atMs: number,
+ context: Record<string, unknown> = {},
+ ) => ({
+ event: 'pty-phase',
+ producer: 'utility',
+ pid: 4,
+ timeOriginMs: 11,
+ sequence: ++sequence,
+ phase,
+ edge,
+ atMs,
+ ptyId: PTY_ID,
+ ...context,
+ });
+ const replacedSpawnBegin = mark('pty-spawn', 'begin', 1, { attempt: 1, backend: 'bundled' });
+ const replacedSpawnEnd = mark('pty-spawn', 'end', 2, { attempt: 1, backend: 'bundled' });
+ const bundledBegin = mark('pty-spawn', 'begin', 10, { attempt: 1, backend: 'bundled' });
+ const bundledError = mark('pty-spawn', 'error', 12, { attempt: 1, backend: 'bundled' });
+ const inboxBegin = mark('pty-spawn', 'begin', 13, { attempt: 2, backend: 'inbox' });
+ const inboxEnd = mark('pty-spawn', 'end', 20, { attempt: 2, backend: 'inbox' });
+ const replacedOutput = mark('pty-first-output', 'point', 35, { currentSession: false });
+ const currentOutput = mark('pty-first-output', 'point', 50, { currentSession: true });
+ const firstForward = mark('pty-first-forward', 'point', 54);
+ const summary = summarizePtyPhases([
+ replacedSpawnBegin,
+ replacedSpawnEnd,
+ bundledBegin,
+ bundledError,
+ inboxBegin,
+ inboxEnd,
+ replacedOutput,
+ currentOutput,
+ firstForward,
+ ]);
+ expect(summary.intervals).toEqual([
+ {
+ producer: 'utility',
+ pid: 4,
+ ptyId: PTY_ID,
+ from: 'pty-spawn',
+ to: 'pty-first-output',
+ durationMs: currentOutput.atMs - inboxEnd.atMs,
+ fromSequence: inboxEnd.sequence,
+ toSequence: currentOutput.sequence,
+ },
+ {
+ producer: 'utility',
+ pid: 4,
+ ptyId: PTY_ID,
+ from: 'pty-first-output',
+ to: 'pty-first-forward',
+ durationMs: firstForward.atMs - currentOutput.atMs,
+ fromSequence: currentOutput.sequence,
+ toSequence: firstForward.sequence,
+ },
+ ]);
+});
+
+test('the longest completed span names an app phase rather than the renderer evaluation that waits for the echo', () => {
+ const PTY_ID = 'echo-timeout';
+ const CREATE_MS = 120;
+ const START_MS = 30;
+ const ECHO_TIMEOUT_MS = 15_000;
+ const CLEANUP_MS = 10;
+ const SHELL_RESOLUTION_BEGIN_MS = 40;
+ const SHELL_RESOLUTION_MS = 600;
+ let rendererSequence = 0;
+ const renderer = (phase: string, edge: string, atMs: number, ptyId: string | null = null) => ({
+ event: 'pty-phase',
+ producer: 'renderer',
+ timeOriginMs: 7,
+ sequence: ++rendererSequence,
+ phase,
+ edge,
+ ptyId,
+ atMs,
+ });
+ let utilitySequence = 0;
+ const utility = (phase: string, edge: string, atMs: number) => ({
+ event: 'pty-phase',
+ producer: 'utility',
+ pid: 4,
+ timeOriginMs: 11,
+ sequence: ++utilitySequence,
+ phase,
+ edge,
+ ptyId: PTY_ID,
+ atMs,
+ });
+ const startBeginMs = CREATE_MS;
+ const cleanupEndMs = ECHO_TIMEOUT_MS + CLEANUP_MS;
+ const summary = summarizePtyPhases([
+ renderer('evaluation', 'begin', 0),
+ renderer('create', 'begin', 0),
+ renderer('create', 'end', CREATE_MS),
+ renderer('start', 'begin', startBeginMs, PTY_ID),
+ renderer('start', 'end', startBeginMs + START_MS, PTY_ID),
+ renderer('echo-timer', 'point', ECHO_TIMEOUT_MS, PTY_ID),
+ renderer('cleanup', 'begin', ECHO_TIMEOUT_MS, PTY_ID),
+ renderer('cleanup', 'end', cleanupEndMs, PTY_ID),
+ renderer('evaluation', 'error', cleanupEndMs),
+ utility('shell-resolution', 'begin', SHELL_RESOLUTION_BEGIN_MS),
+ utility('shell-resolution', 'end', SHELL_RESOLUTION_BEGIN_MS + SHELL_RESOLUTION_MS),
+ ]);
+ expect(summary.completed).toContainEqual(
+ expect.objectContaining({
+ producer: 'renderer',
+ phase: 'evaluation',
+ outcome: 'error',
+ durationMs: cleanupEndMs,
+ }),
+ );
+ expect(summary.longestCompleted).toMatchObject({
+ producer: 'utility',
+ phase: 'shell-resolution',
+ ptyId: PTY_ID,
+ outcome: 'end',
+ durationMs: SHELL_RESOLUTION_MS,
+ });
+});
+
+const LIVENESS = 'bug-report-main-thread-liveness.json';
+const DIRTY_SHUTDOWN = 'bug-report-dirty-shutdown.json';
+const STALL = 'bug-report-main-thread-stall.json';
+const MAIN_EXIT = 'bug-report-main-exit.json';
+const DESKTOP_LOG = 'desktop.2026-10-06.log';
+
+function collectForcedStopEvidence({
+ omit,
+ unreadable,
+}: {
+ omit?: string;
+ unreadable?: string;
+} = {}) {
+ const root = mkdtempSync(join(tmpdir(), 'ok-phase-collection-'));
+ fixtures.push(root);
+ const logDir = join(root, 'logs');
+ const userDataDir = join(root, 'profile');
+ const logPath = join(root, 'stdio.log');
+ mkdirSync(logDir);
+ mkdirSync(userDataDir);
+ if (omit !== 'app-stdio.log') writeFileSync(logPath, 'app output\n');
+ if (omit !== 'desktop-logs') writeFileSync(join(logDir, DESKTOP_LOG), '{"event":"boot"}\n');
+ for (const name of [LIVENESS, DIRTY_SHUTDOWN]) {
+ if (name !== omit) writeFileSync(join(userDataDir, name), '{}\n');
+ }
+ if (unreadable) mkdirSync(join(userDataDir, unreadable));
+ const destination = preservePtyEvidence({
+ diagnosticsDir: join(root, 'retained'),
+ logPath,
+ logDir,
+ userDataDir,
+ launchedAt: 0,
+ appPid: process.pid,
+ driver: { status: 0, stdout: '', stderr: '' },
+ });
+ const manifest = JSON.parse(readFileSync(join(destination, 'manifest.json'), 'utf8'));
+ const sources: Record<string, string> = {
+ 'app-stdio.log': logPath,
+ 'desktop-logs': logDir,
+ [DESKTOP_LOG]: join(logDir, DESKTOP_LOG),
+ };
+ const statusOf = (name: string) =>
+ manifest.files.find(
+ (file: { source: string }) => file.source === (sources[name] ?? join(userDataDir, name)),
+ )?.status;
+ return { collection: manifest.collection, statusOf };
+}
+
+test('a forced stop with no incident counts the evidence as fully collected', () => {
+ const { collection, statusOf } = collectForcedStopEvidence();
+ expect(statusOf('app-stdio.log')).toBe('copied');
+ expect(statusOf(DESKTOP_LOG)).toBe('copied');
+ expect(statusOf(LIVENESS)).toBe('copied');
+ expect(statusOf(DIRTY_SHUTDOWN)).toBe('copied');
+ expect(statusOf(STALL)).toBe('missing');
+ expect(statusOf(MAIN_EXIT)).toBe('missing');
+ expect(collection).toBe('copied');
+});
+
+test.each(['app-stdio.log', 'desktop-logs', LIVENESS, DIRTY_SHUTDOWN])(
+ 'a run without %s counts the evidence as partial',
+ (name) => {
+ const { collection, statusOf } = collectForcedStopEvidence({ omit: name });
+ expect(statusOf(name)).toBe('missing');
+ expect(collection).toBe('partial');
+ },
+);
+
+test('an incident file that cannot be read counts the evidence as partial', () => {
+ const { collection, statusOf } = collectForcedStopEvidence({ unreadable: STALL });
+ expect(statusOf(STALL)).toBe('unavailable');
+ expect(collection).toBe('partial');
+});
+
+test('keeps interrupted phases and separates process clock origins', () => {
+ const records = readPtyPhaseRecords(
+ [
+ 'not a record',
+ JSON.stringify({
+ event: 'pty-phase',
+ producer: 'utility',
+ pid: 4,
+ timeOriginMs: 11,
+ sequence: 1,
+ phase: 'native-import',
+ edge: 'begin',
+ atMs: 2,
+ }),
+ JSON.stringify({
+ event: 'pty-phase',
+ producer: 'utility',
+ pid: 5,
+ timeOriginMs: 22,
+ sequence: 1,
+ phase: 'native-import',
+ edge: 'end',
+ atMs: 900,
+ }),
+ ].join('\n'),
+ );
+ const summary = summarizePtyPhases(records);
+ expect(summary.completed).toEqual([]);
+ expect(summary.longestCompleted).toBeNull();
+ expect(summary.incomplete).toHaveLength(2);
+});
diff --git a/packages/desktop/scripts/smoke-terminal-package-cdp.py b/packages/desktop/scripts/smoke-terminal-package-cdp.py
index c2a14dafd..d87e15c77 100755
--- a/packages/desktop/scripts/smoke-terminal-package-cdp.py
+++ b/packages/desktop/scripts/smoke-terminal-package-cdp.py
@@ -231,6 +231,20 @@ def evaluate_pty_echo(socket_url: str) -> Dict[str, object]:
}}
const marker = {json.dumps(MARKER)};
const startedAt = performance.now();
+ const phaseRecords = {json.dumps(os.environ.get("OK_PTY_PHASE_TRACE") == "1")} ? [] : null;
+ if (phaseRecords) window.__okPtyPhaseTrace = phaseRecords;
+ const markPhase = phaseRecords ? (phase, edge, ptyId = null) => {{
+ if (phaseRecords.length >= 256) return;
+ const sequence = phaseRecords.length + 1;
+ phaseRecords.push({{
+ event: 'pty-phase', producer: 'renderer', sequence,
+ phase: sequence === 256 ? 'trace-limit' : phase,
+ edge: sequence === 256 ? 'point' : edge,
+ ptyId, atMs: performance.now(), wallTimeMs: Date.now(),
+ timeOriginMs: performance.timeOrigin,
+ }});
+ }} : undefined;
+ markPhase?.('evaluation', 'begin');
return await new Promise(async (resolve, reject) => {{
let output = '';
let ptyId = null;
@@ -250,14 +264,20 @@ def evaluate_pty_echo(socket_url: str) -> Dict[str, object]:
const finish = async (error) => {{
if (settled) return;
settled = true;
+ markPhase?.('cleanup', 'begin', ptyId);
clearTimeout(timeout);
for (const release of releases) release();
if (ptyId !== null) await bridge.terminal.kill(ptyId).catch(() => {{}});
+ markPhase?.('cleanup', 'end', ptyId);
+ markPhase?.('evaluation', error ? 'error' : 'end');
if (error) reject(error);
else resolve({{ output, platform: bridge.platform, timings: timings(), endings, notices }});
}};
const consume = (data, at) => {{
- if (firstByteAt === null) firstByteAt = at;
+ if (firstByteAt === null) {{
+ firstByteAt = at;
+ markPhase?.('first-data', 'point', ptyId);
+ }}
output += data;
const plainOutput = output
.replace(
@@ -279,12 +299,14 @@ def evaluate_pty_echo(socket_url: str) -> Dict[str, object]:
}}
}};
const timeout = setTimeout(
- () =>
+ () => {{
+ markPhase?.('echo-timer', 'point', ptyId);
void finish(
new Error(
`PTY echo timed out; output=${{JSON.stringify(output)}}; timings=${{JSON.stringify(timings())}}; endings=${{JSON.stringify(endings)}}; notices=${{JSON.stringify(notices)}}`,
),
- ),
+ );
+ }},
{renderer_echo_timeout_ms()},
);
try {{
@@ -293,9 +315,11 @@ def evaluate_pty_echo(socket_url: str) -> Dict[str, object]:
consume(message.data, performance.now());
}}));
releases.push(bridge.terminal.onExit((message) => {{
+ if (endings.length === 0) markPhase?.('first-exit', 'point', message.ptyId);
endings.push({{ ...message, atMs: sinceStart(performance.now()) }});
}}));
releases.push(bridge.terminal.onNotice((message) => {{
+ if (notices.length === 0) markPhase?.('first-notice', 'point', message.ptyId);
notices.push({{ ...message, atMs: sinceStart(performance.now()) }});
}}));
}} catch (error) {{
@@ -303,7 +327,10 @@ def evaluate_pty_echo(socket_url: str) -> Dict[str, object]:
return;
}}
const isWindows = bridge.platform === 'win32';
- const created = await bridge.terminal.create({{
+ markPhase?.('create', 'begin');
+ let created;
+ try {{
+ created = await bridge.terminal.create({{
cols: 80,
rows: 24,
...(isWindows
@@ -315,13 +342,26 @@ def evaluate_pty_echo(socket_url: str) -> Dict[str, object]:
}}
: {{}}),
}});
+ }} catch (error) {{
+ markPhase?.('create', 'error');
+ throw error;
+ }}
+ markPhase?.('create', 'end');
if (!created.ok) {{
await finish(new Error(`PTY create failed: ${{created.reason}}`));
return;
}}
createdAt = performance.now();
ptyId = created.ptyId;
- const attached = await bridge.terminal.start(ptyId);
+ markPhase?.('start', 'begin', ptyId);
+ let attached;
+ try {{
+ attached = await bridge.terminal.start(ptyId);
+ }} catch (error) {{
+ markPhase?.('start', 'error', ptyId);
+ throw error;
+ }}
+ markPhase?.('start', 'end', ptyId);
if (!attached.ok) {{
await finish(new Error(`PTY attach failed: ${{attached.reason}}`));
return;
@@ -341,6 +381,25 @@ def evaluate_pty_echo(socket_url: str) -> Dict[str, object]:
f"renderer_timer={renderer_echo_timeout_ms() / 1000:.0f}s; "
f"error={type(error).__name__}: {error}"
) from error
+ finally:
+ if os.environ.get("OK_PTY_PHASE_TRACE") == "1":
+ try:
+ remaining = budget_ms / 1000 - (time.monotonic() - started)
+ if remaining <= 0:
+ raise TimeoutError("the original echo budget is exhausted")
+ records = evaluate_value(socket_url, "window.__okPtyPhaseTrace ?? null", timeout=remaining)
+ print(json.dumps({"event": "pty-phase-trace", "socketUrl": socket_url, "records": records}))
+ except Exception as trace_error:
+ print(
+ json.dumps(
+ {
+ "event": "pty-phase-trace-unavailable",
+ "errorType": type(trace_error).__name__,
+ "error": str(trace_error),
+ }
+ ),
+ file=sys.stderr,
+ )
if not isinstance(value, dict):
raise RuntimeError(f"renderer returned no PTY smoke result: {value}")
return value
diff --git a/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs b/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs
new file mode 100644
index 000000000..03eb2892d
--- /dev/null
+++ b/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs
@@ -0,0 +1,124 @@
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+ writeSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, expect, test, vi } from 'vitest';
+
+const child = vi.hoisted(() => ({ spawn: vi.fn(), spawnSync: vi.fn() }));
+vi.mock('node:child_process', () => child);
+
+import { runWindowsPackageTerminalSmoke } from './smoke-windows-terminal-package.mjs';
+
+const fixtures = [];
+afterEach(() => {
+ vi.restoreAllMocks();
+ for (const path of fixtures.splice(0)) rmSync(path, { recursive: true, force: true });
+});
+
+test.each([0, 1])(
+ 'preserves the packaged observation files before cleanup when the driver exits %i',
+ (status) => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-pty-evidence-'));
+ fixtures.push(root);
+ const packageDir = join(root, 'package');
+ const diagnosticsDir = join(root, 'evidence');
+ const logDir = join(root, 'desktop-logs');
+ mkdirSync(packageDir);
+ mkdirSync(logDir);
+ writeFileSync(join(packageDir, 'OpenKnowledge.exe'), 'fixture');
+ let profile;
+ child.spawn.mockImplementation((_file, args, options) => {
+ profile = args
+ .find((arg) => arg.startsWith('--user-data-dir='))
+ .slice('--user-data-dir='.length);
+ writeFileSync(join(profile, 'bug-report-main-thread-liveness.json'), '{"lastAck":1}');
+ const record = {
+ event: 'pty-phase',
+ producer: 'main',
+ pid: 12345,
+ sequence: 1,
+ atMs: 0,
+ wallTimeMs: Date.now(),
+ phase: 'paths',
+ edge: 'point',
+ userDataDir: profile,
+ logDir,
+ };
+ writeFileSync(join(logDir, 'desktop.log'), `${JSON.stringify(record)}\n{"event":"boot"}\n`);
+ writeSync(options.stdio[1], `${JSON.stringify(record)}\napp output\n`);
+ return { pid: 12345 };
+ });
+ child.spawnSync.mockImplementation((file) =>
+ file === 'taskkill'
+ ? { status: 0 }
+ : { status, stdout: 'driver output', stderr: status ? 'original echo failure' : '' },
+ );
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+ vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+ vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+ const run = () =>
+ runWindowsPackageTerminalSmoke({
+ packageDir,
+ diagnosticsDir,
+ platform: 'win32',
+ env: { ComSpec: 'C:\\Windows\\System32\\cmd.exe' },
+ });
+ if (status) expect(run).toThrow('packaged PTY CDP driver exited 1 (signal undefined)');
+ else run();
+ expect(existsSync(profile)).toBe(false);
+ expect(existsSync(diagnosticsDir), 'the uploaded evidence must survive fixture deletion').toBe(
+ true,
+ );
+ const saved = join(diagnosticsDir, readdirSync(diagnosticsDir)[0]);
+ expect(readFileSync(join(saved, 'app-stdio.log'), 'utf8')).toContain('app output');
+ expect(readFileSync(join(saved, 'desktop-logs', 'desktop.log'), 'utf8')).toContain(
+ '"event":"boot"',
+ );
+ expect(
+ readFileSync(join(saved, 'user-data', 'bug-report-main-thread-liveness.json'), 'utf8'),
+ ).toBe('{"lastAck":1}');
+ expect(readFileSync(join(saved, 'driver.stdout.log'), 'utf8')).toBe('driver output');
+ expect(readFileSync(join(saved, 'driver.stderr.log'), 'utf8')).toBe(
+ status ? 'original echo failure' : '',
+ );
+ expect(JSON.parse(readFileSync(join(saved, 'manifest.json'), 'utf8')).driver.status).toBe(
+ status,
+ );
+ },
+);
+
+test.each([0, 1])(
+ 'keeps the original driver outcome %i when evidence cannot be saved',
+ (status) => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-pty-evidence-error-'));
+ fixtures.push(root);
+ writeFileSync(join(root, 'OpenKnowledge.exe'), 'fixture');
+ const diagnosticsDir = join(root, 'file-instead-of-directory');
+ writeFileSync(diagnosticsDir, 'occupied');
+ child.spawn.mockReturnValue({ pid: undefined });
+ child.spawnSync.mockReturnValue({ status, signal: null, stdout: '', stderr: '' });
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const run = () =>
+ runWindowsPackageTerminalSmoke({
+ packageDir: root,
+ diagnosticsDir,
+ platform: 'win32',
+ env: { ComSpec: 'C:\\Windows\\System32\\cmd.exe' },
+ });
+ if (status) expect(run).toThrow('packaged PTY CDP driver exited 1 (signal null)');
+ else expect(run).not.toThrow();
+ expect(warning.mock.calls.flat().join('\n')).toContain(
+ 'Could not preserve packaged PTY diagnostics',
+ );
+ expect(readFileSync(diagnosticsDir, 'utf8')).toBe('occupied');
+ },
+);
diff --git a/packages/desktop/scripts/smoke-windows-terminal-package.mjs b/packages/desktop/scripts/smoke-windows-terminal-package.mjs
index 5459320d4..c83625606 100644
--- a/packages/desktop/scripts/smoke-windows-terminal-package.mjs
+++ b/packages/desktop/scripts/smoke-windows-terminal-package.mjs
@@ -18,7 +18,8 @@ import {
SPAWN_STARTUP_DEADLINE_MS,
SPAWN_WAIT_EXTENSION_FACTOR,
} from '../src/shared/boot-narration.ts';
-import { readBootLog } from '../tests/smoke/_helpers/launch-readiness.ts';
+import { bootLogDirFor, readBootLog } from '../tests/smoke/_helpers/launch-readiness.ts';
+import { preservePtyEvidence } from './pty-phase-evidence.mjs';
export const PACKAGED_BOOT_ENVELOPE_MS = 10_000;
export const PACKAGED_PTY_ECHO_BUDGET_MS = 30_000;
@@ -85,6 +86,7 @@ export function windowsPackageLaunchArgs(projectDir, userDataDir) {
export function windowsPtyDriverEnv(env = process.env) {
return {
...env,
+ OK_PTY_PHASE_TRACE: '1',
OK_SMOKE_EXPECT_PLATFORM: 'win32',
OK_SMOKE_DISCOVERY_DEADLINE_MS: String(packagedDiscoveryDeadlineMs()),
OK_SMOKE_ECHO_DEADLINE_MS: String(PACKAGED_PTY_ECHO_BUDGET_MS),
@@ -92,7 +94,7 @@ export function windowsPtyDriverEnv(env = process.env) {
}
export function windowsPackageAppEnv(env = process.env) {
- return { ...env, OK_DESKTOP_E2E_SMOKE: '1', OK_LOG_LEVEL: 'info' };
+ return { ...env, OK_DESKTOP_E2E_SMOKE: '1', OK_LOG_LEVEL: 'info', OK_PTY_PHASE_TRACE: '1' };
}
export function seedWindowsPtySmokeProject(rootDir, shellPath) {
@@ -156,6 +158,7 @@ export function readTerminalSubsystemLog(launchedAt, home = homedir()) {
export function runWindowsPackageTerminalSmoke({
packageDir = defaultPackageDir,
+ diagnosticsDir = resolve(scriptDir, '../windows-terminal-package-diagnostics'),
platform = process.platform,
env = process.env,
python = env.OK_PYTHON ?? 'python',
@@ -176,6 +179,7 @@ export function runWindowsPackageTerminalSmoke({
const logFd = openSync(logPath, 'w');
const launchedAt = Date.now();
let app = null;
+ let driver = null;
try {
app = spawn(executable, windowsPackageLaunchArgs(projectDir, userDataDir), {
@@ -185,11 +189,7 @@ export function runWindowsPackageTerminalSmoke({
windowsHide: true,
});
- const driver = spawnSync(
- python,
- [cdpDriver],
- packagedDriverSpawnOptions(resolvedPackageDir, env),
- );
+ driver = spawnSync(python, [cdpDriver], packagedDriverSpawnOptions(resolvedPackageDir, env));
if (driver.stdout) process.stdout.write(driver.stdout);
if (driver.stderr) process.stderr.write(driver.stderr);
if (driver.error?.code === 'ETIMEDOUT') {
@@ -214,6 +214,20 @@ export function runWindowsPackageTerminalSmoke({
try {
closeSync(logFd);
} catch {}
+ try {
+ const evidence = preservePtyEvidence({
+ diagnosticsDir,
+ logPath,
+ logDir: bootLogDirFor(homedir()),
+ userDataDir,
+ launchedAt,
+ appPid: app?.pid,
+ driver,
+ });
+ console.log(`Packaged PTY diagnostics: ${evidence}`);
+ } catch (error) {
+ console.warn(`Could not preserve packaged PTY diagnostics: ${error.message}`);
+ }
try {
rmSync(smokeRoot, { recursive: true, force: true });
} catch (error) {
diff --git a/packages/desktop/scripts/smoke-windows-terminal-package.test.mjs b/packages/desktop/scripts/smoke-windows-terminal-package.test.mjs
index d836a5cf1..262fc9342 100644
--- a/packages/desktop/scripts/smoke-windows-terminal-package.test.mjs
+++ b/packages/desktop/scripts/smoke-windows-terminal-package.test.mjs
@@ -1,8 +1,6 @@
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
import { once } from 'node:events';
import {
- constants,
- copyFileSync,
existsSync,
mkdirSync,
mkdtempSync,
@@ -20,6 +18,7 @@ import {
SPAWN_STARTUP_DEADLINE_MS,
SPAWN_WAIT_EXTENSION_FACTOR,
} from '../src/shared/boot-narration.ts';
+import { preservePtyEvidence, readPtyPhaseRecords } from './pty-phase-evidence.mjs';
import {
describeDriverTimeoutBudget,
PACKAGED_BOOT_ENVELOPE_MS,
@@ -160,21 +159,24 @@ function drainDriverBytecode() {
return left;
}
-function ptyEchoSnippet() {
+function ptyEchoSnippet(trace = false) {
const extractor = [
- 'import importlib.util, sys, types',
+ 'import contextlib, importlib.util, io, sys, types',
"sys.modules['websocket'] = types.ModuleType('websocket')",
`spec = importlib.util.spec_from_file_location('d', ${JSON.stringify(driverPath)})`,
'm = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)',
'seen = {}',
'def fake(socket_url, expression, timeout=5):',
- " seen['e'] = expression",
+ " if 'e' not in seen: seen['e'] = expression",
" return {'platform': 'win32'}",
'm.evaluate_value = fake',
- "m.evaluate_pty_echo('ws://stub')",
+ "with contextlib.redirect_stdout(io.StringIO()): m.evaluate_pty_echo('ws://stub')",
"sys.stdout.write(seen['e'])",
].join('\n');
- const run = runPython(['-c', extractor], { OK_SMOKE_ECHO_DEADLINE_MS: '10500' });
+ const run = runPython(['-c', extractor], {
+ OK_SMOKE_ECHO_DEADLINE_MS: '10500',
+ OK_PTY_PHASE_TRACE: trace ? '1' : '',
+ });
if (run.code !== 0) throw new Error(`snippet extraction failed: ${run.output}`);
return run.output;
}
@@ -237,8 +239,8 @@ function stubRenderer({ duringStart = [] } = {}) {
};
}
-function runPtyEchoSnippet(window) {
- return new Function('window', `return (\n${ptyEchoSnippet()}\n);`)(window);
+function runPtyEchoSnippet(window, trace = false) {
+ return new Function('window', `return (\n${ptyEchoSnippet(trace)}\n);`)(window);
}
function rejectionOf(pending) {
@@ -381,6 +383,7 @@ describe('packaged Windows terminal smoke driver', () => {
test('requires the CDP driver to exercise its Windows branch', () => {
expect(windowsPtyDriverEnv({ SENTINEL: 'preserved' })).toEqual({
SENTINEL: 'preserved',
+ OK_PTY_PHASE_TRACE: '1',
OK_SMOKE_EXPECT_PLATFORM: 'win32',
OK_SMOKE_DISCOVERY_DEADLINE_MS: String(packagedDiscoveryDeadlineMs()),
OK_SMOKE_ECHO_DEADLINE_MS: String(PACKAGED_PTY_ECHO_BUDGET_MS),
@@ -413,7 +416,9 @@ describe('packaged Windows terminal smoke driver', () => {
});
vi.resetModules();
- for (const [key, value] of Object.entries(spawned)) vi.stubEnv(key, value);
+ for (const [key, value] of Object.entries(spawned)) {
+ if (key !== 'OK_DESKTOP_E2E_SMOKE') vi.stubEnv(key, value);
+ }
try {
const { getRootDesktopLogger } = await import('../src/main/desktop-logger.ts');
const logger = getRootDesktopLogger();
@@ -1075,7 +1080,7 @@ describe('packaged Windows terminal smoke driver', () => {
).toContain(UNREADABLE_LOG);
});
- test('prints the terminal records this launch wrote, and none from before it, when the driver fails', () => {
+ test('prints the terminal records this launch wrote, and none from before it, when the driver fails', async () => {
const earlierSession = JSON.stringify({
time: BEFORE_LAUNCH,
level: 40,
@@ -1093,10 +1098,17 @@ describe('packaged Windows terminal smoke driver', () => {
const home = homeWithLogs([earlierSession, thisLaunch]);
const packageDir = join(home, 'win-unpacked');
mkdirSync(packageDir);
- copyFileSync(
- process.execPath,
- join(packageDir, 'OpenKnowledge.exe'),
- constants.COPYFILE_FICLONE,
+ writeFileSync(join(packageDir, 'OpenKnowledge.exe'), 'fixture');
+ vi.resetModules();
+ vi.doMock('node:child_process', async (importOriginal) => ({
+ ...(await importOriginal()),
+ spawn: () => ({ pid: undefined }),
+ spawnSync: () => ({
+ error: Object.assign(new Error('fixture python ENOENT'), { code: 'ENOENT' }),
+ }),
+ }));
+ const { runWindowsPackageTerminalSmoke: run } = await import(
+ './smoke-windows-terminal-package.mjs'
);
vi.stubEnv('HOME', home);
@@ -1106,8 +1118,9 @@ describe('packaged Windows terminal smoke driver', () => {
const printed = vi.spyOn(console, 'error').mockImplementation(() => {});
try {
expect(() =>
- runWindowsPackageTerminalSmoke({
+ run({
packageDir,
+ diagnosticsDir: join(home, 'evidence'),
platform: 'win32',
env: { ...process.env, ComSpec: 'C:\\Windows\\System32\\cmd.exe' },
python: join(home, 'no-python-here'),
@@ -1121,6 +1134,8 @@ describe('packaged Windows terminal smoke driver', () => {
'the app shares one log file per day across every session on the host, so a record from before this launch printed beside its own reads to a triager as something this run did',
).not.toContain(earlierSession);
} finally {
+ vi.doUnmock('node:child_process');
+ vi.resetModules();
printed.mockRestore();
vi.useRealTimers();
vi.unstubAllEnvs();
@@ -1200,3 +1215,165 @@ describe('packaged Windows terminal smoke driver', () => {
}
});
});
+
+test.each([false, true])(
+ 'keeps the real renderer echo result while phase tracing is %s',
+ async (enabled) => {
+ const window = stubRenderer();
+ let deliver;
+ const subscribe = window.okDesktop.terminal.onData;
+ window.okDesktop.terminal.onData = (listener) => {
+ deliver = listener;
+ return subscribe(listener);
+ };
+ window.okDesktop.terminal.start = async () => {
+ deliver({ ptyId: STUB_PTY_ID, data: MARKER_LINE });
+ return { ok: true };
+ };
+ const result = await runPtyEchoSnippet(window, enabled);
+ expect(result.output).toBe(MARKER_LINE);
+ expect(result.platform).toBe('win32');
+ expect(window.subscriptionAudit().active).toEqual({ data: 0, exit: 0, notice: 0 });
+ if (!enabled) expect(Object.hasOwn(window, '__okPtyPhaseTrace')).toBe(false);
+ else {
+ const pairs = window.__okPtyPhaseTrace.map(({ phase, edge }) => `${phase}:${edge}`);
+ for (const phase of ['evaluation', 'create', 'start', 'cleanup']) {
+ expect(pairs).toContain(`${phase}:begin`);
+ expect(pairs).toContain(`${phase}:end`);
+ }
+ expect(pairs).toContain('first-data:point');
+ expect(window.__okPtyPhaseTrace.find((record) => record.phase === 'start')).toMatchObject({
+ ptyId: STUB_PTY_ID,
+ });
+ }
+ },
+);
+
+test('does not refresh the echo budget to collect a renderer trace or replace its failure', () => {
+ const result = runPython(
+ [
+ '-c',
+ [
+ 'import importlib.util, sys, types',
+ 'sys.stderr = sys.stdout',
+ "sys.modules['websocket'] = types.ModuleType('websocket')",
+ `spec = importlib.util.spec_from_file_location('d', ${JSON.stringify(driverPath)})`,
+ 'm = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)',
+ 'clock = iter([0, 31, 31])',
+ 'm.time.monotonic = lambda: next(clock)',
+ 'calls = []',
+ 'def evaluate(*args, **kwargs):',
+ ' calls.append(args)',
+ " raise RuntimeError('original echo failure')",
+ 'm.evaluate_value = evaluate',
+ 'try:',
+ " m.evaluate_pty_echo('ws://stub')",
+ 'except RuntimeError as error:',
+ " print('ORIGINAL=' + str(error.__cause__))",
+ "print('CALLS=' + str(len(calls)))",
+ ].join('\n'),
+ ],
+ { OK_PTY_PHASE_TRACE: '1', OK_SMOKE_ECHO_DEADLINE_MS: '30000' },
+ );
+ expect(result.code).toBe(0);
+ expect(result.output).toContain('CALLS=1');
+ expect(result.output).toContain('ORIGINAL=original echo failure');
+ expect(result.output).toContain(
+ '{"event": "pty-phase-trace-unavailable", "errorType": "TimeoutError"',
+ );
+});
+
+test.each([
+ {
+ traceRead: 'answers',
+ replies: (echo, trace) => [echo, trace],
+ survivors: (trace) => trace,
+ rendererSpans: ['cleanup', 'create', 'evaluation', 'start'],
+ unavailable: false,
+ },
+ {
+ traceRead: 'fails',
+ replies: (echo) => [echo],
+ survivors: () => [],
+ rendererSpans: [],
+ unavailable: true,
+ },
+])(
+ 'retains the renderer phase records the driver prints when its trace read $traceRead',
+ async ({ replies, survivors, rendererSpans, unavailable }) => {
+ const window = stubRenderer();
+ let deliver;
+ const subscribe = window.okDesktop.terminal.onData;
+ window.okDesktop.terminal.onData = (listener) => {
+ deliver = listener;
+ return subscribe(listener);
+ };
+ window.okDesktop.terminal.start = async () => {
+ deliver({ ptyId: STUB_PTY_ID, data: MARKER_LINE });
+ return { ok: true };
+ };
+ const echo = await runPtyEchoSnippet(window, true);
+ const trace = window.__okPtyPhaseTrace;
+ expect(trace.length).toBeGreaterThan(0);
+
+ const driver = spawnSync(
+ pythonBin,
+ [
+ '-c',
+ [
+ 'import importlib.util, json, sys, types',
+ "sys.modules['websocket'] = types.ModuleType('websocket')",
+ `spec = importlib.util.spec_from_file_location('d', ${JSON.stringify(driverPath)})`,
+ 'm = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)',
+ 'replies = json.load(sys.stdin)',
+ 'm.time.monotonic = lambda: 0.0',
+ "m.find_editor_websocket = lambda: 'ws://stub'",
+ 'def evaluate(socket_url, expression, timeout=5):',
+ ' if not replies:',
+ " raise RuntimeError('the renderer trace read failed')",
+ ' return replies.pop(0)',
+ 'm.evaluate_value = evaluate',
+ 'raise SystemExit(m.main())',
+ ].join('\n'),
+ ],
+ {
+ encoding: 'utf8',
+ env: windowsPtyDriverEnv({ ...process.env, PYTHONDONTWRITEBYTECODE: '1' }),
+ input: JSON.stringify(replies(echo, trace)),
+ },
+ );
+ expect(driver.error).toBeUndefined();
+ expect(driver.status, driver.stderr).toBe(0);
+
+ const root = mkdtempSync(join(tmpdir(), 'ok-renderer-envelope-'));
+ fixtures.push(root);
+ const logDir = join(root, 'logs');
+ const logPath = join(root, 'stdio.log');
+ mkdirSync(logDir);
+ writeFileSync(logPath, '');
+ const destination = preservePtyEvidence({
+ diagnosticsDir: join(root, 'retained'),
+ logPath,
+ logDir,
+ userDataDir: join(root, 'profile'),
+ launchedAt: 0,
+ appPid: process.pid,
+ driver,
+ });
+ const retained = readPtyPhaseRecords(
+ readFileSync(join(destination, 'phase-trace.jsonl'), 'utf8'),
+ );
+ const summary = JSON.parse(readFileSync(join(destination, 'phase-summary.json'), 'utf8'));
+ const manifest = JSON.parse(readFileSync(join(destination, 'manifest.json'), 'utf8'));
+
+ expect(retained.filter((record) => record.producer === 'renderer')).toEqual(survivors(trace));
+ expect(
+ summary.completed
+ .filter((span) => span.producer === 'renderer')
+ .map((span) => span.phase)
+ .sort(),
+ ).toEqual(rendererSpans);
+ expect(summary.missingProducers.includes('renderer')).toBe(unavailable);
+ expect(manifest.rendererCollectionUnavailable).toBe(unavailable);
+ },
+);
diff --git a/packages/desktop/src/main/desktop-logger.ts b/packages/desktop/src/main/desktop-logger.ts
index c0ac02176..0976e2fdf 100644
--- a/packages/desktop/src/main/desktop-logger.ts
+++ b/packages/desktop/src/main/desktop-logger.ts
@@ -3,7 +3,7 @@ import { join } from 'node:path';
import { okUserHomeDir } from '@inkeep/open-knowledge-core/server';
import pino from 'pino';
-function okLogsDir(): string {
+export function desktopLogDirectory(): string {
return join(okUserHomeDir(), 'logs');
}
const MAX_AGE_DAYS = 7;
@@ -89,10 +89,10 @@ let rootDest: { flushSync: () => void } | undefined;
function getRootLogger(): pino.Logger {
if (rootLogger) return rootLogger;
- mkdirSync(okLogsDir(), { recursive: true });
- setTimeout(() => pruneLogsDir(okLogsDir()), 5000);
+ mkdirSync(desktopLogDirectory(), { recursive: true });
+ setTimeout(() => pruneLogsDir(desktopLogDirectory()), 5000);
- const filePath = join(okLogsDir(), logFileName);
+ const filePath = join(desktopLogDirectory(), logFileName);
const dest = pino.destination({ dest: filePath, append: true, sync: false });
rootDest = dest as unknown as { flushSync: () => void };
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index 2e7dc1e81..d41daa519 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -158,6 +158,7 @@ import type {
import type { EventChannels } from '../shared/ipc-events.ts';
import { createHandler } from '../shared/ipc-handler.ts';
import { registerPendingDelivery, sendToRenderer } from '../shared/ipc-send.ts';
+import { createPtyPhaseTrace } from '../shared/pty-phase-trace.ts';
import { UNINSTALL_PRELOAD_ARG } from '../shared/uninstall-preload-arg.ts';
import { getWindowsEnvValue } from '../shared/windows-env.ts';
import { resolveShell } from '../utility/pty-host.ts';
@@ -243,7 +244,12 @@ import {
runCreateNew,
} from './create-new-project.ts';
import { createDebugIpc, type DebugIpcHandle } from './debug-ipc.ts';
-import { flushDesktopLogger, getLogger, getRootDesktopLogger } from './desktop-logger.ts';
+import {
+ desktopLogDirectory,
+ flushDesktopLogger,
+ getLogger,
+ getRootDesktopLogger,
+} from './desktop-logger.ts';
import {
createDesktopProcessObservability,
type DesktopProcessObservability,
@@ -408,6 +414,7 @@ import {
type ProjectMcpReclaimCliSurface,
} from './project-mcp-reclaim.ts';
import { createProjectSessionHandlers } from './project-session.ts';
+import { observePtyFork } from './pty-phase-observation.ts';
import { readHeadBranch as readHeadBranchImpl } from './read-head-branch.ts';
import {
applyReducedTransparency,
@@ -3859,11 +3866,23 @@ function registerIpcHandlers() {
}
};
+ const phaseTrace = createPtyPhaseTrace(process.env, 'main', (record) => {
+ if (record.phase === 'paths') process.stderr.write(`${JSON.stringify(record)}\n`);
+ getLogger('terminal').info({ ...record }, 'PTY phase');
+ });
+ phaseTrace?.mark('paths', 'point', {
+ userDataDir: app.getPath('userData'),
+ logDir: desktopLogDirectory(),
+ });
+ let nextTraceRequest = 0;
+ let nextTraceFork = 0;
const terminalManager = createTerminalManager({
forkPtyHost: (windowId) =>
- utilityProcess.fork(join(__dirname, 'utility/pty-host.js'), [], {
- serviceName: `OpenKnowledge Terminal Host ${windowId}`,
- }) as unknown as PtyUtilityLike,
+ observePtyFork(phaseTrace, windowId, phaseTrace ? ++nextTraceFork : 0, () =>
+ 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),
@@ -3882,57 +3901,79 @@ function registerIpcHandlers() {
terminalReaper = terminalManager;
handle('ok:pty:create', async (event, opts) => {
- const win = BrowserWindow.fromWebContents(event.sender);
- const editorCtx =
- win && wm ? wm.getContextForBrowserWindow(win as unknown as BrowserWindowLike) : null;
- const projectPath = resolvePtyProjectRoot({
- editorProjectPath: editorCtx?.projectPath ?? null,
- terminalWindow: win ? getTerminalWindowContext(win.id) : undefined,
- homedir: osHomedir(),
- });
- if (!win || !projectPath) {
- logIpcError({
- event: 'ipc.error',
- channel: 'ok:pty:create',
- reason: 'no-project',
- handler: 'createPty',
- });
- return { ok: false, reason: 'no-project' };
- }
- if (!isTerminalConsented(projectPath) && !(await isTerminalConsentedWithGrace(projectPath))) {
- logIpcError({
- event: 'ipc.error',
- channel: 'ok:pty:create',
- reason: 'not-consented',
- handler: 'createPty',
+ const traceContext = phaseTrace
+ ? { scope: `request-${++nextTraceRequest}`, webContentsId: event.sender.id }
+ : undefined;
+ phaseTrace?.mark('ipc-create', 'begin', traceContext);
+ let traceFailed = false;
+ try {
+ const win = BrowserWindow.fromWebContents(event.sender);
+ const editorCtx =
+ win && wm ? wm.getContextForBrowserWindow(win as unknown as BrowserWindowLike) : null;
+ const projectPath = resolvePtyProjectRoot({
+ editorProjectPath: editorCtx?.projectPath ?? null,
+ terminalWindow: win ? getTerminalWindowContext(win.id) : undefined,
+ homedir: osHomedir(),
});
- return { ok: false, reason: 'not-consented' };
- }
- if (opts.launchCli !== undefined) {
- await observeTerminalLaunch({
- launchCli: opts.launchCli,
+ if (!win || !projectPath) {
+ logIpcError({
+ event: 'ipc.error',
+ channel: 'ok:pty:create',
+ reason: 'no-project',
+ handler: 'createPty',
+ });
+ return { ok: false, reason: 'no-project' };
+ }
+ if (!isTerminalConsented(projectPath) && !(await isTerminalConsentedWithGrace(projectPath))) {
+ logIpcError({
+ event: 'ipc.error',
+ channel: 'ok:pty:create',
+ reason: 'not-consented',
+ handler: 'createPty',
+ });
+ return { ok: false, reason: 'not-consented' };
+ }
+ if (opts.launchCli !== undefined) {
+ await observeTerminalLaunch({
+ launchCli: opts.launchCli,
+ projectRoot: projectPath,
+ log: getLogger('agent-gate'),
+ snapshot: (projectRoot) =>
+ collectDesktopHostSnapshot({
+ resolve: createCliProbeResolver({ cwd: projectRoot, home: osHomedir() }),
+ }),
+ });
+ }
+ phaseTrace?.mark('configured-shell', 'begin', traceContext);
+ const shellSetting =
+ process.platform === 'win32'
+ ? readTerminalShellSetting(projectPath)
+ : { kind: 'unset' as const };
+ phaseTrace?.mark('configured-shell', 'end', traceContext);
+ phaseTrace?.mark('reservation', 'begin', traceContext);
+ const result = terminalManager.create({
+ windowId: win.id,
+ webContents: win.webContents,
projectRoot: projectPath,
- log: getLogger('agent-gate'),
- snapshot: (projectRoot) =>
- collectDesktopHostSnapshot({
- resolve: createCliProbeResolver({ cwd: projectRoot, home: osHomedir() }),
- }),
+ cols: clampPtyDimension(opts.cols, DEFAULT_PTY_COLS),
+ rows: clampPtyDimension(opts.rows, DEFAULT_PTY_ROWS),
+ ...(shellSetting.kind === 'configured' ? { shell: shellSetting.shell } : {}),
+ ...(shellSetting.kind === 'invalid' ? { shellInvalidReason: shellSetting.reason } : {}),
+ launchCommand: opts.launchCommand,
});
+ phaseTrace?.mark('reservation', 'end', {
+ ...traceContext,
+ windowId: win.id,
+ ...(result.ok ? { ptyId: result.ptyId } : {}),
+ ok: result.ok,
+ });
+ return result;
+ } catch (error) {
+ traceFailed = true;
+ throw error;
+ } finally {
+ phaseTrace?.mark('ipc-create', traceFailed ? 'error' : 'end', traceContext);
}
- const shellSetting =
- process.platform === 'win32'
- ? readTerminalShellSetting(projectPath)
- : { kind: 'unset' as const };
- return terminalManager.create({
- windowId: win.id,
- webContents: win.webContents,
- projectRoot: projectPath,
- cols: clampPtyDimension(opts.cols, DEFAULT_PTY_COLS),
- rows: clampPtyDimension(opts.rows, DEFAULT_PTY_ROWS),
- ...(shellSetting.kind === 'configured' ? { shell: shellSetting.shell } : {}),
- ...(shellSetting.kind === 'invalid' ? { shellInvalidReason: shellSetting.reason } : {}),
- launchCommand: opts.launchCommand,
- });
});
handle('ok:pty:input', async (event, req) => {
const win = BrowserWindow.fromWebContents(event.sender);
@@ -3966,31 +4007,49 @@ function registerIpcHandlers() {
return win ? terminalManager.listSessions(win.id) : [];
});
handle('ok:pty:adopt', async (event, req) => {
- const win = BrowserWindow.fromWebContents(event.sender);
- if (!win) {
- logIpcError({
- event: 'ipc.error',
- channel: 'ok:pty:adopt',
- reason: 'unknown-session',
- handler: 'adoptPty',
+ const traceContext = phaseTrace
+ ? { scope: `request-${++nextTraceRequest}`, webContentsId: event.sender.id }
+ : undefined;
+ const tracePhase = req.start === true ? 'ipc-start' : 'ipc-adopt';
+ phaseTrace?.mark(tracePhase, 'begin', traceContext);
+ let traceFailed = false;
+ try {
+ const win = BrowserWindow.fromWebContents(event.sender);
+ if (!win) {
+ logIpcError({
+ event: 'ipc.error',
+ channel: 'ok:pty:adopt',
+ reason: 'unknown-session',
+ handler: 'adoptPty',
+ });
+ return { ok: false, reason: 'unknown-session' };
+ }
+ phaseTrace?.mark('message-received', 'point', {
+ ...traceContext,
+ windowId: win.id,
+ ptyId: req.ptyId,
});
- return { ok: false, reason: 'unknown-session' };
- }
- const outcome = terminalManager.adoptSession({
- start: req.start,
- windowId: win.id,
- ptyId: req.ptyId,
- webContents: win.webContents,
- });
- if (!outcome.ok) {
- logIpcError({
- event: 'ipc.error',
- channel: 'ok:pty:adopt',
- reason: outcome.reason,
- handler: 'adoptPty',
+ const outcome = terminalManager.adoptSession({
+ start: req.start,
+ windowId: win.id,
+ ptyId: req.ptyId,
+ webContents: win.webContents,
});
+ if (!outcome.ok) {
+ logIpcError({
+ event: 'ipc.error',
+ channel: 'ok:pty:adopt',
+ reason: outcome.reason,
+ handler: 'adoptPty',
+ });
+ }
+ return outcome;
+ } catch (error) {
+ traceFailed = true;
+ throw error;
+ } finally {
+ phaseTrace?.mark(tracePhase, traceFailed ? 'error' : 'end', traceContext);
}
- return outcome;
});
handle('ok:pty:set-meta', async (event, req) => {
const win = BrowserWindow.fromWebContents(event.sender);
diff --git a/packages/desktop/src/main/pty-phase-observation.ts b/packages/desktop/src/main/pty-phase-observation.ts
new file mode 100644
index 000000000..bc0a3bef5
--- /dev/null
+++ b/packages/desktop/src/main/pty-phase-observation.ts
@@ -0,0 +1,35 @@
+import type { PtyPhaseTrace } from '../shared/pty-phase-trace.ts';
+
+interface ObservedUtility {
+ readonly pid: number | undefined;
+ once(event: 'spawn', listener: () => void): unknown;
+ once(event: 'exit', listener: (code: number) => void): unknown;
+}
+
+export function observePtyFork<T extends ObservedUtility>(
+ trace: PtyPhaseTrace | undefined,
+ windowId: number,
+ forkId: number,
+ fork: () => T,
+): T {
+ if (!trace) return fork();
+ const context = { windowId, forkId, scope: `fork-${forkId}` };
+ trace.mark('utility-fork', 'begin', context);
+ let utility: T;
+ try {
+ utility = fork();
+ } catch (error) {
+ trace.mark('utility-fork', 'error', context);
+ throw error;
+ }
+ trace.mark('utility-fork', 'end', context);
+ let utilityPid: number | undefined;
+ utility.once('spawn', () => {
+ utilityPid = utility.pid;
+ trace.mark('utility-spawn', 'point', { ...context, utilityPid });
+ });
+ utility.once('exit', (exitCode) => {
+ trace.mark('utility-exit', 'point', { ...context, utilityPid, exitCode });
+ });
+ return utility;
+}
diff --git a/packages/desktop/src/shared/pty-phase-trace.test.ts b/packages/desktop/src/shared/pty-phase-trace.test.ts
new file mode 100644
index 000000000..ce7f507e1
--- /dev/null
+++ b/packages/desktop/src/shared/pty-phase-trace.test.ts
@@ -0,0 +1,96 @@
+import { EventEmitter } from 'node:events';
+import { closeSync, mkdtempSync, openSync, rmSync, writeSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, expect, test, vi } from 'vitest';
+import { observePtyFork } from '../main/pty-phase-observation.ts';
+import { createPtyPhaseTrace, type PtyPhaseRecord } from './pty-phase-trace.ts';
+
+afterEach(() => vi.restoreAllMocks());
+
+test.each([undefined, '0'])(
+ 'does not read clocks, emit records or install listeners with tracing %s',
+ (flag) => {
+ const now = vi.spyOn(performance, 'now');
+ const wall = vi.spyOn(Date, 'now');
+ const write = vi.fn();
+ const trace = createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: flag }, 'main', write);
+ const utility = Object.assign(new EventEmitter(), { pid: undefined as number | undefined });
+ expect(observePtyFork(trace, 7, 1, () => utility)).toBe(utility);
+ expect(utility.eventNames()).toEqual([]);
+ expect(trace).toBeUndefined();
+ expect(now).not.toHaveBeenCalled();
+ expect(wall).not.toHaveBeenCalled();
+ expect(write).not.toHaveBeenCalled();
+ },
+);
+
+test('records utility creation, owned process identity and exit without an error listener', () => {
+ const records: PtyPhaseRecord[] = [];
+ const trace = createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: '1' }, 'main', (record) =>
+ records.push(record),
+ );
+ const utility = Object.assign(new EventEmitter(), { pid: undefined as number | undefined });
+ expect(observePtyFork(trace, 7, 1, () => utility)).toBe(utility);
+ utility.pid = 12345;
+ utility.emit('spawn');
+ utility.pid = undefined;
+ utility.emit('exit', 3);
+ expect(records.map(({ phase, edge }) => [phase, edge])).toEqual([
+ ['utility-fork', 'begin'],
+ ['utility-fork', 'end'],
+ ['utility-spawn', 'point'],
+ ['utility-exit', 'point'],
+ ]);
+ expect(records.at(-1)).toMatchObject({
+ windowId: 7,
+ forkId: 1,
+ utilityPid: 12345,
+ exitCode: 3,
+ sequence: 4,
+ });
+ expect(utility.listenerCount('error')).toBe(0);
+});
+
+test('bounds an enabled trace with an explicit limit record', () => {
+ const records: PtyPhaseRecord[] = [];
+ const trace = createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: '1' }, 'utility', (record) =>
+ records.push(record),
+ );
+ for (let index = 0; index < 1000; index += 1) trace?.mark('message-received', 'point');
+ expect(records.length).toBeLessThan(1000);
+ expect(records.at(-1)).toMatchObject({
+ phase: 'trace-limit',
+ edge: 'point',
+ sequence: records.length,
+ });
+});
+
+test('a failed diagnostic write cannot replace an operation error', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-phase-write-'));
+ const fd = openSync(join(root, 'closed.log'), 'w');
+ closeSync(fd);
+ try {
+ const trace = createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: '1' }, 'main', () => {
+ writeSync(fd, 'unwritable');
+ });
+ let original: unknown;
+ let caught: unknown;
+ try {
+ observePtyFork(trace, 7, 1, () => {
+ try {
+ return JSON.parse('{');
+ } catch (error) {
+ original = error;
+ throw error;
+ }
+ });
+ } catch (error) {
+ caught = error;
+ }
+ expect(original).toBeInstanceOf(SyntaxError);
+ expect(caught).toBe(original);
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+});
diff --git a/packages/desktop/src/shared/pty-phase-trace.ts b/packages/desktop/src/shared/pty-phase-trace.ts
new file mode 100644
index 000000000..3babb7058
--- /dev/null
+++ b/packages/desktop/src/shared/pty-phase-trace.ts
@@ -0,0 +1,94 @@
+type PtyPhase =
+ | 'module-entry'
+ | 'logger-import'
+ | 'native-import'
+ | 'listener-ready'
+ | 'message-received'
+ | 'shell-resolution'
+ | 'paths'
+ | 'ipc-create'
+ | 'configured-shell'
+ | 'reservation'
+ | 'ipc-start'
+ | 'ipc-adopt'
+ | 'utility-fork'
+ | 'utility-spawn'
+ | 'utility-exit'
+ | 'pty-spawn'
+ | 'pty-first-output'
+ | 'pty-first-forward'
+ | 'pty-exit'
+ | 'trace-limit';
+
+interface PtyPhaseContext {
+ scope?: string;
+ ptyId?: string;
+ windowId?: number;
+ webContentsId?: number;
+ forkId?: number;
+ utilityPid?: number;
+ userDataDir?: string;
+ logDir?: string;
+ rung?: string;
+ ok?: boolean;
+ exitCode?: number;
+ backend?: 'bundled' | 'inbox' | 'posix';
+ attempt?: number;
+ currentSession?: boolean;
+}
+
+export interface PtyPhaseRecord extends PtyPhaseContext {
+ event: 'pty-phase';
+ producer: 'main' | 'utility';
+ pid: number;
+ sequence: number;
+ phase: PtyPhase;
+ edge: 'begin' | 'end' | 'error' | 'point';
+ atMs: number;
+ wallTimeMs: number;
+ timeOriginMs: number;
+ previousWriteMs: number;
+ droppedWrites: number;
+}
+
+export interface PtyPhaseTrace {
+ mark(phase: PtyPhase, edge: PtyPhaseRecord['edge'], context?: PtyPhaseContext): void;
+}
+
+export function createPtyPhaseTrace(
+ env: Record<string, string | undefined>,
+ producer: PtyPhaseRecord['producer'],
+ write: (record: PtyPhaseRecord) => void,
+): PtyPhaseTrace | undefined {
+ if (env.OK_PTY_PHASE_TRACE !== '1') return undefined;
+ let sequence = 0;
+ let previousWriteMs = 0;
+ let droppedWrites = 0;
+ return {
+ mark(phase, edge, context = {}) {
+ if (sequence >= 256) return;
+ sequence += 1;
+ const record: PtyPhaseRecord = {
+ ...context,
+ event: 'pty-phase',
+ producer,
+ pid: process.pid,
+ sequence,
+ phase: sequence === 256 ? 'trace-limit' : phase,
+ edge: sequence === 256 ? 'point' : edge,
+ atMs: performance.now(),
+ wallTimeMs: Date.now(),
+ timeOriginMs: performance.timeOrigin,
+ previousWriteMs,
+ droppedWrites,
+ };
+ const writeStarted = performance.now();
+ try {
+ write(record);
+ } catch {
+ droppedWrites += 1;
+ }
+ previousWriteMs = performance.now() - writeStarted;
+ },
+ };
+}
diff --git a/packages/desktop/src/utility/pty-host.ts b/packages/desktop/src/utility/pty-host.ts
index f4786010d..47954ece9 100644
--- a/packages/desktop/src/utility/pty-host.ts
+++ b/packages/desktop/src/utility/pty-host.ts
@@ -27,6 +27,7 @@ import {
okManagedBinDirs,
okPackagedCliBinDir,
} from '../shared/ok-child-env.ts';
+import { createPtyPhaseTrace, type PtyPhaseTrace } from '../shared/pty-phase-trace.ts';
import {
commandWithManagedPath,
interactiveShellArgs,
@@ -39,6 +40,13 @@ import {
TERMINAL_SUPPORT_FILE_ESCAPE_CODE,
} from './support-file-write.ts';
+const utilityPhaseTrace = (process as NodeJS.Process & { parentPort?: unknown }).parentPort
+ ? createPtyPhaseTrace(process.env, 'utility', (record) => {
+ process.stderr.write(`${JSON.stringify(record)}\n`);
+ })
+ : undefined;
+utilityPhaseTrace?.mark('module-entry', 'point');
+
const DARWIN_FALLBACK_SHELL = '/bin/zsh';
const KILL_ESCALATE_MS = 250;
@@ -417,6 +425,7 @@ export interface PtyStartupTraceOptions {
let nextStartupTraceId = 0;
export interface SetupPtyHostDeps {
+ phaseTrace?: PtyPhaseTrace;
startupTrace?: PtyStartupTraceOptions;
parentPort: PtyHostParentPort | null;
spawn: SpawnPty;
@@ -965,27 +974,83 @@ function createConptyCursorSyncGate(
};
}
+function markStartupPhase(
+ phaseTrace: PtyPhaseTrace,
+ ptyId: string,
+ attempt: number,
+ observation: PtyStartupHostObservation,
+): void {
+ switch (observation.stage) {
+ case 'lookup-start':
+ phaseTrace.mark('shell-resolution', 'begin', { ptyId });
+ return;
+ case 'lookup-complete':
+ phaseTrace.mark('shell-resolution', 'end', { ptyId, rung: observation.rung });
+ return;
+ case 'spawn-start':
+ phaseTrace.mark('pty-spawn', 'begin', { ptyId, attempt, backend: observation.backend });
+ return;
+ case 'spawn-return':
+ phaseTrace.mark('pty-spawn', 'end', { ptyId, attempt, backend: observation.backend });
+ return;
+ case 'spawn-failed':
+ phaseTrace.mark('pty-spawn', 'error', { ptyId, attempt, backend: observation.backend });
+ return;
+ case 'first-output':
+ phaseTrace.mark('pty-first-output', 'point', {
+ ptyId,
+ currentSession: observation.currentSession,
+ });
+ return;
+ case 'first-forward':
+ phaseTrace.mark('pty-first-forward', 'point', { ptyId });
+ return;
+ case 'terminal-exit':
+ phaseTrace.mark('pty-exit', 'point', { ptyId, exitCode: observation.exitCode });
+ return;
+ case 'snapshot':
+ case 'worker-online':
+ case 'worker-ready-received':
+ case 'data-pipe-connected':
+ case 'worker-error':
+ case 'native-connect-enter':
+ case 'native-connect-return':
+ case 'native-connect-failed':
+ case 'native-shell-exit':
+ case 'worker-exit':
+ case 'observer-unavailable':
+ case 'os-snapshot':
+ return;
+ default: {
+ const _exhaustive: never = observation;
+ void _exhaustive;
+ }
+ }
+}
+
export function setupPtyHost(deps: SetupPtyHostDeps): PtyHostHandle {
const env = deps.env ?? (process.env as Record<string, string | undefined>);
+ const phaseTrace = deps.phaseTrace;
const platform = deps.platform ?? process.platform;
const sessions = new Map<string, PtyProcessLike>();
- const startupTraces = deps.startupTrace
- ? new WeakMap<
- PtyProcessLike,
- {
- emit(
- observation:
- | PtyStartupObservation
- | { stage: 'terminal-exit'; exitCode: number | undefined },
- ): void;
- snapshot(reason: PtyStartupSnapshotReason): void;
- receive(data: string, currentSession: boolean): void;
- forward(data: string): void;
- exited(): void;
- dispose(): void;
- }
- >()
- : undefined;
+ const startupTraces =
+ deps.startupTrace || phaseTrace
+ ? new WeakMap<
+ PtyProcessLike,
+ {
+ emit(
+ observation:
+ | PtyStartupObservation
+ | { stage: 'terminal-exit'; exitCode: number | undefined },
+ ): void;
+ snapshot(reason: PtyStartupSnapshotReason): void;
+ receive(data: string, currentSession: boolean): void;
+ forward(data: string): void;
+ exited(): void;
+ dispose(): void;
+ }
+ >()
+ : undefined;
function snapshot(pty: PtyProcessLike, reason: PtyStartupSnapshotReason): void {
startupTraces?.get(pty)?.snapshot(reason);
@@ -1074,25 +1139,38 @@ export function setupPtyHost(deps: SetupPtyHostDeps): PtyHostHandle {
...observation,
});
};
- emit?.({ stage: 'lookup-start' });
- const resolution = resolveShellWithDetails(env, {
- platform,
- override: message.shell,
- overrideInvalidReason: message.shellInvalidReason,
- userInfoShell: deps.userInfoShell,
- shellExists: deps.shellExists,
- pathProbe:
- platform === 'win32'
- ? (command, probeEnv) => {
- if (traceId !== undefined)
- lookup = cachedWindowsPaths.has(command) ? 'cache' : 'probe';
- return probeWindowsShellPath(command, probeEnv);
- }
- : deps.pathProbe,
- listDirectory: deps.listDirectory,
- logger: deps.logger,
- });
- emit?.({ stage: 'lookup-complete', lookup, rung: resolution.rung });
+ const observe =
+ emit === undefined && phaseTrace === undefined
+ ? undefined
+ : (observation: PtyStartupHostObservation, observedAttempt = attempt): void => {
+ emit?.(observation, observedAttempt);
+ if (phaseTrace) markStartupPhase(phaseTrace, ptyId, observedAttempt, observation);
+ };
+ observe?.({ stage: 'lookup-start' });
+ let resolution: ShellResolution;
+ try {
+ resolution = resolveShellWithDetails(env, {
+ platform,
+ override: message.shell,
+ overrideInvalidReason: message.shellInvalidReason,
+ userInfoShell: deps.userInfoShell,
+ shellExists: deps.shellExists,
+ pathProbe:
+ platform === 'win32'
+ ? (command, probeEnv) => {
+ if (traceId !== undefined)
+ lookup = cachedWindowsPaths.has(command) ? 'cache' : 'probe';
+ return probeWindowsShellPath(command, probeEnv);
+ }
+ : deps.pathProbe,
+ listDirectory: deps.listDirectory,
+ logger: deps.logger,
+ });
+ } catch (error) {
+ phaseTrace?.mark('shell-resolution', 'error', { ptyId });
+ throw error;
+ }
+ observe?.({ stage: 'lookup-complete', lookup, rung: resolution.rung });
if (resolution.invalidOverride) {
const reason = resolution.invalidOverrideReason ?? 'invalid-value';
deps.logger?.warn({
@@ -1198,26 +1276,27 @@ export function setupPtyHost(deps: SetupPtyHostDeps): PtyHostHandle {
};
let observation: PtyStartupObservedProcess | undefined;
const spawnAttempt = (options: PtySpawnOptions): PtyProcessLike => {
- if (traceId === undefined || startedAt === undefined || emit === undefined)
- return deps.spawn(shell, shellArgs, options);
+ if (observe === undefined) return deps.spawn(shell, shellArgs, options);
attempt += 1;
const backend: PtyStartupBackend =
platform === 'win32' ? (options.useConptyDll ? 'bundled' : 'inbox') : 'posix';
- emit({ stage: 'spawn-start', backend });
+ observe({ stage: 'spawn-start', backend });
try {
const next = () => deps.spawn(shell, shellArgs, options);
const observedAttempt = attempt;
- observation = deps.startupTrace?.aroundSpawn?.(next, {
- traceId,
- attempt,
- startedAt,
- backend,
- emit: (entry) => emit(entry, observedAttempt),
- }) ?? { pty: next() };
- emit({ stage: 'spawn-return', backend });
+ observation = (traceId === undefined || startedAt === undefined || emit === undefined
+ ? undefined
+ : deps.startupTrace?.aroundSpawn?.(next, {
+ traceId,
+ attempt,
+ startedAt,
+ backend,
+ emit: (entry) => emit(entry, observedAttempt),
+ })) ?? { pty: next() };
+ observe({ stage: 'spawn-return', backend });
return observation.pty;
} catch (error) {
- emit({
+ observe({
stage: 'spawn-failed',
backend,
reason:
@@ -1261,16 +1340,16 @@ export function setupPtyHost(deps: SetupPtyHostDeps): PtyHostHandle {
),
);
}
- if (emit !== undefined) {
+ if (observe !== undefined) {
let receivedBytes = 0;
let forwardedBytes = 0;
let terminalExitObserved = false;
let received = false;
let forwarded = false;
startupTraces?.set(pty, {
- emit,
+ emit: observe,
snapshot(reason) {
- emit({
+ observe({
stage: 'snapshot',
reason,
receivedBytes,
@@ -1284,14 +1363,14 @@ export function setupPtyHost(deps: SetupPtyHostDeps): PtyHostHandle {
receivedBytes += Buffer.byteLength(data);
if (!received) {
received = true;
- emit({ stage: 'first-output', currentSession });
+ observe({ stage: 'first-output', currentSession });
}
},
forward(data) {
forwardedBytes += Buffer.byteLength(data);
if (!forwarded) {
forwarded = true;
- emit({ stage: 'first-forward' });
+ observe({ stage: 'first-forward' });
}
},
exited() {
@@ -1417,6 +1496,7 @@ export function setupPtyHost(deps: SetupPtyHostDeps): PtyHostHandle {
}
switch (message.type) {
case 'create':
+ phaseTrace?.mark('message-received', 'point', { ptyId: message.ptyId });
handleCreate(message);
break;
case 'input':
@@ -1446,6 +1526,8 @@ export function setupPtyHost(deps: SetupPtyHostDeps): PtyHostHandle {
}
});
+ if (deps.parentPort) phaseTrace?.mark('listener-ready', 'point');
+
return {
snapshotStartup(): void {
if (!startupTraces) return;
@@ -1492,24 +1574,31 @@ if ((process as NodeJS.Process & { parentPort?: unknown }).parentPort) {
info: (data, message) => console.info(message ?? '[pty-host] info', data),
};
let flushLogger = () => {};
+ utilityPhaseTrace?.mark('logger-import', 'begin');
try {
const { flushDesktopLogger, getLogger } = await import('../main/desktop-logger.ts');
log = getLogger('pty-host');
flushLogger = flushDesktopLogger;
+ utilityPhaseTrace?.mark('logger-import', 'end');
} catch (err) {
+ utilityPhaseTrace?.mark('logger-import', 'error');
const code = (err as { code?: unknown } | null)?.code;
console.warn('[pty-host] logger unavailable; using console fallback', {
code: typeof code === 'string' ? code : 'unknown',
});
}
let spawn: SpawnPty;
+ utilityPhaseTrace?.mark('native-import', 'begin');
try {
({ spawn } = await import('node-pty'));
+ utilityPhaseTrace?.mark('native-import', 'end');
} catch (err) {
+ utilityPhaseTrace?.mark('native-import', 'error');
installPtyImportFailureReply(parentPort, err, log);
return;
}
const handle = setupPtyHost({
+ phaseTrace: utilityPhaseTrace,
parentPort,
spawn,
exitHost: (code) => process.exit(code),
diff --git a/packages/desktop/tests/utility/pty-phase-trace.test.ts b/packages/desktop/tests/utility/pty-phase-trace.test.ts
new file mode 100644
index 000000000..b13062033
--- /dev/null
+++ b/packages/desktop/tests/utility/pty-phase-trace.test.ts
@@ -0,0 +1,337 @@
+import { afterEach, expect, test, vi } from 'vitest';
+import { summarizePtyPhases } from '../../scripts/pty-phase-evidence.mjs';
+import { createPtyPhaseTrace, type PtyPhaseRecord } from '../../src/shared/pty-phase-trace.ts';
+import {
+ type PtyHostOutgoingMessage,
+ type PtyProcessLike,
+ type SpawnPty,
+ setupPtyHost,
+} from '../../src/utility/pty-host.ts';
+
+afterEach(() => vi.restoreAllMocks());
+
+const SESSION = 'phase-session';
+
+function stubPty(pid: number) {
+ const dataListeners: Array<(data: string) => void> = [];
+ const exitListeners: Array<(event: { exitCode: number | undefined; signal?: number }) => void> =
+ [];
+ const pty: PtyProcessLike = {
+ pid,
+ onData(listener) {
+ dataListeners.push(listener);
+ },
+ onExit(listener) {
+ exitListeners.push(listener);
+ },
+ write() {},
+ resize() {},
+ kill() {},
+ pause() {},
+ resume() {},
+ };
+ return {
+ pty,
+ dataListeners,
+ output(data: string) {
+ for (const listener of dataListeners) listener(data);
+ },
+ exit(exitCode: number) {
+ for (const listener of exitListeners) listener({ exitCode });
+ },
+ };
+}
+
+function createSession(options: { traced: boolean; platform: 'win32' | 'linux'; spawn: SpawnPty }) {
+ const windows = options.platform === 'win32';
+ const records: PtyPhaseRecord[] = [];
+ const posted: PtyHostOutgoingMessage[] = [];
+ const timeline: string[] = [];
+ let receive = (_event: { data: unknown }) => {};
+ setupPtyHost({
+ ...(options.traced
+ ? {
+ phaseTrace: createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: '1' }, 'utility', (record) => {
+ records.push(record);
+ timeline.push(`${record.phase}:${record.edge}`);
+ }),
+ }
+ : {}),
+ env: windows ? { SystemRoot: 'C:\\Windows' } : { SHELL: '/bin/bash', PATH: '/usr/bin' },
+ platform: options.platform,
+ parentPort: {
+ on(_event, callback) {
+ receive = callback;
+ },
+ postMessage(message) {
+ posted.push(message);
+ timeline.push(`post:${message.type}`);
+ },
+ },
+ shellExists: () => true,
+ spawn: options.spawn,
+ });
+ receive({
+ data: {
+ type: 'create',
+ ptyId: SESSION,
+ cwd: windows ? 'C:\\project' : '/project',
+ cols: 80,
+ rows: 24,
+ shell: windows ? 'C:\\Windows\\System32\\cmd.exe' : '/bin/bash',
+ },
+ });
+ return { records, posted, timeline };
+}
+
+test('attributes a controlled slow shell lookup to the shell-resolution phase', () => {
+ const SHELL_LOOKUP_DELAY_MS = 1000;
+ let clock = 0;
+ vi.spyOn(performance, 'now').mockImplementation(() => clock);
+ const phases: PtyPhaseRecord[] = [];
+ const posted: PtyHostOutgoingMessage[] = [];
+ let receive = (_event: { data: unknown }) => {};
+ const pty: PtyProcessLike = {
+ pid: 12345,
+ onData() {},
+ onExit() {},
+ write() {},
+ resize() {},
+ kill() {},
+ pause() {},
+ resume() {},
+ };
+ setupPtyHost({
+ phaseTrace: createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: '1' }, 'utility', (record) =>
+ phases.push(record),
+ ),
+ env: { SystemRoot: 'C:\\Windows' },
+ platform: 'win32',
+ parentPort: {
+ on(_event, callback) {
+ receive = callback;
+ },
+ postMessage(message) {
+ posted.push(message);
+ },
+ },
+ shellExists: () => {
+ clock += SHELL_LOOKUP_DELAY_MS;
+ return true;
+ },
+ spawn: () => pty,
+ });
+ receive({
+ data: {
+ type: 'create',
+ ptyId: 'phase-session',
+ cwd: 'C:\\project',
+ cols: 80,
+ rows: 24,
+ shell: 'C:\\Windows\\System32\\cmd.exe',
+ },
+ });
+ expect(posted).toContainEqual({
+ type: 'shell-notice',
+ ptyId: 'phase-session',
+ notice: 'shell-resolved',
+ shellFamily: 'cmd',
+ });
+ const durations = phases
+ .filter((record) => record.edge === 'end')
+ .flatMap((end) => {
+ const begin = phases.find(
+ (record) =>
+ record.phase === end.phase && record.edge === 'begin' && record.ptyId === end.ptyId,
+ );
+ return begin
+ ? [{ phase: end.phase, ptyId: end.ptyId, elapsed: Number(end.atMs) - Number(begin.atMs) }]
+ : [];
+ });
+ expect(durations.sort((left, right) => right.elapsed - left.elapsed)[0]).toEqual({
+ phase: 'shell-resolution',
+ ptyId: 'phase-session',
+ elapsed: SHELL_LOOKUP_DELAY_MS,
+ });
+});
+
+test('reports an exceptional shell lookup without changing the thrown value', () => {
+ const records: PtyPhaseRecord[] = [];
+ let receive = (_event: { data: unknown }) => {};
+ let original: unknown;
+ let caught: unknown;
+ setupPtyHost({
+ phaseTrace: createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: '1' }, 'utility', (record) =>
+ records.push(record),
+ ),
+ env: {},
+ platform: 'win32',
+ parentPort: {
+ on(_event, callback) {
+ receive = callback;
+ },
+ postMessage() {},
+ },
+ shellExists: () => {
+ try {
+ return JSON.parse('{');
+ } catch (error) {
+ original = error;
+ throw error;
+ }
+ },
+ spawn: () => {
+ throw new Error('lookup failed before native spawn');
+ },
+ });
+ try {
+ receive({
+ data: {
+ type: 'create',
+ ptyId: 'exception-session',
+ cwd: 'C:\\project',
+ cols: 80,
+ rows: 24,
+ shell: 'C:\\Windows\\System32\\cmd.exe',
+ },
+ });
+ } catch (error) {
+ caught = error;
+ }
+ expect(original).toBeInstanceOf(SyntaxError);
+ expect(caught).toBe(original);
+ expect(records.at(-1)).toMatchObject({
+ event: 'pty-phase',
+ phase: 'shell-resolution',
+ edge: 'error',
+ ptyId: 'exception-session',
+ });
+});
+
+test('brackets the native spawn of a created terminal as a completed pty-spawn span', () => {
+ const SPAWN_DELAY_MS = 750;
+ let clock = 0;
+ vi.spyOn(performance, 'now').mockImplementation(() => clock);
+ const session = stubPty(4321);
+ const { records } = createSession({
+ traced: true,
+ platform: 'win32',
+ spawn: () => {
+ clock += SPAWN_DELAY_MS;
+ return session.pty;
+ },
+ });
+ expect(
+ summarizePtyPhases(records).completed.filter(
+ (span: { phase: string }) => span.phase === 'pty-spawn',
+ ),
+ ).toEqual([
+ expect.objectContaining({ ptyId: SESSION, outcome: 'end', durationMs: SPAWN_DELAY_MS }),
+ ]);
+});
+
+test('brackets each conpty attempt when the bundled spawn falls back to the inbox console', () => {
+ const session = stubPty(4321);
+ const { records, posted } = createSession({
+ traced: true,
+ platform: 'win32',
+ spawn: (_file, _args, options) => {
+ if (options.useConptyDll) {
+ throw new Error('Cannot find conpty.dll at C:\\fixture\\conpty.dll, error code: 2');
+ }
+ return session.pty;
+ },
+ });
+ expect(
+ records
+ .filter((record) => record.phase === 'pty-spawn')
+ .map(({ edge, ptyId, backend, attempt }) => ({ edge, ptyId, backend, attempt })),
+ ).toEqual([
+ { edge: 'begin', ptyId: SESSION, backend: 'bundled', attempt: 1 },
+ { edge: 'error', ptyId: SESSION, backend: 'bundled', attempt: 1 },
+ { edge: 'begin', ptyId: SESSION, backend: 'inbox', attempt: 2 },
+ { edge: 'end', ptyId: SESSION, backend: 'inbox', attempt: 2 },
+ ]);
+ expect(posted.filter((message) => message.type === 'spawn-error')).toEqual([]);
+});
+
+test('marks the first output the host sees and its first forward to main exactly once', () => {
+ const session = stubPty(4321);
+ const { records, posted, timeline } = createSession({
+ traced: true,
+ platform: 'win32',
+ spawn: () => session.pty,
+ });
+ const created = timeline.length;
+ session.output('first chunk');
+ session.output('second chunk');
+ expect(posted.filter((message) => message.type === 'data')).toEqual([
+ { type: 'data', ptyId: SESSION, data: 'first chunk' },
+ { type: 'data', ptyId: SESSION, data: 'second chunk' },
+ ]);
+ expect(timeline.slice(created)).toEqual([
+ 'pty-first-output:point',
+ 'post:data',
+ 'pty-first-forward:point',
+ 'post:data',
+ ]);
+ expect(records.filter((record) => record.phase === 'pty-first-output')).toEqual([
+ expect.objectContaining({ ptyId: SESSION, currentSession: true }),
+ ]);
+});
+
+test('marks a terminal that exits before producing any output', () => {
+ const session = stubPty(4321);
+ const { records, posted } = createSession({
+ traced: true,
+ platform: 'win32',
+ spawn: () => session.pty,
+ });
+ session.exit(-1);
+ expect(records.filter((record) => record.phase === 'pty-exit')).toEqual([
+ expect.objectContaining({ ptyId: SESSION, edge: 'point', exitCode: -1 }),
+ ]);
+ expect(records.filter((record) => record.phase.startsWith('pty-first'))).toEqual([]);
+ expect(posted.at(-1)).toEqual({ type: 'exit', ptyId: SESSION, exitCode: -1, signal: null });
+});
+
+test('reports a failed posix spawn while posting the same spawn-error as an untraced host', () => {
+ const fail: SpawnPty = () => {
+ throw new Error('posix spawn failed');
+ };
+ const traced = createSession({ traced: true, platform: 'linux', spawn: fail });
+ const plain = createSession({ traced: false, platform: 'linux', spawn: fail });
+ expect(
+ traced.records
+ .filter((record) => record.phase === 'pty-spawn')
+ .map(({ edge, ptyId, backend }) => ({ edge, ptyId, backend })),
+ ).toEqual([
+ { edge: 'begin', ptyId: SESSION, backend: 'posix' },
+ { edge: 'error', ptyId: SESSION, backend: 'posix' },
+ ]);
+ expect(traced.posted).toContainEqual({
+ type: 'spawn-error',
+ ptyId: SESSION,
+ message: 'posix spawn failed',
+ });
+ expect(traced.posted).toEqual(plain.posted);
+});
+
+test('an unset trace reads no clock and leaves posted messages and data listeners unchanged', () => {
+ const run = (traced: boolean) => {
+ const session = stubPty(4321);
+ const host = createSession({ traced, platform: 'win32', spawn: () => session.pty });
+ session.output('first chunk');
+ session.output('second chunk');
+ session.exit(0);
+ return { ...host, dataListeners: session.dataListeners.length };
+ };
+ const now = vi.spyOn(performance, 'now');
+ const plain = run(false);
+ expect(now).not.toHaveBeenCalled();
+ now.mockRestore();
+ const traced = run(true);
+ expect(traced.records.some((record) => record.phase === 'pty-first-forward')).toBe(true);
+ expect(plain.posted).toEqual(traced.posted);
+ expect([plain.dataListeners, traced.dataListeners]).toEqual([1, 1]);
+});