Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 gforkAtMs -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 launcexpect(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.tsindex 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 | unconst { 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>): Prolet 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>): Proif (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>): Proconst 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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]]);+ });+});