Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): stop the desktop spawn gate killing a healthy server (PRD-8168) (#3731)

Andrew Mikofalvy6b41c29b9407
diff --git a/.changeset/spawn-gate-liveness-aware.md b/.changeset/spawn-gate-liveness-aware.md
new file mode 100644
index 000000000..f053d52d8
--- /dev/null
+++ b/.changeset/spawn-gate-liveness-aware.md
@@ -0,0 +1,7 @@
+---
+'@inkeep/open-knowledge': patch
+---
+
+Desktop no longer kills a healthy server that is still starting. The post-spawn wait was a fixed 15 s wall-clock deadline, after which the child was SIGTERM'd even when it was alive and mid-boot — so a project whose boot legitimately took longer than 15 s (large working copies, cold caches, a machine under load) could not be opened at all, and retries reproduced it identically. A child observed alive at the deadline now graduates to a longer bounded wait instead of being killed, and both bounds are overridable via `OK_SPAWN_STARTUP_TIMEOUT_MS` / `OK_SPAWN_BIND_TIMEOUT_MS`.
+
+The failure dialog also stops implying that a slow start was caused by whatever the server printed on the way up. Server output is still shown, but it is labelled as the cause only when the child actually exited; a still-running child's output is framed as probably unrelated. Open failures are now written to the desktop log as well as the dialog.
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index bd9093d28..a218b3aa3 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -1623,6 +1623,19 @@ function ensureDebugIpc(): DebugIpcHandle {
return debugIpc;
}
+/**
+ * Parse an env override that must be a positive whole number of milliseconds.
+ * Anything else — unset, empty, non-numeric, zero, negative, fractional — is
+ * `undefined` so the caller's default applies. A malformed override must not
+ * become a `0` deadline that fails every spawn instantly.
+ */
+function readPositiveIntEnv(raw: string | undefined): number | undefined {
+ if (raw === undefined || raw.trim() === '') return undefined;
+ const parsed = Number(raw);
+ if (!Number.isSafeInteger(parsed) || parsed <= 0) return undefined;
+ return parsed;
+}
+
function ensureWindowManager() {
if (wm) return;
// Renderer entry (prod path): electron-builder copies packages/cli/dist/public/ to
@@ -1968,6 +1981,13 @@ function ensureWindowManager() {
// against the exact value a freshly-spawned server reports.
selfProtocolVersion: PROTOCOL_VERSION,
selfRuntimeVersion: RUNTIME_VERSION,
+ // Field escape hatch for the spawn wait. Boot cost scales with project
+ // state, so a working copy can always be found that outgrows whatever
+ // defaults ship — without these there is no way to get such a project open
+ // short of a new release, and no way to shorten the wait when diagnosing a
+ // genuinely stuck boot.
+ spawnLockPollDeadlineMs: readPositiveIntEnv(process.env.OK_SPAWN_STARTUP_TIMEOUT_MS),
+ spawnLockProgressDeadlineMs: readPositiveIntEnv(process.env.OK_SPAWN_BIND_TIMEOUT_MS),
// Dev-only: auto-reclaim a foreign server on the project's contentDir (a
// leftover from a prior packaged run / CLI / another instance) so this
// `electron-vite dev` session runs against its own working-tree build
@@ -2732,11 +2752,24 @@ async function openProjectOrFallbackToNavigator(
const errorMessage = (err as Error).message;
const kind = (err as Error & { kind?: string }).kind;
const holderPid = (err as Error & { holderPid?: number }).holderPid;
- console.error('[main] openProject failed, falling back to Navigator', {
- projectPath,
- kind,
- err: errorMessage,
- });
+ // Route through pino, not only `console.error`: a failure reported solely
+ // to the native dialog leaves nothing in `~/.ok/logs/desktop.*.log`, so a
+ // user who hits this can send logs that contain their successful opens and
+ // no trace of the one that failed. The dialog is for the user; this line
+ // is what makes the failure diagnosable afterwards.
+ getLogger('project').error(
+ {
+ event: 'desktop-open-project-failed',
+ projectPath,
+ entryPoint,
+ kind,
+ pid: (err as Error & { pid?: number }).pid,
+ exitCode: (err as Error & { exitCode?: number | null }).exitCode,
+ exitSignal: (err as Error & { exitSignal?: string | null }).exitSignal,
+ err: errorMessage,
+ },
+ '[main] openProject failed, falling back to Navigator',
+ );
// Pick a dialog title + body based on the error's structured kind.
// Default ("Unable to open project") matches the existing pre-spec
// path so plain failures (generic boot crashes) continue to read the
diff --git a/packages/desktop/src/main/window-manager.ts b/packages/desktop/src/main/window-manager.ts
index 43caccf8d..9b86bc28d 100644
--- a/packages/desktop/src/main/window-manager.ts
+++ b/packages/desktop/src/main/window-manager.ts
@@ -53,6 +53,25 @@ import { classifyServerVersion } from './version-drift.ts';
*/
const RESTART_SIGTERM_GRACE_MS = 3_000;
+/**
+ * How long a freshly-spawned detached server has to show ANY sign of life
+ * before the parent gives up on it. Reached with the child alive, this is not
+ * a kill deadline — see `spawnLockProgressDeadlineMs`.
+ */
+const DEFAULT_SPAWN_STARTUP_DEADLINE_MS = 15_000;
+
+/**
+ * Multiple of the startup deadline that a still-alive child is allowed to run
+ * to before the wait is abandoned (15 s → 120 s at the shipped default).
+ * Sized to clear the pre-listen boot phase on a large working copy — that
+ * phase grows with project state and has no upper bound in the server today —
+ * while still failing eventually if the process is genuinely wedged.
+ *
+ * Derived from the startup deadline rather than fixed so the two stay in
+ * proportion however the first is configured.
+ */
+const SPAWN_WAIT_EXTENSION_FACTOR = 8;
+
/**
* Local mirror of `isValidLockPid` from `@inkeep/open-knowledge-server`. Same
* import-surface rationale as `isProcessAliveLocal` above.
@@ -615,13 +634,31 @@ export interface WindowManagerDeps {
*/
removeDir?(dir: string): Promise<void>;
/**
- * Upper bound (ms) on waiting for the detached server to publish a valid
- * `server.lock` after spawn. Default 15s — generous margin for the
- * `bootServer` cold-start path (shadow-repo init, file-watcher walk,
- * listen + lock write) while keeping a silently-hung spawn detectable
- * within a debuggable window. Tests pass small values.
+ * Upper bound (ms) on waiting for a detached server that shows no sign of
+ * life. Default 15s. This bounds the "did the spawn get anywhere at all"
+ * question only — a child observed to be ALIVE at this deadline is not
+ * killed, it graduates to `spawnLockProgressDeadlineMs` below.
+ *
+ * `bootServer` does O(project-state) work (shadow-repo import, file-watcher
+ * walk, index hydration) BEFORE `httpServer.listen` resolves, and only then
+ * flips the lock's port off its `0` sentinel. On a large working copy that
+ * phase alone can outlast any fixed wall-clock figure, so treating this
+ * deadline as a kill deadline makes such projects permanently unopenable.
+ * Tests pass small values.
*/
spawnLockPollDeadlineMs?: number;
+ /**
+ * Hard cap (ms) on the extended wait a LIVE child earns once
+ * `spawnLockPollDeadlineMs` elapses. Defaults to
+ * `spawnLockPollDeadlineMs * SPAWN_WAIT_EXTENSION_FACTOR`.
+ *
+ * Liveness is the only progress signal the parent has during the pre-listen
+ * phase — the child emits no events there — so the wait is bounded by this
+ * cap rather than continued indefinitely: a genuinely wedged (but alive)
+ * server still has to surface as a failure eventually. Must be >= the
+ * startup deadline; a smaller value is clamped up to it.
+ */
+ spawnLockProgressDeadlineMs?: number;
/**
* Override for `DEFAULT_SIGTERM_GRACE_MS` (10 s) — how long
* `stopAllOwnedServers` waits for a detached pid's lock to release
@@ -1828,8 +1865,14 @@ export class WindowManager {
reactShellDistDir,
});
this.spawnedDetachedPids.set(canonicalKey, handle.pid);
- const POLL_DEADLINE_MS = this.deps.spawnLockPollDeadlineMs ?? 15_000;
- const lock = await this.pollServerLock(lockDir, POLL_DEADLINE_MS, handle);
+ const POLL_DEADLINE_MS =
+ this.deps.spawnLockPollDeadlineMs ?? DEFAULT_SPAWN_STARTUP_DEADLINE_MS;
+ const { lock, waitedDeadlineMs } = await this.pollServerLock(
+ lockDir,
+ POLL_DEADLINE_MS,
+ handle,
+ this.deps.spawnLockProgressDeadlineMs,
+ );
if (lock === null) {
// Both sampled BEFORE the SIGTERM below — afterwards they would be
// observing our own kill and would report a merely-slow child as
@@ -1871,7 +1914,7 @@ export class WindowManager {
pid: handle.pid,
exit: childExit,
lockDir,
- deadlineMs: POLL_DEADLINE_MS,
+ deadlineMs: waitedDeadlineMs,
spawnLabel: 'spawn',
childExited,
});
@@ -2301,8 +2344,13 @@ export class WindowManager {
throw err;
}
- const POLL_DEADLINE_MS = this.deps.spawnLockPollDeadlineMs ?? 15_000;
- const lock = await this.pollServerLock(lockDir, POLL_DEADLINE_MS, handle);
+ const POLL_DEADLINE_MS = this.deps.spawnLockPollDeadlineMs ?? DEFAULT_SPAWN_STARTUP_DEADLINE_MS;
+ const { lock, waitedDeadlineMs } = await this.pollServerLock(
+ lockDir,
+ POLL_DEADLINE_MS,
+ handle,
+ this.deps.spawnLockProgressDeadlineMs,
+ );
if (lock === null) {
// Both sampled BEFORE the SIGTERM below — see the project-open path.
// This path additionally awaits `removeDir` before throwing, so a
@@ -2335,7 +2383,7 @@ export class WindowManager {
pid: handle.pid,
exit: childExit,
lockDir,
- deadlineMs: POLL_DEADLINE_MS,
+ deadlineMs: waitedDeadlineMs,
spawnLabel: 'ephemeral spawn',
childExited,
});
@@ -2581,8 +2629,20 @@ export class WindowManager {
messageBase = `OpenKnowledge server did not bind a port within ${deadlineMs}ms after ${spawnLabel} (pid=${pid}${liveness}).`;
}
+ // Whether the child's output explains the failure depends entirely on
+ // whether it DIED. A child that exited is very likely explaining itself on
+ // the way out, so its stderr reads as the cause and is labelled as such. A
+ // child that is still running has explained nothing — whatever is in the
+ // log is just what the server happened to print during a normal boot
+ // (config advisories, deprecation notices), and juxtaposing it with a
+ // failure header invites the reader to fix a warning that was never the
+ // problem. Say so rather than filtering: a filter would also swallow the
+ // one advisory that did matter.
+ const stderrHeading = exited
+ ? '--- stderr ---'
+ : '--- server output (printed during startup; probably not the cause) ---';
return Object.assign(
- new Error(stderrTail ? `${messageBase}\n--- stderr ---\n${stderrTail}` : messageBase),
+ new Error(stderrTail ? `${messageBase}\n${stderrHeading}\n${stderrTail}` : messageBase),
{
name: 'SpawnLockTimeoutError' as const,
// Discriminant held stable across both framings — `index.ts` branches
@@ -2597,18 +2657,31 @@ export class WindowManager {
/**
* Poll `<lockDir>/server.lock` until a valid lock appears with `port > 0`
- * and a known `kind`, or until `deadlineMs` elapses — or, when `child` is
- * supplied, until that child is observed to have exited (a dead child will
- * never publish a lock, so the rest of the deadline is dead time). Used by
- * the detached-spawn path to wait for the freshly-spawned CLI to bind a port
- * and write its lock atomically (the lock writer in `bootServer` only flips
- * port from `0` to the bound port after `httpServer.listen` resolves, so
- * seeing `port > 0` is the readiness signal).
+ * and a known `kind`. Used by the detached-spawn path to wait for the
+ * freshly-spawned CLI to bind a port and write its lock atomically (the lock
+ * writer in `bootServer` only flips port from `0` to the bound port after
+ * `httpServer.listen` resolves, so seeing `port > 0` is the readiness
+ * signal).
+ *
+ * The wait is TWO-TIER. `deadlineMs` bounds only a spawn showing no sign of
+ * life; when it lands with someone still visibly working on this lock — our
+ * `child`, or the live holder of a non-draining lock in the collision case —
+ * the wait graduates ONCE to `progressDeadlineMs` (default
+ * `deadlineMs * SPAWN_WAIT_EXTENSION_FACTOR`) rather than giving up. The
+ * pre-`listen` boot phase scales with project state and emits no events, so
+ * liveness is the only progress signal available; the cap is what keeps a
+ * genuinely wedged process from waiting forever.
+ *
+ * The wait still ends early once the spawn is observed to have exited with
+ * nobody else starting (a dead child will never publish a lock, so the rest
+ * of the deadline is dead time).
*
- * Returns the parsed lock metadata on success, or `null` on timeout or child
- * death. When `readServerLock` is not wired in `deps` (back-compat with
- * tests that don't exercise the detached path), returns `null` immediately —
- * the caller propagates that as a spawn-failure error.
+ * Always resolves to an object. `lock` is the parsed metadata on success and
+ * `null` on timeout or child death; `waitedDeadlineMs` is the deadline
+ * actually served, which the caller reports rather than the tier it
+ * graduated from. When `readServerLock` is not wired in `deps` (back-compat
+ * with tests that don't exercise the detached path), resolves immediately
+ * with a `null` lock — the caller propagates that as a spawn-failure error.
*
* Polling cadence: 50 ms. Uses `deps.setTimeout` so test injections that
* fire the timer synchronously make the loop deterministic.
@@ -2617,19 +2690,33 @@ export class WindowManager {
lockDir: string,
deadlineMs: number,
child?: { pid: number },
- ): Promise<ServerLockMetadataLike | null> {
+ progressDeadlineMs?: number,
+ ): Promise<{ lock: ServerLockMetadataLike | null; waitedDeadlineMs: number }> {
const POLL_INTERVAL_MS = 50;
const reader = this.deps.readServerLock;
- if (!reader) return null;
+ if (!reader) return { lock: null, waitedDeadlineMs: deadlineMs };
const isAlive = this.deps.isProcessAlive;
- const deadline = Date.now() + deadlineMs;
- while (Date.now() < deadline) {
+ const started = Date.now();
+ // A cap below the startup deadline would shorten the wait rather than
+ // extend it, inverting the whole point of the second tier.
+ const hardCapMs = Math.max(
+ deadlineMs,
+ progressDeadlineMs ?? deadlineMs * SPAWN_WAIT_EXTENSION_FACTOR,
+ );
+ let effectiveDeadlineMs = deadlineMs;
+ let deadline = started + deadlineMs;
+ let extended = false;
+ // Deliberately not `while (Date.now() < deadline)`: the graduation check
+ // has to run ON the deadline, and a loop that exits at the top can have
+ // its final poll interval straddle it — the child would then be killed
+ // without ever being asked whether it was still alive.
+ for (;;) {
const lock = reader(lockDir);
// A draining lock is the PREDECESSOR still exiting, not the fresh
// spawn's readiness signal — keep polling until the successor's
// (non-draining) lock appears.
if (lock !== null && lock.draining !== true && lock.port > 0 && lock.kind !== undefined) {
- return lock;
+ return { lock, waitedDeadlineMs: effectiveDeadlineMs };
}
// Liveness, not wall-clock, ends the wait once the child is gone: a dead
// child will never publish a lock, so the rest of the deadline is dead
@@ -2648,7 +2735,48 @@ export class WindowManager {
if (child !== undefined && isAlive !== undefined && !isAlive(child.pid)) {
const winnerStillStarting =
lock !== null && lock.draining !== true && lock.pid !== child.pid && isAlive(lock.pid);
- if (!winnerStillStarting) return null;
+ if (!winnerStillStarting) return { lock: null, waitedDeadlineMs: effectiveDeadlineMs };
+ }
+ if (Date.now() >= deadline) {
+ // Slow is not hung. A spawn still running when the startup deadline
+ // lands has not failed at anything — it is mid-boot — so giving up
+ // there turns "this project takes a while to open" into "this project
+ // cannot be opened", and every retry reproduces it. Graduate to the
+ // hard cap instead, once, and record the decision: an operator reading
+ // the log needs to see that the wait was extended and on what evidence.
+ //
+ // "Still starting" is asked of whoever is actually booting this
+ // project, not only of our own child. In the lock-collision case above
+ // our child is dead BY DESIGN and the live holder of the non-draining
+ // lock is the one mid-boot — binding it to our child's liveness would
+ // cut the winner off at the startup deadline and reintroduce exactly
+ // the failure this tier exists to prevent, one branch over.
+ const childStarting = child !== undefined && isAlive?.(child.pid) === true;
+ const holderStarting =
+ lock !== null && lock.draining !== true && isAlive?.(lock.pid) === true;
+ const stillStarting =
+ !extended && hardCapMs > deadlineMs && (childStarting || holderStarting);
+ if (!stillStarting) return { lock: null, waitedDeadlineMs: effectiveDeadlineMs };
+ extended = true;
+ effectiveDeadlineMs = hardCapMs;
+ deadline = started + hardCapMs;
+ this.deps.log?.info(
+ {
+ event: 'desktop-spawn-wait-extended',
+ pid: child?.pid,
+ lockDir,
+ startupDeadlineMs: deadlineMs,
+ hardCapMs,
+ // Which of the two signals earned the extension: our own child, or
+ // the live holder of the lock our child lost the race for.
+ startingParty: childStarting ? 'child' : 'lock-holder',
+ // The server publishes its lock with a `port: 0` sentinel early in
+ // boot, so its presence separates "alive and initializing" from
+ // "alive but has not started booting" in the log.
+ lockPublished: lock !== null,
+ },
+ '[window-manager] server still starting at the spawn deadline — extending the wait',
+ );
}
await new Promise<void>((resolveSleep) => {
this.deps.setTimeout(() => {
@@ -2656,7 +2784,6 @@ export class WindowManager {
}, POLL_INTERVAL_MS);
});
}
- return null;
}
/**
diff --git a/packages/desktop/tests/main/window-manager.test.ts b/packages/desktop/tests/main/window-manager.test.ts
index af356586a..9139a3892 100644
--- a/packages/desktop/tests/main/window-manager.test.ts
+++ b/packages/desktop/tests/main/window-manager.test.ts
@@ -1662,6 +1662,175 @@ describe('WindowManager', () => {
expect(pids.size).toBe(0);
});
+ // The defect this guards: a server whose boot legitimately outruns the
+ // startup deadline was SIGTERM'd while mid-boot, so every large project
+ // became permanently unopenable and every retry reproduced it. Being
+ // slow is not being hung — a child observed alive at the deadline has to
+ // keep its wait.
+ test('a live child that binds after the startup deadline still opens the window', async () => {
+ enableSyncTimers();
+ // Gated on elapsed WALL-CLOCK, not poll count: the deadline is
+ // wall-clock and the injected timers fire synchronously, so a
+ // count-based gate would let the lock appear inside the startup
+ // deadline and never exercise the extension at all.
+ const spawnedAt = Date.now();
+ const BINDS_AFTER_MS = 40;
+ env.deps.readServerLock = () =>
+ Date.now() - spawnedAt >= BINDS_AFTER_MS ? spawnedLock : null;
+ env.deps.isProcessAlive = () => true;
+ env.deps.hostname = () => 'my-host';
+ env.deps.probeWsUpgrade = () => Promise.resolve(true);
+ env.deps.spawnDetachedServer = () => Promise.resolve({ pid: 88001 });
+ const killed: number[] = [];
+ env.deps.killProbe = (pid: number) => {
+ killed.push(pid);
+ };
+ // Startup deadline lands well before the bind; the extension is what
+ // has to carry the wait the rest of the way.
+ env.deps.spawnLockPollDeadlineMs = 5;
+ env.deps.spawnLockProgressDeadlineMs = 30_000;
+
+ const wm = new WindowManager(env.deps);
+ const ctx = await wm.createProjectWindow({ projectPath: '/tmp/spawned-project' });
+
+ expect(ctx.port).toBe(60111);
+ expect(env.windows.length).toBe(1);
+ // The whole point: no SIGTERM went to the healthy child.
+ expect(killed).toEqual([]);
+ });
+
+ test('the extended wait is bounded — a live child that never binds still fails', async () => {
+ enableSyncTimers();
+ env.deps.readServerLock = () => null;
+ env.deps.isProcessAlive = () => true;
+ env.deps.hostname = () => 'my-host';
+ env.deps.probeWsUpgrade = () => Promise.resolve(true);
+ env.deps.spawnDetachedServer = () => Promise.resolve({ pid: 88001 });
+ env.deps.spawnLockPollDeadlineMs = 1;
+ env.deps.spawnLockProgressDeadlineMs = 25;
+
+ const wm = new WindowManager(env.deps);
+ const err = await wm.createProjectWindow({ projectPath: '/tmp/never-binds' }).then(
+ () => null,
+ (e: unknown) => e as Error & { kind?: string },
+ );
+
+ expect(err?.kind).toBe('spawn-lock-timeout');
+ // The reported deadline is the wait actually served, not the startup
+ // deadline it graduated from — otherwise the message understates the
+ // wait by the extension factor.
+ expect(err?.message).toMatch(/within 25ms/);
+ });
+
+ // The lock is keyed by PROJECT, not by process: when a concurrent starter
+ // wins the acquire our child exits by design and the WINNER is the one
+ // mid-boot. Tying the extension to our own child's liveness would cut
+ // that winner off at the startup deadline — the same slow-boot failure,
+ // one branch over.
+ test('a live lock-holder earns the extension even though our child lost the race', async () => {
+ enableSyncTimers();
+ const spawnedAt = Date.now();
+ const BINDS_AFTER_MS = 40;
+ const winnerPid = 77002;
+ env.deps.readServerLock = () =>
+ Date.now() - spawnedAt >= BINDS_AFTER_MS
+ ? { ...spawnedLock, pid: winnerPid }
+ : // Winner holds the lock but has not bound yet: the documented
+ // `port: 0`-but-not-yet-listening window.
+ { ...spawnedLock, pid: winnerPid, port: 0 };
+ // Our child is dead (it lost the acquire); the winner is alive.
+ env.deps.isProcessAlive = (pid: number) => pid === winnerPid;
+ env.deps.hostname = () => 'my-host';
+ env.deps.probeWsUpgrade = () => Promise.resolve(true);
+ env.deps.spawnDetachedServer = () => Promise.resolve({ pid: 88001 });
+ env.deps.spawnLockPollDeadlineMs = 5;
+ env.deps.spawnLockProgressDeadlineMs = 30_000;
+
+ const wm = new WindowManager(env.deps);
+ const ctx = await wm.createProjectWindow({ projectPath: '/tmp/spawned-project' });
+
+ expect(ctx.port).toBe(60111);
+ expect(env.windows.length).toBe(1);
+ });
+
+ // A dead child must NOT earn the extension: waiting on a corpse turns a
+ // fast crash into a long stall and reframes it as a slow start.
+ test('a child that dies past the startup deadline is not granted the extension', async () => {
+ enableSyncTimers();
+ env.deps.readServerLock = () => null;
+ env.deps.isProcessAlive = () => false;
+ env.deps.hostname = () => 'my-host';
+ env.deps.probeWsUpgrade = () => Promise.resolve(true);
+ env.deps.spawnDetachedServer = () => Promise.resolve({ pid: 88001 });
+ env.deps.spawnLockPollDeadlineMs = 1;
+ env.deps.spawnLockProgressDeadlineMs = 60_000;
+
+ const wm = new WindowManager(env.deps);
+ const err = await wm.createProjectWindow({ projectPath: '/tmp/dead-child' }).then(
+ () => null,
+ (e: unknown) => e as Error & { kind?: string },
+ );
+
+ expect(err?.kind).toBe('spawn-lock-timeout');
+ expect(err?.message).toMatch(/exited before binding/);
+ });
+
+ // The captured stderr is whatever the server printed on the way up, and
+ // on a healthy boot that is routinely a config advisory. Presenting it
+ // under a bare "stderr" header next to a failure sends the reader off to
+ // fix a warning that had nothing to do with it.
+ function projectWithSpawnErrorLog(contents: string): string {
+ const root = mkdtempSync(join(tmpdir(), 'ok-spawn-stderr-'));
+ mkdirSync(join(root, '.ok', 'local'), { recursive: true });
+ writeFileSync(join(root, '.ok', 'local', 'last-spawn-error.log'), contents);
+ return root;
+ }
+
+ test('a still-running child frames its output as probably not the cause', async () => {
+ enableSyncTimers();
+ const advisory = '[ok] Removed key at .ok/config.yml:5:19: appearance.sidebar.showAllFiles';
+ const projectPath = projectWithSpawnErrorLog(advisory);
+ env.deps.readServerLock = () => null;
+ env.deps.isProcessAlive = () => true;
+ env.deps.hostname = () => 'my-host';
+ env.deps.probeWsUpgrade = () => Promise.resolve(true);
+ env.deps.spawnDetachedServer = () => Promise.resolve({ pid: 88001 });
+ env.deps.spawnLockPollDeadlineMs = 1;
+ env.deps.spawnLockProgressDeadlineMs = 5;
+
+ const wm = new WindowManager(env.deps);
+ const err = await wm.createProjectWindow({ projectPath }).then(
+ () => null,
+ (e: unknown) => e as Error,
+ );
+
+ expect(err?.message).toContain(advisory);
+ expect(err?.message).toMatch(/probably not the cause/);
+ expect(err?.message).not.toMatch(/^--- stderr ---$/m);
+ });
+
+ test('an exited child keeps its stderr labelled as stderr', async () => {
+ enableSyncTimers();
+ const projectPath = projectWithSpawnErrorLog('Error: EACCES on .ok/local\n');
+ env.deps.readServerLock = () => null;
+ env.deps.isProcessAlive = () => false;
+ env.deps.hostname = () => 'my-host';
+ env.deps.probeWsUpgrade = () => Promise.resolve(true);
+ env.deps.spawnDetachedServer = () =>
+ Promise.resolve({ pid: 88001, readExit: () => ({ code: 1, signal: null }) });
+ env.deps.spawnLockPollDeadlineMs = 1;
+
+ const wm = new WindowManager(env.deps);
+ const err = await wm.createProjectWindow({ projectPath }).then(
+ () => null,
+ (e: unknown) => e as Error,
+ );
+
+ expect(err?.message).toMatch(/exited before binding/);
+ expect(err?.message).toMatch(/^--- stderr ---$/m);
+ expect(err?.message).not.toMatch(/probably not the cause/);
+ });
+
// A hung start and a crash otherwise render as the same bare deadline.
// Naming the surviving process is what lets the reader tell them apart.
test('a deadline reached with the child alive says the process was still running', async () => {