Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Retain utility phases in packaged Windows PTY diagnostics (#6114)

Nick Gomez7125b0fde6e0
diff --git a/knip.config.ts b/knip.config.ts
index 69344114d..0004a763a 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -149,11 +149,15 @@ export default {
'packages/server': {
entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],
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 a50b00123..4549c74b3 100644
--- a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
+++ b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
@@ -1,3 +1,4 @@
+
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 6fcdc23f2..4fc2c11f9 100644
--- a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
+++ b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
@@ -1,3 +1,4 @@
+
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 40b5cdfd6..9f2f6feb6 100644
--- a/packages/app/tests/integration/interior-edit-freshness.test.ts
+++ b/packages/app/tests/integration/interior-edit-freshness.test.ts
@@ -1,3 +1,4 @@
+
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 93666af70..2a085742b 100644
--- a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
+++ b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
@@ -1,3 +1,4 @@
+
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 867598d34..878d5196b 100644
--- a/packages/app/tests/integration/producer-guard-wiring.test.ts
+++ b/packages/app/tests/integration/producer-guard-wiring.test.ts
@@ -1,3 +1,4 @@
+
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 0970ac12f..4ada3cf26 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,3 +1,4 @@
+
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 b632185e1..cbe2b705f 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,3 +1,4 @@
+
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 c530ce4ba..89bc9b4d9 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,3 +1,4 @@
+
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 d3767adc9..a78aeb0e4 100644
--- a/packages/app/tests/integration/undo-after-rollback.test.ts
+++ b/packages/app/tests/integration/undo-after-rollback.test.ts
@@ -1,3 +1,4 @@
+
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 b076f955c..e7cc69c3f 100644
--- a/packages/app/tests/integration/undo-recycle-reset.test.ts
+++ b/packages/app/tests/integration/undo-recycle-reset.test.ts
@@ -1,3 +1,4 @@
+
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 7935e35f8..9ddcd0730 100644
--- a/packages/app/tests/integration/undo-rederive-survival.test.ts
+++ b/packages/app/tests/integration/undo-rederive-survival.test.ts
@@ -1,3 +1,4 @@
+
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 f4cc8a286..2a597ec3d 100644
--- a/packages/core/src/bridge/compose.ts
+++ b/packages/core/src/bridge/compose.ts
@@ -1,3 +1,4 @@
+
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 e7e63f43d..ffd8fce06 100644
--- a/packages/core/src/bridge/doc-boundary-space.ts
+++ b/packages/core/src/bridge/doc-boundary-space.ts
@@ -1,3 +1,4 @@
+
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 fc267cbea..fb0ba5a7c 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -1,3 +1,4 @@
+
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 bfd7e3109..fa3cfcd86 100644
--- a/packages/core/src/markdown/merged-walker.ts
+++ b/packages/core/src/markdown/merged-walker.ts
@@ -1,3 +1,4 @@
+
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 4d3250d3a..8be632ba4 100644
--- a/packages/core/src/markdown/safe-url.ts
+++ b/packages/core/src/markdown/safe-url.ts
@@ -1,3 +1,4 @@
+
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
new file mode 100644
index 000000000..9c13d995b
--- /dev/null
+++ b/packages/desktop/scripts/packaged-pty-phase-acceptance.test-helper.mjs
@@ -0,0 +1,107 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readPtyPhaseRecords } from './pty-phase-evidence.mjs';
+
+const UTILITY_STARTUP_PHASES = [
+ ['module-entry', 'point'],
+ ['logger-import', 'begin'],
+ ['native-import', 'begin'],
+ ['native-import', 'end'],
+ ['listener-ready', 'point'],
+];
+
+const RENDERER_SESSION_UTILITY_PHASES = [
+ ['message-received', 'point'],
+ ['shell-resolution', 'begin'],
+ ['shell-resolution', 'end'],
+ ['pty-spawn', 'begin'],
+ ['pty-spawn', 'end'],
+ ['pty-first-output', 'point'],
+ ['pty-first-forward', 'point'],
+];
+
+function findRendererTraceUnavailable(driverStderr) {
+ for (const line of driverStderr.split(/\r?\n/u)) {
+ let entry;
+ try {
+ entry = JSON.parse(line);
+ } catch {
+ continue;
+ }
+ if (entry?.event === 'pty-phase-trace-unavailable') return entry;
+ }
+ return undefined;
+}
+
+function utilityProcessRecords(records, { pid, timeOriginMs }) {
+ return records.filter(
+ (record) =>
+ record.producer === 'utility' && record.pid === pid && record.timeOriginMs === timeOriginMs,
+ );
+}
+
+function missingUtilityStartup(utility) {
+ for (const [phase, edge] of UTILITY_STARTUP_PHASES) {
+ if (!utility.some((record) => record.phase === phase && record.edge === edge)) {
+ return `Packaged PTY phase evidence is missing utility ${phase}/${edge}`;
+ }
+ }
+ if (
+ !utility.some(
+ (record) => record.phase === 'logger-import' && ['end', 'error'].includes(record.edge),
+ )
+ ) {
+ return 'Packaged PTY phase evidence is missing the utility logger-import outcome';
+ }
+ return undefined;
+}
+
+function assertSomeUtilityProcessStarted(records) {
+ const failures = records
+ .filter(
+ (record) =>
+ record.producer === 'utility' && record.phase === 'module-entry' && record.edge === 'point',
+ )
+ .map((entry) => missingUtilityStartup(utilityProcessRecords(records, entry)));
+ assert.ok(failures.includes(undefined), failures[0] ?? missingUtilityStartup([]));
+}
+
+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`;
+}
+
+export function assertPackagedPtyPhaseEvidence(directory, driverStderr = '') {
+ assert.ok(directory, 'Packaged PTY phase evidence was not preserved');
+ const records = readPtyPhaseRecords(readFileSync(join(directory, 'phase-trace.jsonl'), 'utf8'));
+ const rendererTraceUnavailable = findRendererTraceUnavailable(driverStderr);
+ if (rendererTraceUnavailable) {
+ assertSomeUtilityProcessStarted(records);
+ return describeUncheckedRendererSession(rendererTraceUnavailable);
+ }
+ const start = records.find(
+ (record) =>
+ record.producer === 'renderer' && record.phase === 'start' && record.edge === 'begin',
+ );
+ assert.ok(start?.ptyId, 'Packaged PTY phase evidence is missing the renderer session');
+ const session = records.filter(
+ (record) => record.producer === 'utility' && record.ptyId === start.ptyId,
+ );
+ assert.ok(session.length > 0, 'Packaged PTY phase evidence is missing the utility session');
+ const utility = utilityProcessRecords(records, session[0]);
+ const missingStartup = missingUtilityStartup(utility);
+ assert.ok(!missingStartup, missingStartup);
+ for (const [phase, edge] of RENDERER_SESSION_UTILITY_PHASES) {
+ assert.ok(
+ utility.some(
+ (record) =>
+ record.ptyId === start.ptyId &&
+ record.phase === phase &&
+ record.edge === edge &&
+ (phase !== 'pty-first-output' || record.currentSession === true),
+ ),
+ `Packaged PTY phase evidence is missing utility ${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
new file mode 100644
index 000000000..605fa9c53
--- /dev/null
+++ b/packages/desktop/scripts/packaged-pty-phase-acceptance.test.mjs
@@ -0,0 +1,114 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, expect, test } from 'vitest';
+import { assertPackagedPtyPhaseEvidence } from './packaged-pty-phase-acceptance.test-helper.mjs';
+
+const fixtures = [];
+afterEach(() => {
+ for (const directory of fixtures.splice(0)) rmSync(directory, { recursive: true, force: true });
+});
+
+function evidence(utilityRecords) {
+ const directory = mkdtempSync(join(tmpdir(), 'ok-pty-acceptance-'));
+ fixtures.push(directory);
+ const records = [
+ {
+ event: 'pty-phase',
+ producer: 'renderer',
+ phase: 'start',
+ edge: 'begin',
+ ptyId: 'echo-session',
+ atMs: 0,
+ sequence: 1,
+ },
+ ...utilityRecords.map((record, index) => ({
+ event: 'pty-phase',
+ producer: 'utility',
+ pid: 42,
+ timeOriginMs: 100,
+ atMs: index,
+ sequence: index + 1,
+ ...record,
+ })),
+ ];
+ writeFileSync(
+ join(directory, 'phase-trace.jsonl'),
+ records.map((record) => JSON.stringify(record)).join('\n'),
+ );
+ return directory;
+}
+
+const startup = [
+ { phase: 'module-entry', edge: 'point' },
+ { phase: 'logger-import', edge: 'begin' },
+ { phase: 'logger-import', edge: 'end' },
+ { phase: 'native-import', edge: 'begin' },
+ { phase: 'native-import', edge: 'end' },
+ { phase: 'listener-ready', edge: 'point' },
+];
+const session = [
+ { phase: 'message-received', edge: 'point' },
+ { phase: 'shell-resolution', edge: 'begin' },
+ { phase: 'shell-resolution', edge: 'end' },
+ { phase: 'pty-spawn', edge: 'begin' },
+ { phase: 'pty-spawn', edge: 'end' },
+ { phase: 'pty-first-output', edge: 'point', currentSession: true },
+ { phase: 'pty-first-forward', edge: 'point' },
+].map((record) => ({ ...record, ptyId: 'echo-session' }));
+
+test('accepts retained utility startup and output evidence for the renderer session', () => {
+ expect(() => assertPackagedPtyPhaseEvidence(evidence([...startup, ...session]))).not.toThrow();
+});
+
+test('accepts a reported logger import failure when utility startup and output are retained', () => {
+ const failedLogger = startup.map((record) =>
+ record.phase === 'logger-import' && record.edge === 'end'
+ ? { ...record, edge: 'error' }
+ : record,
+ );
+ expect(() =>
+ assertPackagedPtyPhaseEvidence(evidence([...failedLogger, ...session])),
+ ).not.toThrow();
+});
+
+test('rejects a retained renderer session with no utility phase evidence', () => {
+ expect(() => assertPackagedPtyPhaseEvidence(evidence([]))).toThrow(
+ 'Packaged PTY phase evidence is missing the utility session',
+ );
+});
+
+test('rejects utility output without its earliest startup evidence', () => {
+ expect(() => assertPackagedPtyPhaseEvidence(evidence(session))).toThrow(
+ 'Packaged PTY phase evidence is missing utility module-entry/point',
+ );
+});
+
+test('rejects utility records belonging to a different terminal session', () => {
+ const otherSession = session.map((record) => ({ ...record, ptyId: 'other-session' }));
+ expect(() => assertPackagedPtyPhaseEvidence(evidence([...startup, ...otherSession]))).toThrow(
+ 'Packaged PTY phase evidence is missing the utility session',
+ );
+});
+
+test('rejects startup records from a different utility process', () => {
+ const otherProcess = startup.map((record) => ({ ...record, pid: 43 }));
+ expect(() => assertPackagedPtyPhaseEvidence(evidence([...otherProcess, ...session]))).toThrow(
+ 'Packaged PTY phase evidence is missing utility module-entry/point',
+ );
+});
+
+test('rejects a session whose first output was never forwarded', () => {
+ const unforwarded = session.filter((record) => record.phase !== 'pty-first-forward');
+ expect(() => assertPackagedPtyPhaseEvidence(evidence([...startup, ...unforwarded]))).toThrow(
+ 'Packaged PTY phase evidence is missing utility pty-first-forward/point for the renderer session',
+ );
+});
+
+test('rejects an evidence directory without a retained phase trace', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-pty-acceptance-missing-'));
+ fixtures.push(root);
+ const directory = join(root, 'evidence');
+ mkdirSync(directory);
+ expect(() => assertPackagedPtyPhaseEvidence(directory)).toThrow(/ENOENT/);
+});
diff --git a/packages/desktop/scripts/pty-phase-transport.test.mjs b/packages/desktop/scripts/pty-phase-transport.test.mjs
new file mode 100644
index 000000000..b4063ed60
--- /dev/null
+++ b/packages/desktop/scripts/pty-phase-transport.test.mjs
@@ -0,0 +1,84 @@
+import { EventEmitter, once } from 'node:events';
+import { createWriteStream, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PassThrough } from 'node:stream';
+import { finished } from 'node:stream/promises';
+import { expect, test } from 'vitest';
+import { observePtyFork } from '../src/main/pty-phase-observation.ts';
+import { createPtyPhaseTrace } from '../src/shared/pty-phase-trace.ts';
+import { preservePtyEvidence, readPtyPhaseRecords } from './pty-phase-evidence.mjs';
+
+const records = ['module-entry', 'listener-ready'].map((phase, index) => ({
+ event: 'pty-phase',
+ producer: 'utility',
+ pid: 42,
+ timeOriginMs: 100,
+ sequence: index + 1,
+ atMs: index,
+ phase,
+ edge: 'point',
+}));
+
+async function capture(flag) {
+ const root = mkdtempSync(join(tmpdir(), 'ok-pty-transport-'));
+ const logPath = join(root, 'app.log');
+ const destination = createWriteStream(logPath);
+ const stderr = new PassThrough();
+ const utility = Object.assign(new EventEmitter(), { pid: 42, stderr });
+ const trace = createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: flag }, 'main', () => {});
+ const bytes = Buffer.from(
+ `${JSON.stringify(records[0])}\nutility π\n${JSON.stringify(records[1])}\n`,
+ );
+ const split = bytes.indexOf(Buffer.from('π')) + 1;
+ const ended = once(stderr, 'end');
+ try {
+ stderr.write(bytes.subarray(0, split));
+ observePtyFork(trace, 7, 1, () => utility, destination);
+ const firstData = once(stderr, 'data');
+ stderr.resume();
+ await firstData;
+ utility.emit('exit', 0);
+ utility.stderr = null;
+ stderr.resume();
+ stderr.end(bytes.subarray(split));
+ await ended;
+ const destinationEndedBySource = destination.writableEnded;
+ destination.end();
+ await finished(destination);
+ const saved = preservePtyEvidence({
+ diagnosticsDir: join(root, 'saved'),
+ logPath,
+ logDir: join(root, 'logs'),
+ userDataDir: join(root, 'profile'),
+ launchedAt: 0,
+ driver: { status: 0, stdout: '', stderr: '' },
+ });
+ return {
+ input: bytes,
+ output: readFileSync(join(saved, 'app-stdio.log')),
+ records: readPtyPhaseRecords(readFileSync(join(saved, 'phase-trace.jsonl'), 'utf8')),
+ destinationEndedBySource,
+ };
+ } finally {
+ if (!stderr.readableEnded) stderr.end();
+ if (!destination.writableEnded) destination.end();
+ await finished(destination);
+ rmSync(root, { recursive: true, force: true });
+ }
+}
+
+test('retains utility diagnostic bytes through stream end after utility exit', async () => {
+ const result = await capture('1');
+ expect(result.output).toEqual(result.input);
+ expect(result.records).toEqual(records);
+ expect(result.destinationEndedBySource).toBe(false);
+});
+
+test.each([undefined, '0'])('does not forward utility stderr when tracing is %s', async (flag) => {
+ const result = await capture(flag);
+ expect(result.input.length).toBeGreaterThan(0);
+ expect(result.output.length).toBe(0);
+ expect(result.records).toEqual([]);
+ expect(result.destinationEndedBySource).toBe(false);
+});
diff --git a/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs b/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs
index 03eb2892d..8dbde2757 100644
--- a/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs
+++ b/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs
@@ -15,6 +15,7 @@ import { afterEach, expect, test, vi } from 'vitest';
const child = vi.hoisted(() => ({ spawn: vi.fn(), spawnSync: vi.fn() }));
vi.mock('node:child_process', () => child);
+import { readPtyPhaseRecords } from './pty-phase-evidence.mjs';
import { runWindowsPackageTerminalSmoke } from './smoke-windows-terminal-package.mjs';
const fixtures = [];
@@ -35,6 +36,15 @@ test.each([0, 1])(
mkdirSync(logDir);
writeFileSync(join(packageDir, 'OpenKnowledge.exe'), 'fixture');
let profile;
+ const driverOutput = `driver output\n${JSON.stringify({
+ event: 'pty-phase',
+ producer: 'renderer',
+ phase: 'start',
+ edge: 'begin',
+ sequence: 1,
+ atMs: 0,
+ ptyId: 'echo-session',
+ })}\n`;
child.spawn.mockImplementation((_file, args, options) => {
profile = args
.find((arg) => arg.startsWith('--user-data-dir='))
@@ -59,7 +69,7 @@ test.each([0, 1])(
child.spawnSync.mockImplementation((file) =>
file === 'taskkill'
? { status: 0 }
- : { status, stdout: 'driver output', stderr: status ? 'original echo failure' : '' },
+ : { status, stdout: driverOutput, stderr: status ? 'original echo failure' : '' },
);
vi.spyOn(console, 'error').mockImplementation(() => {});
vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
@@ -72,7 +82,7 @@ test.each([0, 1])(
env: { ComSpec: 'C:\\Windows\\System32\\cmd.exe' },
});
if (status) expect(run).toThrow('packaged PTY CDP driver exited 1 (signal undefined)');
- else run();
+ else expect(run).toThrow('Packaged PTY phase evidence is missing the utility session');
expect(existsSync(profile)).toBe(false);
expect(existsSync(diagnosticsDir), 'the uploaded evidence must survive fixture deletion').toBe(
true,
@@ -85,7 +95,7 @@ test.each([0, 1])(
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.stdout.log'), 'utf8')).toBe(driverOutput);
expect(readFileSync(join(saved, 'driver.stderr.log'), 'utf8')).toBe(
status ? 'original echo failure' : '',
);
@@ -96,7 +106,7 @@ test.each([0, 1])(
);
test.each([0, 1])(
- 'keeps the original driver outcome %i when evidence cannot be saved',
+ 'reports driver outcome %i without accepting evidence that could not be saved',
(status) => {
const root = mkdtempSync(join(tmpdir(), 'ok-pty-evidence-error-'));
fixtures.push(root);
@@ -115,10 +125,313 @@ test.each([0, 1])(
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();
+ else expect(run).toThrow('Packaged PTY phase evidence was not preserved');
expect(warning.mock.calls.flat().join('\n')).toContain(
'Could not preserve packaged PTY diagnostics',
);
expect(readFileSync(diagnosticsDir, 'utf8')).toBe('occupied');
},
);
+
+test('reports verified retained utility phases after a successful packaged echo', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-pty-evidence-complete-'));
+ fixtures.push(root);
+ const diagnosticsDir = join(root, 'evidence');
+ const logDir = join(root, 'logs');
+ mkdirSync(logDir);
+ writeFileSync(join(root, 'OpenKnowledge.exe'), 'fixture');
+ const ptyId = 'echo-session';
+ const startup = [
+ ['module-entry', 'point'],
+ ['logger-import', 'begin'],
+ ['logger-import', 'end'],
+ ['native-import', 'begin'],
+ ['native-import', 'end'],
+ ['listener-ready', 'point'],
+ ].map(([phase, edge]) => ({ phase, edge }));
+ const session = [
+ ['message-received', 'point'],
+ ['shell-resolution', 'begin'],
+ ['shell-resolution', 'end'],
+ ['pty-spawn', 'begin'],
+ ['pty-spawn', 'end'],
+ ['pty-first-output', 'point'],
+ ['pty-first-forward', 'point'],
+ ].map(([phase, edge]) => ({ phase, edge, ptyId, currentSession: true }));
+ const utility = [...startup, ...session].map((record, index) => ({
+ event: 'pty-phase',
+ producer: 'utility',
+ pid: 42,
+ sequence: index + 1,
+ atMs: index,
+ timeOriginMs: 100,
+ ...record,
+ }));
+ child.spawn.mockImplementation((_file, args, options) => {
+ const profile = args.find((arg) => arg.startsWith('--user-data-dir=')).slice(16);
+ const paths = {
+ 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(paths)}\n`);
+ writeSync(options.stdio[1], [paths, ...utility].map((r) => JSON.stringify(r)).join('\n'));
+ return { pid: 12345 };
+ });
+ child.spawnSync.mockImplementation((file) => ({
+ status: 0,
+ stdout:
+ file === 'taskkill'
+ ? ''
+ : JSON.stringify({
+ event: 'pty-phase',
+ producer: 'renderer',
+ sequence: 1,
+ atMs: 0,
+ phase: 'start',
+ edge: 'begin',
+ ptyId,
+ }),
+ stderr: '',
+ }));
+ const logs = vi.spyOn(console, 'log').mockImplementation(() => {});
+ vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+ runWindowsPackageTerminalSmoke({
+ packageDir: root,
+ diagnosticsDir,
+ platform: 'win32',
+ env: { ComSpec: 'C:\\Windows\\System32\\cmd.exe' },
+ });
+ const saved = join(diagnosticsDir, readdirSync(diagnosticsDir)[0]);
+ const output = logs.mock.calls.map((args) => args.join(' ')).join('\n');
+ expect(readPtyPhaseRecords(output).filter((r) => r.producer === 'utility')).toEqual(utility);
+ const emitted = output
+ .split('\n')
+ .filter((line) => line.startsWith('{'))
+ .map((line) => JSON.parse(line));
+ expect(emitted).toContainEqual({
+ event: 'pty-phase-summary',
+ summary: JSON.parse(readFileSync(join(saved, 'phase-summary.json'), 'utf8')),
+ });
+});
+
+const echoSessionId = 'echo-session';
+const echoObserved =
+ 'PTY echo marker observed: OK_PTY_SMOKE; timings={}; endings=null; notices=null\n';
+const retainedUtility = [
+ ['module-entry', 'point'],
+ ['logger-import', 'begin'],
+ ['logger-import', 'end'],
+ ['native-import', 'begin'],
+ ['native-import', 'end'],
+ ['listener-ready', 'point'],
+ ['message-received', 'point', echoSessionId],
+ ['shell-resolution', 'begin', echoSessionId],
+ ['shell-resolution', 'end', echoSessionId],
+ ['pty-spawn', 'begin', echoSessionId],
+ ['pty-spawn', 'end', echoSessionId],
+ ['pty-first-output', 'point', echoSessionId],
+ ['pty-first-forward', 'point', echoSessionId],
+].map(([phase, edge, ptyId], index) => ({
+ event: 'pty-phase',
+ producer: 'utility',
+ pid: 42,
+ sequence: index + 1,
+ atMs: index,
+ timeOriginMs: 100,
+ phase,
+ edge,
+ ...(ptyId ? { ptyId, currentSession: true } : {}),
+}));
+
+function pythonJsonLine(object) {
+ const fields = Object.entries(object).map(
+ ([key, value]) => `${JSON.stringify(key)}: ${JSON.stringify(value)}`,
+ );
+ return `{${fields.join(', ')}}`;
+}
+
+function collectedRendererTrace(records) {
+ return `${JSON.stringify({
+ event: 'pty-phase-trace',
+ socketUrl: 'ws://127.0.0.1:9222/devtools/page/editor',
+ records: records.map((record, index) => ({
+ event: 'pty-phase',
+ producer: 'renderer',
+ sequence: index + 1,
+ atMs: index,
+ ...record,
+ })),
+ })}\n`;
+}
+
+function stageSuccessfulPackagedEcho({ stdout, stderr, utility = retainedUtility }) {
+ const root = mkdtempSync(join(tmpdir(), 'ok-pty-evidence-renderer-trace-'));
+ fixtures.push(root);
+ const diagnosticsDir = join(root, 'evidence');
+ const logDir = join(root, 'logs');
+ mkdirSync(logDir);
+ writeFileSync(join(root, 'OpenKnowledge.exe'), 'fixture');
+ child.spawn.mockImplementation((_file, args, options) => {
+ const profile = args
+ .find((arg) => arg.startsWith('--user-data-dir='))
+ .slice('--user-data-dir='.length);
+ const paths = {
+ 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(paths)}\n`);
+ writeSync(options.stdio[1], [paths, ...utility].map((r) => JSON.stringify(r)).join('\n'));
+ return { pid: 12345 };
+ });
+ child.spawnSync.mockImplementation((file) =>
+ file === 'taskkill'
+ ? { status: 0, signal: null, stdout: '', stderr: '' }
+ : { status: 0, signal: null, stdout, stderr },
+ );
+ const emitted = [];
+ for (const method of ['log', 'info', 'warn', 'error']) {
+ vi.spyOn(console, method).mockImplementation((...args) => {
+ emitted.push(args.map(String).join(' '));
+ });
+ }
+ for (const stream of [process.stdout, process.stderr]) {
+ vi.spyOn(stream, 'write').mockImplementation((chunk) => {
+ emitted.push(String(chunk));
+ return true;
+ });
+ }
+ const run = () =>
+ runWindowsPackageTerminalSmoke({
+ packageDir: root,
+ diagnosticsDir,
+ platform: 'win32',
+ env: { ComSpec: 'C:\\Windows\\System32\\cmd.exe' },
+ });
+ const manifest = () =>
+ JSON.parse(
+ readFileSync(join(diagnosticsDir, readdirSync(diagnosticsDir)[0], 'manifest.json'), 'utf8'),
+ );
+ return { run, emitted, manifest };
+}
+
+test.each([
+ { errorType: 'TimeoutError', error: 'the original echo budget is exhausted' },
+ { errorType: 'ReplyPhaseTimeoutError', error: 'no CDP reply for id=1 within 0.4s' },
+])(
+ 'passes a successful packaged echo whose renderer trace read failed with $errorType and names why and what went unchecked',
+ ({ errorType, error }) => {
+ const stderr = `${pythonJsonLine({ event: 'pty-phase-trace-unavailable', errorType, error })}\n`;
+ const { run, emitted, manifest } = stageSuccessfulPackagedEcho({
+ stdout: echoObserved,
+ stderr,
+ });
+ expect(run).not.toThrow();
+ expect(manifest().rendererCollectionUnavailable).toBe(true);
+ const diagnostics = emitted.filter(
+ (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`,
+ ]);
+ expect(emitted.join('\n')).not.toContain('missing the renderer session');
+ },
+);
+
+test('passes a successful packaged echo with an unavailable renderer trace whose retained utility evidence has startup but no renderer session phases', () => {
+ const { run, manifest } = stageSuccessfulPackagedEcho({
+ stdout: echoObserved,
+ stderr: `${pythonJsonLine({
+ event: 'pty-phase-trace-unavailable',
+ errorType: 'TimeoutError',
+ error: 'the original echo budget is exhausted',
+ })}\n`,
+ utility: retainedUtility.filter((record) => record.ptyId === undefined),
+ });
+ expect(run).not.toThrow();
+ expect(manifest().rendererCollectionUnavailable).toBe(true);
+});
+
+test.each([
+ {
+ retained: 'is empty',
+ utility: [],
+ rejection: /^Packaged PTY phase evidence is missing utility /,
+ },
+ {
+ retained: 'lacks the utility listener-ready point',
+ utility: retainedUtility.filter((record) => record.phase !== 'listener-ready'),
+ rejection: 'Packaged PTY phase evidence is missing utility listener-ready/point',
+ },
+ {
+ retained: 'splits the utility startup across two processes',
+ utility: retainedUtility.map((record) =>
+ record.phase === 'listener-ready' ? { ...record, pid: 43 } : record,
+ ),
+ rejection: /^Packaged PTY phase evidence is missing utility /,
+ },
+])(
+ 'rejects a successful packaged echo with an unavailable renderer trace whose retained utility evidence $retained',
+ ({ utility, rejection }) => {
+ const { run, manifest } = stageSuccessfulPackagedEcho({
+ stdout: echoObserved,
+ stderr: `${pythonJsonLine({
+ event: 'pty-phase-trace-unavailable',
+ errorType: 'TimeoutError',
+ error: 'the original echo budget is exhausted',
+ })}\n`,
+ utility,
+ });
+ expect(run).toThrow(rejection);
+ expect(manifest().rendererCollectionUnavailable).toBe(true);
+ },
+);
+
+test.each([
+ {
+ collected: 'lacks the renderer session start',
+ renderer: [
+ { phase: 'evaluation', edge: 'begin' },
+ { phase: 'create', edge: 'begin' },
+ { phase: 'create', edge: 'end' },
+ ],
+ utility: retainedUtility,
+ rejection: 'Packaged PTY phase evidence is missing the renderer session',
+ },
+ {
+ collected: 'has a renderer session whose first output was never forwarded',
+ renderer: [
+ { phase: 'evaluation', edge: 'begin' },
+ { phase: 'start', edge: 'begin', ptyId: echoSessionId },
+ ],
+ utility: retainedUtility.filter((record) => record.phase !== 'pty-first-forward'),
+ rejection:
+ 'Packaged PTY phase evidence is missing utility pty-first-forward/point for the renderer session',
+ },
+])(
+ 'rejects a successful packaged echo whose collected renderer trace $collected',
+ ({ renderer, utility, rejection }) => {
+ const { run, manifest } = stageSuccessfulPackagedEcho({
+ stdout: `${collectedRendererTrace(renderer)}${echoObserved}`,
+ stderr: '',
+ utility,
+ });
+ expect(run).toThrow(rejection);
+ expect(manifest().rendererCollectionUnavailable).toBe(false);
+ },
+);
diff --git a/packages/desktop/scripts/smoke-windows-terminal-package.mjs b/packages/desktop/scripts/smoke-windows-terminal-package.mjs
index c83625606..c4557d010 100644
--- a/packages/desktop/scripts/smoke-windows-terminal-package.mjs
+++ b/packages/desktop/scripts/smoke-windows-terminal-package.mjs
@@ -19,7 +19,8 @@ import {
SPAWN_WAIT_EXTENSION_FACTOR,
} from '../src/shared/boot-narration.ts';
import { bootLogDirFor, readBootLog } from '../tests/smoke/_helpers/launch-readiness.ts';
-import { preservePtyEvidence } from './pty-phase-evidence.mjs';
+import { assertPackagedPtyPhaseEvidence } from './packaged-pty-phase-acceptance.test-helper.mjs';
+import { preservePtyEvidence, readPtyPhaseRecords } from './pty-phase-evidence.mjs';
export const PACKAGED_BOOT_ENVELOPE_MS = 10_000;
export const PACKAGED_PTY_ECHO_BUDGET_MS = 30_000;
@@ -180,6 +181,7 @@ export function runWindowsPackageTerminalSmoke({
const launchedAt = Date.now();
let app = null;
let driver = null;
+ let evidence;
try {
app = spawn(executable, windowsPackageLaunchArgs(projectDir, userDataDir), {
@@ -215,7 +217,7 @@ export function runWindowsPackageTerminalSmoke({
closeSync(logFd);
} catch {}
try {
- const evidence = preservePtyEvidence({
+ evidence = preservePtyEvidence({
diagnosticsDir,
logPath,
logDir: bootLogDirFor(homedir()),
@@ -234,6 +236,20 @@ export function runWindowsPackageTerminalSmoke({
console.warn(`Could not remove packaged PTY smoke fixture ${smokeRoot}: ${error.message}`);
}
}
+ const uncheckedRendererSession = assertPackagedPtyPhaseEvidence(evidence, driver.stderr);
+ if (uncheckedRendererSession) console.warn(uncheckedRendererSession);
+ console.log(
+ JSON.stringify({
+ event: 'pty-phase-trace',
+ records: readPtyPhaseRecords(readFileSync(join(evidence, 'phase-trace.jsonl'), 'utf8')),
+ }),
+ );
+ console.log(
+ JSON.stringify({
+ event: 'pty-phase-summary',
+ summary: JSON.parse(readFileSync(join(evidence, 'phase-summary.json'), 'utf8')),
+ }),
+ );
}
const invokedPath = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : '';
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index 03d7a1613..467b2fa2a 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -3885,6 +3885,7 @@ function registerIpcHandlers() {
observePtyFork(phaseTrace, windowId, phaseTrace ? ++nextTraceFork : 0, () =>
utilityProcess.fork(join(__dirname, 'utility/pty-host.js'), [], {
serviceName: `OpenKnowledge Terminal Host ${windowId}`,
+ ...(phaseTrace ? { stdio: ['ignore', 'inherit', 'pipe'] } : {}),
}),
) as unknown as PtyUtilityLike,
sendData: (wc, payload) => sendToRenderer(wc, 'ok:pty:data', payload),
diff --git a/packages/desktop/src/main/pty-phase-observation.ts b/packages/desktop/src/main/pty-phase-observation.ts
index bc0a3bef5..43d669d48 100644
--- a/packages/desktop/src/main/pty-phase-observation.ts
+++ b/packages/desktop/src/main/pty-phase-observation.ts
@@ -2,6 +2,7 @@ import type { PtyPhaseTrace } from '../shared/pty-phase-trace.ts';
interface ObservedUtility {
readonly pid: number | undefined;
+ readonly stderr?: NodeJS.ReadableStream | null;
once(event: 'spawn', listener: () => void): unknown;
once(event: 'exit', listener: (code: number) => void): unknown;
}
@@ -11,6 +12,7 @@ export function observePtyFork<T extends ObservedUtility>(
windowId: number,
forkId: number,
fork: () => T,
+ destination?: NodeJS.WritableStream,
): T {
if (!trace) return fork();
const context = { windowId, forkId, scope: `fork-${forkId}` };
@@ -23,6 +25,7 @@ export function observePtyFork<T extends ObservedUtility>(
throw error;
}
trace.mark('utility-fork', 'end', context);
+ utility.stderr?.pipe(destination ?? process.stderr, { end: false });
let utilityPid: number | undefined;
utility.once('spawn', () => {
utilityPid = utility.pid;