Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Trace packaged PTY output relay phases (#7273)
Nick Gomez3a79bc5b42a5
diff --git a/knip.config.ts b/knip.config.tsindex 03ef8d4a4..36a395261 100644--- a/knip.config.ts+++ b/knip.config.ts@@ -155,15 +155,11 @@ export default {'src/shadow-fixture-launch.test-helper.mjs',],project: 'src/**',- ignoreDependencies: [- '@types/shell-quote',- ],+ ignoreDependencies: ['@types/shell-quote'],},'packages/cli': {entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],- ignoreDependencies: [- 'yjs',- ],+ ignoreDependencies: ['yjs'],},'packages/desktop': {entry: [diff --git a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts b/packages/app/tests/integration/bug3-source-mode-writeback.test.tsindex 4549c74b3..a50b00123 100644--- a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts+++ b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts@@ -1,4 +1,3 @@-import { readFileSync } from 'node:fs';import { join } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';diff --git a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts b/packages/app/tests/integration/indented-jsx-byte-sacred.test.tsindex 4fc2c11f9..6fcdc23f2 100644--- a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts+++ b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts@@ -1,4 +1,3 @@-import { setTimeout as wait } from 'node:timers/promises';import { normalizeBridge } from '@inkeep/open-knowledge-core';import { updateYFragment } from '@tiptap/y-tiptap';diff --git a/packages/app/tests/integration/interior-edit-freshness.test.ts b/packages/app/tests/integration/interior-edit-freshness.test.tsindex 9f2f6feb6..40b5cdfd6 100644--- a/packages/app/tests/integration/interior-edit-freshness.test.ts+++ b/packages/app/tests/integration/interior-edit-freshness.test.ts@@ -1,4 +1,3 @@-import { setTimeout as wait } from 'node:timers/promises';import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';import { afterAll, beforeAll, describe, expect, test } from 'vitest';diff --git a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts b/packages/app/tests/integration/keystroke-cadence-danger-space.test.tsindex 2a085742b..93666af70 100644--- a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts+++ b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts@@ -1,4 +1,3 @@-import { setTimeout as wait } from 'node:timers/promises';import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';import { afterAll, beforeAll, describe, expect, test } from 'vitest';diff --git a/packages/app/tests/integration/producer-guard-wiring.test.ts b/packages/app/tests/integration/producer-guard-wiring.test.tsindex 878d5196b..867598d34 100644--- a/packages/app/tests/integration/producer-guard-wiring.test.ts+++ b/packages/app/tests/integration/producer-guard-wiring.test.ts@@ -1,4 +1,3 @@-import { setTimeout as wait } from 'node:timers/promises';import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';import { afterAll, beforeAll, describe, expect, test } from 'vitest';diff --git a/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.tsindex 4ada3cf26..0970ac12f 100644--- a/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts+++ b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts@@ -1,4 +1,3 @@-import { randomUUID } from 'node:crypto';import { afterEach, describe, expect, test } from 'vitest';import { agentWriteMd, createTestServer, type TestServer } from './test-harness';diff --git a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts b/packages/app/tests/integration/qa-045-restore-after-gc.test.tsindex cbe2b705f..b632185e1 100644--- a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts+++ b/packages/app/tests/integration/qa-045-restore-after-gc.test.ts@@ -1,4 +1,3 @@-import { execFileSync } from 'node:child_process';import { randomUUID } from 'node:crypto';import { join } from 'node:path';diff --git a/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.tsindex 89bc9b4d9..c530ce4ba 100644--- a/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts+++ b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts@@ -1,4 +1,3 @@-import { randomUUID } from 'node:crypto';import { afterAll, afterEach, beforeAll, describe, expect, test } from 'vitest';import type * as Y from 'yjs';diff --git a/packages/app/tests/integration/undo-after-rollback.test.ts b/packages/app/tests/integration/undo-after-rollback.test.tsindex a78aeb0e4..d3767adc9 100644--- a/packages/app/tests/integration/undo-after-rollback.test.ts+++ b/packages/app/tests/integration/undo-after-rollback.test.ts@@ -1,4 +1,3 @@-import { ROLLBACK_ORIGIN } from '@inkeep/open-knowledge-server';import { afterAll, beforeAll, describe, expect, test } from 'vitest';import * as Y from 'yjs';diff --git a/packages/app/tests/integration/undo-recycle-reset.test.ts b/packages/app/tests/integration/undo-recycle-reset.test.tsindex e7cc69c3f..b076f955c 100644--- a/packages/app/tests/integration/undo-recycle-reset.test.ts+++ b/packages/app/tests/integration/undo-recycle-reset.test.ts@@ -1,4 +1,3 @@-import { writeFileSync } from 'node:fs';import { join } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';diff --git a/packages/app/tests/integration/undo-rederive-survival.test.ts b/packages/app/tests/integration/undo-rederive-survival.test.tsindex 9ddcd0730..7935e35f8 100644--- a/packages/app/tests/integration/undo-rederive-survival.test.ts+++ b/packages/app/tests/integration/undo-rederive-survival.test.ts@@ -1,4 +1,3 @@-import { prependFrontmatter } from '@inkeep/open-knowledge-core';import { Plugin, PluginKey } from '@tiptap/pm/state';import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.tsindex 2a597ec3d..f4cc8a286 100644--- a/packages/core/src/bridge/compose.ts+++ b/packages/core/src/bridge/compose.ts@@ -1,4 +1,3 @@-import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.tsindex ffd8fce06..e7e63f43d 100644--- a/packages/core/src/bridge/doc-boundary-space.ts+++ b/packages/core/src/bridge/doc-boundary-space.ts@@ -1,4 +1,3 @@-import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.tsindex fb0ba5a7c..fc267cbea 100644--- a/packages/core/src/markdown/comment-promoter.ts+++ b/packages/core/src/markdown/comment-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.tsindex ae8cb390b..861003fb4 100644--- a/packages/core/src/markdown/merged-walker.ts+++ b/packages/core/src/markdown/merged-walker.ts@@ -1,4 +1,3 @@-import type { Nodes, Parent, Root } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.tsindex 8be632ba4..4d3250d3a 100644--- a/packages/core/src/markdown/safe-url.ts+++ b/packages/core/src/markdown/safe-url.ts@@ -1,4 +1,3 @@-export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');diff --git a/packages/desktop/scripts/packaged-pty-phase-acceptance.test-helper.mjs b/packages/desktop/scripts/packaged-pty-phase-acceptance.test-helper.mjsindex 2066f52c8..3cf5059e8 100644--- a/packages/desktop/scripts/packaged-pty-phase-acceptance.test-helper.mjs+++ b/packages/desktop/scripts/packaged-pty-phase-acceptance.test-helper.mjs@@ -22,6 +22,14 @@ const RENDERER_SESSION_UTILITY_PHASES = [['pty-first-forward', 'point'],];+const MAIN_RELAY_PHASES = [+ ['utility-data-received', 'point'],+ ['main-data-relay', 'begin'],+ ['main-data-relay', 'end'],+];++const RENDERER_SESSION_PHASES = [['renderer-data-received', 'point']];+function findRendererTraceUnavailable(driverStderr) {for (const line of driverStderr.split(/\r?\n/u)) {let entry;@@ -69,9 +77,18 @@ function assertSomeUtilityProcessStarted(records) {assert.ok(failures.includes(undefined), failures[0] ?? missingUtilityStartup([]));}+const RENDERER_SESSION_PHASES_BY_PRODUCER = [+ ['utility', RENDERER_SESSION_UTILITY_PHASES],+ ['main', MAIN_RELAY_PHASES],+ ['renderer', RENDERER_SESSION_PHASES],+];+function describeUncheckedRendererSession({ errorType, error }) {- const phases = [...new Set(RENDERER_SESSION_UTILITY_PHASES.map(([phase]) => phase))];- return `Packaged PTY renderer trace unavailable (${errorType}: ${error}), so the renderer session of this passing echo and that session's utility phases (${phases.join(', ')}) were not checked`;+ const unchecked = RENDERER_SESSION_PHASES_BY_PRODUCER.map(+ ([producer, phases]) =>+ `${producer} phases (${[...new Set(phases.map(([phase]) => phase))].join(', ')})`,+ );+ return `Packaged PTY renderer trace unavailable (${errorType}: ${error}), so the renderer session of this passing echo and that session's ${unchecked.slice(0, -1).join(', ')} and ${unchecked.at(-1)} were not checked`;}export function assertPackagedPtyPhaseEvidence(directory, driverStderr = '') {@@ -106,4 +123,28 @@ export function assertPackagedPtyPhaseEvidence(directory, driverStderr = '') {`Packaged PTY phase evidence is missing utility ${phase}/${edge} for the renderer session`,);}+ const main = records.filter(+ (record) => record.producer === 'main' && record.ptyId === start.ptyId,+ );+ for (const [phase, edge] of MAIN_RELAY_PHASES) {+ assert.ok(+ main.some(+ (record) =>+ record.phase === phase && record.edge === edge && (edge !== 'end' || record.ok === true),+ ),+ `Packaged PTY phase evidence is missing main ${phase}/${edge} for the renderer session`,+ );+ }+ for (const [phase, edge] of RENDERER_SESSION_PHASES) {+ assert.ok(+ records.some(+ (record) =>+ record.producer === 'renderer' &&+ record.ptyId === start.ptyId &&+ record.phase === phase &&+ record.edge === edge,+ ),+ `Packaged PTY phase evidence is missing renderer ${phase}/${edge} for the renderer session`,+ );+ }}diff --git a/packages/desktop/scripts/packaged-pty-phase-acceptance.test.mjs b/packages/desktop/scripts/packaged-pty-phase-acceptance.test.mjsindex 418b05b1c..5e186d9f9 100644--- a/packages/desktop/scripts/packaged-pty-phase-acceptance.test.mjs+++ b/packages/desktop/scripts/packaged-pty-phase-acceptance.test.mjs@@ -1,4 +1,4 @@-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';import { afterEach, expect, test } from 'vitest';@@ -22,6 +22,29 @@ function evidence(utilityRecords) {atMs: 0,sequence: 1,},+ {+ event: 'pty-phase',+ producer: 'renderer',+ phase: 'renderer-data-received',+ edge: 'point',+ ptyId: 'echo-session',+ atMs: 1,+ sequence: 2,+ },+ ...[+ { phase: 'utility-data-received', edge: 'point' },+ { phase: 'main-data-relay', edge: 'begin' },+ { phase: 'main-data-relay', edge: 'end', ok: true },+ ].map((record, index) => ({+ event: 'pty-phase',+ producer: 'main',+ pid: 7,+ timeOriginMs: 100,+ atMs: index,+ sequence: index + 1,+ ptyId: 'echo-session',+ ...record,+ })),...utilityRecords.map((record, index) => ({event: 'pty-phase',producer: 'utility',@@ -133,6 +156,38 @@ test('rejects a session whose first output was never forwarded', () => {);});+test('rejects a renderer session without a renderer receive phase', () => {+ const directory = evidence([...startup, ...session]);+ const tracePath = join(directory, 'phase-trace.jsonl');+ const records = readFileSync(tracePath, 'utf8')+ .trim()+ .split('\n')+ .map((line) => JSON.parse(line))+ .filter((record) => record.phase !== 'renderer-data-received');+ writeFileSync(tracePath, records.map((record) => JSON.stringify(record)).join('\n'));+ expect(() => assertPackagedPtyPhaseEvidence(directory)).toThrow(+ 'Packaged PTY phase evidence is missing renderer renderer-data-received/point',+ );+});++test('rejects a renderer session whose main relay did not send', () => {+ const directory = evidence([...startup, ...session]);+ const tracePath = join(directory, 'phase-trace.jsonl');+ const records = readFileSync(tracePath, 'utf8')+ .trim()+ .split('\n')+ .map((line) => JSON.parse(line))+ .map((record) =>+ record.producer === 'main' && record.phase === 'main-data-relay' && record.edge === 'end'+ ? { ...record, ok: false }+ : record,+ );+ writeFileSync(tracePath, records.map((record) => JSON.stringify(record)).join('\n'));+ expect(() => assertPackagedPtyPhaseEvidence(directory)).toThrow(+ 'Packaged PTY phase evidence is missing main main-data-relay/end',+ );+});+test('rejects an evidence directory without a retained phase trace', () => {const root = mkdtempSync(join(tmpdir(), 'ok-pty-acceptance-missing-'));fixtures.push(root);diff --git a/packages/desktop/scripts/smoke-terminal-package-cdp.py b/packages/desktop/scripts/smoke-terminal-package-cdp.pyindex d87e15c77..5c88419ee 100755--- a/packages/desktop/scripts/smoke-terminal-package-cdp.py+++ b/packages/desktop/scripts/smoke-terminal-package-cdp.py@@ -255,6 +255,7 @@ def evaluate_pty_echo(socket_url: str) -> Dict[str, object]:const endings = [];const notices = [];const releases = [];+ const receivedPtyIds = new Set();const sinceStart = (at) => (at === null ? null : Math.round(at - startedAt));const timings = () => ({{createdMs: sinceStart(createdAt),@@ -311,6 +312,10 @@ def evaluate_pty_echo(socket_url: str) -> Dict[str, object]:);try {{releases.push(bridge.terminal.onData((message) => {{+ if (!receivedPtyIds.has(message.ptyId)) {{+ receivedPtyIds.add(message.ptyId);+ markPhase?.('renderer-data-received', 'point', message.ptyId);+ }}if (message.ptyId !== ptyId) return;consume(message.data, performance.now());}}));diff --git a/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs b/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjsindex b88b66b7e..872d133fd 100644--- a/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs+++ b/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs@@ -168,6 +168,20 @@ test('reports verified retained utility phases after a successful packaged echo'timeOriginMs: 100,...record,}));+ const mainRelay = ['utility-data-received', 'main-data-relay', 'main-data-relay'].map(+ (phase, index) => ({+ event: 'pty-phase',+ producer: 'main',+ pid: 12345,+ sequence: index + 2,+ atMs: index + 1,+ timeOriginMs: 100,+ phase,+ edge: phase === 'main-data-relay' ? (index === 1 ? 'begin' : 'end') : 'point',+ ptyId,+ ...(phase === 'main-data-relay' && index === 2 ? { ok: true } : {}),+ }),+ );child.spawn.mockImplementation((_file, args, options) => {const profile = args.find((arg) => arg.startsWith('--user-data-dir=')).slice(16);const paths = {@@ -183,7 +197,10 @@ test('reports verified retained utility phases after a successful packaged echo'logDir,};writeFileSync(join(logDir, 'desktop.log'), `${JSON.stringify(paths)}\n`);- writeSync(options.stdio[1], [paths, ...utility].map((r) => JSON.stringify(r)).join('\n'));+ writeSync(+ options.stdio[1],+ [paths, ...mainRelay, ...utility].map((r) => JSON.stringify(r)).join('\n'),+ );return { pid: 12345 };});child.spawnSync.mockImplementation((file) => ({@@ -199,6 +216,16 @@ test('reports verified retained utility phases after a successful packaged echo'phase: 'start',edge: 'begin',ptyId,+ }) ++ '\n' ++ JSON.stringify({+ event: 'pty-phase',+ producer: 'renderer',+ sequence: 2,+ atMs: 1,+ phase: 'renderer-data-received',+ edge: 'point',+ ptyId,}),stderr: '',}));@@ -349,7 +376,7 @@ test.each([(chunk) => chunk !== stderr && chunk.includes(errorType) && chunk.includes(error),);expect(diagnostics).toEqual([- `Packaged PTY renderer trace unavailable (${errorType}: ${error}), so the renderer session of this passing echo and that session's utility phases (message-received, shell-resolution, pty-spawn, pty-first-output, pty-first-forward) were not checked`,+ `Packaged PTY renderer trace unavailable (${errorType}: ${error}), so the renderer session of this passing echo and that session's utility phases (message-received, shell-resolution, pty-spawn, pty-first-output, pty-first-forward), main phases (utility-data-received, main-data-relay) and renderer phases (renderer-data-received) were not checked`,]);expect(emitted.join('\n')).not.toContain('missing the renderer session');},diff --git a/packages/desktop/scripts/smoke-windows-terminal-package.test.mjs b/packages/desktop/scripts/smoke-windows-terminal-package.test.mjsindex 262fc9342..7b6afcc1f 100644--- a/packages/desktop/scripts/smoke-windows-terminal-package.test.mjs+++ b/packages/desktop/scripts/smoke-windows-terminal-package.test.mjs@@ -1242,6 +1242,7 @@ test.each([false, true])(expect(pairs).toContain(`${phase}:end`);}expect(pairs).toContain('first-data:point');+ expect(pairs).toContain('renderer-data-received:point');expect(window.__okPtyPhaseTrace.find((record) => record.phase === 'start')).toMatchObject({ptyId: STUB_PTY_ID,});@@ -1249,6 +1250,33 @@ test.each([false, true])(},);+test('records renderer receipt of output for another session in the same window before the session filter drops it', async () => {+ 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: OTHER_PTY_ID, data: 'other session$ ' });+ deliver({ ptyId: STUB_PTY_ID, data: MARKER_LINE });+ return { ok: true };+ };++ const result = await runPtyEchoSnippet(window, true);++ expect(result.output).toBe(MARKER_LINE);+ const phasesFor = (ptyId) =>+ window.__okPtyPhaseTrace+ .filter((record) => record.ptyId === ptyId)+ .map(({ phase, edge }) => `${phase}:${edge}`);+ expect(phasesFor(OTHER_PTY_ID)).toEqual(['renderer-data-received:point']);+ expect(phasesFor(STUB_PTY_ID)).toEqual(+ expect.arrayContaining(['renderer-data-received:point', 'first-data:point']),+ );+});+test('does not refresh the echo budget to collect a renderer trace or replace its failure', () => {const result = runPython([diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.tsindex 1823d053e..95b90b57c 100644--- a/packages/desktop/src/main/index.ts+++ b/packages/desktop/src/main/index.ts@@ -3936,6 +3936,7 @@ function registerIpcHandlers() {}),) as unknown as PtyUtilityLike,sendData: (wc, payload) => sendToRenderer(wc, 'ok:pty:data', payload),+ phaseTrace,sendExit: (wc, payload) => sendToRenderer(wc, 'ok:pty:exit', payload),sendNotice: (wc, payload) => sendToRenderer(wc, 'ok:pty:notice', payload),newPtyId: () => randomUUID(),diff --git a/packages/desktop/src/main/terminal-manager.ts b/packages/desktop/src/main/terminal-manager.tsindex a9d6bbe13..410a8c452 100644--- a/packages/desktop/src/main/terminal-manager.ts+++ b/packages/desktop/src/main/terminal-manager.ts@@ -18,6 +18,7 @@ import type {TerminalShellNoticeReason,} from '../shared/bridge-contract.ts';import type { SendableWebContents } from '../shared/ipc-send.ts';+import type { PtyPhaseTrace } from '../shared/pty-phase-trace.ts';import type {PtyCreateMessage,PtyHostIncomingMessage,@@ -54,6 +55,7 @@ export interface TerminalManagerDeps {recordShellExit?: (info: { crashed: boolean }) => void;recordTerminalSession?: () => void;recordConcurrentSessions?: (info: { count: number }) => void;+ phaseTrace?: PtyPhaseTrace;}interface TerminalCreateRequest {@@ -92,6 +94,7 @@ interface SessionState {killRequested: boolean;commandRan: boolean;sawOutput: boolean;+ relayTraced: boolean;spawnedAt: number | null;customLabel: string | null;ordinal: number | null;@@ -198,6 +201,7 @@ export function createTerminalManager(deps: TerminalManagerDeps): TerminalManageconst shutdownMs = deps.shutdownMs ?? DEFAULT_SHUTDOWN_MS;const handles = new Map<number, PtyWindowHandle>();const pendingShutdowns = new Set<Promise<void>>();+ const tracedUtilityData = new Set<string>();let announcedShutdown: AppShutdownCause | null = null;function safeKillUtility(handle: PtyWindowHandle): void {@@ -271,12 +275,35 @@ export function createTerminalManager(deps: TerminalManagerDeps): TerminalManagedeps.sendNotice?.(handle.webContents, payload);}- function deliver(handle: PtyWindowHandle, ptyId: string, session: SessionState): void {- if (handle.webContents.isDestroyed?.()) return;+ function deliver(+ windowId: number,+ handle: PtyWindowHandle,+ ptyId: string,+ session: SessionState,+ ): void {if (session.outbound.length === 0) return;+ const traceRelay = !session.relayTraced;+ session.relayTraced = true;+ if (handle.webContents.isDestroyed?.()) {+ if (traceRelay) {+ deps.phaseTrace?.mark('main-data-relay-skipped', 'point', { windowId, ptyId });+ }+ return;+ }const chunk = session.outbound;session.outbound = '';- pushData(handle, ptyId, chunk);+ if (traceRelay) {+ deps.phaseTrace?.mark('main-data-relay', 'begin', { windowId, ptyId });+ let returned = false;+ try {+ pushData(handle, ptyId, chunk);+ returned = true;+ } finally {+ deps.phaseTrace?.mark('main-data-relay', 'end', { windowId, ptyId, ok: returned });+ }+ } else {+ pushData(handle, ptyId, chunk);+ }session.pendingBytes += chunk.length;if (!session.paused && !session.killRequested && session.pendingBytes > highWater) {handle.utility.postMessage({ type: 'pause', ptyId });@@ -289,7 +316,7 @@ export function createTerminalManager(deps: TerminalManagerDeps): TerminalManageconst session = handle?.sessions.get(ptyId);if (!handle || !session) return;session.flushToken = null;- deliver(handle, ptyId, session);+ deliver(windowId, handle, ptyId, session);}function scheduleFlush(windowId: number, ptyId: string, session: SessionState): void {@@ -370,6 +397,18 @@ export function createTerminalManager(deps: TerminalManagerDeps): TerminalManagereturn;}const session = handle.sessions.get(message.ptyId);+ if (+ message.type === 'data' &&+ deps.phaseTrace !== undefined &&+ !tracedUtilityData.has(message.ptyId)+ ) {+ tracedUtilityData.add(message.ptyId);+ deps.phaseTrace.mark('utility-data-received', 'point', {+ windowId,+ ptyId: message.ptyId,+ currentSession: session !== undefined,+ });+ }if (!session) return;switch (message.type) {@@ -387,7 +426,7 @@ export function createTerminalManager(deps: TerminalManagerDeps): TerminalManageconst { ptyId } = message;const exitCode = message.exitCode ?? -1;clearSessionTimers(session);- deliver(handle, ptyId, session);+ deliver(windowId, handle, ptyId, session);maybeRecordSession(session);handle.sessions.delete(ptyId);deps.recordShellExit?.({ crashed: false });@@ -587,6 +626,7 @@ export function createTerminalManager(deps: TerminalManagerDeps): TerminalManagekillRequested: false,commandRan: false,sawOutput: false,+ relayTraced: false,spawnedAt: null,customLabel: null,ordinal: null,diff --git a/packages/desktop/src/shared/pty-phase-trace.ts b/packages/desktop/src/shared/pty-phase-trace.tsindex 3ed72b348..9c40ff0af 100644--- a/packages/desktop/src/shared/pty-phase-trace.ts+++ b/packages/desktop/src/shared/pty-phase-trace.ts@@ -5,6 +5,9 @@ type PtyPhase =| 'native-import'| 'listener-ready'| 'message-received'+ | 'utility-data-received'+ | 'main-data-relay'+ | 'main-data-relay-skipped'| 'shell-resolution'| 'paths'| 'ipc-create'diff --git a/packages/desktop/tests/main/terminal-manager.test.ts b/packages/desktop/tests/main/terminal-manager.test.tsindex 5696ba19d..29466492f 100644--- a/packages/desktop/tests/main/terminal-manager.test.ts+++ b/packages/desktop/tests/main/terminal-manager.test.ts@@ -13,6 +13,7 @@ import {type TerminalManagerDeps,} from '../../src/main/terminal-manager.ts';import type { SendableWebContents } from '../../src/shared/ipc-send.ts';+import { createPtyPhaseTrace, type PtyPhaseRecord } from '../../src/shared/pty-phase-trace.ts';import type { PtyHostIncomingMessage } from '../../src/utility/pty-host.ts';import { createStartedTerminal } from '../support/terminal-create.test-helper.ts';@@ -141,6 +142,32 @@ function makeManager(over?: Partial<TerminalManagerDeps>) {const PROJECT = '/Users/me/project';+const VOLATILE_PHASE_FIELDS = new Set([+ 'pid',+ 'sequence',+ 'atMs',+ 'wallTimeMs',+ 'timeOriginMs',+ 'previousWriteMs',+ 'droppedWrites',+]);++function tracedRecords() {+ const records: PtyPhaseRecord[] = [];+ const phaseTrace = createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: '1' }, 'main', (record) =>+ records.push(record),+ );+ const stable = (): Array<Record<string, unknown>> =>+ records.map((record) =>+ Object.fromEntries(Object.entries(record).filter(([key]) => !VOLATILE_PHASE_FIELDS.has(key))),+ );+ return { records, phaseTrace, stable };+}++function mainPhase(phase: string, edge: string, context: Record<string, unknown>) {+ return { event: 'pty-phase', producer: 'main', phase, edge, ...context };+}+describe('terminal creation waits for the renderer to subscribe', () => {function reserve(over?: Partial<TerminalManagerDeps>) {const h = makeManager(over);@@ -160,7 +187,12 @@ describe('terminal creation waits for the renderer to subscribe', () => {}test('neither create nor a replay request starts the shell; the first start starts it once', () => {- const h = reserve();+ const records: PtyPhaseRecord[] = [];+ const h = reserve({+ phaseTrace: createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: '1' }, 'main', (record) =>+ records.push(record),+ ),+ });h.runTimers();expect(h.forked[0]?.posted).toEqual([]);expect(h.mgr.adoptSession({ windowId: 1, ptyId: 'pty-1', webContents: h.webContents })).toEqual(@@ -177,6 +209,11 @@ describe('terminal creation waits for the renderer to subscribe', () => {h.forked[0]?.emitMessage({ type: 'data', ptyId: 'pty-1', data: 'prompt$ ' });h.runTimers();expect(h.dataPayloads()).toEqual(['prompt$ ']);+ expect(records.map(({ phase, edge, ptyId }) => [phase, edge, ptyId])).toEqual([+ ['utility-data-received', 'point', 'pty-1'],+ ['main-data-relay', 'begin', 'pty-1'],+ ['main-data-relay', 'end', 'pty-1'],+ ]);expect(h.forked[0]?.posted).toEqual([{type: 'create',@@ -562,6 +599,37 @@ describe('createTerminalManager — create', () => {});});+ test('does not mark a shell notice as PTY data received, and marks the data that follows it', () => {+ const trace = tracedRecords();+ const h = makeManager({ phaseTrace: trace.phaseTrace });+ createStartedTerminal(h.mgr, {+ windowId: 1,+ webContents: makeWebContents(),+ projectRoot: PROJECT,+ cols: 80,+ rows: 24,+ });++ h.forked[0]?.emitMessage({+ type: 'shell-notice',+ ptyId: 'pty-1',+ notice: 'shell-resolved',+ shellFamily: 'bash',+ });++ expect(trace.records.some((record) => record.phase === 'utility-data-received')).toBe(false);++ h.forked[0]?.emitMessage({ type: 'data', ptyId: 'pty-1', data: 'prompt$ ' });++ expect(trace.stable().filter((record) => record.phase === 'utility-data-received')).toEqual([+ mainPhase('utility-data-received', 'point', {+ windowId: 1,+ ptyId: 'pty-1',+ currentSession: true,+ }),+ ]);+ });+test('forwards the resolved Windows shell family to the addressed renderer session', () => {const h = makeManager();createStartedTerminal(h.mgr, {@@ -1868,6 +1936,119 @@ describe('createTerminalManager — destroyed-window guard', () => {});});+describe('createTerminalManager output relay phase trace', () => {+ test('records data addressed to a session main no longer holds', () => {+ const trace = tracedRecords();+ const h = makeManager({ phaseTrace: trace.phaseTrace });+ createStartedTerminal(h.mgr, {+ windowId: 1,+ webContents: makeWebContents(),+ projectRoot: PROJECT,+ cols: 80,+ rows: 24,+ });++ h.forked[0]?.emitMessage({ type: 'data', ptyId: 'pty-gone', data: 'late' });+ h.runTimers();++ expect(h.dataPayloads()).toEqual([]);+ expect(trace.stable()).toEqual([+ mainPhase('utility-data-received', 'point', {+ windowId: 1,+ ptyId: 'pty-gone',+ currentSession: false,+ }),+ ]);+ });++ test('records the first receipt and the first relay of a session once across later flushes', () => {+ const trace = tracedRecords();+ const h = makeManager({ phaseTrace: trace.phaseTrace });+ createStartedTerminal(h.mgr, {+ windowId: 1,+ webContents: makeWebContents(),+ projectRoot: PROJECT,+ cols: 80,+ rows: 24,+ });++ h.forked[0]?.emitMessage({ type: 'data', ptyId: 'pty-1', data: 'first' });+ h.runTimers();+ h.forked[0]?.emitMessage({ type: 'data', ptyId: 'pty-1', data: 'second' });+ h.runTimers();++ expect(h.dataPayloads()).toEqual(['first', 'second']);+ expect(trace.stable()).toEqual([+ mainPhase('utility-data-received', 'point', {+ windowId: 1,+ ptyId: 'pty-1',+ currentSession: true,+ }),+ mainPhase('main-data-relay', 'begin', { windowId: 1, ptyId: 'pty-1' }),+ mainPhase('main-data-relay', 'end', { windowId: 1, ptyId: 'pty-1', ok: true }),+ ]);+ });++ test('records a relay skipped for a destroyed window once, and never as an attempted send', () => {+ const trace = tracedRecords();+ const h = makeManager({ phaseTrace: trace.phaseTrace });+ const wc = makeWebContents();+ createStartedTerminal(h.mgr, {+ windowId: 1,+ webContents: wc,+ projectRoot: PROJECT,+ cols: 80,+ rows: 24,+ });+ wc.destroyed = true;++ h.forked[0]?.emitMessage({ type: 'data', ptyId: 'pty-1', data: 'first' });+ h.runTimers();+ h.forked[0]?.emitMessage({ type: 'data', ptyId: 'pty-1', data: 'second' });+ h.runTimers();++ expect(h.sent).toEqual([]);+ expect(trace.stable()).toEqual([+ mainPhase('utility-data-received', 'point', {+ windowId: 1,+ ptyId: 'pty-1',+ currentSession: true,+ }),+ mainPhase('main-data-relay-skipped', 'point', { windowId: 1, ptyId: 'pty-1' }),+ ]);+ });++ test('records a send that threw as a relay that did not return, and lets the throw propagate', () => {+ const trace = tracedRecords();+ const h = makeManager({+ phaseTrace: trace.phaseTrace,+ sendData: () => {+ throw new TypeError('webContents has no main frame to send to');+ },+ });+ createStartedTerminal(h.mgr, {+ windowId: 1,+ webContents: makeWebContents(),+ projectRoot: PROJECT,+ cols: 80,+ rows: 24,+ });++ h.forked[0]?.emitMessage({ type: 'data', ptyId: 'pty-1', data: 'first' });++ expect(() => h.runTimers()).toThrow(TypeError);+ expect(trace.stable()).toEqual([+ mainPhase('utility-data-received', 'point', {+ windowId: 1,+ ptyId: 'pty-1',+ currentSession: true,+ }),+ mainPhase('main-data-relay', 'begin', { windowId: 1, ptyId: 'pty-1' }),+ mainPhase('main-data-relay', 'end', { windowId: 1, ptyId: 'pty-1', ok: false }),+ ]);+ });+});+describe('createTerminalManager — lifecycle reap', () => {test('killForWindow requests shutdown, then force-kills at the deadline', () => {const h = makeManager();