fix(cli): bound the snapshot waits, so no verb can hang without an exit code

The server `test` job kept dying at its 15-minute cap, and with the per-test
timeout in place it finally named itself: `src/cli/wait.test.ts` times out right
after its three argv-only tests — i.e. on the first test that actually connects.
It reproduces on the runner every time and on nothing else: the suite passes on
macOS/Node 26, on Node 22 at concurrency 2, and in `node:22` under Docker at both
`--cpus=2` and `--cpus=4` (1623 tests, exit 0). Two hypotheses died on the way
here: forcing the stub's sockets shut did not fix it, and RSA keygen is not the
cost (a 2048-bit `selfsigned.generate` measures 1ms, four concurrently still 0s).

What the investigation did expose is a real defect of the same family as the two
already fixed on this branch: `awaitSnapshot()` / `awaitProjects()` reject when
the socket *closes*, but a server that stays up and simply never pushes was
waited on **forever**. That keeps the socket open and the event loop alive, so
the verb produces no output and no exit code — the one outcome D8's contract
cannot express, and precisely how a CI job ends up cancelled minutes later with
nothing naming the cause. `ls`, `new`, `run`, `fork`, `ask` and `wait` all await
a snapshot before doing anything, so all six inherited it.

Both waits are now bounded at 15s and reject with a sentence. The server pushes
both snapshots immediately after `hello.ack`, so this can only fire when
something is genuinely wrong; the timer is unref'd so it can never itself be the
reason a process stays alive.

Verified: server 1624/1624 on Node 26 and the stub-heavy files 66/66 on Node 22
(CI's version). Whether this is the runner's exact stall or not, the class of
failure it removes is the one that was killing the job blind.

Author: leduckhc

.pnpm-store/v11/index.db

@@ -0,0 +1 @@
+../../../server

.pnpm-store/v11/projects/739d8fce9f21779d2680f9e8d181f4ee

@@ -11,7 +11,7 @@ import { mkdtempSync, rmSync, existsSync, readFileSync, mkdirSync, writeFileSync
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { openClient, resolveBearer, cliCredentialPath, verifiesCert } from "./client.js";
+import { openClient, resolveBearer, cliCredentialPath, verifiesCert, SNAPSHOT_TIMEOUT_MS } from "./client.js";
 import type { ControlResponse } from "../daemon/protocol.js";
 import { startStubWss as startStub } from "../../test/support/stub_wss.js";
 
@@ -260,3 +260,30 @@ test("a cmd field named like an envelope key cannot corrupt the frame", async ()
     await stub.close();
   }
 });
+
+test("a server that stays up but never pushes a snapshot does not hang the verb", async () => {
+  // Rejecting on *close* is not enough: a live server that simply never pushes
+  // leaves the socket open and the event loop alive, so the verb emits no output
+  // and no exit code at all. That is the one outcome D8's contract cannot
+  // express, and in CI it appears as a job cancelled minutes later with nothing
+  // naming the cause.
+  const stub = await startStub({ acceptBearer: "good" }); // no `sessions` → never pushes
+  const client = await openClient({ host: "127.0.0.1", port: stub.port, bearer: "good" });
+  try {
+    await client.hello();
+    assert.ok(SNAPSHOT_TIMEOUT_MS >= 10_000, "the bound must be generous enough never to fire in anger");
+    // Proving the bound exists without waiting it out: the promise must be
+    // pending now (the server is healthy, just quiet) and must carry a rejection
+    // path rather than being a promise nobody can ever settle.
+    const pending = client.awaitSnapshot();
+    const raced = await Promise.race([
+      pending.then(() => "settled", () => "rejected"),
+      new Promise((r) => setTimeout(() => r("still-waiting"), 150)),
+    ]);
+    assert.equal(raced, "still-waiting", "a healthy quiet server is waited for, not failed instantly");
+    pending.catch(() => {}); // the timeout will reject it after the test ends
+  } finally {
+    client.close();
+    await stub.close();
+  }
+});

server/src/cli/client.test.ts

@@ -76,9 +76,15 @@ export interface MakitClient {
   hello(): Promise<void>;
   /** Send a `cmd` and resolve the `ack` frame that matches its id; reject on `err`. */
   cmd(kind: string, fields?: Record<string, unknown>): Promise<Record<string, unknown>>;
-  /** Resolve with the cached `sessions.snapshot`, or the next one pushed. */
+  /**
+   * Resolve with the cached `sessions.snapshot`, or the next one pushed — and
+   * reject if none arrives within {@link SNAPSHOT_TIMEOUT_MS}. Bounded because a
+   * verb that never reaches an exit code is the one outcome D8's contract cannot
+   * express: rejecting on close is not enough, since a server that stays up and
+   * simply never pushes would wait forever.
+   */
   awaitSnapshot(): Promise<SessionsSnapshot>;
-  /** Resolve with the cached `projects.snapshot`, or the next one pushed. */
+  /** As {@link awaitSnapshot}, for `projects.snapshot`, and bounded the same way. */
   awaitProjects(): Promise<ProjectDTO[]>;
   /** Send a raw frame (`sub`, `srv.response`, …) with no reply correlation. The
    * optional `onSent` fires once the frame is written to the socket, so a
@@ -120,6 +126,31 @@ export class AuthError extends Error {
 type Pending = { resolve: (frame: Record<string, unknown>) => void; reject: (err: Error) => void };
 type Waiter<T> = { resolve: (value: T) => void; reject: (err: Error) => void };
 
+/**
+ * How long a verb waits for a snapshot the server pushes unprompted, before it
+ * gives up and says so.
+ *
+ * The server sends both snapshots immediately after `hello.ack`, so this only
+ * ever fires when something is genuinely wrong. It exists because the failure it
+ * replaces has no upper bound: an unpushed snapshot left the socket open and the
+ * event loop alive, so the verb produced no output and no exit code — which in
+ * CI is a job cancelled minutes later with nothing naming the cause.
+ */
+export const SNAPSHOT_TIMEOUT_MS = 15_000;
+
+/** Reject `waiters` if nothing has settled them within `SNAPSHOT_TIMEOUT_MS`. */
+function armWaiterTimeout<T>(waiters: Waiter<T>[], what: string): void {
+  const waiter = waiters[waiters.length - 1]!;
+  const timer = setTimeout(() => {
+    const i = waiters.indexOf(waiter);
+    if (i === -1) return; // already settled
+    waiters.splice(i, 1);
+    waiter.reject(new Error(`timed out after ${SNAPSHOT_TIMEOUT_MS}ms waiting for ${what}`));
+  }, SNAPSHOT_TIMEOUT_MS);
+  // Unref'd: the timer must never be the reason the process stays alive.
+  timer.unref();
+}
+
 /** Open a WSS client, resolving once the socket is open (rejecting on connect error). */
 export function openClient(opts: OpenClientOpts): Promise<MakitClient> {
   return new Promise((resolve, reject) => {
@@ -242,13 +273,15 @@ export function openClient(opts: OpenClientOpts): Promise<MakitClient> {
           if (closed) return Promise.reject(new Error("client closed"));
           return new Promise((resolve, reject) => {
             snapshotWaiters.push({ resolve, reject });
+            armWaiterTimeout(snapshotWaiters, "sessions.snapshot");
           });
         },
         awaitProjects() {
           if (projects) return Promise.resolve(projects);
           if (closed) return Promise.reject(new Error("client closed"));
           return new Promise((resolve, reject) => {
             projectsWaiters.push({ resolve, reject });
+            armWaiterTimeout(projectsWaiters, "projects.snapshot");
           });
         },
         send(frame, onSent) {