@specific.dev/spectest 0.68.0 → 0.70.0

package/src/harness/tls-terminator.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Adding a certificate must cost no connection.
+ *
+ * This is the file the previous shape of :443 could not have: when the
+ * listener was a `Bun.serve` whose `tls` array was fixed at serve time,
+ * every new certificate meant a swap, and the best a swap could do was
+ * save requests that were already in flight (`ingress-rebind.test.ts`).
+ * The failure that kept reaching production was the other half — an
+ * **idle kept-alive connection**, severed by `stop(false)` within 1-2 ms,
+ * surfacing in an unrelated test as `SocketError: other side closed`.
+ *
+ * So these drive real TLS sockets rather than a model of them: the whole
+ * bug was in socket behaviour, and a model would have agreed with the
+ * broken code. The client is Node's own `node:tls`/HTTP-over-socket so
+ * that keep-alive is under the test's control rather than a pool's.
+ */
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import net from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import tls from "node:tls";
+
+import type { Leaf } from "./ingress-table";
+import { selectCertName } from "./hostmatch";
+import { startTlsTerminator, type TlsTerminator } from "./tls-terminator";
+
+// ── a throwaway CA and leaves, so the client can verify for real ──────────
+let dir: string;
+const leaves = new Map<string, Leaf>();
+let caPem: string;
+
+function openssl(args: string[], input?: string): void {
+  const r = spawnSync("openssl", args, { cwd: dir, input, encoding: "utf8" });
+  if (r.status !== 0) throw new Error(`openssl ${args.join(" ")}: ${r.stderr}`);
+}
+
+function mintLeaf(name: string, san: string): Leaf {
+  const file = name.replace("*", "wild");
+  openssl(["req", "-newkey", "rsa:2048", "-keyout", `${file}.key`, "-out", `${file}.csr`,
+    "-nodes", "-subj", `/CN=${name}`]);
+  openssl(["x509", "-req", "-in", `${file}.csr`, "-CA", "ca.crt", "-CAkey", "ca.key",
+    "-CAcreateserial", "-out", `${file}.crt`, "-days", "2", "-extfile", "ext.cnf"]);
+  // -extfile is rewritten per call; write it first.
+  return {
+    cert: readFileSync(join(dir, `${file}.crt`), "utf8"),
+    key: readFileSync(join(dir, `${file}.key`), "utf8"),
+  };
+}
+
+beforeAll(() => {
+  dir = mkdtempSync(join(tmpdir(), "spectest-tls-"));
+  openssl(["req", "-x509", "-newkey", "rsa:2048", "-keyout", "ca.key", "-out", "ca.crt",
+    "-days", "2", "-nodes", "-subj", "/CN=spectest-test-ca"]);
+  caPem = readFileSync(join(dir, "ca.crt"), "utf8");
+  for (const [name, san] of [
+    ["app.test", "DNS:app.test"],
+    ["late.test", "DNS:late.test"],
+    ["*.db.test", "DNS:*.db.test"],
+  ] as const) {
+    require("node:fs").writeFileSync(join(dir, "ext.cnf"), `subjectAltName=${san}\n`);
+    leaves.set(name, mintLeaf(name, san));
+  }
+});
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+// ── the ingress shape: a plaintext Bun.serve behind the terminator ────────
+const PORT = 19701;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let plain: any;
+let term: TlsTerminator;
+/** The live SNI table, exactly as the daemon mutates `INGRESS.certByHost`. */
+let certByHost: Map<string, Leaf>;
+/** What the plaintext server reported as the client's address, per request. */
+let seenClientIp: string | undefined;
+
+beforeAll(async () => {
+  certByHost = new Map([["app.test", leaves.get("app.test")!]]);
+  plain = Bun.serve({
+    port: 0,
+    hostname: "127.0.0.1",
+    idleTimeout: 0,
+    fetch(req, server) {
+      const peer = server.requestIP(req);
+      seenClientIp = term.clientIpFor(peer?.port) ?? peer?.address;
+      return new Response(`served ${new URL(req.url).hostname}`);
+    },
+  });
+  term = await startTlsTerminator({
+    port: PORT,
+    hostname: "127.0.0.1",
+    upstreamPort: plain.port,
+    certFor: (serverName) => {
+      if (serverName === undefined) return certByHost.values().next().value;
+      const name = selectCertName(certByHost.keys(), serverName.toLowerCase());
+      return name === undefined ? undefined : certByHost.get(name);
+    },
+    onWarning: () => {
+      /* a client hanging up mid-handshake is a case under test */
+    },
+  });
+});
+afterAll(() => {
+  term?.close();
+  plain?.stop(true);
+});
+
+const sockets: tls.TLSSocket[] = [];
+afterEach(() => {
+  for (const s of sockets.splice(0)) s.destroy();
+});
+
+/** A kept-alive TLS connection, handshaken and left open. */
+async function connect(servername: string, localAddress?: string): Promise<tls.TLSSocket> {
+  const sock = tls.connect({
+    host: "127.0.0.1", port: PORT, servername, ca: caPem,
+    ...(localAddress ? { localAddress } : {}),
+  });
+  sockets.push(sock);
+  await new Promise<void>((resolve, reject) => {
+    sock.once("secureConnect", () => resolve());
+    sock.once("error", reject);
+  });
+  return sock;
+}
+
+/** One keep-alive request on an existing connection. Rejects if the peer
+ *  closed it instead of answering — which is exactly the reported bug. */
+function request(sock: tls.TLSSocket, host: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let buf = "";
+    const onData = (d: Buffer): void => {
+      buf += d.toString();
+      if (buf.includes("\r\n\r\n")) {
+        sock.off("data", onData);
+        resolve(buf);
+      }
+    };
+    sock.on("data", onData);
+    sock.once("close", () => reject(new Error("other side closed")));
+    sock.once("error", (err) => reject(err));
+    sock.write(`GET / HTTP/1.1\r\nHost: ${host}\r\nConnection: keep-alive\r\n\r\n`);
+    setTimeout(() => reject(new Error("timed out")), 4000);
+  });
+}
+
+describe("adding a certificate", () => {
+  /**
+   * THE regression. An idle pooled connection is what a client actually
+   * holds between polls, and a listener swap severed it: the next request
+   * written into that socket came back `SocketError: other side closed`,
+   * unretried, failing whichever test happened to be deploying. Adding a
+   * leaf to the live table must be invisible to it.
+   */
+  test("an idle kept-alive connection survives it", async () => {
+    const sock = await connect("app.test");
+    expect(await request(sock, "app.test")).toContain("served app.test");
+
+    // …the connection now sits idle in the client's pool, as a CLI polling
+    // a deploy would leave it, while an unrelated service is provisioned.
+    certByHost.set("late.test", leaves.get("late.test")!);
+    await Bun.sleep(50);
+
+    expect(await request(sock, "app.test")).toContain("served app.test");
+  });
+
+  test("many certificates later, the same connection is still good", async () => {
+    const sock = await connect("app.test");
+    await request(sock, "app.test");
+    for (let i = 0; i < 10; i++) {
+      certByHost.set(`svc-${i}.db.test`, leaves.get("*.db.test")!);
+      await Bun.sleep(5);
+    }
+    expect(await request(sock, "app.test")).toContain("served app.test");
+  });
+
+  /** The other side of the same coin: the point of adding a leaf is that
+   *  it serves the next handshake, with no restart to wait for. */
+  test("the new hostname is served on the next handshake", async () => {
+    certByHost.set("late.test", leaves.get("late.test")!);
+    const sock = await connect("late.test");
+    expect((sock.getPeerCertificate().subject as { CN: string }).CN).toBe("late.test");
+    expect(await request(sock, "late.test")).toContain("served late.test");
+  });
+
+  /** A wildcard leaf serves one label under it — the same RFC 6125 rule
+   *  `certCovers` plans against, now enforced at the handshake. */
+  test("a wildcard leaf serves a name one label under it", async () => {
+    certByHost.set("*.db.test", leaves.get("*.db.test")!);
+    const sock = await connect("tenant-7.db.test");
+    expect((sock.getPeerCertificate().subject as { CN: string }).CN).toBe("*.db.test");
+  });
+});
+
+describe("the pipe", () => {
+  /** `x-forwarded-for` is built from this. The plaintext server's peer is
+   *  the terminator, so without the port map every proxied request would
+   *  tell the app under test its caller was 127.0.0.1. */
+  test("reports the real client address, not the loopback hop", async () => {
+    seenClientIp = undefined;
+    const sock = await connect("app.test", "127.0.0.2");
+    await request(sock, "app.test");
+    expect(seenClientIp).toBe("127.0.0.2");
+  });
+
+  /** A handshake the terminator cannot complete must cost the process
+   *  nothing: an unhandled 'error' on a node server is thrown, and taking
+   *  the daemon down over one bad client would be worse than the bug. */
+  test("a client that speaks no TLS does not disturb the listener", async () => {
+    const raw = net.connect(PORT, "127.0.0.1");
+    await new Promise<void>((r) => raw.on("connect", () => r()));
+    raw.write("this is not a ClientHello\r\n\r\n");
+    await Bun.sleep(100);
+    raw.destroy();
+
+    const sock = await connect("app.test");
+    expect(await request(sock, "app.test")).toContain("served app.test");
+  });
+
+  /** A test VM is short-lived, but a fake that provisions in a loop opens
+   *  a connection per probe — the terminator must not accumulate them. */
+  test("connections are released when they close", async () => {
+    // Earlier tests' sockets are destroyed in afterEach; let those close
+    // events land so this measures only what it opens itself.
+    const settle = async (): Promise<void> => {
+      for (let i = 0; i < 100 && term.connectionCount() > 0; i++) await Bun.sleep(20);
+    };
+    await settle();
+    expect(term.connectionCount()).toBe(0);
+
+    const sock = await connect("app.test");
+    await request(sock, "app.test");
+    expect(term.connectionCount()).toBe(1);
+
+    sock.destroy();
+    await settle();
+    expect(term.connectionCount()).toBe(0);
+  });
+});

package/src/harness/tls-terminator.ts

@@ -0,0 +1,244 @@
+/**
+ * The :443 TLS terminator — one listener, for the life of the harness.
+ *
+ * ## Why this exists
+ *
+ * Ingress certificates are minted *while tests run*: a fake that
+ * provisions a database hands the app a CA-trusted `https://<new-host>/`
+ * endpoint, and that hostname did not exist a second earlier. Bun fixes a
+ * server's TLS configuration at `Bun.serve` time — `reload({ tls })` is
+ * accepted and then ignored (re-measured on Bun 1.4.0: the added
+ * `serverName` still gets the first entry's leaf) — so for as long as
+ * :443 was a `Bun.serve`, every new certificate meant swapping the
+ * listener.
+ *
+ * **No listener swap can be made safe.** Binding the replacement first
+ * under SO_REUSEPORT and draining the original with `stop(false)` saves a
+ * request that is already *in flight*, and that is all it saves: measured
+ * on Bun 1.4.0, `stop(false)` sends FIN to an **idle kept-alive
+ * connection within 1–2 ms**. A client that writes a request into that
+ * socket in the same instant gets `SocketError: other side closed`
+ * (`UND_ERR_SOCKET` under undici), and Node's `fetch` does not retry it.
+ * That is a flake in whatever unrelated test happened to be talking
+ * through the ingress — never in the one that provisioned the service —
+ * and it is why the app under test would die far from any ingress code.
+ *
+ * So the listener must stop being swapped, which means the certificate
+ * must be chosen **per handshake** rather than baked into the socket.
+ * That is what every real server does, and under Bun it is reachable
+ * through `node:tls`'s `SNICallback` (verified working on Bun 1.4.0:
+ * adding an entry to the table is served on the next handshake, with no
+ * restart and no effect on any established connection).
+ *
+ * ## The shape, and why it is a byte pipe
+ *
+ * The terminator does TLS and *nothing else*: it accepts on :443, picks a
+ * leaf by SNI, and pipes the decrypted stream to a plaintext `Bun.serve`
+ * bound on loopback. Everything downstream — routing, fakes,
+ * interceptors, reverse-proxying, and `server.upgrade()` WebSocket
+ * bridging — is the same `Bun.serve` code that already serves :80, run
+ * unchanged. Terminating HTTP here instead (`node:https`, `(req, res)`)
+ * would have meant reimplementing the WebSocket bridge against a
+ * different API, which is exactly the kind of trade this change exists to
+ * avoid: one flake removed, another introduced somewhere subtler.
+ *
+ * Measured cost of the extra hop on this host (Bun 1.4.0, undici client,
+ * 50 MB bodies): ~11 % fewer small requests per second, download
+ * throughput unchanged, upload ~500 MB/s against ~800 MB/s direct. Ingress
+ * traffic in a test VM is nowhere near either bound.
+ *
+ * ## Recovering the client's address
+ *
+ * The plaintext server's peer is the terminator, so `server.requestIP()`
+ * reports loopback and `x-forwarded-for` would lose the caller. The
+ * upstream socket's *source port* is unique among live connections, so the
+ * terminator records `source port → real client address` for the life of
+ * each connection and {@link TlsTerminator.clientIpFor} hands it back.
+ * Verified end to end: a client connecting from 127.0.0.2 is reported as
+ * 127.0.0.2 by the plaintext server behind the pipe.
+ */
+import net from "node:net";
+import tls from "node:tls";
+
+import type { Leaf } from "./ingress-table";
+
+export interface TlsTerminatorOptions {
+  /** Public port to accept TLS on (443 in the harness). */
+  port: number;
+  /** Interface to accept on. */
+  hostname: string;
+  /** Loopback port of the plaintext ingress server to pipe into. */
+  upstreamPort: number;
+  /**
+   * The leaf to serve for an SNI server name, read live on every
+   * handshake — this is what lets a certificate be added with no restart.
+   * `undefined` server name means the client sent no SNI.
+   */
+  certFor(serverName: string | undefined): Leaf | undefined;
+  /** Non-fatal diagnostics (a handshake a client aborted, a pipe error). */
+  onWarning?(message: string, err: unknown): void;
+}
+
+export interface TlsTerminator {
+  /** The port actually bound. */
+  readonly port: number;
+  /**
+   * The real client address behind an upstream connection, keyed by the
+   * source port the plaintext server sees. `undefined` for a port this
+   * terminator did not open.
+   */
+  clientIpFor(upstreamPort: number | undefined): string | undefined;
+  /** Open TLS connections right now (diagnostics and tests). */
+  connectionCount(): number;
+  /** Stop accepting and force-close every connection. */
+  close(): void;
+}
+
+/**
+ * Start the terminator. Resolves once :443 is accepting, so a caller can
+ * register the hostname in DNS immediately afterwards and know the port is
+ * live.
+ */
+/**
+ * Is this the ordinary end of a connection rather than a fault? A peer
+ * that goes away mid-stream, or a half-finished handshake, is routine on a
+ * listener that fronts browsers.
+ */
+function isRoutineDisconnect(err: unknown): boolean {
+  const code = (err as { code?: string } | undefined)?.code;
+  return (
+    code === "ECONNRESET" ||
+    code === "EPIPE" ||
+    code === "ERR_STREAM_PREMATURE_CLOSE" ||
+    code === "ECONNABORTED"
+  );
+}
+
+export function startTlsTerminator(opts: TlsTerminatorOptions): Promise<TlsTerminator> {
+  // Parsing a PEM into a SecureContext is the expensive half of choosing a
+  // certificate, and the table is stable — cache by the certificate's own
+  // bytes so a handshake is a Map lookup. Keyed on the PEM rather than the
+  // hostname so a re-minted leaf for the same name cannot be served stale.
+  const contexts = new Map<string, tls.SecureContext>();
+  const contextFor = (leaf: Leaf): tls.SecureContext => {
+    let ctx = contexts.get(leaf.cert);
+    if (!ctx) {
+      ctx = tls.createSecureContext({ cert: leaf.cert, key: leaf.key });
+      contexts.set(leaf.cert, ctx);
+    }
+    return ctx;
+  };
+
+  const warn = (message: string, err: unknown): void => {
+    // A client hanging up is not a fault, and this listener carries every
+    // browser in the VM: Chromium opens speculative connections and drops
+    // them, a fetch is abandoned when its test ends, and each of those
+    // arrives here as a reset. Logging them would bury the boot log a user
+    // reads with `spectest env logs` in noise that means nothing.
+    if (isRoutineDisconnect(err)) return;
+    if (opts.onWarning) opts.onWarning(message, err);
+    // eslint-disable-next-line no-console
+    else console.warn(`[ingress] ${message}:`, err);
+  };
+
+  /** upstream source port → the address the TLS client connected from. */
+  const clientIpByUpstreamPort = new Map<number, string>();
+  const live = new Set<net.Socket>();
+
+  // A default leaf is only ever used for a client that sends no SNI at
+  // all; `SNICallback` decides every other handshake. This mirrors what
+  // Bun did with the first entry of its `tls` array.
+  const fallback = opts.certFor(undefined);
+
+  const server = tls.createServer(
+    {
+      ...(fallback ? { cert: fallback.cert, key: fallback.key } : {}),
+      SNICallback: (serverName, cb) => {
+        const leaf = opts.certFor(serverName) ?? fallback;
+        // No certificate at all is a handshake we cannot complete. Answer
+        // with the fallback context rather than an error so the client
+        // gets a certificate-mismatch alert it can report, which is the
+        // same thing it saw when Bun served the first entry.
+        cb(null, leaf ? contextFor(leaf) : undefined);
+      },
+    },
+    (client) => {
+      // No idle timeout anywhere on the ingress path: it fronts app
+      // endpoints that legitimately take minutes (a deploy), and a
+      // timeout here would surface as a truncated response with no
+      // explanation.
+      client.setTimeout(0);
+      live.add(client);
+
+      // Nothing reads from `client` until `pipe` below, so a socket that
+      // is written to before the upstream is connected stays paused and
+      // its bytes are buffered rather than dropped — which is the normal
+      // case, since a client sends its first request the instant the
+      // handshake completes.
+      const upstream = net.connect(opts.upstreamPort, "127.0.0.1");
+      upstream.setTimeout(0);
+      upstream.setNoDelay(true);
+      client.setNoDelay(true);
+
+      let recordedPort: number | undefined;
+      upstream.on("connect", () => {
+        recordedPort = upstream.localPort;
+        if (recordedPort !== undefined && client.remoteAddress) {
+          clientIpByUpstreamPort.set(recordedPort, client.remoteAddress);
+        }
+        // `pipe` carries backpressure and the half-close in both
+        // directions, which is what a WebSocket bridge and a streamed
+        // upload each need.
+        client.pipe(upstream);
+        upstream.pipe(client);
+      });
+
+      const teardown = (): void => {
+        if (recordedPort !== undefined) clientIpByUpstreamPort.delete(recordedPort);
+        live.delete(client);
+        client.destroy();
+        upstream.destroy();
+      };
+      client.on("error", (err) => {
+        warn("tls client connection failed", err);
+        teardown();
+      });
+      upstream.on("error", (err) => {
+        warn(`ingress upstream :${opts.upstreamPort} failed`, err);
+        teardown();
+      });
+      client.on("close", teardown);
+      upstream.on("close", teardown);
+    },
+  );
+
+  // A client that aborts mid-handshake, or offers a protocol version we
+  // do not speak, emits this. It must be handled: an unhandled 'error' on
+  // a net server is thrown, and taking the daemon down over one bad
+  // handshake would be a far worse failure than the one being fixed.
+  server.on("tlsClientError", (err) => warn("tls handshake failed", err));
+  server.on("error", (err) => warn(`tls listener :${opts.port} failed`, err));
+
+  return new Promise<TlsTerminator>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(opts.port, opts.hostname, () => {
+      server.removeListener("error", reject);
+      resolve({
+        port: opts.port,
+        clientIpFor: (upstreamPort) =>
+          upstreamPort === undefined ? undefined : clientIpByUpstreamPort.get(upstreamPort),
+        connectionCount: () => live.size,
+        close: () => {
+          try {
+            server.close();
+          } catch (err) {
+            warn("closing the tls listener failed", err);
+          }
+          for (const sock of [...live]) sock.destroy();
+          live.clear();
+          clientIpByUpstreamPort.clear();
+        },
+      });
+    });
+  });
+}

package/src/index.ts

@@ -2900,7 +2900,7 @@ function buildLocatorMatchers(
     // The last error a probe threw, kept for the failure message: a matcher
     // whose read waits for the element (textContent, inputValue, isEnabled …)
     // reports a missing element as a playwright timeout, and that — not
-    // "got <error: Timeout 5000ms exceeded …>" — is the sentence to fail with.
+    // "got <error: Timeout 10000ms exceeded …>" — is the sentence to fail with.
     let probeError: unknown;
     for (;;) {
       let satisfied: boolean;
@@ -2939,8 +2939,8 @@ function buildLocatorMatchers(
       }
       if (Date.now() >= deadline) {
         // The deadline, not the stopwatch: every one of these polled until it
-        // ran out, and "(waited 5s)" is both what the author set and the same
-        // number twice in a row — a measured 4_987ms is neither.
+        // ran out, and "(waited 10s)" is both what the author set and the same
+        // number twice in a row — a measured 9_987ms is neither.
         const msg = (await elementFailure(probeError)) ??
           `${describe(actual)} (waited ${formatWaited(budget)})`;
         const sourceSeq = await probe.settle(matcher, Date.now() - started, msg, settleOpts);

package/src/locator-errors.ts

@@ -1,7 +1,7 @@
 // Readable failures for locator steps.
 //
 // Playwright reports every unmet actionability wait the same way: a
-// `TimeoutError` whose message is "Timeout 5000ms exceeded." with the real
+// `TimeoutError` whose message is "Timeout 10000ms exceeded." with the real
 // story — did the element exist at all? was it disabled? did something cover
 // it? — buried in a call log below it. A test that clicks a button that is not
 // on the page therefore fails with a sentence about OUR deadline, which reads

package/src/locator.ts

@@ -32,11 +32,16 @@ import { resolveExistingProjectPath } from "./project-files.js";
 import { truncateUtf8 } from "./recorder.js";
 
 /** Default deadline for a locator action/read's target to become actionable.
- *  Playwright's own default is 30s — far too slow-failing for tests; 5s
- *  matches the pre-Playwright behavior. A per-call `{ timeout }` overrides it;
- *  `undefined` falls through to the context default (also set to this in
- *  browser.ts's `newViewContext`). Navigations keep a longer deadline. */
-export const DEFAULT_ACTION_TIMEOUT_MS = 5_000;
+ *  Playwright's own default is 30s — far too slow-failing for tests. This was
+ *  5s (the pre-Playwright behavior) until 2026-09-03, and 5s turned out to be
+ *  about one page load: a real app under a full VM fan-out took 1.8-2.0s for a
+ *  full navigation plus its client data chain on a quiet box, and 4x that on
+ *  the tail, so a step that was correct and merely late failed. 10s still
+ *  fails fast enough to be useful and leaves room for the tail. A per-call
+ *  `{ timeout }` overrides it; `undefined` falls through to the context
+ *  default (also set to this in browser.ts's `newViewContext`). Navigations
+ *  keep a longer deadline. */
+export const DEFAULT_ACTION_TIMEOUT_MS = 10_000;
 
 // Brand + chain carrier. Both are `Symbol.for` keys so `JSON.stringify` drops
 // them (locators are never serialized) while runtime code can still detect a
@@ -656,7 +661,7 @@ export interface Locator {
   /** Explicit strict-mode opt-out: the i-th resolved element (0-based). */
   nth(index: number): Locator;
 
-  // ── Actions (auto-wait; default 5s, `{ timeout }` overrides) ──────────
+  // ── Actions (auto-wait; default 10s, `{ timeout }` overrides) ─────────
   click(opts?: ClickOptions): Promise<void>;
   dblclick(opts?: ClickOptions): Promise<void>;
   /** Touch-tap (mobile sessions only; throws on desktop). `duration`
@@ -761,7 +766,7 @@ export function makeLocator(
   };
 
   // Every terminal op runs through this: playwright's actionability timeouts
-  // say "Timeout 5000ms exceeded" and hide what actually went wrong in a call
+  // say "Timeout 10000ms exceeded" and hide what actually went wrong in a call
   // log, so they are rewritten into a sentence naming the element and its
   // state (see locator-errors.ts), and a failure that found NO element asks
   // the page what it does hold. Applied INSIDE `pageOp`, so the recorded step

package/src/terminal.ts

@@ -32,6 +32,9 @@ import { recordTerminalStep, reserveEvent, truncateUtf8 } from "./recorder.js";
 import type { EventReservation } from "./recorder.js";
 import type { TerminalStepAction } from "./recorder.js";
 import { wrap } from "./inspect.js";
+// One default deadline for "wait until the app shows it", whichever surface
+// the author is watching — see the constant for why it is what it is.
+import { DEFAULT_ACTION_TIMEOUT_MS } from "./locator.js";
 import type { Wrapped } from "./inspect.js";
 
 export interface TerminalOpts {
@@ -614,7 +617,7 @@ export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerm
       matcher: string | RegExp | ((screen: string, output: string) => unknown),
       waitOpts?: { timeoutMs?: number; intervalMs?: number },
     ) {
-      const timeoutMs = waitOpts?.timeoutMs ?? 5_000;
+      const timeoutMs = waitOpts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS;
       const intervalMs = waitOpts?.intervalMs ?? 100;
       const t = Date.now();
       const resv = reserveEvent();