Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): make the readiness cap own the wait, not just the gaps (#4188)

Nick Gomez3531dc274c9a
diff --git a/packages/desktop/tests/smoke/_helpers/launch-readiness.test.ts b/packages/desktop/tests/smoke/_helpers/launch-readiness.test.ts
index 601bde8ed..d33ad9800 100644
--- a/packages/desktop/tests/smoke/_helpers/launch-readiness.test.ts
+++ b/packages/desktop/tests/smoke/_helpers/launch-readiness.test.ts
@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
@@ -748,8 +749,14 @@ describe('the recorded ready wait names which wait it measured', () => {
markLine('appReady', 0, '2026-09-04T00:00:01.000Z'),
]),
);
- await expect(waitForWindowByMode(app, 'editor', { capMs: 300, pollMs: 60 })).rejects.toThrow();
+ const error = await waitForWindowByMode(app, 'editor', { capMs: 300, pollMs: 60 }).catch(
+ (e: unknown) => e,
+ );
+ expect(error).toBeInstanceOf(Error);
expect(tryFirstWaitFor(app)?.reason).toBe('cap');
+ const message = (error as Error).message;
+ expect(message).toContain('though the app kept logging boot activity');
+ expect(message).not.toContain('The last probe had not answered');
});
});
@@ -988,3 +995,292 @@ describe('formatBootGapLine', () => {
}
});
});
+
+describe('the cap bounds the wait itself, not only the gaps between polls', () => {
+ const RELEASE_AFTER_MS = 5_000;
+
+ function heldProbe<T>() {
+ const gate = Promise.withResolvers<T | undefined>();
+ let calls = 0;
+ return {
+ probe: async () => {
+ calls += 1;
+ return gate.promise;
+ },
+ hit: (value: T) => gate.resolve(value),
+ miss: () => gate.resolve(undefined),
+ calls: () => calls,
+ };
+ }
+
+ function timerDeadline(ms: number) {
+ const reached = Promise.withResolvers<void>();
+ const timer = setTimeout(reached.resolve, ms);
+ return { expired: reached.promise, cancel: () => clearTimeout(timer) };
+ }
+
+ function narratingHome(): string {
+ return seedHome([
+ JSON.stringify({ time: '2026-09-04T00:00:00.000Z', event: DESKTOP_BOOT_EVENT }),
+ markLine('appReady', 0, '2026-09-04T00:00:01.000Z'),
+ markLine('serverSpawned', 500, '2026-09-04T00:00:01.500Z'),
+ ]);
+ }
+
+ it('gives up at the cap while the probe is still pending', async () => {
+ const gate = heldProbe<string>();
+ let released = false;
+ const release = setTimeout(() => {
+ released = true;
+ gate.miss();
+ }, RELEASE_AFTER_MS);
+ const error = await waitForReadySignal<string>({
+ probe: gate.probe,
+ home: narratingHome(),
+ what: 'editor window',
+ capMs: 80,
+ stallMs: 600_000,
+ pollMs: 10,
+ }).catch((e: unknown) => e);
+ clearTimeout(release);
+ gate.miss();
+ expect(released).toBe(false);
+ expect(error).toBeInstanceOf(Error);
+ expect((error as Error).message).toMatch(/did not arrive within \d+ms\./);
+ expect((error as Error).message).not.toContain('though the app kept logging boot activity');
+ expect((error as Error).message).toContain(
+ 'The last probe had not answered when the cap fired.',
+ );
+ expect(gate.calls()).toBe(1);
+ });
+
+ it('discards a hit that arrives after the cap instead of reporting it as success', async () => {
+ const gate = heldProbe<string>();
+ let released = false;
+ const release = setTimeout(() => {
+ released = true;
+ gate.hit('late-editor-page');
+ }, RELEASE_AFTER_MS);
+ const outcome = await waitForReadySignal<string>({
+ probe: gate.probe,
+ home: narratingHome(),
+ what: 'editor window',
+ capMs: 80,
+ stallMs: 600_000,
+ pollMs: 10,
+ }).then(
+ (value) => ({ resolvedWith: value }),
+ (error: unknown) => ({ rejectedWith: (error as Error).message }),
+ );
+ clearTimeout(release);
+ gate.hit('late-editor-page');
+ expect(released).toBe(false);
+ expect(outcome).not.toHaveProperty('resolvedWith');
+ expect(outcome).toMatchObject({ rejectedWith: expect.stringMatching(/did not arrive/) });
+ });
+
+ it('swallows a probe rejection that arrives after the cap, so no worker dies of it', () => {
+ const script = join(mkdtempSync(join(tmpdir(), 'ok-readiness-strict-')), 'late-rejection.mjs');
+ writeFileSync(
+ script,
+ [
+ 'const { waitForReadySignal } = await import(process.argv[2]);',
+ 'let fail = (error) => { throw error; };',
+ 'const gate = new Promise((_resolve, reject) => { fail = reject; });',
+ "setTimeout(() => fail(new Error('renderer detached after the cap')), 250);",
+ 'const error = await waitForReadySignal({',
+ ' probe: async () => gate,',
+ ' home: process.argv[3],',
+ " what: 'editor window',",
+ ' capMs: 60,',
+ ' stallMs: 600_000,',
+ ' pollMs: 10,',
+ '}).catch((e) => e);',
+ "if (!(error instanceof Error)) { console.error('the wait did not give up'); process.exit(2); }",
+ 'await new Promise((r) => setTimeout(r, 600));',
+ "console.log('survived');",
+ ].join('\n'),
+ 'utf8',
+ );
+ const run = spawnSync(
+ process.execPath,
+ [
+ '--unhandled-rejections=strict',
+ script,
+ new URL('./launch-readiness.ts', import.meta.url).href,
+ narratingHome(),
+ ],
+ { encoding: 'utf8', timeout: 20_000 },
+ );
+ expect({
+ status: run.status,
+ stdout: run.stdout.trim(),
+ stderr: run.stderr.trim(),
+ }).toEqual({ status: 0, stdout: 'survived', stderr: '' });
+ });
+
+ it('records a give-up when the first window never answers, instead of no record at all', async () => {
+ let releaseStuck: () => void = () => {};
+ const stuck = {
+ evaluate: () =>
+ new Promise<string | undefined>((resolve) => {
+ releaseStuck = () => resolve('navigator');
+ }),
+ };
+ const ready = { evaluate: async () => 'editor' };
+ const app = { windows: () => [stuck, ready] };
+ rememberLaunchHome(app, narratingHome());
+ let released = false;
+ const release = setTimeout(() => {
+ released = true;
+ releaseStuck();
+ }, RELEASE_AFTER_MS);
+ const outcome = await waitForWindowByMode(app, 'editor', {
+ capMs: 80,
+ stallMs: 600_000,
+ pollMs: 10,
+ }).then(
+ (page) => ({ resolvedWith: page === ready ? 'ready-page' : 'stuck-page' }),
+ (error: unknown) => ({ rejectedWith: (error as Error).message }),
+ );
+ clearTimeout(release);
+ releaseStuck();
+ expect(released).toBe(false);
+ expect(outcome).not.toHaveProperty('resolvedWith');
+ expect(outcome).toMatchObject({ rejectedWith: expect.stringMatching(/did not arrive/) });
+ expect(tryFirstWaitFor(app)).toMatchObject({ gaveUp: true, reason: 'cap', capMs: 80 });
+ });
+
+ it('lets the deadline end the wait even when the caller supplies a clock of its own', async () => {
+ const gate = heldProbe<string>();
+ let reachDeadline: () => void = () => {};
+ const outcome = waitForReadySignal<string>({
+ probe: gate.probe,
+ home: '/unused',
+ what: 'editor window',
+ capMs: 600_000,
+ stallMs: 600_000,
+ pollMs: 1,
+ now: () => 0,
+ readLog: () => snapshot({ lineCount: 3, lastEvent: 'desktop.startup.serverSpawned' }),
+ startDeadline: () => ({
+ expired: new Promise<void>((resolve) => {
+ reachDeadline = resolve;
+ }),
+ cancel: () => {},
+ }),
+ }).then(
+ (value) => ({ resolvedWith: value }),
+ (error: unknown) => ({ rejectedWith: (error as Error).message }),
+ );
+ await Promise.resolve();
+ reachDeadline();
+ let watchdog: ReturnType<typeof setTimeout> | undefined;
+ const settledOrStillWaiting = await Promise.race([
+ outcome,
+ new Promise<{ stillWaiting: true }>((resolve) => {
+ watchdog = setTimeout(() => resolve({ stillWaiting: true }), 2_000);
+ }),
+ ]);
+ clearTimeout(watchdog);
+ gate.hit('editor-page');
+ expect(settledOrStillWaiting).toMatchObject({
+ rejectedWith: expect.stringMatching(/did not arrive within 0ms/),
+ });
+ });
+
+ it('arms one deadline for the whole wait, not a fresh one per poll', async () => {
+ const gate = heldProbe<string>();
+ let polls = 0;
+ let armings = 0;
+ let released = false;
+ const release = setTimeout(() => {
+ released = true;
+ gate.miss();
+ }, RELEASE_AFTER_MS);
+ const error = await waitForReadySignal<string>({
+ probe: async () => (polls++ < 3 ? undefined : gate.probe()),
+ home: narratingHome(),
+ what: 'editor window',
+ capMs: 400,
+ stallMs: 600_000,
+ pollMs: 5,
+ startDeadline: (ms) => {
+ armings += 1;
+ return timerDeadline(ms);
+ },
+ }).catch((e: unknown) => e);
+ clearTimeout(release);
+ gate.miss();
+ expect({ released, armings }).toEqual({ released: false, armings: 1 });
+ expect(polls).toBeGreaterThan(1);
+ expect((error as Error).message).toContain(
+ 'The last probe had not answered when the cap fired.',
+ );
+ });
+
+ it('reports a stall over a latched lap without claiming the probe was outstanding', async () => {
+ let clock = 0;
+ let sleeps = 0;
+ let probes = 0;
+ let reachDeadline: () => void = () => {};
+ const error = await waitForReadySignal<string>({
+ probe: async () => {
+ probes += 1;
+ throw new Error('Execution context was destroyed');
+ },
+ home: '/unused',
+ what: 'editor window',
+ capMs: 600_000,
+ stallMs: 150,
+ liveness: 'boot',
+ pollMs: 1,
+ now: () => clock,
+ sleep: () =>
+ new Promise((resolve) => {
+ sleeps += 1;
+ clock += 200;
+ if (sleeps === 1) reachDeadline();
+ setTimeout(resolve, 0);
+ }),
+ readLog: () => snapshot({ lineCount: 3, lastEvent: 'desktop.startup.serverSpawned' }),
+ startDeadline: () => ({
+ expired: new Promise<void>((resolve) => {
+ reachDeadline = resolve;
+ }),
+ cancel: () => {},
+ }),
+ }).catch((e: unknown) => e);
+ const message = (error as Error).message;
+ expect(probes).toBe(1);
+ expect(message).toContain('Probe threw on 1 of 1 polls');
+ expect(message).toContain('logged no new boot activity for 150ms (gave up after 200ms)');
+ expect(message).not.toContain('The last probe had not answered');
+ });
+
+ it('discloses the pending probe even when a later-poll hang trips the stall clock first', async () => {
+ const gate = heldProbe<string>();
+ let polls = 0;
+ let released = false;
+ const release = setTimeout(() => {
+ released = true;
+ gate.miss();
+ }, RELEASE_AFTER_MS);
+ const error = await waitForReadySignal<string>({
+ probe: async () => (polls++ < 2 ? undefined : gate.probe()),
+ home: '/unused',
+ what: 'editor window',
+ capMs: 400,
+ stallMs: 120,
+ liveness: 'boot',
+ pollMs: 5,
+ readLog: () => snapshot({ lineCount: 3, lastEvent: 'desktop.startup.serverSpawned' }),
+ }).catch((e: unknown) => e);
+ clearTimeout(release);
+ gate.miss();
+ const message = (error as Error).message;
+ expect(released).toBe(false);
+ expect(message).toMatch(/logged no new boot activity/);
+ expect(message).toContain('The last probe had not answered when the cap fired.');
+ });
+});
diff --git a/packages/desktop/tests/smoke/_helpers/launch-readiness.ts b/packages/desktop/tests/smoke/_helpers/launch-readiness.ts
index 51fe03ac2..523f8c6a1 100644
--- a/packages/desktop/tests/smoke/_helpers/launch-readiness.ts
+++ b/packages/desktop/tests/smoke/_helpers/launch-readiness.ts
@@ -297,6 +297,12 @@ export interface ReadySignalOptions<T> {
now?: () => number;
sleep?: (ms: number) => Promise<void>;
readLog?: (home: string) => BootLogSnapshot;
+ startDeadline?: (ms: number) => ReadyDeadline;
+}
+
+export interface ReadyDeadline {
+ readonly expired: Promise<void>;
+ cancel(): void;
}
export interface ProbeErrorSummary {
@@ -346,6 +352,7 @@ function describeFailure(
stallMs: number,
snapshot: BootLogSnapshot,
probeError: ProbeErrorSummary | undefined,
+ probePending: boolean,
): string {
const phase = snapshot.lastEvent ?? '(no boot event recorded)';
const state = classifyBootLog(snapshot);
@@ -357,7 +364,9 @@ function describeFailure(
`(gave up after ${elapsedMs}ms). Main narrates every ${BOOT_LOG_HEARTBEAT_MS}ms from ` +
'process start until the first window is shown, so this silence after phase ' +
`${phase} means the app stopped making progress.`
- : `${what} did not arrive within ${elapsedMs}ms, though the app kept logging boot activity.`;
+ : probePending
+ ? `${what} did not arrive within ${elapsedMs}ms.`
+ : `${what} did not arrive within ${elapsedMs}ms, though the app kept logging boot activity.`;
const lines = [head, `Last main-process boot event: ${phase}`, describeBootLog(snapshot)];
lines.push(
probeError === undefined
@@ -365,6 +374,7 @@ function describeFailure(
: `Probe threw on ${probeError.threwPolls} of ${probeError.totalPolls} polls; ` +
`last: ${probeError.last}`,
);
+ if (probePending) lines.push('The last probe had not answered when the cap fired.');
if (snapshot.tail.length > 0) lines.push('', 'Boot log tail:', snapshot.tail);
return lines.join('\n');
}
@@ -393,6 +403,14 @@ export function giveUpReason(
}
}
+const DEADLINE_PASSED = Symbol('ready-signal-deadline-passed');
+
+function startTimerDeadline(ms: number): ReadyDeadline {
+ const reached = Promise.withResolvers<void>();
+ const timer = setTimeout(reached.resolve, ms);
+ return { expired: reached.promise, cancel: () => clearTimeout(timer) };
+}
+
export async function waitForReadySignal<T>(options: ReadySignalOptions<T>): Promise<T> {
const stallMs = options.stallMs ?? BOOT_LOG_STALL_MS;
const capMs = options.capMs ?? BOOT_LOG_CAP_MS;
@@ -400,6 +418,7 @@ export async function waitForReadySignal<T>(options: ReadySignalOptions<T>): Pro
const now = options.now ?? (() => Date.now());
const sleep = options.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
const readLog = options.readLog ?? readBootLog;
+ const startDeadline = options.startDeadline ?? startTimerDeadline;
const startedAt = now();
let lastProgressAt = startedAt;
@@ -410,42 +429,76 @@ export async function waitForReadySignal<T>(options: ReadySignalOptions<T>): Pro
let threwPolls = 0;
let totalPolls = 0;
- for (;;) {
- totalPolls += 1;
- try {
- const hit = await options.probe();
- if (hit !== undefined) return hit;
- } catch (error) {
- lastProbeError = error instanceof Error ? error.message : String(error);
- threwPolls += 1;
- }
+ let capElapsed = false;
+ const deadline = startDeadline(capMs);
+ const capReached = deadline.expired.then((): typeof DEADLINE_PASSED => {
+ capElapsed = true;
+ return DEADLINE_PASSED;
+ });
+ let probePendingAtGiveUp = false;
- snapshot = readLog(options.home);
- if (snapshot.lineCount > cursor) {
- cursor = snapshot.lineCount;
- lastProgressAt = now();
- }
+ try {
+ for (;;) {
+ if (!capElapsed) {
+ totalPolls += 1;
+ try {
+ const settled = await Promise.race([
+ options.probe().then((hit) => ({ hit })),
+ capReached,
+ ]);
+ if (settled === DEADLINE_PASSED) probePendingAtGiveUp = true;
+ else if (settled.hit !== undefined) return settled.hit;
+ } catch (error) {
+ lastProbeError = error instanceof Error ? error.message : String(error);
+ threwPolls += 1;
+ }
+ }
- const probeError: ProbeErrorSummary | undefined =
- lastProbeError === undefined ? undefined : { last: lastProbeError, threwPolls, totalPolls };
- const elapsed = now() - startedAt;
- const stallArmed =
- explicitLiveness !== undefined
- ? explicitLiveness === 'boot'
- : !hasBootCompleted(snapshot.lines);
- if (stallArmed && now() - lastProgressAt >= stallMs) {
- throw new ReadySignalGiveUp(
- describeFailure('stalled', options.what, elapsed, stallMs, snapshot, probeError),
- giveUpReason('stall', snapshot),
- );
- }
- if (elapsed >= capMs) {
- throw new ReadySignalGiveUp(
- describeFailure('cap', options.what, elapsed, stallMs, snapshot, probeError),
- giveUpReason('cap', snapshot),
- );
+ snapshot = readLog(options.home);
+ if (snapshot.lineCount > cursor) {
+ cursor = snapshot.lineCount;
+ lastProgressAt = now();
+ }
+
+ const probeError: ProbeErrorSummary | undefined =
+ lastProbeError === undefined ? undefined : { last: lastProbeError, threwPolls, totalPolls };
+ const elapsed = now() - startedAt;
+ const stallArmed =
+ explicitLiveness !== undefined
+ ? explicitLiveness === 'boot'
+ : !hasBootCompleted(snapshot.lines);
+ if (stallArmed && now() - lastProgressAt >= stallMs) {
+ throw new ReadySignalGiveUp(
+ describeFailure(
+ 'stalled',
+ options.what,
+ elapsed,
+ stallMs,
+ snapshot,
+ probeError,
+ probePendingAtGiveUp,
+ ),
+ giveUpReason('stall', snapshot),
+ );
+ }
+ if (capElapsed || elapsed >= capMs) {
+ throw new ReadySignalGiveUp(
+ describeFailure(
+ 'cap',
+ options.what,
+ elapsed,
+ stallMs,
+ snapshot,
+ probeError,
+ probePendingAtGiveUp,
+ ),
+ giveUpReason('cap', snapshot),
+ );
+ }
+ await sleep(pollMs);
}
- await sleep(pollMs);
+ } finally {
+ deadline.cancel();
}
}