Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Retain utility phases in packaged Windows PTY diagnostics (#6114)
Nick Gomez7125b0fde6e0
diff --git a/knip.config.ts b/knip.config.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.tsindex 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.tsindex 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;