Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Trace packaged PTY output relay phases (#7273)

Nick Gomez3a79bc5b42a5
diff --git a/knip.config.ts b/knip.config.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.mjs
index 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.mjs
index 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.py
index 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.mjs
index 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.mjs
index 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.ts
index 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.ts
index 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): TerminalManage
const 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): TerminalManage
deps.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): TerminalManage
const 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): TerminalManage
return;
}
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): TerminalManage
const { 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): TerminalManage
killRequested: 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.ts
index 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.ts
index 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();