Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Record packaged PTY startup phases (#7243)

Nick Gomez6d261641ae05
diff --git a/knip.config.ts b/knip.config.ts
index eb9727af8..36a395261 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -155,21 +155,17 @@ 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: [
'src/main/entry.ts',
'src/utility/server-entry.ts',
- 'src/utility/pty-host.ts',
+ 'src/utility/pty-host-entry.ts',
'src/**/*.test.ts',
'src/**/*.typelock.ts',
'src/utility/server-entry-load-probe.fixture.test-helper.ts',
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/electron.vite.config.ts b/packages/desktop/electron.vite.config.ts
index b9fff4652..3697e5c8e 100644
--- a/packages/desktop/electron.vite.config.ts
+++ b/packages/desktop/electron.vite.config.ts
@@ -86,7 +86,7 @@ export default defineConfig({
'src/main/desktop-uninstall-result-window.ts',
),
'utility/server-entry': resolve(__dirname, 'src/utility/server-entry.ts'),
- 'utility/pty-host': resolve(__dirname, 'src/utility/pty-host.ts'),
+ 'utility/pty-host': resolve(__dirname, 'src/utility/pty-host-entry.ts'),
},
output: { format: 'es', entryFileNames: '[name].js' },
},
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 9c13d995b..2066f52c8 100644
--- a/packages/desktop/scripts/packaged-pty-phase-acceptance.test-helper.mjs
+++ b/packages/desktop/scripts/packaged-pty-phase-acceptance.test-helper.mjs
@@ -4,6 +4,7 @@ import { join } from 'node:path';
import { readPtyPhaseRecords } from './pty-phase-evidence.mjs';
const UTILITY_STARTUP_PHASES = [
+ ['utility-entry', 'point'],
['module-entry', 'point'],
['logger-import', 'begin'],
['native-import', 'begin'],
@@ -58,10 +59,11 @@ function missingUtilityStartup(utility) {
}
function assertSomeUtilityProcessStarted(records) {
+ const [entryPhase, entryEdge] = UTILITY_STARTUP_PHASES[0];
const failures = records
.filter(
(record) =>
- record.producer === 'utility' && record.phase === 'module-entry' && record.edge === 'point',
+ record.producer === 'utility' && record.phase === entryPhase && record.edge === entryEdge,
)
.map((entry) => missingUtilityStartup(utilityProcessRecords(records, entry)));
assert.ok(failures.includes(undefined), failures[0] ?? missingUtilityStartup([]));
diff --git a/packages/desktop/scripts/packaged-pty-phase-acceptance.test.mjs b/packages/desktop/scripts/packaged-pty-phase-acceptance.test.mjs
index 605fa9c53..418b05b1c 100644
--- a/packages/desktop/scripts/packaged-pty-phase-acceptance.test.mjs
+++ b/packages/desktop/scripts/packaged-pty-phase-acceptance.test.mjs
@@ -40,6 +40,7 @@ function evidence(utilityRecords) {
}
const startup = [
+ { phase: 'utility-entry', edge: 'point' },
{ phase: 'module-entry', edge: 'point' },
{ phase: 'logger-import', edge: 'begin' },
{ phase: 'logger-import', edge: 'end' },
@@ -80,10 +81,37 @@ test('rejects a retained renderer session with no utility phase evidence', () =>
test('rejects utility output without its earliest startup evidence', () => {
expect(() => assertPackagedPtyPhaseEvidence(evidence(session))).toThrow(
+ 'Packaged PTY phase evidence is missing utility utility-entry/point',
+ );
+});
+
+test('rejects utility startup whose process never marked the diagnostic entry', () => {
+ const withoutEntry = startup.filter((record) => record.phase !== 'utility-entry');
+ expect(() => assertPackagedPtyPhaseEvidence(evidence([...withoutEntry, ...session]))).toThrow(
+ 'Packaged PTY phase evidence is missing utility utility-entry/point',
+ );
+});
+
+test('rejects utility startup without the host module entry', () => {
+ const withoutModule = startup.filter((record) => record.phase !== 'module-entry');
+ expect(() => assertPackagedPtyPhaseEvidence(evidence([...withoutModule, ...session]))).toThrow(
'Packaged PTY phase evidence is missing utility module-entry/point',
);
});
+const rendererTraceUnavailable = `${JSON.stringify({
+ event: 'pty-phase-trace-unavailable',
+ errorType: 'TimeoutError',
+ error: 'the original echo budget is exhausted',
+})}\n`;
+
+test('rejects an unavailable renderer trace whose utility process stopped after its diagnostic entry, naming the host module entry', () => {
+ const entryOnly = startup.filter((record) => record.phase === 'utility-entry');
+ expect(() =>
+ assertPackagedPtyPhaseEvidence(evidence(entryOnly), rendererTraceUnavailable),
+ ).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(
@@ -94,7 +122,7 @@ test('rejects utility records belonging to a different terminal 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',
+ 'Packaged PTY phase evidence is missing utility utility-entry/point',
);
});
diff --git a/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs b/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs
index 8dbde2757..b88b66b7e 100644
--- a/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs
+++ b/packages/desktop/scripts/smoke-windows-terminal-evidence.test.mjs
@@ -142,6 +142,7 @@ test('reports verified retained utility phases after a successful packaged echo'
writeFileSync(join(root, 'OpenKnowledge.exe'), 'fixture');
const ptyId = 'echo-session';
const startup = [
+ ['utility-entry', 'point'],
['module-entry', 'point'],
['logger-import', 'begin'],
['logger-import', 'end'],
@@ -226,6 +227,7 @@ const echoSessionId = 'echo-session';
const echoObserved =
'PTY echo marker observed: OK_PTY_SMOKE; timings={}; endings=null; notices=null\n';
const retainedUtility = [
+ ['utility-entry', 'point'],
['module-entry', 'point'],
['logger-import', 'begin'],
['logger-import', 'end'],
@@ -378,6 +380,11 @@ test.each([
utility: retainedUtility.filter((record) => record.phase !== 'listener-ready'),
rejection: 'Packaged PTY phase evidence is missing utility listener-ready/point',
},
+ {
+ retained: 'lacks the utility diagnostic entry point',
+ utility: retainedUtility.filter((record) => record.phase !== 'utility-entry'),
+ rejection: 'Packaged PTY phase evidence is missing utility utility-entry/point',
+ },
{
retained: 'splits the utility startup across two processes',
utility: retainedUtility.map((record) =>
diff --git a/packages/desktop/src/shared/pty-phase-trace.test.ts b/packages/desktop/src/shared/pty-phase-trace.test.ts
index ce7f507e1..9e998b608 100644
--- a/packages/desktop/src/shared/pty-phase-trace.test.ts
+++ b/packages/desktop/src/shared/pty-phase-trace.test.ts
@@ -4,7 +4,12 @@ import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, expect, test, vi } from 'vitest';
import { observePtyFork } from '../main/pty-phase-observation.ts';
-import { createPtyPhaseTrace, type PtyPhaseRecord } from './pty-phase-trace.ts';
+import {
+ createPtyPhaseTrace,
+ installUtilityPtyPhaseTrace,
+ type PtyPhaseRecord,
+ takeUtilityPtyPhaseTrace,
+} from './pty-phase-trace.ts';
afterEach(() => vi.restoreAllMocks());
@@ -66,6 +71,35 @@ test('bounds an enabled trace with an explicit limit record', () => {
});
});
+test('passes the entry trace to the host once', () => {
+ const trace = createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: '1' }, 'utility', () => {});
+ installUtilityPtyPhaseTrace(trace);
+
+ expect(takeUtilityPtyPhaseTrace()).toBe(trace);
+ expect(takeUtilityPtyPhaseTrace()).toBeUndefined();
+});
+
+test('records utility process origin context on the module entry mark', () => {
+ const write = vi.fn();
+ const trace = createPtyPhaseTrace({ OK_PTY_PHASE_TRACE: '1' }, 'utility', write);
+
+ trace?.mark('utility-entry', 'point');
+ trace?.mark('module-entry', 'point', {
+ processUptimeMs: 17425,
+ nodeStartMs: 26.8,
+ });
+
+ expect(write.mock.calls.map(([record]) => record)).toEqual([
+ expect.objectContaining({ phase: 'utility-entry', edge: 'point' }),
+ expect.objectContaining({
+ phase: 'module-entry',
+ edge: 'point',
+ processUptimeMs: 17425,
+ nodeStartMs: 26.8,
+ }),
+ ]);
+});
+
test('a failed diagnostic write cannot replace an operation error', () => {
const root = mkdtempSync(join(tmpdir(), 'ok-phase-write-'));
const fd = openSync(join(root, 'closed.log'), 'w');
diff --git a/packages/desktop/src/shared/pty-phase-trace.ts b/packages/desktop/src/shared/pty-phase-trace.ts
index 3babb7058..3ed72b348 100644
--- a/packages/desktop/src/shared/pty-phase-trace.ts
+++ b/packages/desktop/src/shared/pty-phase-trace.ts
@@ -1,4 +1,5 @@
type PtyPhase =
+ | 'utility-entry'
| 'module-entry'
| 'logger-import'
| 'native-import'
@@ -35,6 +36,8 @@ interface PtyPhaseContext {
backend?: 'bundled' | 'inbox' | 'posix';
attempt?: number;
currentSession?: boolean;
+ processUptimeMs?: number;
+ nodeStartMs?: number;
}
export interface PtyPhaseRecord extends PtyPhaseContext {
@@ -55,6 +58,18 @@ export interface PtyPhaseTrace {
mark(phase: PtyPhase, edge: PtyPhaseRecord['edge'], context?: PtyPhaseContext): void;
}
+let utilityPtyPhaseTrace: PtyPhaseTrace | undefined;
+
+export function installUtilityPtyPhaseTrace(trace: PtyPhaseTrace | undefined): void {
+ utilityPtyPhaseTrace = trace;
+}
+
+export function takeUtilityPtyPhaseTrace(): PtyPhaseTrace | undefined {
+ const trace = utilityPtyPhaseTrace;
+ utilityPtyPhaseTrace = undefined;
+ return trace;
+}
+
export function createPtyPhaseTrace(
env: Record<string, string | undefined>,
producer: PtyPhaseRecord['producer'],
diff --git a/packages/desktop/src/utility/pty-host-entry.ts b/packages/desktop/src/utility/pty-host-entry.ts
new file mode 100644
index 000000000..640939a82
--- /dev/null
+++ b/packages/desktop/src/utility/pty-host-entry.ts
@@ -0,0 +1,9 @@
+import { createPtyPhaseTrace, installUtilityPtyPhaseTrace } from '../shared/pty-phase-trace.ts';
+
+const utilityPhaseTrace = createPtyPhaseTrace(process.env, 'utility', (record) => {
+ process.stderr.write(`${JSON.stringify(record)}\n`);
+});
+
+installUtilityPtyPhaseTrace(utilityPhaseTrace);
+utilityPhaseTrace?.mark('utility-entry', 'point');
+await import('./pty-host.ts');
diff --git a/packages/desktop/src/utility/pty-host.ts b/packages/desktop/src/utility/pty-host.ts
index 1402e3764..c6aa8ace4 100644
--- a/packages/desktop/src/utility/pty-host.ts
+++ b/packages/desktop/src/utility/pty-host.ts
@@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process';
import { existsSync, readdirSync } from 'node:fs';
import { userInfo } from 'node:os';
import { basename, win32 } from 'node:path';
+import { performance } from 'node:perf_hooks';
import {
composeWindowsShellLaunchArgs,
isTerminalLaunchEnvName,
@@ -27,7 +28,7 @@ import {
okManagedBinDirs,
okPackagedCliBinDir,
} from '../shared/ok-child-env.ts';
-import { createPtyPhaseTrace, type PtyPhaseTrace } from '../shared/pty-phase-trace.ts';
+import { type PtyPhaseTrace, takeUtilityPtyPhaseTrace } from '../shared/pty-phase-trace.ts';
import {
commandWithManagedPath,
interactiveShellArgs,
@@ -40,12 +41,11 @@ import {
TERMINAL_SUPPORT_FILE_ESCAPE_CODE,
} from './support-file-write.ts';
-const utilityPhaseTrace = (process as NodeJS.Process & { parentPort?: unknown }).parentPort
- ? createPtyPhaseTrace(process.env, 'utility', (record) => {
- process.stderr.write(`${JSON.stringify(record)}\n`);
- })
- : undefined;
-utilityPhaseTrace?.mark('module-entry', 'point');
+const utilityPhaseTrace = takeUtilityPtyPhaseTrace();
+utilityPhaseTrace?.mark('module-entry', 'point', {
+ processUptimeMs: Math.round(process.uptime() * 1000),
+ nodeStartMs: performance.nodeTiming.nodeStart,
+});
const DARWIN_FALLBACK_SHELL = '/bin/zsh';
const KILL_ESCALATE_MS = 250;
diff --git a/packages/desktop/tests/unit/electron-vite-pty-entry.test.ts b/packages/desktop/tests/unit/electron-vite-pty-entry.test.ts
new file mode 100644
index 000000000..600b9f132
--- /dev/null
+++ b/packages/desktop/tests/unit/electron-vite-pty-entry.test.ts
@@ -0,0 +1,15 @@
+import { resolve } from 'node:path';
+import { describe, expect, test } from 'vitest';
+
+const desktopRoot = resolve(import.meta.dirname, '../..');
+
+describe('packaged PTY utility entry', () => {
+ test('builds the packaged PTY utility output from the diagnostic entry module', async () => {
+ const config = (await import('../../electron.vite.config.ts')).default as {
+ main?: { build?: { rolldownOptions?: { input?: Record<string, string> } } };
+ };
+ expect(config.main?.build?.rolldownOptions?.input?.['utility/pty-host']).toBe(
+ resolve(desktopRoot, 'src/utility/pty-host-entry.ts'),
+ );
+ });
+});