Tears the session's machinery down and boots it again — browser, page, server, esbuild context and watchers — then runs the suite once, resolving with that run's result.

The session survives. this is the same object, and events() / results() keep streaming straight across: a restart is one transition in the life of a session, not a close followed by a new one. If it ended the feeds it would be close() plus watch() with extra steps, and there would be no reason for it to exist.

For picking up a change no rerun can see — an edited package.json, a plugin whose module you replaced, a browser wedged by the page under test.

initial still refers to the run the session STARTED with; it is readonly and callers hold it. The restart's own first run arrives through results() and latest like any other.

url may change. The old port is released and reacquired, and if something took it in between, the new server binds the next one — so re-read url afterwards rather than caching it. The live objects are replaced too — all but WatchSession.esbuild, which a restart deliberately keeps.

Ordering: it takes the same queue reruns take, so a restart waits for an in-flight run and a rerun asked for during one waits for the restart. Calling it twice concurrently gives both callers the SAME restart rather than tearing down twice.

import type { WatchSession } from './watch.ts';

// Defined, not invoked: needs a live session.
async function afterConfigChange(session: WatchSession) {
  const result = await session.restart();
  return { total: result.counts.total, url: session.url };
}