Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mjsnew file mode 100644index 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.tsnew file mode 100644index 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.pyindex 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 valuediff --git a/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs b/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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]);+});