Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.tsindex 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.tsindex 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>): Proconst 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>): Prolet 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();}}