Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): honor an explicit --port for background preview reuse and launch (#3915)
miga-heygenfcc637068c1e
diff --git a/packages/cli/src/commands/preview.test.ts b/packages/cli/src/commands/preview.test.tsindex 74e08cf694..51c5a1469e 100644--- a/packages/cli/src/commands/preview.test.ts+++ b/packages/cli/src/commands/preview.test.ts@@ -5,8 +5,11 @@ import { fileURLToPath } from "node:url";import * as clack from "@clack/prompts";import { afterEach, describe, expect, it, vi } from "vitest";import { runCommand } from "citty";+import { PreviewServerPortMismatchError } from "../utils/studioSelectionClient.js";+import { PreviewPortUnavailableError } from "./previewLifecycle.js";import {default as previewCommand,+ backgroundStartFailureCode,foregroundPreviewReadyPayload,prebuildPreview,handlePreviewKillAll,@@ -369,6 +372,14 @@ describe("preview lifecycle JSON failures", () => {expect(error).not.toHaveBeenCalled();});+ it.each([+ [new PreviewServerPortMismatchError(3500, []), "preview-port-mismatch"],+ [new PreviewPortUnavailableError(3500, 3501), "preview-port-unavailable"],+ [new Error("spawn failed"), "preview-start-failed"],+ ])("maps a background start failure to its JSON code (%#)", (error, code) => {+ expect(backgroundStartFailureCode(error)).toBe(code);+ });+it("wraps missing-project start failures without human stderr", async () => {const missing = join(tmpdir(), `hf-preview-missing-start-${process.pid}-${Date.now()}`);const log = vi.spyOn(console, "log").mockImplementation(() => {});diff --git a/packages/cli/src/commands/preview.ts b/packages/cli/src/commands/preview.tsindex 92ce2bbe43..a134b2615a 100644--- a/packages/cli/src/commands/preview.ts+++ b/packages/cli/src/commands/preview.ts@@ -62,7 +62,9 @@ import { killOrphanedProcesses, killProcessTree } from "../utils/orphanCleanup.jimport { resolveProject, resolveProjectOrThrow } from "../utils/project.js";import { resolveAutoProxy } from "../utils/projectConfig.js";import { studioProxyEnv } from "../utils/studioProxyEnv.js";+import { PreviewServerPortMismatchError } from "../utils/studioSelectionClient.js";import {+ PreviewPortUnavailableError,listBackgroundPreviewStatuses,readBackgroundPreviewStatus,startBackgroundPreview,@@ -124,6 +126,14 @@ type CompactSelectionPayload = Pick<const DEFAULT_CONTEXT_FIELDS: ContextField[] = ["server", "selection", "lint", "capabilities"];+const PREVIEW_PORT_MISMATCH_CODE = "preview-port-mismatch";++export function backgroundStartFailureCode(error: unknown): string {+ if (error instanceof PreviewServerPortMismatchError) return PREVIEW_PORT_MISMATCH_CODE;+ if (error instanceof PreviewPortUnavailableError) return "preview-port-unavailable";+ return "preview-start-failed";+}+export default defineCommand({meta: {name: "preview",@@ -299,7 +309,7 @@ export default defineCommand({if (args["browser-gpu"] === true) process.env.PRODUCER_BROWSER_GPU_MODE = "hardware";if (args["browser-gpu"] === false) process.env.PRODUCER_BROWSER_GPU_MODE = "software";const startPort = parseInt(args.port ?? "3002", 10);- const preferredContextPort = hasExplicitPreviewPort(process.argv) ? startPort : undefined;+ const explicitPort = hasExplicitPreviewPort(process.argv) ? startPort : undefined;if (args.status || args.stop) {try {@@ -388,18 +398,13 @@ export default defineCommand({json: Boolean(args.json),fields: args["context-fields"] as string | undefined,detail: args["context-detail"] as string | undefined,- ...(preferredContextPort === undefined ? {} : { preferredPort: preferredContextPort }),+ preferredPort: explicitPort,});}if (args.selection) {const project = resolveProject(args.dir);- return printCurrentSelection(- project.dir,- startPort,- Boolean(args.json),- preferredContextPort,- );+ return printCurrentSelection(project.dir, startPort, Boolean(args.json), explicitPort);}const rawArg = args.dir;@@ -502,11 +507,14 @@ export default defineCommand({// the existing managed server resolved earlier. Only an explicit// --browser-gpu/--no-browser-gpu request authorizes replacement.browserGpuMode: args["browser-gpu"] === undefined ? undefined : browserGpuMode,+ preferredPort: explicitPort,});} catch (error) {const message = errorMessage(error);if (args.json) {- writeLifecycleJson(lifecycleFailurePayload("start", "preview-start-failed", message));+ writeLifecycleJson(+ lifecycleFailurePayload("start", backgroundStartFailureCode(error), message),+ );} else {clack.log.error(message);}@@ -923,7 +931,7 @@ async function printCurrentSelection(return;}if (err instanceof PreviewServerPortMismatchError) {- printSelectionFailure("preview-port-mismatch", err.message, json);+ printSelectionFailure(PREVIEW_PORT_MISMATCH_CODE, err.message, json);return;}throw err;@@ -1045,7 +1053,7 @@ async function printCurrentContext(return;}if (err instanceof PreviewServerPortMismatchError) {- printSelectionFailure("preview-port-mismatch", err.message, options.json);+ printSelectionFailure(PREVIEW_PORT_MISMATCH_CODE, err.message, options.json);return;}throw err;diff --git a/packages/cli/src/commands/previewLifecycle.test.ts b/packages/cli/src/commands/previewLifecycle.test.tsindex fe737754e7..9f1c1cd974 100644--- a/packages/cli/src/commands/previewLifecycle.test.ts+++ b/packages/cli/src/commands/previewLifecycle.test.ts@@ -3,7 +3,9 @@ import { tmpdir } from "node:os";import { join, resolve } from "node:path";import { describe, expect, it, onTestFinished, vi } from "vitest";import type { ActiveServer } from "../server/portUtils.js";+import { PreviewServerPortMismatchError } from "../utils/studioSelectionClient.js";import {+ PreviewPortUnavailableError,buildBackgroundPreviewArgs,listBackgroundPreviewStatuses,previewSessionPath,@@ -35,6 +37,25 @@ function savePreviewSession(stateHome: string): void {);}+/** Launch deps whose wrapper (PID 4321) brings up `server` (PID 9876) on spawn and takes it down on kill. */+function reachableChildDependencies(stateHome: string, { immortal = false } = {}) {+ let spawned = false;+ let killed = false;+ const liveServer = { ...server, pid: "9876" };+ return {+ scan: async () => (spawned && (immortal || !killed) ? [liveServer] : []),+ spawn: () => {+ spawned = true;+ return { pid: 4321, unref: vi.fn() };+ },+ sleep: async () => {},+ kill: vi.fn(() => {+ killed = true;+ }),+ stateHome,+ };+}+async function expectStaleSessionRemoved(stateHome: string): Promise<void> {const status = await readBackgroundPreviewStatus(projectDir, 3002, {scan: async () => [],@@ -105,6 +126,36 @@ describe("background preview lifecycle", () => {expect(spawn).not.toHaveBeenCalled();});+ it("throws a port-mismatch error when the caller explicitly requests a port the reused server isn't on", async () => {+ const spawn = vi.fn();+ const scan = vi.fn(async () => [server]);++ await expect(+ startBackgroundPreview(projectDir, 3002, {+ scan,+ spawn,+ stateHome: mkdtempSync(join(tmpdir(), "hf-preview-state-")),+ preferredPort: server.port + 1,+ }),+ ).rejects.toThrow(PreviewServerPortMismatchError);+ expect(spawn).not.toHaveBeenCalled();+ });++ it("reuses normally when the caller's explicit port matches the reused server", async () => {+ const spawn = vi.fn();+ const scan = vi.fn(async () => [server]);++ const result = await startBackgroundPreview(projectDir, 3002, {+ scan,+ spawn,+ stateHome: mkdtempSync(join(tmpdir(), "hf-preview-state-")),+ preferredPort: server.port,+ });++ expect(result).toMatchObject({ type: "reused", port: server.port });+ expect(spawn).not.toHaveBeenCalled();+ });+it("discovers managed previews outside the default port scan and removes stale records", async () => {const stateHome = tempDir("hf-preview-state-");const otherProjectDir = resolve("/tmp/hyperframes-preview-managed-custom-port");@@ -385,6 +436,195 @@ describe("background preview lifecycle", () => {).toMatchObject({ pid: 4321 });});+ it("reports the explicitly requested port when the detached child binds it", async () => {+ const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));+ const dependencies = reachableChildDependencies(stateHome);++ const result = await startBackgroundPreview(projectDir, server.port, {+ ...dependencies,+ preferredPort: server.port,+ });++ expect(result).toMatchObject({ type: "started", port: server.port, pid: 9876 });+ expect(dependencies.kill).not.toHaveBeenCalled();+ expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(true);+ });++ it("reaps a detached child that could not bind the explicitly requested port", async () => {+ // The child scans upward from --port and lands on the next free port.+ const requestedPort = server.port - 1;+ const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));+ const dependencies = reachableChildDependencies(stateHome);++ const launch = startBackgroundPreview(projectDir, requestedPort, {+ ...dependencies,+ preferredPort: requestedPort,+ });++ await expect(launch).rejects.toThrow(PreviewPortUnavailableError);+ await expect(launch).rejects.toMatchObject({ requestedPort, boundPort: server.port });+ // The wrapper PID is reaped, not the server's self-reported PID.+ expect(dependencies.kill).toHaveBeenCalledExactlyOnceWith(4321);+ expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(false);+ });++ it("fails loudly when the reaped child keeps serving the substitute port", async () => {+ const requestedPort = server.port - 1;+ const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));+ const dependencies = reachableChildDependencies(stateHome, { immortal: true });++ await expect(+ startBackgroundPreview(projectDir, requestedPort, {+ ...dependencies,+ preferredPort: requestedPort,+ }),+ ).rejects.toThrow(/did not stop after failing to bind port/);+ expect(dependencies.kill).toHaveBeenCalledExactlyOnceWith(4321);+ expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(false);+ });++ it("keeps the next free port when no explicit port was requested", async () => {+ const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));+ const dependencies = reachableChildDependencies(stateHome);++ const result = await startBackgroundPreview(projectDir, server.port - 1, dependencies);++ expect(result).toMatchObject({ type: "started", port: server.port });+ expect(dependencies.kill).not.toHaveBeenCalled();+ });++ it("reuses the same-project server on the explicit port when several are running", async () => {+ const sibling = { ...server, port: server.port + 1, pid: "5555" };+ const spawn = vi.fn();++ const result = await startBackgroundPreview(projectDir, 3002, {+ scan: async () => [server, sibling],+ spawn,+ stateHome: mkdtempSync(join(tmpdir(), "hf-preview-state-")),+ preferredPort: sibling.port,+ });++ expect(result).toMatchObject({ type: "reused", port: sibling.port, pid: 5555 });+ expect(spawn).not.toHaveBeenCalled();+ });++ it("reuses the unmanaged sibling on the explicit port instead of rejecting against the owned server", async () => {+ const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));+ const owned = { ...server, port: 3002 };+ const sibling = { ...server, port: 3003, pid: "5555" };+ writePreviewSession(+ { pid: 4321, port: owned.port, projectDir, logPath: "/tmp/preview.log" },+ stateHome,+ );+ const spawn = vi.fn();+ const kill = vi.fn();++ const result = await startBackgroundPreview(projectDir, 3002, {+ kill,+ scan: async () => [owned, sibling],+ spawn,+ stateHome,+ preferredPort: sibling.port,+ });++ expect(result).toMatchObject({ type: "reused", port: sibling.port, pid: 5555 });+ expect(spawn).not.toHaveBeenCalled();+ expect(kill).not.toHaveBeenCalled();+ });++ it("lists every same-project server in the port-mismatch error, not just the reuse candidate", async () => {+ const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));+ const owned = { ...server, port: 3002 };+ const sibling = { ...server, port: 3003, pid: "5555" };+ const foreign = {+ ...server,+ port: 3004,+ projectDir: resolve("/tmp/hyperframes-preview-lifecycle-other"),+ pid: "7777",+ };+ writePreviewSession(+ { pid: 4321, port: owned.port, projectDir, logPath: "/tmp/preview.log" },+ stateHome,+ );+ const spawn = vi.fn();++ const failure = await startBackgroundPreview(projectDir, 3002, {+ scan: async () => [owned, sibling, foreign],+ spawn,+ stateHome,+ preferredPort: 3004,+ }).then(+ () => null,+ (error: unknown) => error,+ );++ expect(failure).toBeInstanceOf(PreviewServerPortMismatchError);+ expect(failure).toMatchObject({ requestedPort: 3004, ports: [3002, 3003] });+ expect((failure as Error).message).toContain("add --force-new or run --stop first");+ expect(spawn).not.toHaveBeenCalled();+ });++ it("reuses a same-project server on an explicit port outside the saved port's scan window", async () => {+ const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));+ const owned = { ...server, port: 3002 };+ const farSibling = { ...server, port: 3500, pid: "5555" };+ writePreviewSession(+ { pid: 4321, port: owned.port, projectDir, logPath: "/tmp/preview.log" },+ stateHome,+ );+ const spawn = vi.fn();+ const probe = vi.fn(async (port: number) => (port === farSibling.port ? farSibling : null));++ const result = await startBackgroundPreview(projectDir, farSibling.port, {+ scan: async () => [owned],+ probe,+ spawn,+ stateHome,+ preferredPort: farSibling.port,+ });++ expect(result).toMatchObject({ type: "reused", port: farSibling.port, pid: 5555 });+ expect(probe).toHaveBeenCalledExactlyOnceWith(farSibling.port);+ expect(spawn).not.toHaveBeenCalled();+ });++ it("replaces the owned server on the explicit port when the GPU policy changes", async () => {+ const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));+ const owned = { ...server, port: 3002, browserGpuMode: "hardware" as const };+ const replacement = { ...server, port: 3002, pid: "5432", browserGpuMode: "software" as const };+ writePreviewSession(+ { pid: 4321, port: owned.port, projectDir, logPath: "/tmp/preview.log" },+ stateHome,+ );+ let ownedRunning = true;+ let replacementRunning = false;+ const scan = vi.fn(async () => [+ ...(ownedRunning ? [owned] : []),+ ...(replacementRunning ? [replacement] : []),+ ]);+ const kill = vi.fn((pid: number) => {+ if (pid === 4321) ownedRunning = false;+ });+ const spawn = vi.fn(() => {+ replacementRunning = true;+ return { pid: 5432, unref: vi.fn() };+ });++ const result = await startBackgroundPreview(projectDir, 3002, {+ browserGpuMode: "software",+ kill,+ scan,+ sleep: async () => {},+ spawn,+ stateHome,+ preferredPort: 3002,+ });++ expect(kill).toHaveBeenCalledWith(4321);+ expect(spawn).toHaveBeenCalledOnce();+ expect(result).toMatchObject({ type: "started", port: 3002, pid: 5432 });+ });+it("reaps a detached child that never becomes reachable without recording ownership", async () => {const stateHome = tempDir("hf-preview-state-");const kill = vi.fn();diff --git a/packages/cli/src/commands/previewLifecycle.ts b/packages/cli/src/commands/previewLifecycle.tsindex 57bb8b311f..354141db92 100644--- a/packages/cli/src/commands/previewLifecycle.ts+++ b/packages/cli/src/commands/previewLifecycle.ts@@ -13,10 +13,30 @@ import {} from "node:fs";import { homedir } from "node:os";import { dirname, join, resolve } from "node:path";-import { scanActiveServers, type ActiveServer } from "../server/portUtils.js";+import {+ activeServerOnPort,+ MAX_PORT_SCAN,+ scanActiveServers,+ type ActiveServer,+} from "../server/portUtils.js";import type { BrowserGpuMode } from "../browser/gpuPolicy.js";import { isProcessDescendant, processIdentity } from "../utils/orphanCleanup.js";import { terminateProcessTree } from "../utils/processTree.js";+import { PreviewServerPortMismatchError } from "../utils/studioSelectionClient.js";++export class PreviewPortUnavailableError extends Error {+ readonly requestedPort: number;+ readonly boundPort: number;++ constructor(requestedPort: number, boundPort: number) {+ super(+ `Port ${requestedPort} is already in use; the background preview would have started on port ${boundPort} instead. Free port ${requestedPort}, pick another --port, or omit --port to accept the next free port.`,+ );+ this.name = "PreviewPortUnavailableError";+ this.requestedPort = requestedPort;+ this.boundPort = boundPort;+ }+}export interface PreviewSession {pid: number;@@ -47,9 +67,12 @@ interface LifecycleDependencies {isDescendant?: (childPid: number, ancestorPid: number) => boolean;identity?: (pid: number) => string | null;isSignalable?: (pid: number) => boolean;+ probe?: (port: number) => Promise<ActiveServer | null>;stateHome?: string;forceNew?: boolean;browserGpuMode?: BrowserGpuMode;+ /** Set only when the caller explicitly passed --port, not the CLI default. */+ preferredPort?: number;}function defaultStateHome(): string {@@ -160,12 +183,16 @@ function matchingServer(projectDir: string,browserGpuMode?: BrowserGpuMode,): ActiveServer | null {- return (- servers.find(- (server) =>- normalized(server.projectDir) === normalized(projectDir) &&- (browserGpuMode === undefined || server.browserGpuMode === browserGpuMode),- ) ?? null+ return policyMatchingServers(servers, projectDir, browserGpuMode)[0] ?? null;+}++function policyMatchingServers(+ servers: ActiveServer[],+ projectDir: string,+ browserGpuMode?: BrowserGpuMode,+): ActiveServer[] {+ return sameProjectServers(servers, projectDir).filter(+ (server) => browserGpuMode === undefined || server.browserGpuMode === browserGpuMode,);}@@ -180,13 +207,13 @@ function matchingServerAtPort();}-function sameProjectPorts(servers: ActiveServer[], projectDir: string): Set<number> {+function sameProjectServers(servers: ActiveServer[], projectDir: string): ActiveServer[] {const project = normalized(projectDir);- return new Set(- servers- .filter((server) => normalized(server.projectDir) === project)- .map((server) => server.port),- );+ return servers.filter((server) => normalized(server.projectDir) === project);+}++function sameProjectPorts(servers: ActiveServer[], projectDir: string): Set<number> {+ return new Set(sameProjectServers(servers, projectDir).map((server) => server.port));}async function stopProcess(pid: number): Promise<void> {@@ -433,39 +460,80 @@ async function readPreviewLifecycleState(return { scan, stateHome, saved, scanStart, scanned };}+function unmetPreferredPort(port: number, preferredPort: number | undefined): number | undefined {+ return preferredPort !== undefined && port !== preferredPort ? preferredPort : undefined;+}++type BackgroundPreviewResult =+ | { type: "reused"; port: number; pid: number | null; logPath: string | null }+ | { type: "started"; port: number; pid: number; logPath: string };++function reuseExistingPreview(+ reusableExisting: ActiveServer | null,+ candidates: ActiveServer[],+ dependencies: LifecycleDependencies,+): Extract<BackgroundPreviewResult, { type: "reused" }> | null {+ if (!reusableExisting || dependencies.forceNew) return null;+ const unmet = unmetPreferredPort(reusableExisting.port, dependencies.preferredPort);+ if (unmet !== undefined) {+ throw new PreviewServerPortMismatchError(+ unmet,+ candidates,+ ` To start one on port ${unmet} instead, add --force-new or run --stop first.`,+ );+ }+ return {+ type: "reused",+ port: reusableExisting.port,+ pid: reusableExisting.pid ? Number(reusableExisting.pid) : null,+ logPath: null,+ };+}++// The scan only covers scanStart..+MAX_PORT_SCAN-1; an explicit --port outside it is probed directly.+async function addPreferredPortServer(+ scanned: ActiveServer[],+ scanStart: number,+ dependencies: LifecycleDependencies,+): Promise<void> {+ const preferred = dependencies.preferredPort;+ if (preferred === undefined) return;+ if (preferred >= scanStart && preferred < scanStart + MAX_PORT_SCAN) return;+ const server = await (dependencies.probe ?? activeServerOnPort)(preferred);+ if (server) scanned.push(server);+}+export async function startBackgroundPreview(projectDir: string,startPort: number,dependencies: LifecycleDependencies = {},-): Promise<- | { type: "reused"; port: number; pid: number | null; logPath: string | null }- | { type: "started"; port: number; pid: number; logPath: string }-> {- const { scan, stateHome, saved, scanned } = await readPreviewLifecycleState(+): Promise<BackgroundPreviewResult> {+ const { scan, stateHome, saved, scanStart, scanned } = await readPreviewLifecycleState(projectDir,startPort,dependencies,);+ await addPreferredPortServer(scanned, scanStart, dependencies);// Always inspect a saved custom port first. `--force-new --port <new>` must// replace that owned server before recording the replacement, otherwise the// single per-project ownership record would orphan the old listener.- const requestedExisting = matchingServer(scanned, projectDir, dependencies.browserGpuMode);+ const candidates = policyMatchingServers(scanned, projectDir, dependencies.browserGpuMode);+ // A policy-matching server on the explicit --port satisfies it even when it is not the owned one,+ // so `--port 3003` reuses the 3003 sibling instead of reporting a mismatch against the owned 3002.+ const onPreferredPort =+ candidates.find((server) => server.port === dependencies.preferredPort) ?? null;+ const requestedExisting = candidates[0] ?? null;const ownedExisting = savedOwnedPreview(scanned, saved, projectDir);- // A saved managed preview is the authoritative same-project instance. An- // explicit GPU-policy change replaces it; it must not silently adopt an- // unmanaged sibling that happens to match the new policy.+ // Otherwise a saved managed preview is the authoritative same-project+ // instance. An explicit GPU-policy change replaces it; it must not silently+ // adopt an unmanaged sibling that happens to match the new policy.const reusableOwned = ownedExisting? matchingServer([ownedExisting], projectDir, dependencies.browserGpuMode): null;- const reusableExisting = reusableOwned ?? (ownedExisting ? null : requestedExisting);- if (reusableExisting && !dependencies.forceNew) {- return {- type: "reused",- port: reusableExisting.port,- pid: reusableExisting.pid ? Number(reusableExisting.pid) : null,- logPath: null,- };- }+ const reusableExisting =+ onPreferredPort ?? reusableOwned ?? (ownedExisting ? null : requestedExisting);+ const reused = reuseExistingPreview(reusableExisting, candidates, dependencies);+ if (reused) return reused;await stopOwnedPreviewBeforeReplacement(ownedExisting, projectDir, dependencies);// Snapshot every same-project listener in the prospective launch range only// after the owned listener is gone. Readiness must identify a newly appeared@@ -478,6 +546,47 @@ export async function startBackgroundPreview(dependencies,);+ const kill = dependencies.kill ?? stopProcess;+ const server = await awaitStartedServer(projectDir, startPort, preLaunchPorts, dependencies);+ if (!server) {+ await kill(pid);+ throw new Error(`background preview did not become ready; see ${logPath}`);+ }+ // The child scans upward from --port; one that missed an explicit --port is reaped, never recorded.+ const unmet = unmetPreferredPort(server.port, dependencies.preferredPort);+ if (unmet !== undefined) {+ // Wait until it stops answering so a concurrent launch or --status cannot adopt a dying server.+ await kill(pid);+ if (!(await awaitServerGone(projectDir, startPort, server.port, dependencies))) {+ throw new Error(+ `background preview on port ${server.port} did not stop after failing to bind port ${unmet}; see ${logPath}`,+ );+ }+ throw new PreviewPortUnavailableError(unmet, server.port);+ }+ const ready = readyPreviewSession(+ server,+ pid,+ wrapperIdentity,+ projectDir,+ logPath,+ dependencies,+ );+ writePreviewSession(ready.session, stateHome);+ return {+ type: "started",+ ...ready.session,+ pid: ready.publicPid,+ };+}++async function awaitStartedServer(+ projectDir: string,+ startPort: number,+ preLaunchPorts: Set<number>,+ dependencies: LifecycleDependencies,+): Promise<ActiveServer | null> {+ const scan = dependencies.scan ?? scanActiveServers;const sleep = dependencies.sleep ?? delay;for (let attempt = 0; attempt < 50; attempt++) {const server = startedServer(@@ -486,27 +595,10 @@ export async function startBackgroundPreview(preLaunchPorts,dependencies.browserGpuMode,);- if (server) {- const ready = readyPreviewSession(- server,- pid,- wrapperIdentity,- projectDir,- logPath,- dependencies,- );- writePreviewSession(ready.session, stateHome);- return {- type: "started",- ...ready.session,- pid: ready.publicPid,- };- }+ if (server) return server;await sleep(200);}-- await (dependencies.kill ?? stopProcess)(pid);- throw new Error(`background preview did not become ready; see ${logPath}`);+ return null;}export async function stopBackgroundPreview(@@ -514,7 +606,7 @@ export async function stopBackgroundPreview(startPort: number,dependencies: LifecycleDependencies = {},): Promise<boolean> {- const { scan, stateHome, saved, scanStart, scanned } = await readPreviewLifecycleState(+ const { stateHome, saved, scanStart, scanned } = await readPreviewLifecycleState(projectDir,startPort,dependencies,@@ -537,13 +629,24 @@ export async function stopBackgroundPreview(const kill = dependencies.kill ?? stopProcess;await kill(ownedStopTargetPid(saved, pid, dependencies));+ if (!(await awaitServerGone(projectDir, scanStart, server.port, dependencies))) {+ throw new Error(`background preview did not stop for ${resolve(projectDir)}`);+ }+ removePreviewSession(projectDir, stateHome);+ return true;+}++async function awaitServerGone(+ projectDir: string,+ scanStart: number,+ port: number,+ dependencies: LifecycleDependencies,+): Promise<boolean> {+ const scan = dependencies.scan ?? scanActiveServers;const sleep = dependencies.sleep ?? delay;for (let attempt = 0; attempt < 25; attempt++) {- if (!matchingServerAtPort(await scan(scanStart), projectDir, server.port)) {- removePreviewSession(projectDir, stateHome);- return true;- }+ if (!matchingServerAtPort(await scan(scanStart), projectDir, port)) return true;await sleep(100);}- throw new Error(`background preview did not stop for ${resolve(projectDir)}`);+ return false;}diff --git a/packages/cli/src/server/portUtils.ts b/packages/cli/src/server/portUtils.tsindex 44de5a60c4..2f81597468 100644--- a/packages/cli/src/server/portUtils.ts+++ b/packages/cli/src/server/portUtils.ts@@ -20,7 +20,7 @@ import type { BrowserGpuMode } from "../browser/gpuPolicy.js";const execFileAsync = promisify(execFile);/** Max ports to scan before giving up. */-const MAX_PORT_SCAN = 100;+export const MAX_PORT_SCAN = 100;/** Localhost HTTP probe timeout — HyperFrames responds in <1ms, so 300ms is generous. */const PROBE_TIMEOUT_MS = 300;diff --git a/packages/cli/src/utils/studioSelectionClient.ts b/packages/cli/src/utils/studioSelectionClient.tsindex 9a44eb351b..8f64a887a1 100644--- a/packages/cli/src/utils/studioSelectionClient.ts+++ b/packages/cli/src/utils/studioSelectionClient.ts@@ -36,10 +36,10 @@ export class PreviewServerPortMismatchError extends Error {readonly requestedPort: number;readonly ports: number[];- constructor(requestedPort: number, servers: ActiveServer[]) {+ constructor(requestedPort: number, servers: ActiveServer[], hint = "") {const ports = servers.map((server) => server.port).sort((a, b) => a - b);super(- `No Studio preview server for this project is running on port ${requestedPort}. Matching server port${ports.length === 1 ? "" : "s"}: ${ports.join(", ")}. Rerun with --port ${ports[0]}${ports.length > 1 ? " or omit --port to see all candidates" : ""}.`,+ `No Studio preview server for this project is running on port ${requestedPort}. Matching server port${ports.length === 1 ? "" : "s"}: ${ports.join(", ")}. Rerun with --port ${ports[0]}${ports.length > 1 ? " or omit --port to see all candidates" : ""}.${hint}`,);this.name = "PreviewServerPortMismatchError";this.requestedPort = requestedPort;