Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Give a live dev utility the packaged two-tier startup wait (#5003)

Nick Gomezb7232e4ac19f
diff --git a/.changeset/desktop-utility-wait-graduates-live-server.md b/.changeset/desktop-utility-wait-graduates-live-server.md
new file mode 100644
index 000000000..02745ac25
--- /dev/null
+++ b/.changeset/desktop-utility-wait-graduates-live-server.md
@@ -0,0 +1,6 @@
+---
+"@inkeep/open-knowledge": patch
+"@inkeep/open-knowledge-desktop": patch
+---
+
+In unpackaged Electron runs, a project server that is still starting when the 20 s startup deadline passes now gets up to 160 s instead of the project failing to open, and a server that times out is stopped rather than left running.
diff --git a/packages/desktop/src/main/boot-heartbeat.test.ts b/packages/desktop/src/main/boot-heartbeat.test.ts
index a49c275ab..255b2273c 100644
--- a/packages/desktop/src/main/boot-heartbeat.test.ts
+++ b/packages/desktop/src/main/boot-heartbeat.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import {
BOOT_HEARTBEAT_ABANDONED_SUFFIX,
BOOT_HEARTBEAT_EVENTS,
@@ -96,3 +96,117 @@ describe('startBootHeartbeat', () => {
expect(cleared).toBe(1);
});
});
+
+describe('startBootHeartbeat beat() publishes a beat on demand, inside the same budget', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ function beatOf(heartbeat: ReturnType<typeof startBootHeartbeat>): () => void {
+ expect(heartbeat.beat, 'the heartbeat handle exposes beat()').toBeTypeOf('function');
+ return () => heartbeat.beat();
+ }
+
+ test('publishes one beat now, with the elapsed time and the fields as they stand, and flushes it', () => {
+ const h = harness();
+ let stage = 'startup';
+ const heartbeat = startBootHeartbeat(
+ h.deps,
+ BOOT_HEARTBEAT_EVENTS.utilityWait,
+ 'waiting',
+ () => ({
+ stage,
+ }),
+ );
+ const beat = beatOf(heartbeat);
+ const betweenTicksMs = SPAWN_WAIT_HEARTBEAT_MS / 2;
+ vi.advanceTimersByTime(betweenTicksMs);
+ stage = 'graduated';
+
+ beat();
+
+ expect(h.lines).toEqual([
+ { event: BOOT_HEARTBEAT_EVENTS.utilityWait, elapsedMs: betweenTicksMs, stage: 'graduated' },
+ ]);
+ expect(h.flushes()).toBe(1);
+ expect(h.intervals[0]?.cleared).toBe(false);
+ });
+
+ test('spends a beat of the budget, so the narration abandons after the same number of lines', () => {
+ const h = harness();
+ const heartbeat = startBootHeartbeat(
+ h.deps,
+ BOOT_HEARTBEAT_EVENTS.boot,
+ 'probing',
+ () => ({ phase: 'parked' }),
+ { maxBeats: 3 },
+ );
+ beatOf(heartbeat)();
+ for (let i = 0; i < 10; i += 1) h.intervals[0]?.tick();
+
+ const normal = h.lines.filter((l) => l.event === BOOT_HEARTBEAT_EVENTS.boot);
+ const abandoned = h.lines.filter(
+ (l) => l.event === `${BOOT_HEARTBEAT_EVENTS.boot}${BOOT_HEARTBEAT_ABANDONED_SUFFIX}`,
+ );
+ expect(normal).toHaveLength(3);
+ expect(abandoned).toHaveLength(1);
+ expect(abandoned[0]).toMatchObject({ beats: 3, phase: 'parked' });
+ expect(h.intervals[0]?.cleared).toBe(true);
+ });
+
+ test('abandons the narration when a beat() would exceed the budget, then stays silent', () => {
+ const h = harness();
+ const heartbeat = startBootHeartbeat(
+ h.deps,
+ BOOT_HEARTBEAT_EVENTS.boot,
+ 'probing',
+ () => ({ phase: 'parked' }),
+ { maxBeats: 2 },
+ );
+ const beat = beatOf(heartbeat);
+ h.intervals[0]?.tick();
+ h.intervals[0]?.tick();
+
+ beat();
+ beat();
+
+ expect(h.lines.map((l) => l.event)).toEqual([
+ BOOT_HEARTBEAT_EVENTS.boot,
+ BOOT_HEARTBEAT_EVENTS.boot,
+ `${BOOT_HEARTBEAT_EVENTS.boot}${BOOT_HEARTBEAT_ABANDONED_SUFFIX}`,
+ ]);
+ expect(h.lines.at(-1)).toMatchObject({ beats: 2, phase: 'parked' });
+ expect(h.intervals[0]?.cleared).toBe(true);
+ });
+
+ test('stays silent once the heartbeat is stopped', () => {
+ const h = harness();
+ const heartbeat = startBootHeartbeat(h.deps, BOOT_HEARTBEAT_EVENTS.boot, 'probing', () => ({}));
+ const beat = beatOf(heartbeat);
+
+ heartbeat();
+ beat();
+
+ expect(h.lines).toEqual([]);
+ expect(h.flushes()).toBe(0);
+ });
+
+ test('stays silent when no interval was armed', () => {
+ const h = harness();
+ const heartbeat = startBootHeartbeat(
+ { log: h.deps.log, flushLog: h.deps.flushLog, clearInterval: h.deps.clearInterval },
+ BOOT_HEARTBEAT_EVENTS.boot,
+ 'probing',
+ () => ({}),
+ );
+
+ beatOf(heartbeat)();
+
+ expect(h.lines).toEqual([]);
+ expect(h.flushes()).toBe(0);
+ });
+});
diff --git a/packages/desktop/src/main/boot-heartbeat.ts b/packages/desktop/src/main/boot-heartbeat.ts
index 484a5fcb9..88a2d2ec5 100644
--- a/packages/desktop/src/main/boot-heartbeat.ts
+++ b/packages/desktop/src/main/boot-heartbeat.ts
@@ -21,7 +21,7 @@ export function startBootHeartbeat(
message: string,
fields: () => Record<string, unknown>,
options: BootHeartbeatOptions = {},
-): () => void {
+): (() => void) & { readonly beat: () => void } {
const startedAt = Date.now();
const maxBeats = options.maxBeats;
let beats = 0;
@@ -31,7 +31,7 @@ export function startBootHeartbeat(
deps.clearInterval?.(handle);
handle = undefined;
};
- handle = deps.setInterval?.(() => {
+ const tick = () => {
beats += 1;
const elapsedMs = Date.now() - startedAt;
if (maxBeats !== undefined && beats > maxBeats) {
@@ -50,6 +50,11 @@ export function startBootHeartbeat(
}
deps.log?.info({ event, elapsedMs, ...fields() }, message);
deps.flushLog?.();
- }, SPAWN_WAIT_HEARTBEAT_MS);
- return stop;
+ };
+ handle = deps.setInterval?.(tick, SPAWN_WAIT_HEARTBEAT_MS);
+ const beat = () => {
+ if (handle === undefined) return;
+ tick();
+ };
+ return Object.assign(stop, { beat });
}
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index 4b11a6bb6..e51da44b0 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -2121,6 +2121,7 @@ async function openProjectOrFallbackToNavigator(
},
'[main] openProject failed, falling back to Navigator',
);
+ flushDesktopLogger();
let dialogTitle = 'Unable to open project';
let dialogBody = `${projectPath}\n\n${errorMessage}`;
if (kind === 'mcp-server-stuck') {
@@ -2189,12 +2190,14 @@ async function openProjectOrFallbackToNavigator(
},
'[main] openProject retry after stopping the conflicting server failed',
);
+ flushDesktopLogger();
dialog.showErrorBox(
'Unable to open project',
`${projectPath}\n\n${(retryErr as Error).message}`,
);
}
} else {
+ flushDesktopLogger();
dialog.showErrorBox(
'Unable to open project',
`${projectPath}\n\n` +
@@ -2215,6 +2218,7 @@ async function openProjectOrFallbackToNavigator(
);
if (isStaleLockHolder) {
const stopCommandTarget = quoteStopCommandPath(projectPath, process.platform);
+ flushDesktopLogger();
dialog.showErrorBox(
dialogTitle,
`${dialogBody}\n\n` +
diff --git a/packages/desktop/src/main/window-manager.ts b/packages/desktop/src/main/window-manager.ts
index c7fb42394..a0ec5f1aa 100644
--- a/packages/desktop/src/main/window-manager.ts
+++ b/packages/desktop/src/main/window-manager.ts
@@ -11,10 +11,17 @@ import type { KeepaliveHandle } from '@inkeep/open-knowledge-core/keepalive';
import { getLocalDir, type LocalOpCliInvocation } from '@inkeep/open-knowledge-server';
import {
BOOT_HEARTBEAT_EVENTS,
+ isUtilityInitPhase,
SPAWN_STARTUP_DEADLINE_MS,
- SPAWN_WAIT_EXTENSION_FACTOR,
SPAWN_WAIT_HEARTBEAT_MS,
+ startupWaitHardCapMs,
+ UTILITY_INIT_COUNTERS,
UTILITY_INIT_TIMEOUT_MS,
+ UTILITY_WAIT_EXPIRED_EVENT,
+ UTILITY_WAIT_EXTENDED_EVENT,
+ UTILITY_WAIT_LATE_KILL_EVENT,
+ type UtilityInitPhase,
+ utilityInitPhaseEvent,
} from '../shared/boot-narration.ts';
import type { OkServerRestartOutcome } from '../shared/bridge-contract.ts';
import { registerPendingDelivery } from '../shared/ipc-send.ts';
@@ -64,6 +71,23 @@ function isValidLockPidLocal(value: unknown): value is number {
return true;
}
+type UtilityInitCounter = (typeof UTILITY_INIT_COUNTERS)[number];
+
+type UtilityInitPhaseMark = { phase?: unknown } & Partial<Record<UtilityInitCounter, unknown>>;
+
+function nonNegativeInitCounters(
+ mark: UtilityInitPhaseMark,
+): Partial<Record<UtilityInitCounter, number>> {
+ const counters: Partial<Record<UtilityInitCounter, number>> = {};
+ for (const counter of UTILITY_INIT_COUNTERS) {
+ const value = mark[counter];
+ if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+ counters[counter] = value;
+ }
+ }
+ return counters;
+}
+
let windowInstanceLabel: string | null = null;
export function setWindowInstanceLabel(label: string | null): void {
@@ -113,6 +137,7 @@ export interface UtilityProcessLike {
on(event: 'message', cb: (msg: unknown) => void): void;
on(event: 'exit', cb: (code: number | null) => void): void;
once(event: 'message', cb: (msg: unknown) => void): void;
+ once(event: 'spawn', cb: () => void): void;
removeListener?(event: 'message', cb: (msg: unknown) => void): void;
removeListener?(event: 'exit', cb: (code: number | null) => void): void;
kill(signal?: NodeJS.Signals): boolean;
@@ -1207,7 +1232,6 @@ export class WindowManager {
});
}
- const INIT_TIMEOUT_MS = this.deps.utilityInitTimeoutMs ?? UTILITY_INIT_TIMEOUT_MS;
const localOpCliArgs = opts.localOpCliInvocation
? resolveLocalOpCliArgsForUtilityFork(opts.localOpCliInvocation)
: null;
@@ -1221,6 +1245,7 @@ export class WindowManager {
serviceName,
},
);
+ const forkedAt = Date.now();
this.deps.log?.info(
{
event: 'desktop-project-server-forked',
@@ -1229,55 +1254,7 @@ export class WindowManager {
},
'[window-manager] project server utility forked',
);
- const utilityRef = utility;
- const stopUtilityWaitHeartbeat = startBootHeartbeat(
- this.deps,
- BOOT_HEARTBEAT_EVENTS.utilityWait,
- '[window-manager] still waiting for the utility process to report ready',
- () => ({ pid: utilityRef.pid, lockDir, initTimeoutMs: INIT_TIMEOUT_MS }),
- );
- const ready = new Promise<{ port: number; apiOrigin: string }>((resolveReady, reject) => {
- let settled = false;
- const settle = (fn: () => void) => {
- if (settled) return;
- settled = true;
- stopUtilityWaitHeartbeat();
- utilityRef.removeListener?.('message', onMessage);
- utilityRef.removeListener?.('exit', onExit);
- fn();
- };
- const onMessage = (msg: unknown) => {
- const m = msg as {
- type?: string;
- port?: number;
- apiOrigin?: string;
- message?: string;
- kind?: string;
- existingLock?: ServerLockMetadataLike;
- };
- if (m.type === 'ready' && typeof m.port === 'number' && typeof m.apiOrigin === 'string') {
- const p = m.port;
- const o = m.apiOrigin;
- settle(() => resolveReady({ port: p, apiOrigin: o }));
- } else if (m.type === 'error') {
- const richError = Object.assign(new Error(m.message ?? 'utility init failed'), {
- name: m.kind === 'lock-collision' ? 'LockCollisionError' : 'UtilityInitError',
- kind: m.kind,
- existingLock: m.existingLock,
- });
- settle(() => reject(richError));
- }
- };
- const onExit = (code: number | null) => {
- settle(() => reject(new Error(`utility exited before ready (code=${code})`)));
- };
- utilityRef.on('message', onMessage);
- utilityRef.on('exit', onExit);
-
- this.deps.setTimeout(() => {
- settle(() => reject(new Error(`utility init timed out after ${INIT_TIMEOUT_MS}ms`)));
- }, INIT_TIMEOUT_MS);
- });
+ const ready = this.waitForForkedUtilityReady(utility, lockDir, forkedAt);
const reactShellDistDir = this.deps.rendererDevUrl
? null
@@ -1424,6 +1401,136 @@ export class WindowManager {
return context;
}
+ private waitForForkedUtilityReady(
+ utility: UtilityProcessLike,
+ lockDir: string,
+ forkedAt: number,
+ ): Promise<{ port: number; apiOrigin: string }> {
+ const startupDeadlineMs = this.deps.utilityInitTimeoutMs ?? UTILITY_INIT_TIMEOUT_MS;
+ const hardCapMs = startupWaitHardCapMs(startupDeadlineMs);
+ let declaredBudgetMs = startupDeadlineMs;
+ const utilityWaitHeartbeat = startBootHeartbeat(
+ this.deps,
+ BOOT_HEARTBEAT_EVENTS.utilityWait,
+ '[window-manager] still waiting for the utility process to report ready',
+ () => ({ pid: utility.pid, lockDir, initTimeoutMs: declaredBudgetMs }),
+ );
+ return new Promise((resolveReady, reject) => {
+ let settled = false;
+ let lastInitPhase: UtilityInitPhase | null = null;
+ const settle = (fn: () => void) => {
+ if (settled) return;
+ settled = true;
+ utilityWaitHeartbeat();
+ utility.removeListener?.('message', onMessage);
+ utility.removeListener?.('exit', onExit);
+ fn();
+ };
+ const logInitPhase = (mark: UtilityInitPhaseMark) => {
+ const { phase } = mark;
+ if (!isUtilityInitPhase(phase)) return;
+ lastInitPhase = phase;
+ this.deps.log?.info(
+ {
+ event: utilityInitPhaseEvent(phase),
+ pid: utility.pid,
+ phase,
+ sinceForkMs: Date.now() - forkedAt,
+ ...nonNegativeInitCounters(mark),
+ },
+ '[window-manager] utility reached a startup phase',
+ );
+ this.deps.flushLog?.();
+ };
+ const killOnceSpawned = () => {
+ const termination = utility.kill() ? 'killed' : 'kill-refused';
+ this.deps.log?.warn(
+ { event: UTILITY_WAIT_LATE_KILL_EVENT, pid: utility.pid, termination },
+ '[window-manager] utility spawned after its wait expired, terminating it',
+ );
+ this.deps.flushLog?.();
+ };
+ const terminate = (): 'killed' | 'deferred-until-spawn' | 'kill-refused' => {
+ // UPSTREAM([email protected]): kill() before spawn returns false and leaves the launch running.
+ if (utility.kill()) return 'killed';
+ if (utility.pid !== undefined) return 'kill-refused';
+ utility.once('spawn', killOnceSpawned);
+ utility.postMessage({ type: 'shutdown' });
+ return 'deferred-until-spawn';
+ };
+ const expire = (budgetMs: number, graduated: boolean) => {
+ if (settled) return;
+ settle(() => reject(new Error(`utility init timed out after ${budgetMs}ms`)));
+ const pid = utility.pid;
+ const termination = terminate();
+ this.deps.log?.warn(
+ {
+ event: UTILITY_WAIT_EXPIRED_EVENT,
+ pid,
+ budgetMs,
+ graduated,
+ termination,
+ lastInitPhase,
+ },
+ '[window-manager] utility did not report ready within its wait',
+ );
+ this.deps.flushLog?.();
+ };
+ const onMessage = (msg: unknown) => {
+ const m = msg as {
+ type?: string;
+ port?: number;
+ apiOrigin?: string;
+ message?: string;
+ kind?: string;
+ existingLock?: ServerLockMetadataLike;
+ };
+ if (m.type === 'init-phase') {
+ logInitPhase(msg as UtilityInitPhaseMark);
+ } else if (
+ m.type === 'ready' &&
+ typeof m.port === 'number' &&
+ typeof m.apiOrigin === 'string'
+ ) {
+ const p = m.port;
+ const o = m.apiOrigin;
+ settle(() => resolveReady({ port: p, apiOrigin: o }));
+ } else if (m.type === 'error') {
+ const richError = Object.assign(new Error(m.message ?? 'utility init failed'), {
+ name: m.kind === 'lock-collision' ? 'LockCollisionError' : 'UtilityInitError',
+ kind: m.kind,
+ existingLock: m.existingLock,
+ });
+ settle(() => reject(richError));
+ }
+ };
+ const onExit = (code: number | null) => {
+ settle(() => reject(new Error(`utility exited before ready (code=${code})`)));
+ };
+ utility.on('message', onMessage);
+ utility.on('exit', onExit);
+
+ this.deps.setTimeout(() => {
+ if (settled) return;
+ const pid = utility.pid;
+ if (!isValidLockPidLocal(pid) || this.deps.isProcessAlive?.(pid) !== true) {
+ expire(startupDeadlineMs, false);
+ return;
+ }
+ declaredBudgetMs = hardCapMs;
+ this.deps.log?.info(
+ { event: UTILITY_WAIT_EXTENDED_EVENT, pid, startupDeadlineMs, hardCapMs, lastInitPhase },
+ '[window-manager] utility still starting at its startup deadline, extending the wait',
+ );
+ utilityWaitHeartbeat.beat();
+ this.deps.setTimeout(
+ () => expire(hardCapMs, true),
+ Math.max(0, forkedAt + hardCapMs - Date.now()),
+ );
+ }, startupDeadlineMs);
+ });
+ }
+
async createEphemeralWindow(opts: {
canonicalFilePath: string;
contentDir: string;
@@ -1817,10 +1924,7 @@ export class WindowManager {
if (!reader) return { lock: null, waitedDeadlineMs: deadlineMs };
const isAlive = this.deps.isProcessAlive;
const started = Date.now();
- const hardCapMs = Math.max(
- deadlineMs,
- progressDeadlineMs ?? deadlineMs * SPAWN_WAIT_EXTENSION_FACTOR,
- );
+ const hardCapMs = startupWaitHardCapMs(deadlineMs, progressDeadlineMs);
let effectiveDeadlineMs = deadlineMs;
let deadline = started + deadlineMs;
let extended = false;
diff --git a/packages/desktop/src/shared/boot-narration.ts b/packages/desktop/src/shared/boot-narration.ts
index 19afbef47..d48150395 100644
--- a/packages/desktop/src/shared/boot-narration.ts
+++ b/packages/desktop/src/shared/boot-narration.ts
@@ -8,6 +8,47 @@ export const UTILITY_INIT_TIMEOUT_MS = 20_000;
export const SPAWN_WAIT_EXTENSION_FACTOR = 8;
+export function startupWaitHardCapMs(
+ startupDeadlineMs: number,
+ progressDeadlineMs?: number,
+): number {
+ return Math.max(
+ startupDeadlineMs,
+ progressDeadlineMs ?? startupDeadlineMs * SPAWN_WAIT_EXTENSION_FACTOR,
+ );
+}
+
+export const UTILITY_INIT_HARD_CAP_MS = startupWaitHardCapMs(UTILITY_INIT_TIMEOUT_MS);
+
+export const UTILITY_WAIT_EXTENDED_EVENT = 'desktop-utility-wait-extended';
+
+export const UTILITY_WAIT_EXPIRED_EVENT = 'desktop-utility-wait-expired';
+
+export const UTILITY_WAIT_LATE_KILL_EVENT = 'desktop-utility-wait-late-kill';
+
+export const UTILITY_INIT_PHASES = [
+ 'init-received',
+ 'imports-resolved',
+ 'project-git-ensured',
+ 'boot-server-started',
+] as const;
+
+export type UtilityInitPhase = (typeof UTILITY_INIT_PHASES)[number];
+
+export const UTILITY_INIT_COUNTERS = ['uptimeMs', 'cpuUserMs', 'cpuSystemMs'] as const;
+
+export type UtilityInitCounters = Record<(typeof UTILITY_INIT_COUNTERS)[number], number>;
+
+export function isUtilityInitPhase(value: unknown): value is UtilityInitPhase {
+ return (UTILITY_INIT_PHASES as readonly unknown[]).includes(value);
+}
+
+export function utilityInitPhaseEvent(
+ phase: UtilityInitPhase,
+): `desktop-utility-init.${UtilityInitPhase}` {
+ return `desktop-utility-init.${phase}`;
+}
+
export const BOOT_HEARTBEAT_MAX_BEATS = 24;
export const DESKTOP_BOOT_EVENT = 'desktop.boot';
diff --git a/packages/desktop/src/utility/server-entry.ts b/packages/desktop/src/utility/server-entry.ts
index 1699b7572..ac1e7745a 100644
--- a/packages/desktop/src/utility/server-entry.ts
+++ b/packages/desktop/src/utility/server-entry.ts
@@ -7,6 +7,7 @@ import type {
Config,
ServerExitReason,
} from '@inkeep/open-knowledge-server';
+import type { UtilityInitCounters, UtilityInitPhase } from '../shared/boot-narration.ts';
import { type KeyringSmokeResult, runKeyringSmoke } from './keyring-smoke.ts';
export type { KeyringSmokeResult } from './keyring-smoke.ts';
@@ -70,11 +71,16 @@ export interface UtilityDebugKeyringSmokeResultMessage {
correlationId: string;
result: KeyringSmokeResult;
}
+export interface UtilityInitPhaseMessage extends UtilityInitCounters {
+ type: 'init-phase';
+ phase: UtilityInitPhase;
+}
export type UtilityOutgoingMessage =
| UtilityReadyMessage
| UtilityErrorMessage
| UtilityDegradedMessage
- | UtilityDebugKeyringSmokeResultMessage;
+ | UtilityDebugKeyringSmokeResultMessage
+ | UtilityInitPhaseMessage;
type UtilityBootedServer = Pick<BootedServer, 'port' | 'destroy' | 'degraded'>;
@@ -98,6 +104,16 @@ export interface SetupUtilityDeps {
env?: Record<string, string | undefined>;
writeSmokeResult?: (path: string, contents: string) => Promise<void>;
prepareBootEnvironment?: PrepareBootEnvironment;
+ readInitCounters?: () => UtilityInitCounters;
+}
+
+function readOwnInitCounters(): UtilityInitCounters {
+ const cpu = process.cpuUsage();
+ return {
+ uptimeMs: Math.round(process.uptime() * 1000),
+ cpuUserMs: Math.round(cpu.user / 1000),
+ cpuSystemMs: Math.round(cpu.system / 1000),
+ };
}
export interface PreparedBootEnvironment {
@@ -111,6 +127,7 @@ export interface PreparedBootEnvironment {
export type PrepareBootEnvironment = (
ipcOpts: UtilityInitMessage['opts'],
+ onPhase?: (phase: UtilityInitPhase) => void,
) => Promise<PreparedBootEnvironment>;
export type UtilityShutdownReason = 'parent-died' | 'shutdown-ipc' | 'SIGTERM' | 'SIGINT';
@@ -184,13 +201,21 @@ export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
deps.exit(drainOk ? 0 : 1);
}
+ const readInitCounters = deps.readInitCounters ?? readOwnInitCounters;
+
+ function markInitPhase(phase: UtilityInitPhase): void {
+ deps.parentPort?.postMessage({ type: 'init-phase', phase, ...readInitCounters() });
+ }
+
async function handleInit(msg: UtilityInitMessage) {
try {
+ markInitPhase('init-received');
const [server, cli, serverNamespace] = await Promise.all([
deps.importServer(),
import('@inkeep/open-knowledge'),
import('@inkeep/open-knowledge-server'),
]);
+ markInitPhase('imports-resolved');
const {
detectGh,
detectGhAccounts,
@@ -203,7 +228,8 @@ export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
const { makeLazyEmbeddingsKeyStore } = serverNamespace;
const projectDir = msg.opts.projectDir ?? msg.opts.contentDir;
const prepare = deps.prepareBootEnvironment ?? defaultPrepareBootEnvironment;
- const prepared = await prepare(msg.opts);
+ const prepared = await prepare(msg.opts, markInitPhase);
+ if (shuttingDown) return;
if (env.OK_DEBUG_DESKTOP_BOOT_TRACE === '1') {
console.warn(
@@ -242,6 +268,7 @@ export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
};
const requestedPort = prepared.serverRuntime.port ?? msg.opts.port;
+ markInitPhase('boot-server-started');
try {
booted = await server.bootServer({ ...bootOpts, port: requestedPort });
} catch (err) {
@@ -420,6 +447,7 @@ export async function resolveDesktopServerRuntime(projectDir: string): Promise<{
async function defaultPrepareBootEnvironment(
ipcOpts: UtilityInitMessage['opts'],
+ onPhase?: (phase: UtilityInitPhase) => void,
): Promise<PreparedBootEnvironment> {
const projectDir = ipcOpts.projectDir ?? ipcOpts.contentDir;
const { ensureProjectGit, initContent } = await import('@inkeep/open-knowledge-server');
@@ -427,6 +455,7 @@ async function defaultPrepareBootEnvironment(
const degradedHints: string[] = [];
if (ipcOpts.didEnsureGit !== true) {
const result = await ensureProjectGit(projectDir);
+ onPhase?.('project-git-ensured');
if (result.repaired === true) {
degradedHints.push('project-git-shell-only');
}
diff --git a/packages/desktop/tests/main/window-manager.test.ts b/packages/desktop/tests/main/window-manager.test.ts
index f688b2261..f3f6aa0bf 100644
--- a/packages/desktop/tests/main/window-manager.test.ts
+++ b/packages/desktop/tests/main/window-manager.test.ts
@@ -1,3 +1,4 @@
+import { EventEmitter } from 'node:events';
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
@@ -14,7 +15,19 @@ import {
WindowManager,
type WindowManagerDeps,
} from '../../src/main/window-manager.ts';
-import { SPAWN_WAIT_HEARTBEAT_MS } from '../../src/shared/boot-narration.ts';
+import {
+ BOOT_HEARTBEAT_EVENTS,
+ SPAWN_STARTUP_DEADLINE_MS,
+ SPAWN_WAIT_EXTENSION_FACTOR,
+ SPAWN_WAIT_HEARTBEAT_MS,
+ UTILITY_INIT_PHASES,
+ UTILITY_INIT_TIMEOUT_MS,
+ UTILITY_WAIT_EXPIRED_EVENT,
+ UTILITY_WAIT_EXTENDED_EVENT,
+ UTILITY_WAIT_LATE_KILL_EVENT,
+ utilityInitPhaseEvent,
+} from '../../src/shared/boot-narration.ts';
+import { parseDeclaredPhaseBudget } from '../smoke/_helpers/launch-readiness.ts';
interface MockUtility extends UtilityProcessLike {
fire: (msg: unknown) => void;
@@ -3985,6 +3998,831 @@ describe('boot heartbeats (the unpackaged path CI runs)', () => {
});
});
+interface Settlement<T> {
+ state: 'pending' | 'resolved' | 'rejected';
+ value?: T;
+ reason?: unknown;
+}
+
+function settlementOf<T>(promise: Promise<T>): Settlement<T> {
+ const settlement: Settlement<T> = { state: 'pending' };
+ promise.then(
+ (value) => {
+ settlement.state = 'resolved';
+ settlement.value = value;
+ },
+ (reason: unknown) => {
+ settlement.state = 'rejected';
+ settlement.reason = reason;
+ },
+ );
+ return settlement;
+}
+
+function isSignalablePid(pid: unknown): boolean {
+ return typeof pid === 'number' && Number.isInteger(pid) && pid >= 2;
+}
+
+function rejectionMessage(settlement: Settlement<unknown>): string {
+ return settlement.reason instanceof Error ? settlement.reason.message : String(settlement.reason);
+}
+
+function exportedEventName(event: string): string {
+ expect(event, 'boot-narration exports the event name').toBeTypeOf('string');
+ return event;
+}
+
+function exportedUtilityInitPhases(): typeof UTILITY_INIT_PHASES {
+ expect(UTILITY_INIT_PHASES, 'boot-narration exports UTILITY_INIT_PHASES').toBeInstanceOf(Array);
+ return UTILITY_INIT_PHASES;
+}
+
+function exportedUtilityInitPhaseEvent(): typeof utilityInitPhaseEvent {
+ expect(utilityInitPhaseEvent, 'boot-narration exports utilityInitPhaseEvent').toBeTypeOf(
+ 'function',
+ );
+ return utilityInitPhaseEvent;
+}
+
+type ListenerRegistration = (event: string, listener: (value: never) => void) => void;
+
+const FORK_PATH_STARTUP_BUDGETS: ReadonlyArray<{
+ budget: string;
+ utilityInitTimeoutMs: number | undefined;
+}> = [
+ { budget: 'the default startup deadline', utilityInitTimeoutMs: undefined },
+ { budget: 'an injected startup deadline', utilityInitTimeoutMs: SPAWN_STARTUP_DEADLINE_MS },
+];
+
+describe.each(FORK_PATH_STARTUP_BUDGETS)(
+ 'the forked utility wait keeps the packaged two-tier startup contract under $budget',
+ ({ utilityInitTimeoutMs }) => {
+ const startupDeadlineMs = utilityInitTimeoutMs ?? UTILITY_INIT_TIMEOUT_MS;
+ const hardCapMs = startupDeadlineMs * SPAWN_WAIT_EXTENSION_FACTOR;
+
+ let env: TestEnv;
+ let alivePids: Set<number>;
+ let probedPids: unknown[];
+ let forkedAt: number;
+
+ beforeEach(() => {
+ vi.useFakeTimers({
+ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
+ });
+ env = buildEnv();
+ alivePids = new Set();
+ probedPids = [];
+ if (utilityInitTimeoutMs !== undefined) env.deps.utilityInitTimeoutMs = utilityInitTimeoutMs;
+ env.deps.setTimeout = (cb, ms) => setTimeout(cb, ms);
+ env.deps.setInterval = (cb, ms) => setInterval(cb, ms);
+ env.deps.clearInterval = (handle) => clearInterval(handle as ReturnType<typeof setInterval>);
+ env.deps.isProcessAlive = (pid) => {
+ probedPids.push(pid);
+ return alivePids.has(pid);
+ };
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ function openProject(projectPath: string): {
+ opening: Settlement<Awaited<ReturnType<WindowManager['createProjectWindow']>>>;
+ utility: MockUtility;
+ } {
+ const wm = new WindowManager(env.deps);
+ const opening = settlementOf(wm.createProjectWindow({ projectPath }));
+ forkedAt = Date.now();
+ const utility = env.utilities[0];
+ if (!utility) throw new Error('utility not forked');
+ return { opening, utility };
+ }
+
+ function observeAlive(utility: MockUtility): void {
+ if (utility.pid !== undefined) alivePids.add(utility.pid);
+ }
+
+ async function drainPendingSettlements(): Promise<void> {
+ await new Promise<void>((resolve) => setImmediate(resolve));
+ }
+
+ async function advanceSinceForkTo(elapsedMs: number): Promise<void> {
+ await vi.advanceTimersByTimeAsync(forkedAt + elapsedMs - Date.now());
+ await drainPendingSettlements();
+ }
+
+ function utilityWaitBeats(): Array<{ elapsedMs: number; initTimeoutMs: number }> {
+ return env.logEntries
+ .map((entry) => entry.payload as Record<string, unknown>)
+ .filter((payload) => payload.event === BOOT_HEARTBEAT_EVENTS.utilityWait)
+ .map((payload) => ({
+ elapsedMs: typeof payload.elapsedMs === 'number' ? payload.elapsedMs : Number.NaN,
+ initTimeoutMs:
+ typeof payload.initTimeoutMs === 'number' ? payload.initTimeoutMs : Number.NaN,
+ }));
+ }
+
+ function utilityWaitBootLogLines(): string[] {
+ return env.logEntries
+ .filter(
+ (entry) =>
+ (entry.payload as Record<string, unknown>).event === BOOT_HEARTBEAT_EVENTS.utilityWait,
+ )
+ .map((entry) => JSON.stringify({ ...entry.payload, msg: entry.message }));
+ }
+
+ function terminatingSignalsSentByPid(): unknown[][] {
+ return env.killProbe.mock.calls.filter(([, signal]) => signal !== 0);
+ }
+
+ test('keeps waiting past the startup deadline for a utility observed alive, and opens the editor on a ready posted before the hard cap', async () => {
+ const { opening, utility } = openProject('/tmp/graduating-utility');
+ observeAlive(utility);
+
+ await advanceSinceForkTo(startupDeadlineMs);
+ expect(opening.state).toBe('pending');
+
+ await advanceSinceForkTo(hardCapMs - SPAWN_WAIT_HEARTBEAT_MS);
+ expect(opening.state).toBe('pending');
+ utility.fire({ type: 'ready', port: 51777, apiOrigin: 'http://localhost:51777' });
+ await drainPendingSettlements();
+
+ expect(opening.state).toBe('resolved');
+ expect(opening.value?.port).toBe(51777);
+ expect(env.windows).toHaveLength(1);
+ expect(env.createWindowOpts[0]?.additionalArguments).toContain('--ok-mode=editor');
+
+ await advanceSinceForkTo(hardCapMs + SPAWN_WAIT_HEARTBEAT_MS);
+ expect(utility.kill).not.toHaveBeenCalled();
+ });
+
+ test('declares the hard cap as its utility-wait budget once a live utility graduates', async () => {
+ const { opening, utility } = openProject('/tmp/graduated-narration');
+ observeAlive(utility);
+
+ await advanceSinceForkTo(startupDeadlineMs + SPAWN_WAIT_HEARTBEAT_MS);
+
+ const beats = utilityWaitBeats();
+ const beforeDeadline = beats.filter((beat) => beat.elapsedMs < startupDeadlineMs);
+ const afterDeadline = beats.filter((beat) => beat.elapsedMs > startupDeadlineMs);
+ expect(beforeDeadline.length).toBeGreaterThan(0);
+ expect(beforeDeadline.map((beat) => beat.initTimeoutMs)).toEqual(
+ beforeDeadline.map(() => startupDeadlineMs),
+ );
+ expect(afterDeadline.length).toBeGreaterThan(0);
+ expect(afterDeadline.map((beat) => beat.initTimeoutMs)).toEqual(
+ afterDeadline.map(() => hardCapMs),
+ );
+ expect(opening.state).toBe('pending');
+ });
+
+ test('fails at the startup deadline and terminates the utility through its handle when the liveness probe finds it dead', async () => {
+ const { opening, utility } = openProject('/tmp/dead-utility');
+
+ await advanceSinceForkTo(startupDeadlineMs - 1);
+ expect(opening.state).toBe('pending');
+
+ await advanceSinceForkTo(startupDeadlineMs);
+ expect(opening.state).toBe('rejected');
+ expect(rejectionMessage(opening)).toMatch(/timed out/);
+ expect(utility.kill).toHaveBeenCalled();
+ expect(terminatingSignalsSentByPid()).toEqual([]);
+ expect(env.windows).toHaveLength(0);
+ });
+
+ test('fails at the startup deadline and terminates the utility through its handle when it never spawned', async () => {
+ const osAnswersAliveForEveryPid = (pid: number): boolean => {
+ probedPids.push(pid);
+ return true;
+ };
+ env.deps.isProcessAlive = osAnswersAliveForEveryPid;
+ const forkUtility = env.deps.forkUtility;
+ env.deps.forkUtility = (entry, args, opts) => {
+ const neverSpawned = forkUtility(entry, args, opts);
+ neverSpawned.pid = undefined;
+ neverSpawned.kill = vi.fn(() => false);
+ return neverSpawned;
+ };
+ const { opening, utility } = openProject('/tmp/never-spawned-utility');
+
+ await advanceSinceForkTo(startupDeadlineMs - 1);
+ expect(opening.state).toBe('pending');
+
+ await advanceSinceForkTo(startupDeadlineMs);
+ expect(opening.state).toBe('rejected');
+ expect(rejectionMessage(opening)).toMatch(/timed out/);
+ expect(utility.kill).toHaveBeenCalled();
+ expect(probedPids.filter((pid) => !isSignalablePid(pid))).toEqual([]);
+ expect(terminatingSignalsSentByPid()).toEqual([]);
+ expect(env.windows).toHaveLength(0);
+ });
+
+ test('fails at the hard cap without a second graduation and terminates the utility through its handle when a live utility never reports ready', async () => {
+ const { opening, utility } = openProject('/tmp/live-utility-never-ready');
+ observeAlive(utility);
+
+ await advanceSinceForkTo(startupDeadlineMs);
+ expect(opening.state).toBe('pending');
+
+ await advanceSinceForkTo(hardCapMs - 1);
+ expect(opening.state).toBe('pending');
+ expect(utility.kill).not.toHaveBeenCalled();
+
+ await advanceSinceForkTo(hardCapMs);
+ expect(opening.state).toBe('rejected');
+ expect(rejectionMessage(opening)).toMatch(/timed out/);
+ expect(utility.kill).toHaveBeenCalledTimes(1);
+ expect(terminatingSignalsSentByPid()).toEqual([]);
+ expect(Math.max(...utilityWaitBeats().map((beat) => beat.initTimeoutMs))).toBe(hardCapMs);
+ expect(env.windows).toHaveLength(0);
+ });
+
+ test('narrates every beat of a graduated wait as a budget the smoke harness honors', async () => {
+ const { utility } = openProject('/tmp/graduated-harness-reading');
+ observeAlive(utility);
+
+ await advanceSinceForkTo(hardCapMs - 1);
+
+ const lines = utilityWaitBootLogLines();
+ const graduated = utilityWaitBeats().filter((beat) => beat.elapsedMs > startupDeadlineMs);
+ expect(graduated.length).toBeGreaterThan(0);
+ expect(lines.filter((line) => parseDeclaredPhaseBudget(line) === undefined)).toEqual([]);
+ });
+
+ function logPayloadsOf(event: unknown): Array<Record<string, unknown>> {
+ return env.logEntries
+ .map((entry) => entry.payload as Record<string, unknown>)
+ .filter((payload) => payload.event === event);
+ }
+
+ function forkUtilityThatSpawnsLate(): {
+ pidsKilledWith: Array<number | undefined>;
+ spawn: () => number | undefined;
+ } {
+ const spawnListeners: Array<() => void> = [];
+ const pidsKilledWith: Array<number | undefined> = [];
+ let lateUtility: UtilityProcessLike | undefined;
+ let pidOnceSpawned: number | undefined;
+ const forkUtility = env.deps.forkUtility;
+ env.deps.forkUtility = (entry, args, opts) => {
+ const utility = forkUtility(entry, args, opts);
+ lateUtility = utility;
+ pidOnceSpawned = utility.pid;
+ utility.pid = undefined;
+ utility.kill = vi.fn(() => {
+ pidsKilledWith.push(utility.pid);
+ return utility.pid !== undefined;
+ });
+ const captureSpawn =
+ (register: ListenerRegistration): ListenerRegistration =>
+ (event, listener) => {
+ if (event === 'spawn') spawnListeners.push(listener as () => void);
+ else register(event, listener);
+ };
+ utility.on = captureSpawn(utility.on as ListenerRegistration) as UtilityProcessLike['on'];
+ utility.once = captureSpawn(
+ utility.once as ListenerRegistration,
+ ) as UtilityProcessLike['once'];
+ return utility;
+ };
+ return {
+ pidsKilledWith,
+ spawn: () => {
+ if (lateUtility) lateUtility.pid = pidOnceSpawned;
+ for (const listener of spawnListeners.splice(0)) listener();
+ return pidOnceSpawned;
+ },
+ };
+ }
+
+ test('terminates a utility that spawns only after its startup deadline through its handle once it has spawned', async () => {
+ const lateSpawn = forkUtilityThatSpawnsLate();
+ const { opening } = openProject('/tmp/late-spawning-utility');
+
+ await advanceSinceForkTo(startupDeadlineMs);
+ expect(opening.state).toBe('rejected');
+ expect(lateSpawn.pidsKilledWith.filter(isSignalablePid)).toEqual([]);
+
+ const spawnedPid = lateSpawn.spawn();
+
+ expect(isSignalablePid(spawnedPid)).toBe(true);
+ expect(lateSpawn.pidsKilledWith.filter(isSignalablePid)).toEqual([spawnedPid]);
+ expect(terminatingSignalsSentByPid()).toEqual([]);
+ expect(env.windows).toHaveLength(0);
+ });
+
+ test('declares the hard cap in a beat at the instant a live utility graduates, even between two heartbeats', async () => {
+ const betweenHeartbeatsDeadlineMs = startupDeadlineMs + SPAWN_WAIT_HEARTBEAT_MS / 2;
+ const betweenHeartbeatsHardCapMs = betweenHeartbeatsDeadlineMs * SPAWN_WAIT_EXTENSION_FACTOR;
+ expect(betweenHeartbeatsDeadlineMs % SPAWN_WAIT_HEARTBEAT_MS).not.toBe(0);
+ env.deps.utilityInitTimeoutMs = betweenHeartbeatsDeadlineMs;
+ const { opening, utility } = openProject('/tmp/graduation-beat');
+ observeAlive(utility);
+
+ await advanceSinceForkTo(betweenHeartbeatsDeadlineMs);
+
+ expect(opening.state).toBe('pending');
+ expect(
+ utilityWaitBeats().filter((beat) => beat.initTimeoutMs === betweenHeartbeatsHardCapMs),
+ ).toEqual([
+ { elapsedMs: betweenHeartbeatsDeadlineMs, initTimeoutMs: betweenHeartbeatsHardCapMs },
+ ]);
+ });
+
+ test.each([
+ {
+ ending: 'the liveness probe finds the utility dead at the startup deadline',
+ utilityAtDeadline: 'dead',
+ graduated: false,
+ termination: 'killed',
+ },
+ {
+ ending: 'the utility has not spawned by the startup deadline',
+ utilityAtDeadline: 'never-spawned',
+ graduated: false,
+ termination: 'deferred-until-spawn',
+ },
+ {
+ ending: 'the probe finds the utility dead and its handle refuses the kill',
+ utilityAtDeadline: 'kill-refused',
+ graduated: false,
+ termination: 'kill-refused',
+ },
+ {
+ ending: 'a utility observed alive never reports ready by the hard cap',
+ utilityAtDeadline: 'alive',
+ graduated: true,
+ termination: 'killed',
+ },
+ ] as const)(
+ 'narrates how the wait ended, in bounded fields, when $ending',
+ async ({ utilityAtDeadline, graduated, termination }) => {
+ const extendedEvent = exportedEventName(UTILITY_WAIT_EXTENDED_EVENT);
+ const expiredEvent = exportedEventName(UTILITY_WAIT_EXPIRED_EVENT);
+ if (utilityAtDeadline === 'never-spawned' || utilityAtDeadline === 'kill-refused') {
+ const forkUtility = env.deps.forkUtility;
+ env.deps.forkUtility = (entry, args, opts) => {
+ const utility = forkUtility(entry, args, opts);
+ if (utilityAtDeadline === 'never-spawned') utility.pid = undefined;
+ utility.kill = vi.fn(() => false);
+ return utility;
+ };
+ }
+ const { opening, utility } = openProject(`/tmp/wait-ending-${utilityAtDeadline}`);
+ if (utilityAtDeadline === 'alive') observeAlive(utility);
+ const endsAtMs = graduated ? hardCapMs : startupDeadlineMs;
+
+ await advanceSinceForkTo(endsAtMs - 1);
+ expect(logPayloadsOf(expiredEvent)).toEqual([]);
+
+ await advanceSinceForkTo(endsAtMs);
+ expect(opening.state).toBe('rejected');
+ expect(logPayloadsOf(expiredEvent)).toEqual([
+ {
+ event: expiredEvent,
+ pid: utility.pid,
+ budgetMs: endsAtMs,
+ graduated,
+ termination,
+ lastInitPhase: null,
+ },
+ ]);
+ expect(logPayloadsOf(extendedEvent)).toEqual(
+ graduated
+ ? [
+ {
+ event: extendedEvent,
+ pid: utility.pid,
+ startupDeadlineMs,
+ hardCapMs,
+ lastInitPhase: null,
+ },
+ ]
+ : [],
+ );
+ },
+ );
+
+ test('logs each startup phase mark the utility posts as a bounded diagnostic line, and flushes it', async () => {
+ const phaseEvent = exportedUtilityInitPhaseEvent();
+ const phases = exportedUtilityInitPhases();
+ const logLengthAtFlush: number[] = [];
+ env.deps.flushLog = () => {
+ logLengthAtFlush.push(env.logEntries.length);
+ };
+ const { opening, utility } = openProject('/tmp/utility-phase-marks');
+ observeAlive(utility);
+ const markSpacingMs = SPAWN_WAIT_HEARTBEAT_MS / phases.length;
+
+ const expectedLines: Array<Record<string, unknown>> = [];
+ for (const [index, phase] of phases.entries()) {
+ const sinceForkMs = markSpacingMs * (index + 1);
+ await advanceSinceForkTo(sinceForkMs);
+ utility.fire({
+ type: 'init-phase',
+ phase,
+ uptimeMs: sinceForkMs,
+ cpuUserMs: index,
+ cpuSystemMs: index,
+ });
+ expect(logLengthAtFlush.at(-1)).toBe(env.logEntries.length);
+ expectedLines.push({
+ event: phaseEvent(phase),
+ pid: utility.pid,
+ phase,
+ sinceForkMs,
+ uptimeMs: sinceForkMs,
+ cpuUserMs: index,
+ cpuSystemMs: index,
+ });
+ }
+
+ expect(phases.length).toBeGreaterThan(0);
+ expect(
+ env.logEntries
+ .map((entry) => entry.payload as Record<string, unknown>)
+ .filter((payload) => phases.some((phase) => payload.event === phaseEvent(phase))),
+ ).toEqual(expectedLines);
+ expect(opening.state).toBe('pending');
+ });
+
+ test('drops a phase mark outside the utility startup phases and omits any counter that is not a finite, non-negative number', async () => {
+ const phaseEvent = exportedUtilityInitPhaseEvent();
+ const [firstPhase, secondPhase] = exportedUtilityInitPhases();
+ const { utility } = openProject('/tmp/utility-malformed-marks');
+
+ for (const phase of ['constructor', 'not-a-startup-phase', 7, undefined]) {
+ utility.fire({ type: 'init-phase', phase, uptimeMs: 0, cpuUserMs: 0, cpuSystemMs: 0 });
+ }
+ utility.fire({
+ type: 'init-phase',
+ phase: firstPhase,
+ uptimeMs: Number.NaN,
+ cpuUserMs: -1,
+ cpuSystemMs: '1',
+ });
+ utility.fire({
+ type: 'init-phase',
+ phase: secondPhase,
+ uptimeMs: Number.POSITIVE_INFINITY,
+ cpuUserMs: 0,
+ cpuSystemMs: 0,
+ });
+
+ expect(
+ env.logEntries
+ .map((entry) => entry.payload as Record<string, unknown>)
+ .filter((payload) => 'phase' in payload),
+ ).toEqual([
+ { event: phaseEvent(firstPhase), pid: utility.pid, phase: firstPhase, sinceForkMs: 0 },
+ {
+ event: phaseEvent(secondPhase),
+ pid: utility.pid,
+ phase: secondPhase,
+ sinceForkMs: 0,
+ cpuUserMs: 0,
+ cpuSystemMs: 0,
+ },
+ ]);
+ });
+
+ test('fails a utility the liveness probe finds dead at its startup deadline, though it posted phase marks up to the last moment', async () => {
+ const phaseEvent = exportedUtilityInitPhaseEvent();
+ const phases = exportedUtilityInitPhases();
+ const expiredEvent = exportedEventName(UTILITY_WAIT_EXPIRED_EVENT);
+ const { opening, utility } = openProject('/tmp/marking-but-dead');
+
+ for (const [index, phase] of phases.entries()) {
+ await advanceSinceForkTo(startupDeadlineMs - phases.length + index);
+ utility.fire({ type: 'init-phase', phase, uptimeMs: 0, cpuUserMs: 0, cpuSystemMs: 0 });
+ }
+ expect(opening.state).toBe('pending');
+
+ await advanceSinceForkTo(startupDeadlineMs);
+
+ expect(opening.state).toBe('rejected');
+ expect(rejectionMessage(opening)).toMatch(/timed out/);
+ expect(phases.flatMap((phase) => logPayloadsOf(phaseEvent(phase)))).toHaveLength(
+ phases.length,
+ );
+ expect(logPayloadsOf(expiredEvent).map((payload) => payload.lastInitPhase)).toEqual([
+ phases.at(-1),
+ ]);
+ });
+
+ test('names the last startup phase the utility marked on the line that extends its wait and on the line that expires it, never a mark it dropped', async () => {
+ const extendedEvent = exportedEventName(UTILITY_WAIT_EXTENDED_EVENT);
+ const expiredEvent = exportedEventName(UTILITY_WAIT_EXPIRED_EVENT);
+ const [markedBeforeGraduation, markedAfterGraduation] = exportedUtilityInitPhases();
+ const { opening, utility } = openProject('/tmp/graduated-utility-names-its-last-phase');
+ observeAlive(utility);
+
+ await advanceSinceForkTo(startupDeadlineMs - 1);
+ utility.fire({
+ type: 'init-phase',
+ phase: markedBeforeGraduation,
+ uptimeMs: 0,
+ cpuUserMs: 0,
+ cpuSystemMs: 0,
+ });
+ await advanceSinceForkTo(startupDeadlineMs);
+ expect(opening.state).toBe('pending');
+ expect(logPayloadsOf(extendedEvent).map((payload) => payload.lastInitPhase)).toEqual([
+ markedBeforeGraduation,
+ ]);
+
+ await advanceSinceForkTo(hardCapMs - 1);
+ for (const phase of [markedAfterGraduation, 'not-a-startup-phase']) {
+ utility.fire({ type: 'init-phase', phase, uptimeMs: 0, cpuUserMs: 0, cpuSystemMs: 0 });
+ }
+ await advanceSinceForkTo(hardCapMs);
+
+ expect(opening.state).toBe('rejected');
+ expect(rejectionMessage(opening)).toBe(`utility init timed out after ${hardCapMs}ms`);
+ expect(logPayloadsOf(expiredEvent).map((payload) => payload.lastInitPhase)).toEqual([
+ markedAfterGraduation,
+ ]);
+ });
+
+ test('does not extend the wait of a live utility that reported ready before its startup deadline once that deadline passes', async () => {
+ const extendedEvent = exportedEventName(UTILITY_WAIT_EXTENDED_EVENT);
+ const { opening, utility } = openProject('/tmp/ready-before-startup-deadline');
+ observeAlive(utility);
+
+ await advanceSinceForkTo(startupDeadlineMs - 1);
+ utility.fire({ type: 'ready', port: 51888, apiOrigin: 'http://localhost:51888' });
+ await drainPendingSettlements();
+ expect(opening.state).toBe('resolved');
+ expect(env.createWindowOpts[0]?.additionalArguments).toContain('--ok-mode=editor');
+ const beatsAtReady = utilityWaitBeats();
+ expect(beatsAtReady.length).toBeGreaterThan(0);
+
+ await advanceSinceForkTo(hardCapMs + SPAWN_WAIT_HEARTBEAT_MS);
+
+ expect(logPayloadsOf(extendedEvent)).toEqual([]);
+ expect(utilityWaitBeats()).toEqual(beatsAtReady);
+ expect(utility.kill).not.toHaveBeenCalled();
+ expect(terminatingSignalsSentByPid()).toEqual([]);
+ });
+
+ function refuseEveryKill(): void {
+ const forkUtility = env.deps.forkUtility;
+ env.deps.forkUtility = (entry, args, opts) => {
+ const utility = forkUtility(entry, args, opts);
+ const attemptKill = utility.kill;
+ utility.kill = vi.fn((signal?: NodeJS.Signals) => {
+ attemptKill.call(utility, signal);
+ return false;
+ });
+ return utility;
+ };
+ }
+
+ test.each([
+ { lateKillSucceeds: true, termination: 'killed' },
+ { lateKillSucceeds: false, termination: 'kill-refused' },
+ ] as const)(
+ 'narrates the kill that lands once a utility spawns after its wait expired, as $termination from what that kill returned, and flushes it',
+ async ({ lateKillSucceeds, termination }) => {
+ const lateKillEvent = exportedEventName(UTILITY_WAIT_LATE_KILL_EVENT);
+ const logLengthAtFlush: number[] = [];
+ env.deps.flushLog = () => {
+ logLengthAtFlush.push(env.logEntries.length);
+ };
+ const lateSpawn = forkUtilityThatSpawnsLate();
+ if (!lateKillSucceeds) refuseEveryKill();
+ const { opening } = openProject(`/tmp/late-kill-${termination}`);
+
+ await advanceSinceForkTo(startupDeadlineMs);
+ expect(opening.state).toBe('rejected');
+ expect(logPayloadsOf(lateKillEvent)).toEqual([]);
+ const flushesBeforeSpawn = logLengthAtFlush.length;
+
+ const spawnedPid = lateSpawn.spawn();
+
+ expect(isSignalablePid(spawnedPid)).toBe(true);
+ expect(lateSpawn.pidsKilledWith.filter(isSignalablePid)).toEqual([spawnedPid]);
+ expect(logPayloadsOf(lateKillEvent)).toEqual([
+ { event: lateKillEvent, pid: spawnedPid, termination },
+ ]);
+ expect(logLengthAtFlush.length).toBeGreaterThan(flushesBeforeSpawn);
+ expect(logLengthAtFlush.at(-1)).toBe(env.logEntries.length);
+ expect(terminatingSignalsSentByPid()).toEqual([]);
+ },
+ );
+
+ function forkUtilityWithEventEmitterListeners(): void {
+ const forkUtility = env.deps.forkUtility;
+ env.deps.forkUtility = (entry, args, opts) => {
+ const forked = forkUtility(entry, args, opts);
+ const utility = env.utilities.at(-1);
+ if (!utility || utility !== forked) throw new Error('utility not forked');
+ const emitter = new EventEmitter();
+ const through =
+ (
+ register: (event: string, listener: (...values: unknown[]) => void) => unknown,
+ ): ListenerRegistration =>
+ (event, listener) => {
+ register(event, listener as (...values: unknown[]) => void);
+ };
+ utility.on = through((event, listener) =>
+ emitter.on(event, listener),
+ ) as UtilityProcessLike['on'];
+ utility.once = through((event, listener) =>
+ emitter.once(event, listener),
+ ) as UtilityProcessLike['once'];
+ utility.removeListener = through((event, listener) =>
+ emitter.removeListener(event, listener),
+ ) as UtilityProcessLike['removeListener'];
+ utility.fire = (msg) => {
+ emitter.emit('message', msg);
+ };
+ utility.fireExit = (code) => {
+ emitter.emit('exit', code);
+ };
+ return utility;
+ };
+ }
+
+ test.each([
+ {
+ ending: 'exits',
+ end: (utility: MockUtility) => utility.fireExit(1),
+ outcome: /utility exited before ready.*code=1/,
+ },
+ {
+ ending: 'reports that its start failed',
+ end: (utility: MockUtility) =>
+ utility.fire({ type: 'error', message: 'project server failed to start' }),
+ outcome: /^project server failed to start$/,
+ },
+ ])(
+ 'ends a graduated wait at once with the outcome of a utility that $ending, and neither kills it nor narrates the wait further',
+ async ({ end, outcome }) => {
+ forkUtilityWithEventEmitterListeners();
+ const { opening, utility } = openProject('/tmp/graduated-utility-ends-its-wait');
+ observeAlive(utility);
+
+ await advanceSinceForkTo(startupDeadlineMs + SPAWN_WAIT_HEARTBEAT_MS);
+ expect(opening.state).toBe('pending');
+ const beatsBeforeTheEnd = utilityWaitBeats();
+ expect(
+ beatsBeforeTheEnd.filter((beat) => beat.initTimeoutMs === hardCapMs).length,
+ ).toBeGreaterThan(0);
+
+ end(utility);
+ await drainPendingSettlements();
+
+ expect(opening.state).toBe('rejected');
+ expect(rejectionMessage(opening)).toMatch(outcome);
+
+ await advanceSinceForkTo(hardCapMs + SPAWN_WAIT_HEARTBEAT_MS);
+
+ expect(utilityWaitBeats()).toEqual(beatsBeforeTheEnd);
+ expect(logPayloadsOf(exportedEventName(UTILITY_WAIT_EXPIRED_EVENT))).toEqual([]);
+ expect(utility.kill).not.toHaveBeenCalled();
+ expect(terminatingSignalsSentByPid()).toEqual([]);
+ expect(env.windows).toHaveLength(0);
+ },
+ );
+
+ test('rejects a live utility that never reports ready with a timeout naming the hard cap', async () => {
+ const { opening, utility } = openProject('/tmp/graduated-utility-times-out');
+ observeAlive(utility);
+
+ await advanceSinceForkTo(hardCapMs);
+
+ expect(opening.state).toBe('rejected');
+ expect(rejectionMessage(opening)).toBe(`utility init timed out after ${hardCapMs}ms`);
+ });
+
+ test('ends a graduated wait at the hard cap counted from the fork when its startup deadline runs late', async () => {
+ const { opening, utility } = openProject('/tmp/graduated-after-a-late-startup-deadline');
+ observeAlive(utility);
+ const eventLoopStallMs = SPAWN_WAIT_HEARTBEAT_MS;
+
+ await advanceSinceForkTo(startupDeadlineMs - 1);
+ vi.setSystemTime(Date.now() + eventLoopStallMs);
+ await advanceSinceForkTo(startupDeadlineMs + eventLoopStallMs);
+ expect(opening.state).toBe('pending');
+ expect(utilityWaitBeats().find((beat) => beat.initTimeoutMs === hardCapMs)).toEqual({
+ elapsedMs: startupDeadlineMs + eventLoopStallMs,
+ initTimeoutMs: hardCapMs,
+ });
+
+ await advanceSinceForkTo(hardCapMs - 1);
+ expect(opening.state).toBe('pending');
+
+ await advanceSinceForkTo(hardCapMs);
+ expect(opening.state).toBe('rejected');
+ expect(rejectionMessage(opening)).toBe(`utility init timed out after ${hardCapMs}ms`);
+ });
+
+ test('logs the phase marks a graduated utility keeps posting up to the last moment, and still ends its wait at the hard cap', async () => {
+ const { opening, utility } = openProject('/tmp/graduated-utility-keeps-marking');
+ observeAlive(utility);
+
+ await advanceSinceForkTo(startupDeadlineMs);
+ expect(opening.state).toBe('pending');
+
+ const phaseEvent = exportedUtilityInitPhaseEvent();
+ const phases = exportedUtilityInitPhases();
+ expect(phases.length).toBeGreaterThan(0);
+ const lastMarkSinceForkMs = hardCapMs - 1;
+ const graduatedMarkWindowMs = lastMarkSinceForkMs - startupDeadlineMs;
+ const expectedLines: Array<Record<string, unknown>> = [];
+ for (const [index, phase] of phases.entries()) {
+ const sinceForkMs =
+ startupDeadlineMs + Math.floor((graduatedMarkWindowMs * (index + 1)) / phases.length);
+ await advanceSinceForkTo(sinceForkMs);
+ utility.fire({
+ type: 'init-phase',
+ phase,
+ uptimeMs: sinceForkMs,
+ cpuUserMs: index,
+ cpuSystemMs: index,
+ });
+ expectedLines.push({
+ event: phaseEvent(phase),
+ pid: utility.pid,
+ phase,
+ sinceForkMs,
+ uptimeMs: sinceForkMs,
+ cpuUserMs: index,
+ cpuSystemMs: index,
+ });
+ }
+ await drainPendingSettlements();
+
+ expect(phases.flatMap((phase) => logPayloadsOf(phaseEvent(phase)))).toEqual(expectedLines);
+ expect(opening.state).toBe('pending');
+ expect(utility.kill).not.toHaveBeenCalled();
+
+ await advanceSinceForkTo(hardCapMs);
+
+ expect(opening.state).toBe('rejected');
+ expect(rejectionMessage(opening)).toMatch(/timed out/);
+ expect(utility.kill).toHaveBeenCalledTimes(1);
+ expect(terminatingSignalsSentByPid()).toEqual([]);
+ });
+
+ test('tells a utility that has not spawned by its startup deadline to shut down through its handle, after its init, and still kills it once it spawns', async () => {
+ const lateSpawn = forkUtilityThatSpawnsLate();
+ const { opening, utility } = openProject('/tmp/unspawned-utility-told-to-shut-down');
+ const postedToUtility = (): unknown[] =>
+ vi.mocked(utility.postMessage).mock.calls.map(([message]) => message);
+
+ await advanceSinceForkTo(startupDeadlineMs - 1);
+ expect(opening.state).toBe('pending');
+ expect(utility.pid).toBeUndefined();
+ expect(postedToUtility()).toEqual([expect.objectContaining({ type: 'init' })]);
+
+ await advanceSinceForkTo(startupDeadlineMs);
+ expect(opening.state).toBe('rejected');
+ expect(rejectionMessage(opening)).toMatch(/timed out/);
+ expect(lateSpawn.pidsKilledWith.filter(isSignalablePid)).toEqual([]);
+ expect(postedToUtility()).toEqual([
+ expect.objectContaining({ type: 'init' }),
+ { type: 'shutdown' },
+ ]);
+
+ const spawnedPid = lateSpawn.spawn();
+
+ expect(isSignalablePid(spawnedPid)).toBe(true);
+ expect(lateSpawn.pidsKilledWith.filter(isSignalablePid)).toEqual([spawnedPid]);
+ expect(terminatingSignalsSentByPid()).toEqual([]);
+ expect(env.windows).toHaveLength(0);
+ });
+
+ test('has told a utility that has not spawned to shut down by the time the failed open reaches its caller', async () => {
+ forkUtilityThatSpawnsLate();
+ const open = new WindowManager(env.deps).createProjectWindow({
+ projectPath: '/tmp/unspawned-utility-shut-down-before-its-caller-sees-the-failure',
+ });
+ forkedAt = Date.now();
+ const utility = env.utilities[0];
+ if (!utility) throw new Error('utility not forked');
+ let postedWhenFailureReachedCaller: unknown[] | undefined;
+ open.catch(() => {
+ postedWhenFailureReachedCaller = vi
+ .mocked(utility.postMessage)
+ .mock.calls.map(([message]) => message);
+ });
+ const opening = settlementOf(open);
+
+ await advanceSinceForkTo(startupDeadlineMs);
+
+ expect(opening.state).toBe('rejected');
+ expect(rejectionMessage(opening)).toMatch(/timed out/);
+ expect(utility.pid).toBeUndefined();
+ expect(postedWhenFailureReachedCaller).toEqual([
+ expect.objectContaining({ type: 'init' }),
+ { type: 'shutdown' },
+ ]);
+ });
+ },
+);
+
describe('WindowManager — local-op CLI invocation threading', () => {
const WIN_EXE = 'C:\\Program Files\\OpenKnowledge\\OpenKnowledge.exe';
const WIN_RESOURCES = 'C:\\Program Files\\OpenKnowledge\\resources';
diff --git a/packages/desktop/tests/smoke/_helpers/launch-readiness.test.ts b/packages/desktop/tests/smoke/_helpers/launch-readiness.test.ts
index 8c0a72715..e4cc7af11 100644
--- a/packages/desktop/tests/smoke/_helpers/launch-readiness.test.ts
+++ b/packages/desktop/tests/smoke/_helpers/launch-readiness.test.ts
@@ -19,12 +19,18 @@ import {
BOOT_HEARTBEAT_MAX_BEATS,
DESKTOP_BOOT_EVENT,
DESKTOP_OPEN_PROJECT_FAILED_EVENT,
+ isBootHeartbeatEvent,
isStartupMarkEvent,
SPAWN_STARTUP_DEADLINE_MS,
SPAWN_WAIT_EXTENSION_FACTOR,
SPAWN_WAIT_HEARTBEAT_MS,
startupMarkLine,
+ UTILITY_INIT_PHASES,
UTILITY_INIT_TIMEOUT_MS,
+ UTILITY_WAIT_EXPIRED_EVENT,
+ UTILITY_WAIT_EXTENDED_EVENT,
+ UTILITY_WAIT_LATE_KILL_EVENT,
+ utilityInitPhaseEvent,
} from '../../../src/shared/boot-narration.ts';
import {
BOOT_LOG_CAP_MS,
@@ -38,6 +44,7 @@ import {
bootLogGapSummary,
bootNarrationFor,
classifyBootLog,
+ DECLARED_UTILITY_BUDGET_CEILING_MS,
describeMissingBootLog,
EVERY_STARTUP_PHASE,
formatBootGapLine,
@@ -48,6 +55,7 @@ import {
launchAdvancementPhases,
launchDesktopApp,
launchHomeFor,
+ parseDeclaredPhaseBudget,
READY_WAIT_GIVE_UP_REASONS,
type ReadyDeadline,
type ReadyWaitRecord,
@@ -1232,7 +1240,8 @@ describe("the wait outlives the app's own deadline for the phase the window is g
forkAtMs -
LAUNCH_RESOLVED_AT_MS +
UTILITY_INIT_TIMEOUT_MS +
- UTILITY_TIMEOUT_OBSERVATION_MARGIN_MS,
+ UTILITY_TIMEOUT_OBSERVATION_MARGIN_MS +
+ BOOT_LOG_POLL_MS,
);
});
});
@@ -1254,7 +1263,7 @@ describe('the give-up describes the narration the wait actually read', () => {
eventAt(5_500, {
event: BOOT_HEARTBEAT_EVENTS.utilityWait,
elapsedMs: 5_000,
- initTimeoutMs: UTILITY_INIT_TIMEOUT_MS,
+ initTimeoutMs: SPAWN_STARTUP_DEADLINE_MS,
}),
eventAt(7_000, {
event: DESKTOP_OPEN_PROJECT_FAILED_EVENT,
@@ -1347,7 +1356,7 @@ describe('a budget the app did not declare cleanly buys the wait no extra time',
[
'an initTimeoutMs larger than the budget the app can declare',
(beat: Record<string, unknown>) =>
- JSON.stringify({ ...beat, initTimeoutMs: UTILITY_INIT_TIMEOUT_MS * 2 }),
+ JSON.stringify({ ...beat, initTimeoutMs: DECLARED_UTILITY_BUDGET_CEILING_MS + 1 }),
],
[
'the budget on a heartbeat that does not own the open phase',
@@ -1404,6 +1413,366 @@ describe('a budget the app did not declare cleanly buys the wait no extra time',
});
});
+const UTILITY_WAIT_HARD_CAP_MS = UTILITY_INIT_TIMEOUT_MS * SPAWN_WAIT_EXTENSION_FACTOR;
+
+function utilityWaitBeatLine(elapsedMs: number, initTimeoutMs: number): string {
+ return JSON.stringify({ event: BOOT_HEARTBEAT_EVENTS.utilityWait, elapsedMs, initTimeoutMs });
+}
+
+function graduatedUtilityNarration(forkAtMs: number, lastBeatElapsedMs: number): NarrationLine[] {
+ const beatsFromTheStartupDeadline: NarrationLine[] = [];
+ for (
+ let elapsedMs = UTILITY_INIT_TIMEOUT_MS;
+ elapsedMs <= lastBeatElapsedMs;
+ elapsedMs += SPAWN_WAIT_HEARTBEAT_MS
+ ) {
+ beatsFromTheStartupDeadline.push(
+ eventAt(forkAtMs + elapsedMs, {
+ event: BOOT_HEARTBEAT_EVENTS.utilityWait,
+ elapsedMs,
+ initTimeoutMs:
+ elapsedMs > UTILITY_INIT_TIMEOUT_MS ? UTILITY_WAIT_HARD_CAP_MS : UTILITY_INIT_TIMEOUT_MS,
+ }),
+ );
+ }
+ return [...deepLinkNarration(forkAtMs).slice(0, -1), ...beatsFromTheStartupDeadline];
+}
+
+describe("the wait honors the hard cap a live utility's startup wait graduates to", () => {
+ it('reads a utility-wait beat declaring the hard cap as a budget, and refuses one declaring past it', () => {
+ const graduatedElapsedMs = UTILITY_INIT_TIMEOUT_MS + SPAWN_WAIT_HEARTBEAT_MS;
+ expect(
+ parseDeclaredPhaseBudget(utilityWaitBeatLine(graduatedElapsedMs, UTILITY_WAIT_HARD_CAP_MS)),
+ ).toEqual({ elapsedMs: graduatedElapsedMs, initTimeoutMs: UTILITY_WAIT_HARD_CAP_MS });
+ expect(
+ parseDeclaredPhaseBudget(
+ utilityWaitBeatLine(graduatedElapsedMs, UTILITY_WAIT_HARD_CAP_MS + 1),
+ ),
+ ).toBeUndefined();
+ });
+
+ it('finds an editor window that answers past the startup deadline, inside the graduated budget', async () => {
+ const forkAtMs = MEASURED_FORK_OFFSETS[0];
+ const readyAtElapsedMs =
+ UTILITY_INIT_TIMEOUT_MS + UTILITY_TIMEOUT_OBSERVATION_MARGIN_MS + SPAWN_WAIT_HEARTBEAT_MS;
+ const windowAnswersAtMs = forkAtMs + readyAtElapsedMs - LAUNCH_RESOLVED_AT_MS;
+ expect(windowAnswersAtMs).toBeGreaterThan(BOOT_LOG_CAP_MS);
+ expect(readyAtElapsedMs).toBeLessThan(UTILITY_WAIT_HARD_CAP_MS);
+
+ const home = seedHome();
+ mkdirSync(bootLogDirFor(home), { recursive: true });
+ const clock = virtualClock(home, graduatedUtilityNarration(forkAtMs, readyAtElapsedMs));
+ const outcome = await waitForReadySignal<string>({
+ home,
+ what: 'editor window',
+ probe: async () => (clock.now() >= windowAnswersAtMs ? 'graduated-editor-page' : undefined),
+ now: clock.now,
+ sleep: clock.sleep,
+ readLog: clock.readLog,
+ startDeadline: clock.startDeadline,
+ }).then(
+ (found) => ({ found, gaveUpWith: undefined }),
+ (error: unknown) => ({ found: undefined, gaveUpWith: (error as Error).message }),
+ );
+ expect(outcome).toEqual({ found: 'graduated-editor-page', gaveUpWith: undefined });
+ });
+});
+
+function utilityWaitBeatWrittenAt(
+ forkAtMs: number,
+ sinceForkMs: number,
+ initTimeoutMs: number,
+): NarrationLine {
+ return eventAt(forkAtMs + sinceForkMs, {
+ event: BOOT_HEARTBEAT_EVENTS.utilityWait,
+ elapsedMs: sinceForkMs,
+ initTimeoutMs,
+ });
+}
+
+function graduatingUtilityNarration(
+ forkAtMs: number,
+ options: {
+ graduationBeat: boolean;
+ decisionLateMs: number;
+ graduatedBeatsLateMs: number;
+ lastBeatElapsedMs: number;
+ },
+): NarrationLine[] {
+ const decisionWrittenAtMs = UTILITY_INIT_TIMEOUT_MS + options.decisionLateMs;
+ const lines: NarrationLine[] = [
+ ...deepLinkNarration(forkAtMs).slice(0, -1),
+ utilityWaitBeatWrittenAt(forkAtMs, decisionWrittenAtMs, UTILITY_INIT_TIMEOUT_MS),
+ ];
+ if (options.graduationBeat) {
+ lines.push(utilityWaitBeatWrittenAt(forkAtMs, decisionWrittenAtMs, UTILITY_WAIT_HARD_CAP_MS));
+ }
+ for (
+ let nominalMs = UTILITY_INIT_TIMEOUT_MS + SPAWN_WAIT_HEARTBEAT_MS;
+ nominalMs <= options.lastBeatElapsedMs;
+ nominalMs += SPAWN_WAIT_HEARTBEAT_MS
+ ) {
+ lines.push(
+ utilityWaitBeatWrittenAt(
+ forkAtMs,
+ nominalMs + options.decisionLateMs + options.graduatedBeatsLateMs,
+ UTILITY_WAIT_HARD_CAP_MS,
+ ),
+ );
+ }
+ return lines;
+}
+
+async function waitForEditorWindowAnsweringAt(
+ narration: readonly NarrationLine[],
+ windowAnswersAtMs: number,
+): Promise<{ found: string | undefined; gaveUpWith: string | undefined }> {
+ const home = seedHome();
+ mkdirSync(bootLogDirFor(home), { recursive: true });
+ const clock = virtualClock(home, narration);
+ return waitForReadySignal<string>({
+ home,
+ what: 'editor window',
+ probe: async () => (clock.now() >= windowAnswersAtMs ? 'graduated-editor-page' : undefined),
+ now: clock.now,
+ sleep: clock.sleep,
+ readLog: clock.readLog,
+ startDeadline: clock.startDeadline,
+ }).then(
+ (found) => ({ found, gaveUpWith: undefined }),
+ (error: unknown) => ({ found: undefined, gaveUpWith: (error as Error).message }),
+ );
+}
+
+describe("the wait grants its observation margin after the app's declared decision, not only up to it", () => {
+ it.each(FORKS_THE_STATIC_CAP_CUTS_SHORT)(
+ 'finds an editor window in the graduated tier when the lines the app writes at its startup deadline run a poll late, for a utility fork at %ims',
+ async (forkAtMs) => {
+ const windowAnswersAtElapsedMs = UTILITY_INIT_TIMEOUT_MS + SPAWN_WAIT_HEARTBEAT_MS;
+ const outcome = await waitForEditorWindowAnsweringAt(
+ graduatingUtilityNarration(forkAtMs, {
+ graduationBeat: true,
+ decisionLateMs: BOOT_LOG_POLL_MS,
+ graduatedBeatsLateMs: 0,
+ lastBeatElapsedMs: windowAnswersAtElapsedMs,
+ }),
+ forkAtMs + windowAnswersAtElapsedMs - LAUNCH_RESOLVED_AT_MS,
+ );
+ expect(outcome).toEqual({ found: 'graduated-editor-page', gaveUpWith: undefined });
+ },
+ );
+});
+
+describe('the graduated budget reaches the wait on the beat the app writes at its decision', () => {
+ it('keeps waiting through a late first graduated heartbeat because the graduation beat declared the hard cap', async () => {
+ const forkAtMs = MEASURED_FORK_OFFSETS[0];
+ const windowAnswersAtElapsedMs = UTILITY_INIT_TIMEOUT_MS + 2 * SPAWN_WAIT_HEARTBEAT_MS;
+ const windowAnswersAtMs = forkAtMs + windowAnswersAtElapsedMs - LAUNCH_RESOLVED_AT_MS;
+ const narrationWith = (graduationBeat: boolean): NarrationLine[] =>
+ graduatingUtilityNarration(forkAtMs, {
+ graduationBeat,
+ decisionLateMs: 0,
+ graduatedBeatsLateMs: BOOT_LOG_POLL_MS,
+ lastBeatElapsedMs: windowAnswersAtElapsedMs,
+ });
+
+ const withoutGraduationBeat = await waitForEditorWindowAnsweringAt(
+ narrationWith(false),
+ windowAnswersAtMs,
+ );
+ expect(withoutGraduationBeat.found).toBeUndefined();
+
+ const withGraduationBeat = await waitForEditorWindowAnsweringAt(
+ narrationWith(true),
+ windowAnswersAtMs,
+ );
+ expect(withGraduationBeat).toEqual({ found: 'graduated-editor-page', gaveUpWith: undefined });
+ });
+});
+
+describe("the wait honors a live utility's whole graduated budget", () => {
+ it('finds an editor window that answers one heartbeat before the hard cap', async () => {
+ const forkAtMs = MEASURED_FORK_OFFSETS[3];
+ const windowAnswersAtElapsedMs = UTILITY_WAIT_HARD_CAP_MS - SPAWN_WAIT_HEARTBEAT_MS;
+ const windowAnswersAtMs = forkAtMs + windowAnswersAtElapsedMs - LAUNCH_RESOLVED_AT_MS;
+ expect(windowAnswersAtMs).toBeGreaterThan(
+ BOOT_LOG_CAP_MS +
+ BOOT_LOG_STALL_MS +
+ UTILITY_INIT_TIMEOUT_MS +
+ UTILITY_TIMEOUT_OBSERVATION_MARGIN_MS,
+ );
+
+ const outcome = await waitForEditorWindowAnsweringAt(
+ graduatingUtilityNarration(forkAtMs, {
+ graduationBeat: true,
+ decisionLateMs: 0,
+ graduatedBeatsLateMs: 0,
+ lastBeatElapsedMs: windowAnswersAtElapsedMs,
+ }),
+ windowAnswersAtMs,
+ );
+ expect(outcome).toEqual({ found: 'graduated-editor-page', gaveUpWith: undefined });
+ });
+});
+
+function exportedEventName(event: string): string {
+ expect(event, 'boot-narration exports the event name').toBeTypeOf('string');
+ return event;
+}
+
+describe("the utility's startup diagnostics are neither launch progress nor a budget to the wait", () => {
+ it('reads the phase-mark, graduation and expiry lines as neither heartbeats, startup stages nor declared budgets', () => {
+ const extendedEvent = exportedEventName(UTILITY_WAIT_EXTENDED_EVENT);
+ const expiredEvent = exportedEventName(UTILITY_WAIT_EXPIRED_EVENT);
+ expect(UTILITY_INIT_PHASES, 'boot-narration exports UTILITY_INIT_PHASES').toBeInstanceOf(Array);
+ expect(utilityInitPhaseEvent, 'boot-narration exports utilityInitPhaseEvent').toBeTypeOf(
+ 'function',
+ );
+ const phaseEvents = UTILITY_INIT_PHASES.map((phase) => utilityInitPhaseEvent(phase));
+ const diagnosticEvents = [...phaseEvents, extendedEvent, expiredEvent];
+ expect(phaseEvents.length).toBeGreaterThan(0);
+ expect(isBootHeartbeatEvent(BOOT_HEARTBEAT_EVENTS.utilityWait)).toBe(true);
+ expect(isStartupMarkEvent(startupMarkLine('serverSpawned', 0).event)).toBe(true);
+ expect(diagnosticEvents.filter((event) => isBootHeartbeatEvent(event))).toEqual([]);
+ expect(diagnosticEvents.filter((event) => isStartupMarkEvent(event))).toEqual([]);
+
+ const forkAtMs = MEASURED_FORK_OFFSETS[0];
+ const launch = deepLinkNarration(forkAtMs).slice(0, -1);
+ const diagnostics: NarrationLine[] = [
+ ...phaseEvents.map((event, index) =>
+ eventAt(forkAtMs + index + 1, { event, sinceForkMs: index + 1 }),
+ ),
+ eventAt(forkAtMs + UTILITY_INIT_TIMEOUT_MS, {
+ event: extendedEvent,
+ startupDeadlineMs: UTILITY_INIT_TIMEOUT_MS,
+ hardCapMs: UTILITY_WAIT_HARD_CAP_MS,
+ }),
+ eventAt(forkAtMs + UTILITY_WAIT_HARD_CAP_MS, {
+ event: expiredEvent,
+ budgetMs: UTILITY_WAIT_HARD_CAP_MS,
+ graduated: true,
+ termination: 'killed',
+ }),
+ ];
+ const bootLog = (narration: readonly NarrationLine[]): string[] =>
+ [...narration].sort((a, b) => a.at - b.at).map((entry) => entry.text);
+ const withoutDiagnostics = bootLog(launch);
+ const withDiagnostics = bootLog([...launch, ...diagnostics]);
+
+ expect(launchAdvancementPhases(withoutDiagnostics).length).toBeGreaterThan(0);
+ expect(launchAdvancementPhases(withDiagnostics)).toEqual(
+ launchAdvancementPhases(withoutDiagnostics),
+ );
+ expect(
+ launch.filter((line) => parseDeclaredPhaseBudget(line.text) !== undefined).length,
+ ).toBeGreaterThan(0);
+ expect(diagnostics.map((line) => parseDeclaredPhaseBudget(line.text))).toEqual(
+ diagnostics.map(() => undefined),
+ );
+ expect(bootLogGapSummary(withoutDiagnostics).beatsSeen).toBeGreaterThan(0);
+ expect(bootLogGapSummary(withDiagnostics).beatsSeen).toBe(
+ bootLogGapSummary(withoutDiagnostics).beatsSeen,
+ );
+ });
+
+ it('reads the line narrating a late kill as neither a heartbeat, a startup stage nor a declared budget', () => {
+ const lateKillEvent = exportedEventName(UTILITY_WAIT_LATE_KILL_EVENT);
+ expect(isBootHeartbeatEvent(BOOT_HEARTBEAT_EVENTS.utilityWait)).toBe(true);
+ expect(isStartupMarkEvent(startupMarkLine('serverSpawned', 0).event)).toBe(true);
+ expect(isBootHeartbeatEvent(lateKillEvent)).toBe(false);
+ expect(isStartupMarkEvent(lateKillEvent)).toBe(false);
+
+ const forkAtMs = MEASURED_FORK_OFFSETS[0];
+ const launch = deepLinkNarration(forkAtMs);
+ const lateKill = eventAt(forkAtMs + UTILITY_INIT_TIMEOUT_MS + SPAWN_WAIT_HEARTBEAT_MS, {
+ event: lateKillEvent,
+ pid: 10001,
+ termination: 'killed',
+ });
+ const withoutLateKill = launch.map((line) => line.text);
+ const withLateKill = [...withoutLateKill, lateKill.text];
+
+ expect(launchAdvancementPhases(withoutLateKill).length).toBeGreaterThan(0);
+ expect(launchAdvancementPhases(withLateKill)).toEqual(launchAdvancementPhases(withoutLateKill));
+ expect(
+ launch.filter((line) => parseDeclaredPhaseBudget(line.text) !== undefined).length,
+ ).toBeGreaterThan(0);
+ expect(parseDeclaredPhaseBudget(lateKill.text)).toBeUndefined();
+ expect(bootLogGapSummary(withoutLateKill).beatsSeen).toBeGreaterThan(0);
+ expect(bootLogGapSummary(withLateKill).beatsSeen).toBe(
+ bootLogGapSummary(withoutLateKill).beatsSeen,
+ );
+ });
+});
+
+function sameInstantDecisionNarration(
+ forkAtMs: number,
+ graduationBeat: 'first' | 'a poll later',
+ lastBeatElapsedMs: number,
+): NarrationLine[] {
+ const intervalBeat = utilityWaitBeatWrittenAt(
+ forkAtMs,
+ UTILITY_INIT_TIMEOUT_MS,
+ UTILITY_INIT_TIMEOUT_MS,
+ );
+ const graduation = eventAt(
+ forkAtMs + UTILITY_INIT_TIMEOUT_MS + (graduationBeat === 'first' ? 0 : BOOT_LOG_POLL_MS),
+ {
+ event: BOOT_HEARTBEAT_EVENTS.utilityWait,
+ elapsedMs: UTILITY_INIT_TIMEOUT_MS,
+ initTimeoutMs: UTILITY_WAIT_HARD_CAP_MS,
+ },
+ );
+ const lines: NarrationLine[] = [
+ ...deepLinkNarration(forkAtMs).slice(0, -1),
+ ...(graduationBeat === 'first' ? [graduation, intervalBeat] : [intervalBeat, graduation]),
+ ];
+ for (
+ let nominalMs = UTILITY_INIT_TIMEOUT_MS + SPAWN_WAIT_HEARTBEAT_MS;
+ nominalMs <= lastBeatElapsedMs;
+ nominalMs += SPAWN_WAIT_HEARTBEAT_MS
+ ) {
+ lines.push(
+ utilityWaitBeatWrittenAt(forkAtMs, nominalMs + BOOT_LOG_POLL_MS, UTILITY_WAIT_HARD_CAP_MS),
+ );
+ }
+ return lines;
+}
+
+describe('the graduated budget reaches the wait whichever of the two beats the app writes at its decision it reads first', () => {
+ it.each([
+ { graduationBeat: 'first', reachesTheLog: 'before the interval beat of the same instant' },
+ {
+ graduationBeat: 'a poll later',
+ reachesTheLog: 'a poll after the interval beat, stamped with the same elapsed time',
+ },
+ ] as const)(
+ 'keeps waiting through a late first graduated heartbeat when the graduation beat reaches the log $reachesTheLog',
+ async ({ graduationBeat }) => {
+ const forkAtMs = MEASURED_FORK_OFFSETS[0];
+ const windowAnswersAtElapsedMs = UTILITY_INIT_TIMEOUT_MS + 2 * SPAWN_WAIT_HEARTBEAT_MS;
+ const windowAnswersAtMs = forkAtMs + windowAnswersAtElapsedMs - LAUNCH_RESOLVED_AT_MS;
+
+ const withoutGraduationBeat = await waitForEditorWindowAnsweringAt(
+ graduatingUtilityNarration(forkAtMs, {
+ graduationBeat: false,
+ decisionLateMs: 0,
+ graduatedBeatsLateMs: BOOT_LOG_POLL_MS,
+ lastBeatElapsedMs: windowAnswersAtElapsedMs,
+ }),
+ windowAnswersAtMs,
+ );
+ expect(withoutGraduationBeat.found).toBeUndefined();
+
+ const outcome = await waitForEditorWindowAnsweringAt(
+ sameInstantDecisionNarration(forkAtMs, graduationBeat, windowAnswersAtElapsedMs),
+ windowAnswersAtMs,
+ );
+ expect(outcome).toEqual({ found: 'graduated-editor-page', gaveUpWith: undefined });
+ },
+ );
+});
+
function slowForkNarration(): NarrationLine[] {
const forkAtMs = BOOT_LOG_CAP_MS + LAUNCH_RESOLVED_AT_MS - SPAWN_WAIT_HEARTBEAT_MS;
const lines: NarrationLine[] = [eventAt(0, { event: DESKTOP_BOOT_EVENT })];
@@ -3165,6 +3534,17 @@ describe("a launch inside the app's own contract, read on polls further out of p
}
});
+function anEarlierLaunchThatStoppedJustAfterItsUtilityWaitGraduated(pollMs: number) {
+ const forkAtMs = MEASURED_FORK_OFFSETS[0];
+ const graduatedAtMs = forkAtMs + UTILITY_INIT_TIMEOUT_MS;
+ return graduatingUtilityNarration(forkAtMs, {
+ graduationBeat: true,
+ decisionLateMs: 0,
+ graduatedBeatsLateMs: 0,
+ lastBeatElapsedMs: UTILITY_INIT_TIMEOUT_MS,
+ }).map(({ at, text }) => ({ atMs: at - graduatedAtMs - pollMs, text }));
+}
+
describe('a launch that boots after the wait first reads a home an earlier launch left its log in', () => {
const verdictOf = ({ gaveUpAtMs, decidingCapMs, advancements }: GiveUp) => ({
gaveUpAtMs,
@@ -3201,6 +3581,29 @@ describe('a launch that boots after the wait first reads a home an earlier launc
expect(sharedGiveUp.gaveUpAtMs).toBeGreaterThan(shared.appVerdictAtMs);
expect(sharedGiveUp.message).toContain(DESKTOP_OPEN_PROJECT_FAILED_EVENT);
});
+
+ it("decides as it would alone when the earlier launch stopped just after its utility wait graduated, and reaches the app's own verdict", async () => {
+ const alone = utilityForkBootingAfterTheWaitsFirstRead(
+ {},
+ { sharedWithALaunchThatStoppedInItsUtilityWait: false },
+ );
+ const shared = {
+ ...alone,
+ name: "a utility fork booting after the wait's first read, into a home an earlier launch left just after its utility wait graduated",
+ narrationUntil: (untilMs: number) => [
+ ...anEarlierLaunchThatStoppedJustAfterItsUtilityWaitGraduated(
+ pollIntervalOf(alone.options),
+ ),
+ ...alone.narrationUntil(untilMs),
+ ],
+ };
+ const watchMs = 2 * readinessWorstCaseMs({ path: 'fork', ...alone.options });
+ const aloneGiveUp = giveUpOf(await reachOf(alone, watchMs), alone);
+ const sharedGiveUp = giveUpOf(await reachOf(shared, watchMs), shared);
+ expect(verdictOf(sharedGiveUp)).toEqual(verdictOf(aloneGiveUp));
+ expect(sharedGiveUp.gaveUpAtMs).toBeGreaterThan(shared.appVerdictAtMs);
+ expect(sharedGiveUp.message).toContain(DESKTOP_OPEN_PROJECT_FAILED_EVENT);
+ });
});
describe('a wait over a home that also holds the log a launch the day before left decides as it would had every poll read both logs', () => {
diff --git a/packages/desktop/tests/smoke/_helpers/launch-readiness.ts b/packages/desktop/tests/smoke/_helpers/launch-readiness.ts
index 88f6180e4..f35ff936a 100644
--- a/packages/desktop/tests/smoke/_helpers/launch-readiness.ts
+++ b/packages/desktop/tests/smoke/_helpers/launch-readiness.ts
@@ -9,10 +9,12 @@ import {
SPAWN_WAIT_HEARTBEAT_MS,
type StartupMarkLine,
startupMarkLine,
- UTILITY_INIT_TIMEOUT_MS,
+ UTILITY_INIT_HARD_CAP_MS,
} from '../../../src/shared/boot-narration.ts';
import type { DesktopLaunchMode } from './launch-desktop';
+export const DECLARED_UTILITY_BUDGET_CEILING_MS = UTILITY_INIT_HARD_CAP_MS;
+
export const BOOT_LOG_HEARTBEAT_MS = SPAWN_WAIT_HEARTBEAT_MS;
export const BOOT_LOG_STALL_MS = BOOT_LOG_HEARTBEAT_MS * 3;
@@ -40,7 +42,9 @@ export function readinessWorstCaseMs({
case 'packaged':
return capMs + stallMs;
case 'fork':
- return capMs + stallMs + UTILITY_INIT_TIMEOUT_MS + UTILITY_TIMEOUT_OBSERVATION_MARGIN_MS;
+ return (
+ capMs + stallMs + DECLARED_UTILITY_BUDGET_CEILING_MS + UTILITY_TIMEOUT_OBSERVATION_MARGIN_MS
+ );
}
}
@@ -270,24 +274,36 @@ export function parseDeclaredPhaseBudget(line: string): DeclaredPhaseBudget | un
const { elapsedMs, initTimeoutMs } = parsed;
if (!isUsableDurationField(elapsedMs) || !isUsableDurationField(initTimeoutMs))
return undefined;
- if (initTimeoutMs > UTILITY_INIT_TIMEOUT_MS) return undefined;
+ if (initTimeoutMs > DECLARED_UTILITY_BUDGET_CEILING_MS) return undefined;
if (elapsedMs < 0 || elapsedMs > initTimeoutMs) return undefined;
return { elapsedMs, initTimeoutMs };
} catch {}
return undefined;
}
+function declaresLaterBudget(
+ budget: DeclaredPhaseBudget,
+ than: DeclaredPhaseBudget | undefined,
+): boolean {
+ if (than === undefined) return true;
+ if (budget.elapsedMs !== than.elapsedMs) return budget.elapsedMs > than.elapsedMs;
+ return budget.initTimeoutMs > than.initTimeoutMs;
+}
+
function newestDeclaredPhaseBudget(all: readonly string[]): DeclaredPhaseBudget | undefined {
const launch = currentLaunch(all);
const openedAt = openDeclaredPhaseStart(launch);
if (openedAt === -1) return undefined;
+ let newest: DeclaredPhaseBudget | undefined;
for (let i = launch.length - 1; i > openedAt; i -= 1) {
const line = launch[i];
if (line === undefined) continue;
const budget = parseDeclaredPhaseBudget(line);
- if (budget !== undefined) return budget;
+ if (budget === undefined) continue;
+ if (newest !== undefined && budget.elapsedMs !== newest.elapsedMs) break;
+ if (declaresLaterBudget(budget, newest)) newest = budget;
}
- return undefined;
+ return newest;
}
export interface LaunchAdvancement {
@@ -681,7 +697,7 @@ export async function waitForReadySignal<T>(options: ReadySignalOptions<T>): Pro
let deadline = startDeadline(capMs);
let capReached = armCapReached(deadline);
let armedCapMs = capMs;
- let grantedElapsedMs = Number.NEGATIVE_INFINITY;
+ let grantedBudget: DeclaredPhaseBudget | undefined;
let derivedDeadlineAt: number | undefined;
let probePendingAtGiveUp = false;
@@ -719,8 +735,16 @@ export async function waitForReadySignal<T>(options: ReadySignalOptions<T>): Pro
if (bootLineNow !== undefined && !readsAnEarlierLaunch) {
if (launchBootLine !== undefined && bootLineNow !== launchBootLine) {
advancementSeen.clear();
- grantedElapsedMs = Number.NEGATIVE_INFINITY;
+ grantedBudget = undefined;
derivedDeadlineAt = undefined;
+ if (armedCapMs !== capMs) {
+ deadline.cancel();
+ capElapsed = false;
+ probePendingAtGiveUp = false;
+ armedCapMs = capMs;
+ deadline = startDeadline(Math.max(startedAt + armedCapMs - now(), 0));
+ capReached = armCapReached(deadline);
+ }
options.onNewLaunch?.();
}
launchBootLine = bootLineNow;
@@ -738,12 +762,10 @@ export async function waitForReadySignal<T>(options: ReadySignalOptions<T>): Pro
const declaredPhaseOpen = hasOpenDeclaredPhase(snapshot.lines);
if (declaredPhaseOpen && !readsAnEarlierLaunch) {
const budget = newestDeclaredPhaseBudget(snapshot.lines);
- if (budget !== undefined && budget.elapsedMs > grantedElapsedMs) {
- grantedElapsedMs = budget.elapsedMs;
- const remaining = Math.max(
- budget.initTimeoutMs - budget.elapsedMs,
- UTILITY_TIMEOUT_OBSERVATION_MARGIN_MS,
- );
+ if (budget !== undefined && declaresLaterBudget(budget, grantedBudget)) {
+ grantedBudget = budget;
+ const remaining =
+ budget.initTimeoutMs - budget.elapsedMs + UTILITY_TIMEOUT_OBSERVATION_MARGIN_MS;
derivedDeadlineAt = Math.max(derivedDeadlineAt ?? 0, now() + remaining);
options.onDeclaredGrant?.(derivedDeadlineAt - startedAt);
}
@@ -968,6 +990,7 @@ export async function waitForWindowByMode<TPage extends ModeProbePage>(
onNewLaunch: () => {
advancements.length = 0;
declaredGrantMs = undefined;
+ decidingCapMs = capMs;
},
probe: async () => {
const pages = app.windows();
diff --git a/packages/desktop/tests/smoke/_helpers/platform-gate.ts b/packages/desktop/tests/smoke/_helpers/platform-gate.ts
index 44aa34bee..c37a6cd85 100644
--- a/packages/desktop/tests/smoke/_helpers/platform-gate.ts
+++ b/packages/desktop/tests/smoke/_helpers/platform-gate.ts
@@ -67,6 +67,7 @@ export const SPEC_PLATFORM_GATES = {
'uninstall-picker.e2e.ts': ['!DARWIN'],
'uninstall-survey.e2e.ts': ['!DARWIN'],
'uninstall-window-chrome.e2e.ts': ['!DARWIN'],
+ 'utility-process-pre-spawn.e2e.ts': ['!DARWIN'],
'window-chrome.e2e.ts': ['!PLATFORM_SUPPORTED', 'DARWIN', '!PLATFORM_SUPPORTED'],
'window-min-size.e2e.ts': ['!PLATFORM_SUPPORTED'],
} as const satisfies Record<string, readonly string[]>;
diff --git a/packages/desktop/tests/smoke/consent-dialog.e2e.ts b/packages/desktop/tests/smoke/consent-dialog.e2e.ts
index aa10183e9..81c6f9f0b 100644
--- a/packages/desktop/tests/smoke/consent-dialog.e2e.ts
+++ b/packages/desktop/tests/smoke/consent-dialog.e2e.ts
@@ -155,6 +155,7 @@ test.describe('Consent-dialog smoke', () => {
test('Browse button populates content.dir with project-relative path', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const tmpHome = seedTmpHome('browse');
const projectDir = seedFreshNonGitProject('browse');
trackForCleanup(tmpHome, projectDir);
diff --git a/packages/desktop/tests/smoke/terminal-dock.e2e.ts b/packages/desktop/tests/smoke/terminal-dock.e2e.ts
index 64ff7d305..3ebdedbb0 100644
--- a/packages/desktop/tests/smoke/terminal-dock.e2e.ts
+++ b/packages/desktop/tests/smoke/terminal-dock.e2e.ts
@@ -406,6 +406,7 @@ test.describe('Docked terminal — live Electron', () => {
test('QA-004 first open mounts the live panel (no consent dialog)', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('default-on');
track(s.tmpHome, s.projectDir);
const app = await launchApp(s, { restrictPath: true });
@@ -419,6 +420,7 @@ test.describe('Docked terminal — live Electron', () => {
test('QA-005 default-on spawns without writing terminal.enabled', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('default-on-no-write');
track(s.tmpHome, s.projectDir);
const app = await launchApp(s, { restrictPath: true });
@@ -435,6 +437,7 @@ test.describe('Docked terminal — live Electron', () => {
test('QA-006 opted-out shows not-enabled notice; Enable re-enables the shell', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('opt-out', { optOut: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s, { restrictPath: true });
@@ -453,6 +456,7 @@ test.describe('Docked terminal — live Electron', () => {
test('QA-002 View-menu Terminal item toggles the panel and flips label', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('toggle', { consent: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s);
@@ -470,6 +474,7 @@ test.describe('Docked terminal — live Electron', () => {
test('native Terminal placement action follows the current home', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('placement-menu', { consent: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s);
@@ -491,6 +496,7 @@ test.describe('Docked terminal — live Electron', () => {
test('Terminal header placement is symmetric and clears the Agents reveal tab', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('header-placement', { consent: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s);
@@ -529,6 +535,7 @@ test.describe('Docked terminal — live Electron', () => {
test('a pointerleave mid-drag resizes the right column by the real delta, never collapsing it', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('divider-pointerleave', { consent: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s);
@@ -672,6 +679,7 @@ test.describe('Docked terminal — live Electron', () => {
test('QA-022 toggle reveals the dock and mounts the terminal inside their liveness budgets', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('perf', { consent: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s);
@@ -703,6 +711,7 @@ test.describe('Docked terminal — live Electron', () => {
});
test('QA-003 shell starts at project root and runs commands', async ({ captureStderrFor }) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('cmd', { consent: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s, { restrictPath: true });
@@ -770,6 +779,7 @@ test.describe('Docked terminal — live Electron', () => {
test('terminal tab strip exposes collapse without legacy dock chrome', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('dock-controls', { consent: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s, { restrictPath: true });
@@ -787,6 +797,7 @@ test.describe('Docked terminal — live Electron', () => {
test('the terminal lives in the bottom panel, never in the right column', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('dock-edges', { consent: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s, { restrictPath: true });
@@ -804,6 +815,7 @@ test.describe('Docked terminal — live Electron', () => {
test('QA-020 panel exposes region + screen-reader mode + AA contrast', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('a11y', { consent: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s, { restrictPath: true });
@@ -821,6 +833,7 @@ test.describe('Docked terminal — live Electron', () => {
test('QA-019 Escape reaches the terminal; CmdOrCtrl+J is the no-trap exit', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('escape', { consent: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s, { restrictPath: true });
@@ -846,6 +859,7 @@ test.describe('Docked terminal — live Electron', () => {
});
test('Ctrl+` collapses the dock from inside a focused terminal', async ({ captureStderrFor }) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('ctrl-backtick', { consent: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s, { restrictPath: true });
@@ -875,6 +889,7 @@ test.describe('Docked terminal — live Electron', () => {
test('QA-021 collapsed panel is inert and focus returns on collapse', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('inert', { consent: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s, { restrictPath: true });
@@ -900,6 +915,7 @@ test.describe('Docked terminal — live Electron', () => {
});
test('QA-023 panel height persists across reopen', async ({ captureStderrFor }) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('resize', { consent: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s);
@@ -974,6 +990,7 @@ test.describe('Docked terminal — live Electron', () => {
test('QA-017 plain terminal stays quiet; missing Claude launch shows Get-Claude-Code banner', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('claude-missing', { consent: true, pinRestrictedPath: true });
track(s.tmpHome, s.projectDir);
const app = await launchApp(s, { restrictPath: true });
@@ -1001,6 +1018,7 @@ test.describe('Docked terminal — live Electron', () => {
test('QA-018 Connect tools opens Claude setup and can restart the terminal afterward', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('mcp-rewire', {
consent: true,
fakeClaudeTui: true,
@@ -1079,6 +1097,7 @@ test.describe('Docked terminal — live Electron', () => {
test('Settings installation prompts both running Claude terminals to restart', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('settings-agent-tools', {
consent: true,
fakeClaudeTui: true,
diff --git a/packages/desktop/tests/smoke/terminal-tabs.e2e.ts b/packages/desktop/tests/smoke/terminal-tabs.e2e.ts
index ef01bb36c..45bbc5c46 100644
--- a/packages/desktop/tests/smoke/terminal-tabs.e2e.ts
+++ b/packages/desktop/tests/smoke/terminal-tabs.e2e.ts
@@ -196,6 +196,7 @@ test.describe('Terminal tabs — live Electron', () => {
test('first and second tabs display their initial prompt without keyboard input', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('initial-prompts');
const app = await launchApp(s);
captureStderrFor(app, { home: s.tmpHome, cleanupDirs: [s.tmpHome, s.projectDir] });
@@ -216,6 +217,7 @@ test.describe('Terminal tabs — live Electron', () => {
test('no output arrives before the explicit start, and the initial prompt survives a late one', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
const s = seed('delayed-attach');
const app = await launchApp(s);
captureStderrFor(app, { home: s.tmpHome, cleanupDirs: [s.tmpHome, s.projectDir] });
@@ -388,6 +390,7 @@ test.describe('Terminal tabs — live Electron', () => {
test('the seeded profile pins the shell’s PSReadLine state inside the run home', async ({
captureStderrFor,
}) => {
+ test.setTimeout(sumOfDeclaredBoundsMs(test.info()));
test.skip(!WINDOWS, 'PSReadLine state only exists on the Windows shell rungs.');
const s = seed('psreadline-state');
const app = await launchApp(s);
diff --git a/packages/desktop/tests/smoke/utility-process-pre-spawn.e2e.ts b/packages/desktop/tests/smoke/utility-process-pre-spawn.e2e.ts
new file mode 100644
index 000000000..e6687776d
--- /dev/null
+++ b/packages/desktop/tests/smoke/utility-process-pre-spawn.e2e.ts
@@ -0,0 +1,98 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { type ElectronApplication, _electron as electron } from '@playwright/test';
+import { UTILITY_INIT_TIMEOUT_MS } from '../../src/shared/boot-narration.ts';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
+import { homeEnv, SMOKE_ENABLED, userDataDirFor } from './_helpers/platform-gate';
+import { expect, test } from './_helpers/smoke-test';
+
+const TARGET = resolveDesktopTarget();
+const DARWIN = process.platform === 'darwin';
+
+const ECHO_UTILITY_SOURCE =
+ "process.parentPort.on('message', (event) => process.parentPort.postMessage(event.data));\n";
+
+const POSTED_BEFORE_SPAWN = 'posted before the utility spawned';
+
+function launchIsolated(tmpHome: string): Promise<ElectronApplication> {
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDirFor(tmpHome)}`],
+ env: homeEnv(tmpHome),
+ }),
+ );
+}
+
+test.describe('Electron utilityProcess keeps the pre-spawn behaviour the forked project server wait relies on', () => {
+ test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
+ test.skip(!DARWIN, 'Verified in the macOS desktop-smoke job.');
+ test.skip(!TARGET.exists, TARGET.missingReason);
+
+ test('a utility is not killed before it spawns, receives a message posted before it spawned, and is killed once it has spawned', async ({
+ captureStderrFor,
+ }) => {
+ const tmpHome = mkdtempSync(join(tmpdir(), 'ok-utility-pre-spawn-'));
+ const echoUtilityEntry = join(tmpHome, 'echo-utility.mjs');
+ writeFileSync(echoUtilityEntry, ECHO_UTILITY_SOURCE);
+ const app = await launchIsolated(tmpHome);
+ captureStderrFor(app, { cleanupDirs: [tmpHome] });
+
+ const observed = await app.evaluate(
+ async ({ app: electronApp, utilityProcess }, { entry, message, boundMs }) => {
+ await electronApp.whenReady();
+ const child = utilityProcess.fork(entry, [], {
+ serviceName: 'OpenKnowledge pre-spawn probe',
+ });
+ const spawned = new Promise<number | undefined>((resolve) => {
+ child.once('spawn', () => resolve(child.pid));
+ });
+ const echoed = new Promise<unknown>((resolve) => {
+ child.once('message', resolve);
+ });
+ const exited = new Promise<number | undefined>((resolve) => {
+ child.once('exit', () => resolve(child.pid));
+ });
+ const killedBeforeSpawn = child.kill();
+ const pidBeforeSpawn = child.pid;
+ child.postMessage(message);
+ let bound: ReturnType<typeof setTimeout> | undefined;
+ const afterSpawn = await Promise.race([
+ (async () => {
+ const pidAtSpawn = await spawned;
+ const echo = await echoed;
+ const killedAfterSpawn = child.kill();
+ const pidInExitListener = await exited;
+ return {
+ settled: true,
+ pidAtSpawn,
+ echo,
+ killedAfterSpawn,
+ pidInExitListener,
+ pidAfterExit: child.pid,
+ };
+ })(),
+ new Promise<{ settled: false }>((resolve) => {
+ bound = setTimeout(() => resolve({ settled: false }), boundMs);
+ }),
+ ]);
+ clearTimeout(bound);
+ if (!afterSpawn.settled) child.kill();
+ return { killedBeforeSpawn, pidBeforeSpawn, ...afterSpawn };
+ },
+ { entry: echoUtilityEntry, message: POSTED_BEFORE_SPAWN, boundMs: UTILITY_INIT_TIMEOUT_MS },
+ );
+
+ expect(observed).toEqual({
+ killedBeforeSpawn: false,
+ pidBeforeSpawn: undefined,
+ settled: true,
+ pidAtSpawn: expect.any(Number),
+ echo: POSTED_BEFORE_SPAWN,
+ killedAfterSpawn: true,
+ pidInExitListener: undefined,
+ pidAfterExit: undefined,
+ });
+ });
+});
diff --git a/packages/desktop/tests/utility/server-entry.test.ts b/packages/desktop/tests/utility/server-entry.test.ts
index 8b4846e2d..9b4a9c74b 100644
--- a/packages/desktop/tests/utility/server-entry.test.ts
+++ b/packages/desktop/tests/utility/server-entry.test.ts
@@ -5,39 +5,44 @@ import { resolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { resolveServerRuntimeConfig } from '@inkeep/open-knowledge-core';
import { ConfigSchema } from '@inkeep/open-knowledge-server';
-import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { beforeEach, describe, expect, type Mock, test, vi } from 'vitest';
+import { UTILITY_INIT_PHASES } from '../../src/shared/boot-narration.ts';
import type { KeyringSmokeResult } from '../../src/utility/keyring-smoke.ts';
import {
type PreparedBootEnvironment,
resolveContentDir,
+ type SetupUtilityDeps,
setupUtility,
+ type UtilityOutgoingMessage,
} from '../../src/utility/server-entry.ts';
+type UtilityParentPort = NonNullable<SetupUtilityDeps['parentPort']>;
+
interface MockParentPort {
- on: ReturnType<typeof vi.fn>;
- postMessage: ReturnType<typeof vi.fn>;
+ on: Mock<UtilityParentPort['on']>;
+ postMessage: Mock<UtilityParentPort['postMessage']>;
fire: (msg: unknown) => void;
}
function mockParentPort(): MockParentPort {
let handler: ((event: { data: unknown }) => void) | null = null;
- const on = vi.fn((_event: 'message', h: (event: { data: unknown }) => void) => {
+ const on = vi.fn<UtilityParentPort['on']>((_event, h) => {
handler = h;
});
return {
on,
- postMessage: vi.fn(() => {}),
+ postMessage: vi.fn<UtilityParentPort['postMessage']>(() => {}),
fire: (msg: unknown) => handler?.({ data: msg }),
};
}
interface MockEnv {
parentPort: MockParentPort;
- exit: ReturnType<typeof vi.fn>;
- killProbe: ReturnType<typeof vi.fn>;
+ exit: Mock<SetupUtilityDeps['exit']>;
+ killProbe: Mock<SetupUtilityDeps['killProbe']>;
signalHandlers: Map<string, () => void>;
intervals: Array<{ cb: () => void; ms: number }>;
- intervalCancel: ReturnType<typeof vi.fn>;
+ intervalCancel: Mock<() => void>;
}
function buildEnv(): MockEnv {
@@ -1046,3 +1051,356 @@ describe('handleInit defaultPrepareBootEnvironment (integration)', () => {
rmSync(tmpRoot, { recursive: true, force: true });
});
});
+
+const PLANNED_UTILITY_INIT_PHASES = [
+ 'init-received',
+ 'imports-resolved',
+ 'project-git-ensured',
+ 'boot-server-started',
+];
+
+const PHASES_WITHOUT_ENSURING_GIT = PLANNED_UTILITY_INIT_PHASES.filter(
+ (phase) => phase !== 'project-git-ensured',
+);
+
+function postedToMain(env: MockEnv): UtilityOutgoingMessage[] {
+ return env.parentPort.postMessage.mock.calls.map(([message]) => message);
+}
+
+function initPhasesPostedToMain(env: MockEnv): unknown[] {
+ return postedToMain(env)
+ .filter((message) => message.type === 'init-phase')
+ .map((message) => message.phase);
+}
+
+function countersAtRead(read: number): {
+ uptimeMs: number;
+ cpuUserMs: number;
+ cpuSystemMs: number;
+} {
+ return { uptimeMs: read * 3, cpuUserMs: read * 2, cpuSystemMs: read };
+}
+
+function isUsableCounter(counter: unknown): boolean {
+ return typeof counter === 'number' && Number.isFinite(counter) && counter >= 0;
+}
+
+describe('setupUtility narrates its startup phases to main before it reports ready', () => {
+ let env: MockEnv;
+
+ beforeEach(() => {
+ env = buildEnv();
+ });
+
+ test('marks receiving init, resolving its imports and starting the server, each with the counters read at that mark, then posts ready', async () => {
+ const phasesPostedBefore: Record<string, unknown[]> = {};
+ let counterReads = 0;
+ const fakeBooted = {
+ port: 51234,
+ destroy: vi.fn(() => Promise.resolve()),
+ degraded: [] as readonly string[],
+ };
+ const bootServer = vi.fn(() => {
+ phasesPostedBefore.bootServer = initPhasesPostedToMain(env);
+ return Promise.resolve(fakeBooted);
+ });
+ const plannedDeps = {
+ readInitCounters: () => {
+ counterReads += 1;
+ return countersAtRead(counterReads);
+ },
+ };
+
+ const handle = setupUtility({
+ parentPort: env.parentPort,
+ importServer: () => {
+ phasesPostedBefore.importServer = initPhasesPostedToMain(env);
+ return Promise.resolve({
+ bootServer,
+ } as unknown as typeof import('@inkeep/open-knowledge-server'));
+ },
+ exit: env.exit,
+ parentPid: 99999,
+ killProbe: env.killProbe,
+ onSignal: (sig, h) => env.signalHandlers.set(sig, h),
+ setInterval: (cb, ms) => {
+ env.intervals.push({ cb, ms });
+ return { unref: vi.fn(() => {}), clear: env.intervalCancel };
+ },
+ prepareBootEnvironment: () => {
+ phasesPostedBefore.prepare = initPhasesPostedToMain(env);
+ return Promise.resolve(makeFakePrepared());
+ },
+ ...plannedDeps,
+ });
+
+ env.parentPort.fire({
+ type: 'init',
+ opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
+ });
+ await handle.readyPromise;
+
+ expect(postedToMain(env)).toEqual([
+ ...PHASES_WITHOUT_ENSURING_GIT.map((phase, index) => ({
+ type: 'init-phase',
+ phase,
+ ...countersAtRead(index + 1),
+ })),
+ { type: 'ready', port: 51234, apiOrigin: 'http://localhost:51234' },
+ ]);
+ expect(phasesPostedBefore).toEqual({
+ importServer: PHASES_WITHOUT_ENSURING_GIT.slice(0, 1),
+ prepare: PHASES_WITHOUT_ENSURING_GIT.slice(0, 2),
+ bootServer: PHASES_WITHOUT_ENSURING_GIT,
+ });
+ });
+
+ test.each([
+ { didEnsureGit: false, markedPhases: PLANNED_UTILITY_INIT_PHASES },
+ { didEnsureGit: true, markedPhases: PHASES_WITHOUT_ENSURING_GIT },
+ ])(
+ 'marks ensuring the project git only when it ensured it itself (didEnsureGit=$didEnsureGit), with counters it read itself',
+ async ({ didEnsureGit, markedPhases }) => {
+ expect(UTILITY_INIT_PHASES).toEqual(PLANNED_UTILITY_INIT_PHASES);
+ const tmpRoot = mkdtempSync(resolve(tmpdir(), 'ok-utility-phase-marks-'));
+ if (didEnsureGit) {
+ mkdirSync(resolve(tmpRoot, '.git'), { recursive: true });
+ writeFileSync(resolve(tmpRoot, '.git/HEAD'), 'ref: refs/heads/main\n', 'utf-8');
+ }
+ try {
+ const fakeBooted = {
+ port: 4242,
+ destroy: vi.fn(() => Promise.resolve()),
+ degraded: [] as readonly string[],
+ };
+ const bootServer = vi.fn(() => Promise.resolve(fakeBooted));
+ const handle = setupUtility({
+ parentPort: env.parentPort,
+ importServer: () =>
+ Promise.resolve({
+ bootServer,
+ } as unknown as typeof import('@inkeep/open-knowledge-server')),
+ exit: env.exit,
+ parentPid: 99999,
+ killProbe: env.killProbe,
+ onSignal: (sig, h) => env.signalHandlers.set(sig, h),
+ setInterval: (cb, ms) => {
+ env.intervals.push({ cb, ms });
+ return { unref: vi.fn(() => {}), clear: env.intervalCancel };
+ },
+ });
+
+ env.parentPort.fire({
+ type: 'init',
+ opts: {
+ contentDir: tmpRoot,
+ projectDir: tmpRoot,
+ port: 0,
+ host: 'localhost',
+ didEnsureGit,
+ },
+ });
+ await handle.readyPromise;
+
+ const posted = postedToMain(env);
+ const marks = posted.filter((message) => message.type === 'init-phase');
+ expect(marks.map((mark) => mark.phase)).toEqual(markedPhases);
+ expect(
+ marks
+ .flatMap((mark) => [mark.uptimeMs, mark.cpuUserMs, mark.cpuSystemMs])
+ .filter((counter) => !isUsableCounter(counter)),
+ ).toEqual([]);
+ expect(posted.findIndex((message) => message.type === 'ready')).toBeGreaterThan(
+ posted.findLastIndex((message) => message.type === 'init-phase'),
+ );
+ } finally {
+ rmSync(tmpRoot, { recursive: true, force: true });
+ }
+ },
+ );
+
+ test('reports a failed start as an error after the phase marks it reached', async () => {
+ const handle = setupUtility({
+ parentPort: env.parentPort,
+ importServer: vi.fn(() => Promise.reject(new Error('boot failed'))),
+ exit: env.exit,
+ parentPid: 99999,
+ killProbe: env.killProbe,
+ onSignal: (sig, h) => env.signalHandlers.set(sig, h),
+ setInterval: (cb, ms) => {
+ env.intervals.push({ cb, ms });
+ return { unref: vi.fn(() => {}), clear: env.intervalCancel };
+ },
+ });
+
+ env.parentPort.fire({
+ type: 'init',
+ opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
+ });
+
+ await expect(handle.readyPromise).rejects.toThrow('boot failed');
+ expect(
+ postedToMain(env).map((message) =>
+ message.type === 'init-phase' ? message.phase : message.type,
+ ),
+ ).toEqual([...PHASES_WITHOUT_ENSURING_GIT.slice(0, 1), 'error']);
+ expect(env.exit).toHaveBeenCalledWith(1);
+ });
+
+ test('reads its default phase counters in milliseconds of its own uptime and CPU clocks', async () => {
+ const tmpRoot = mkdtempSync(resolve(tmpdir(), 'ok-utility-phase-counters-'));
+ mkdirSync(resolve(tmpRoot, '.git'), { recursive: true });
+ writeFileSync(resolve(tmpRoot, '.git/HEAD'), 'ref: refs/heads/main\n', 'utf-8');
+ try {
+ const fakeBooted = {
+ port: 4243,
+ destroy: vi.fn(() => Promise.resolve()),
+ degraded: [] as readonly string[],
+ };
+ const handle = setupUtility({
+ parentPort: env.parentPort,
+ importServer: () =>
+ Promise.resolve({
+ bootServer: vi.fn(() => Promise.resolve(fakeBooted)),
+ } as unknown as typeof import('@inkeep/open-knowledge-server')),
+ exit: env.exit,
+ parentPid: 99999,
+ killProbe: env.killProbe,
+ onSignal: (sig, h) => env.signalHandlers.set(sig, h),
+ setInterval: (cb, ms) => {
+ env.intervals.push({ cb, ms });
+ return { unref: vi.fn(() => {}), clear: env.intervalCancel };
+ },
+ });
+
+ const beforeInit = ownClocksInMs(Math.floor);
+ env.parentPort.fire({
+ type: 'init',
+ opts: {
+ contentDir: tmpRoot,
+ projectDir: tmpRoot,
+ port: 0,
+ host: 'localhost',
+ didEnsureGit: true,
+ },
+ });
+ await handle.readyPromise;
+ const afterReady = ownClocksInMs(Math.ceil);
+
+ const marks = postedToMain(env).filter((message) => message.type === 'init-phase');
+ expect(marks.map((mark) => mark.phase)).toEqual(PHASES_WITHOUT_ENSURING_GIT);
+ expect(
+ marks.flatMap((mark) =>
+ OWN_CLOCK_COUNTERS.filter((counter) => {
+ const value = mark[counter];
+ return !(
+ typeof value === 'number' &&
+ value >= beforeInit[counter] &&
+ value <= afterReady[counter]
+ );
+ }).map((counter) => ({
+ phase: mark.phase,
+ counter,
+ value: mark[counter],
+ from: beforeInit[counter],
+ to: afterReady[counter],
+ })),
+ ),
+ ).toEqual([]);
+ } finally {
+ rmSync(tmpRoot, { recursive: true, force: true });
+ }
+ });
+});
+
+const OWN_CLOCK_COUNTERS = ['uptimeMs', 'cpuUserMs', 'cpuSystemMs'] as const;
+
+function ownClocksInMs(
+ round: (ms: number) => number,
+): Record<(typeof OWN_CLOCK_COUNTERS)[number], number> {
+ const cpu = process.cpuUsage();
+ return {
+ uptimeMs: round(process.uptime() * 1000),
+ cpuUserMs: round(cpu.user / 1000),
+ cpuSystemMs: round(cpu.system / 1000),
+ };
+}
+
+function startUtilityWhoseBootPreparationWaits(env: MockEnv): {
+ bootServer: Mock<
+ () => Promise<{ port: number; destroy: () => Promise<void>; degraded: readonly string[] }>
+ >;
+ reachedBootPreparation: Promise<void>;
+ finishBootPreparation: () => void;
+} {
+ let enterBootPreparation!: () => void;
+ let finishBootPreparation!: () => void;
+ const entered = new Promise<void>((resolve) => {
+ enterBootPreparation = resolve;
+ });
+ const finished = new Promise<void>((resolve) => {
+ finishBootPreparation = resolve;
+ });
+ const bootServer = vi.fn(() =>
+ Promise.resolve({
+ port: 51289,
+ destroy: () => Promise.resolve(),
+ degraded: [] as readonly string[],
+ }),
+ );
+ const handle = setupUtility({
+ parentPort: env.parentPort,
+ importServer: () =>
+ Promise.resolve({
+ bootServer,
+ } as unknown as typeof import('@inkeep/open-knowledge-server')),
+ exit: env.exit,
+ parentPid: 99999,
+ killProbe: env.killProbe,
+ onSignal: (sig, h) => env.signalHandlers.set(sig, h),
+ setInterval: (cb, ms) => {
+ env.intervals.push({ cb, ms });
+ return { unref: vi.fn(() => {}), clear: env.intervalCancel };
+ },
+ prepareBootEnvironment: async () => {
+ enterBootPreparation();
+ await finished;
+ return makeFakePrepared();
+ },
+ });
+
+ env.parentPort.fire({
+ type: 'init',
+ opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
+ });
+ return {
+ bootServer,
+ reachedBootPreparation: Promise.race([entered, handle.readyPromise.then(() => {})]),
+ finishBootPreparation,
+ };
+}
+
+async function finishBootPreparationAndLetInitContinue(finish: () => void): Promise<void> {
+ finish();
+ await new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+describe('setupUtility honours a shutdown that arrives before its init reaches bootServer', () => {
+ test('exits 0 without calling bootServer when shutdown arrives while its init is still preparing the boot environment', async () => {
+ const withoutShutdown = startUtilityWhoseBootPreparationWaits(buildEnv());
+ await withoutShutdown.reachedBootPreparation;
+ await finishBootPreparationAndLetInitContinue(withoutShutdown.finishBootPreparation);
+ expect(withoutShutdown.bootServer).toHaveBeenCalledTimes(1);
+
+ const env = buildEnv();
+ const utility = startUtilityWhoseBootPreparationWaits(env);
+ await utility.reachedBootPreparation;
+ expect(utility.bootServer).not.toHaveBeenCalled();
+
+ env.parentPort.fire({ type: 'shutdown' });
+ await finishBootPreparationAndLetInitContinue(utility.finishBootPreparation);
+
+ expect(utility.bootServer).not.toHaveBeenCalled();
+ expect(env.exit.mock.calls).toEqual([[0]]);
+ });
+});