@xfey/tutti 0.1.42 → 0.1.44

package/dist/artifacts/preview-runtime.js

@@ -1,28 +1,37 @@
-import { spawn } from "node:child_process";
-import { tmpdir } from "node:os";
-import { resolve } from "node:path";
+import { lstatSync, realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
 import { redactAndTruncateText } from "@tutti/shared/utils";
 import { WorkspaceOpsError } from "../workspace-ops/errors.js";
 import { ARTIFACT_PREVIEW_BASE_PATH, readArtifactDeclaration, } from "./manifest.js";
+import { allocateArtifactPreviewPort, ArtifactDiagnosticBuffer, cleanupArtifactProcessRuntime, createArtifactPreviewEnv, createArtifactProcessRuntime, spawnArtifactPreviewProcess, terminateArtifactProcessTree, } from "./process-boundary.js";
 import { rewriteArtifactPreviewResourceUrls } from "./static-preview.js";
+export const ARTIFACT_PREVIEW_REQUEST_BODY_LIMIT_BYTES = 1024 * 1024;
+export const ARTIFACT_PREVIEW_RESPONSE_BODY_LIMIT_BYTES = 5 * 1024 * 1024;
 const DEFAULT_READY_TIMEOUT_MS = 20_000;
 const DEFAULT_READY_PROBE_INTERVAL_MS = 250;
+const DEFAULT_READY_PROBE_REQUEST_TIMEOUT_MS = 2_000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const DEFAULT_IDLE_STOP_TTL_MS = 120_000;
-const MAX_DIAGNOSTIC_CHARS = 8_000;
-const MIN_DYNAMIC_PORT = 49152;
-const MAX_DYNAMIC_PORT = 65535;
-const SAFE_ENV_NAMES = new Set([
-    "PATH",
-    "LANG",
-    "LC_ALL",
-    "LC_CTYPE",
-    "TMPDIR",
-    "TEMP",
-    "TMP",
+const MAX_READY_REDIRECTS = 3;
+const MAX_PORT_LAUNCH_ATTEMPTS = 2;
+const ALLOWED_REQUEST_HEADERS = new Set([
+    "accept",
+    "accept-language",
+    "cache-control",
+    "content-type",
+    "if-match",
+    "if-modified-since",
+    "if-none-match",
+    "if-unmodified-since",
+    "pragma",
+    "range",
+    "sec-fetch-dest",
+    "sec-fetch-mode",
+    "sec-fetch-site",
 ]);
 const RESPONSE_HEADER_DENYLIST = new Set([
     "connection",
+    "content-encoding",
     "content-length",
     "keep-alive",
     "proxy-authenticate",
@@ -34,60 +43,22 @@ const RESPONSE_HEADER_DENYLIST = new Set([
     "upgrade",
     "www-authenticate",
 ]);
-function defaultAllocatePort() {
-    const range = MAX_DYNAMIC_PORT - MIN_DYNAMIC_PORT + 1;
-    return MIN_DYNAMIC_PORT + Math.floor(Math.random() * range);
-}
-function defaultSpawnProcess(plan) {
-    const child = spawn(plan.command, plan.args, {
-        cwd: plan.cwd,
-        env: plan.env,
-        shell: false,
-        stdio: ["pipe", "pipe", "pipe"],
-    });
-    child.stdin.end();
-    return child;
-}
-function createArtifactPreviewEnv(options) {
-    const env = {};
-    for (const name of SAFE_ENV_NAMES) {
-        const value = options.sourceEnv[name];
-        if (value !== undefined && value.trim() !== "") {
-            env[name] = value;
-        }
-    }
-    env.HOME = tmpdir();
-    env.TMPDIR = env.TMPDIR ?? tmpdir();
-    env.HOST = "127.0.0.1";
-    env.PORT = String(options.port);
-    env.TUTTI_ARTIFACT_PREVIEW = "1";
-    env.npm_config_update_notifier = "false";
-    env.npm_config_fund = "false";
-    env.npm_config_audit = "false";
-    return env;
-}
-function appendDiagnostic(existing, chunk) {
-    const next = `${existing}${redactAndTruncateText(chunk.toString("utf8"), MAX_DIAGNOSTIC_CHARS)}`;
-    if (next.length <= MAX_DIAGNOSTIC_CHARS) {
-        return next;
-    }
-    return next.slice(next.length - MAX_DIAGNOSTIC_CHARS);
+const SENSITIVE_RESPONSE_HEADER_PATTERN = /authorization|cookie|credential|proxy-auth|secret|token|x-api[-_]?key/iu;
+function isServerDeclaration(declaration) {
+    return declaration.status === "declared" && declaration.runtime.kind === "server";
 }
 function serverDeclarationKey(declaration) {
     return [
         declaration.manifest_blob_oid,
         declaration.runtime.cwd_path,
-        declaration.runtime.ready_path,
+        declaration.runtime.entry_path,
     ].join(":");
 }
 function buildServerPreviewUrl(options) {
     const basePath = (options.basePath ?? ARTIFACT_PREVIEW_BASE_PATH).replace(/\/+$/u, "");
-    const normalizedReadyPath = options.readyPath === "/" ? "/" : `/${options.readyPath.replace(/^\/+/u, "")}`;
-    const separator = normalizedReadyPath.includes("?") ? "&" : "?";
-    return `${basePath}${normalizedReadyPath}${separator}v=${encodeURIComponent(options.manifestBlobOid)}&preview=${encodeURIComponent(options.instanceId)}`;
-}
-function isServerDeclaration(declaration) {
-    return declaration.status === "declared" && declaration.runtime.kind === "server";
+    const normalizedEntryPath = options.entryPath === "/" ? "/" : `/${options.entryPath.replace(/^\/+/, "")}`;
+    const separator = normalizedEntryPath.includes("?") ? "&" : "?";
+    return `${basePath}${normalizedEntryPath}${separator}v=${encodeURIComponent(options.manifestBlobOid)}&preview=${encodeURIComponent(options.instanceId)}`;
 }
 function declarationInvalidDisposition(declaration) {
     const disposition = {
@@ -109,7 +80,7 @@ function projectionWithServerState(options) {
         artifact: {
             title: artifact.title,
             kind: "server",
-            network: artifact.network ?? false,
+            network: artifact.network,
         },
         preview: {
             status: "stopped",
@@ -126,7 +97,7 @@ function projectionWithServerState(options) {
                 status: "ready",
                 url: buildServerPreviewUrl({
                     basePath: options.previewBasePath,
-                    readyPath: state.readyPath,
+                    entryPath: state.entryPath,
                     manifestBlobOid: state.manifestBlobOid,
                     instanceId: state.instanceId,
                 }),
@@ -141,15 +112,22 @@ function projectionWithServerState(options) {
         },
     };
 }
-function filteredResponseHeaders(headers) {
-    const result = {};
-    headers.forEach((value, key) => {
-        const normalized = key.toLowerCase();
-        if (!RESPONSE_HEADER_DENYLIST.has(normalized)) {
-            result[normalized] = value;
+function isContainedPath(root, target) {
+    const relativePath = relative(root, target);
+    return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+function resolveServerCwd(workspaceRoot, cwdPath) {
+    try {
+        const repoRealPath = realpathSync.native(workspaceRoot);
+        const cwdRealPath = realpathSync.native(resolve(repoRealPath, cwdPath));
+        if (!isContainedPath(repoRealPath, cwdRealPath) || !lstatSync(cwdRealPath).isDirectory()) {
+            throw new Error("Server artifact cwd is not a contained directory");
         }
-    });
-    return result;
+        return cwdRealPath;
+    }
+    catch {
+        throw new WorkspaceOpsError("validation_failed", "Server artifact cwd is not usable");
+    }
 }
 function normalizePreviewRequestPath(path) {
     if (path === undefined || path.trim() === "") {
@@ -157,40 +135,151 @@ function normalizePreviewRequestPath(path) {
     }
     const withoutQuery = path.split("?")[0] ?? "";
     const normalized = withoutQuery.startsWith("/") ? withoutQuery : `/${withoutQuery}`;
-    if (normalized.includes("..")) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(normalized);
+    }
+    catch {
+        throw new WorkspaceOpsError("bad_request", "Artifact preview path is invalid");
+    }
+    if (decoded.includes("\\") ||
+        decoded.includes("\0") ||
+        decoded.split("/").some((segment) => segment === "." || segment === "..")) {
         throw new WorkspaceOpsError("forbidden", "Artifact preview path is not allowed");
     }
     return normalized;
 }
+function responseLooksLikeHtml(content) {
+    const prefix = content.subarray(0, 1024).toString("utf8").trimStart().toLowerCase();
+    return prefix.startsWith("<!doctype html") || prefix.startsWith("<html");
+}
+async function readBoundedResponseBody(response, maxBytes) {
+    const contentLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+        throw new WorkspaceOpsError("validation_failed", "Artifact preview response is too large");
+    }
+    if (response.body === null) {
+        return Buffer.alloc(0);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const result = await reader.read();
+            if (result.done) {
+                break;
+            }
+            const value = result.value;
+            if (!(value instanceof Uint8Array)) {
+                throw new WorkspaceOpsError("validation_failed", "Artifact preview response body is invalid");
+            }
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel();
+                throw new WorkspaceOpsError("validation_failed", "Artifact preview response is too large");
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, total);
+}
+function filteredResponseHeaders(headers) {
+    const result = {};
+    headers.forEach((value, key) => {
+        const normalized = key.toLowerCase();
+        if (!RESPONSE_HEADER_DENYLIST.has(normalized) &&
+            !SENSITIVE_RESPONSE_HEADER_PATTERN.test(normalized) &&
+            normalized !== "location") {
+            result[normalized] = value;
+        }
+    });
+    return result;
+}
+function sanitizeRequestHeaders(headers) {
+    const result = {};
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        const normalized = name.toLowerCase();
+        if (value !== undefined && ALLOWED_REQUEST_HEADERS.has(normalized)) {
+            result[normalized] = value;
+        }
+    }
+    return result;
+}
+function safeRedirectLocation(options) {
+    const redirected = new URL(options.location, options.localUrl);
+    if (redirected.origin !== options.localUrl.origin) {
+        throw new WorkspaceOpsError("validation_failed", "Artifact preview redirect left the managed preview instance");
+    }
+    redirected.searchParams.set("v", options.state.manifestBlobOid);
+    redirected.searchParams.set("preview", options.state.instanceId);
+    return `${ARTIFACT_PREVIEW_BASE_PATH}${redirected.pathname}${redirected.search}${redirected.hash}`;
+}
+function unrefTimer(timer) {
+    if (typeof timer === "object" && "unref" in timer && typeof timer.unref === "function") {
+        timer.unref();
+    }
+}
+function processIsAlive(child) {
+    return child !== undefined && child.exitCode === null && child.signalCode === null;
+}
+export function isArtifactPreviewHttpMethod(method) {
+    return (method === "GET" ||
+        method === "HEAD" ||
+        method === "POST" ||
+        method === "PUT" ||
+        method === "PATCH" ||
+        method === "DELETE" ||
+        method === "OPTIONS");
+}
 export class ArtifactPreviewManager {
     now;
     baseEnv;
     spawnProcess;
+    terminateProcess;
     fetchImpl;
     allocatePort;
+    createProcessRuntime;
+    cleanupProcessRuntime;
     clockMs;
     setTimeoutFn;
     clearTimeoutFn;
     onStatusChange;
     readyTimeoutMs;
     readyProbeIntervalMs;
+    readyProbeRequestTimeoutMs;
     requestTimeoutMs;
+    requestBodyLimitBytes;
+    responseBodyLimitBytes;
     idleStopTtlMs;
+    pendingTasks = new Set();
     state;
     nextInstanceSequence = 0;
     constructor(options = {}) {
         this.now = options.now ?? (() => new Date());
         this.baseEnv = options.baseEnv ?? process.env;
-        this.spawnProcess = options.spawnProcess ?? defaultSpawnProcess;
+        this.spawnProcess = options.spawnProcess ?? spawnArtifactPreviewProcess;
+        this.terminateProcess = options.terminateProcess ?? terminateArtifactProcessTree;
         this.fetchImpl = options.fetchImpl ?? fetch;
-        this.allocatePort = options.allocatePort ?? defaultAllocatePort;
+        this.allocatePort = options.allocatePort ?? allocateArtifactPreviewPort;
+        this.createProcessRuntime = options.createProcessRuntime ?? createArtifactProcessRuntime;
+        this.cleanupProcessRuntime = options.cleanupProcessRuntime ?? cleanupArtifactProcessRuntime;
         this.clockMs = options.clockMs ?? (() => Date.now());
         this.setTimeoutFn = options.setTimeoutFn ?? setTimeout;
         this.clearTimeoutFn = options.clearTimeoutFn ?? clearTimeout;
         this.onStatusChange = options.onStatusChange ?? (() => { });
         this.readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
         this.readyProbeIntervalMs = options.readyProbeIntervalMs ?? DEFAULT_READY_PROBE_INTERVAL_MS;
+        this.readyProbeRequestTimeoutMs =
+            options.readyProbeRequestTimeoutMs ?? DEFAULT_READY_PROBE_REQUEST_TIMEOUT_MS;
         this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.requestBodyLimitBytes =
+            options.requestBodyLimitBytes ?? ARTIFACT_PREVIEW_REQUEST_BODY_LIMIT_BYTES;
+        this.responseBodyLimitBytes =
+            options.responseBodyLimitBytes ?? ARTIFACT_PREVIEW_RESPONSE_BODY_LIMIT_BYTES;
         this.idleStopTtlMs = options.idleStopTtlMs ?? DEFAULT_IDLE_STOP_TTL_MS;
     }
     readProjection(options) {
@@ -296,7 +385,8 @@ export class ArtifactPreviewManager {
                 result: { artifact: declaration.projection },
             };
         }
-        if (!isServerDeclaration(declaration) || this.state?.key !== serverDeclarationKey(declaration)) {
+        if (!isServerDeclaration(declaration) ||
+            this.state?.key !== serverDeclarationKey(declaration)) {
             return {
                 disposition: { kind: "not_running" },
                 result: {
@@ -354,7 +444,8 @@ export class ArtifactPreviewManager {
                 result: { artifact: declaration.projection },
             };
         }
-        if (!isServerDeclaration(declaration) || this.state?.key !== serverDeclarationKey(declaration)) {
+        if (!isServerDeclaration(declaration) ||
+            this.state?.key !== serverDeclarationKey(declaration)) {
             return {
                 disposition: { kind: "not_running" },
                 result: { artifact: declaration.projection },
@@ -374,50 +465,87 @@ export class ArtifactPreviewManager {
         };
     }
     async fetchServerPreview(options) {
+        if (options.body !== undefined && options.body.byteLength > this.requestBodyLimitBytes) {
+            throw new WorkspaceOpsError("validation_failed", "Artifact preview request is too large");
+        }
+        if ((options.method === "GET" || options.method === "HEAD") && options.body !== undefined) {
+            throw new WorkspaceOpsError("bad_request", "Artifact preview request method cannot have a body");
+        }
         const declaration = readArtifactDeclaration({
             workspaceRoot: options.workspaceRoot,
             now: this.now,
         });
         this.stopStaleRuntime(declaration);
-        if (!isServerDeclaration(declaration) || this.state?.key !== serverDeclarationKey(declaration)) {
+        const state = this.state;
+        if (!isServerDeclaration(declaration) || state?.key !== serverDeclarationKey(declaration)) {
             throw new WorkspaceOpsError("not_found", "Artifact preview is not running");
         }
-        if (this.state.status !== "ready") {
+        if (state.status !== "ready" || state.port === undefined || !processIsAlive(state.child)) {
+            if (state.status === "ready") {
+                this.failState(state, "Preview process is no longer running");
+            }
             throw new WorkspaceOpsError("validation_failed", "Artifact preview is not ready");
         }
         const requestPath = normalizePreviewRequestPath(options.path);
-        const localUrl = new URL(`http://127.0.0.1:${this.state.port}${requestPath}`);
-        const query = options.query?.replace(/^\?/u, "");
-        if (query !== undefined && query.length > 0) {
-            localUrl.search = query;
-            localUrl.searchParams.delete("v");
+        const localUrl = new URL(`http://127.0.0.1:${state.port}${requestPath}`);
+        const query = new URLSearchParams(options.query?.replace(/^\?/u, "") ?? "");
+        const requestedManifestBlobOid = query.get("v");
+        if (requestedManifestBlobOid !== null && requestedManifestBlobOid !== state.manifestBlobOid) {
+            throw new WorkspaceOpsError("not_found", "Artifact preview manifest is stale");
+        }
+        const requestedInstanceId = query.get("preview");
+        if (requestedInstanceId !== null && requestedInstanceId !== state.instanceId) {
+            throw new WorkspaceOpsError("not_found", "Artifact preview instance is stale");
+        }
+        query.delete("v");
+        query.delete("preview");
+        localUrl.search = query.toString();
+        const requestHeaders = sanitizeRequestHeaders(options.headers);
+        if (options.headers?.origin !== undefined) {
+            requestHeaders.origin = localUrl.origin;
         }
         const controller = new AbortController();
         const timeout = this.setTimeoutFn(() => controller.abort(), this.requestTimeoutMs);
+        unrefTimer(timeout);
         try {
             const response = await this.fetchImpl(localUrl, {
-                method: "GET",
-                headers: {
-                    ...(options.headers?.accept === undefined ? {} : { accept: options.headers.accept }),
-                    ...(options.headers?.["accept-language"] === undefined
-                        ? {}
-                        : { "accept-language": options.headers["accept-language"] }),
-                },
+                method: options.method,
+                headers: requestHeaders,
+                ...(options.body === undefined ? {} : { body: options.body }),
                 redirect: "manual",
                 signal: controller.signal,
             });
+            const content = await readBoundedResponseBody(response, this.responseBodyLimitBytes);
+            if (this.state !== state ||
+                state.status !== "ready" ||
+                state.port === undefined ||
+                !processIsAlive(state.child)) {
+                throw new WorkspaceOpsError("not_found", "Artifact preview instance is stale");
+            }
             const headers = filteredResponseHeaders(response.headers);
-            const content = rewriteArtifactPreviewResourceUrls({
+            const location = response.headers.get("location");
+            if (location !== null) {
+                headers.location = safeRedirectLocation({ location, localUrl, state });
+            }
+            const rewrittenContent = rewriteArtifactPreviewResourceUrls({
                 mediaType: headers["content-type"],
                 resourcePath: requestPath,
-                content: Buffer.from(await response.arrayBuffer()),
+                content,
             });
             return {
                 status_code: response.status,
                 headers,
-                content,
+                content: rewrittenContent,
             };
         }
+        catch (error) {
+            if (error instanceof WorkspaceOpsError) {
+                throw error;
+            }
+            throw new WorkspaceOpsError("validation_failed", controller.signal.aborted
+                ? "Artifact preview request timed out"
+                : "Artifact preview request failed");
+        }
         finally {
             this.clearTimeoutFn(timeout);
         }
@@ -432,54 +560,91 @@ export class ArtifactPreviewManager {
         }
         this.stopCurrentProcess();
     }
-    stopAll() {
+    async stopAll() {
         this.stopCurrentProcess();
+        while (this.pendingTasks.size > 0) {
+            await Promise.all([...this.pendingTasks]);
+        }
     }
     startProcess(workspaceRoot, declaration) {
-        const port = this.allocatePort();
-        const cwd = resolve(workspaceRoot, declaration.runtime.cwd_path);
-        const plan = {
-            command: "npm",
-            args: ["run", "artifact:preview"],
-            cwd,
-            env: createArtifactPreviewEnv({
-                sourceEnv: this.baseEnv,
-                port,
-            }),
-            port,
-        };
-        const child = this.spawnProcess(plan);
         const state = {
             key: serverDeclarationKey(declaration),
             manifestBlobOid: declaration.manifest_blob_oid,
-            readyPath: declaration.runtime.ready_path,
-            port,
+            entryPath: declaration.runtime.entry_path,
+            cwdPath: resolveServerCwd(workspaceRoot, declaration.runtime.cwd_path),
             status: "starting",
-            child,
+            child: undefined,
+            processRuntime: undefined,
+            port: undefined,
             instanceId: this.nextInstanceId(),
+            launchAttempt: 0,
             lastHeartbeatAtMs: this.clockMs(),
             errorMessage: undefined,
-            diagnostics: "",
+            diagnostics: new ArtifactDiagnosticBuffer(),
             idleTimer: undefined,
         };
         this.state = state;
         this.scheduleIdleSweep(state);
-        this.attachProcessListeners(state, child);
         this.onStatusChange();
-        void this.waitUntilReady(state);
+        this.trackTask(this.launchProcess(state));
     }
-    attachProcessListeners(state, child) {
-        child.stdout.on("data", (chunk) => {
-            state.diagnostics = appendDiagnostic(state.diagnostics, chunk);
-        });
-        child.stderr.on("data", (chunk) => {
-            state.diagnostics = appendDiagnostic(state.diagnostics, chunk);
-        });
+    async launchProcess(state) {
+        if (this.state !== state || state.status !== "starting") {
+            return;
+        }
+        state.launchAttempt += 1;
+        const runtime = this.createProcessRuntime();
+        state.processRuntime = runtime;
+        try {
+            const port = await this.allocatePort();
+            if (this.state !== state || state.status !== "starting") {
+                this.cleanupStateRuntime(state, runtime);
+                return;
+            }
+            const plan = {
+                command: "npm",
+                args: ["run", "artifact:preview"],
+                cwd: state.cwdPath,
+                env: createArtifactPreviewEnv({
+                    sourceEnv: this.baseEnv,
+                    port,
+                    runtime,
+                }),
+                port,
+            };
+            const child = this.spawnProcess(plan);
+            state.port = port;
+            state.child = child;
+            this.attachProcessListeners(state, child, runtime);
+            await this.waitUntilReady(state);
+        }
+        catch (error) {
+            this.cleanupStateRuntime(state, runtime);
+            this.failState(state, redactAndTruncateText(error instanceof Error ? error.message : "Preview process could not start", 220));
+        }
+    }
+    attachProcessListeners(state, child, runtime) {
+        child.stdout.on("data", (chunk) => state.diagnostics.append("stdout", chunk));
+        child.stderr.on("data", (chunk) => state.diagnostics.append("stderr", chunk));
         child.on("error", (error) => {
-            this.failState(state, redactAndTruncateText(error.message, 220));
+            if (state.child === child) {
+                this.failState(state, redactAndTruncateText(error.message, 220));
+            }
         });
         child.on("close", (code, signal) => {
-            if (this.state !== state || state.status === "stopped") {
+            if (this.state !== state || state.child !== child || state.status === "stopped") {
+                this.cleanupStateRuntime(state, runtime);
+                return;
+            }
+            state.child = undefined;
+            state.port = undefined;
+            this.cleanupStateRuntime(state, runtime);
+            const diagnostic = state.diagnostics.read();
+            if (state.status === "starting" &&
+                state.launchAttempt < MAX_PORT_LAUNCH_ATTEMPTS &&
+                /EADDRINUSE/iu.test(diagnostic.text)) {
+                state.diagnostics = new ArtifactDiagnosticBuffer();
+                this.trackTask(this.launchProcess(state));
                 return;
             }
             const reason = code === null ? `signal ${signal ?? "unknown"}` : `exit code ${code}`;
@@ -488,38 +653,98 @@ export class ArtifactPreviewManager {
     }
     async waitUntilReady(state) {
         const deadline = this.clockMs() + this.readyTimeoutMs;
-        const readyUrl = new URL(`http://127.0.0.1:${state.port}${state.readyPath}`);
         while (this.state === state && state.status === "starting" && this.clockMs() < deadline) {
-            try {
-                const controller = new AbortController();
-                const timeout = this.setTimeoutFn(() => controller.abort(), this.readyProbeIntervalMs);
-                try {
-                    const response = await this.fetchImpl(readyUrl, {
-                        method: "GET",
-                        signal: controller.signal,
-                    });
-                    if (response.status >= 200 && response.status < 500) {
-                        state.status = "ready";
-                        state.errorMessage = undefined;
-                        this.onStatusChange();
-                        return;
-                    }
-                }
-                finally {
-                    this.clearTimeoutFn(timeout);
-                }
+            if (state.port === undefined || !processIsAlive(state.child)) {
+                return;
             }
-            catch {
-                // Keep probing until timeout or process exit.
+            const probe = await this.probeReadyEntry(state);
+            if (this.state !== state || state.status !== "starting") {
+                return;
+            }
+            if (probe.kind === "ready") {
+                state.status = "ready";
+                state.errorMessage = undefined;
+                this.onStatusChange();
+                return;
+            }
+            if (probe.kind === "invalid") {
+                this.failState(state, probe.message);
+                return;
             }
             await new Promise((resolveDelay) => {
-                this.setTimeoutFn(resolveDelay, this.readyProbeIntervalMs);
+                const timer = this.setTimeoutFn(resolveDelay, this.readyProbeIntervalMs);
+                unrefTimer(timer);
             });
         }
         if (this.state === state && state.status === "starting") {
             this.failState(state, "Preview did not become ready in time");
         }
     }
+    async probeReadyEntry(state) {
+        if (state.port === undefined) {
+            return { kind: "retry" };
+        }
+        const entryOrigin = `http://127.0.0.1:${state.port}`;
+        let current = new URL(state.entryPath, entryOrigin);
+        for (let redirects = 0; redirects <= MAX_READY_REDIRECTS; redirects += 1) {
+            const controller = new AbortController();
+            const timeout = this.setTimeoutFn(() => controller.abort(), this.readyProbeRequestTimeoutMs);
+            unrefTimer(timeout);
+            let response;
+            try {
+                response = await this.fetchImpl(current, {
+                    method: "GET",
+                    redirect: "manual",
+                    signal: controller.signal,
+                });
+            }
+            catch {
+                return { kind: "retry" };
+            }
+            finally {
+                this.clearTimeoutFn(timeout);
+            }
+            if (response.status >= 300 && response.status < 400) {
+                const location = response.headers.get("location");
+                if (location === null || redirects === MAX_READY_REDIRECTS) {
+                    return { kind: "invalid", message: "Preview entry returned an invalid redirect" };
+                }
+                const redirected = new URL(location, current);
+                if (redirected.origin !== entryOrigin) {
+                    return {
+                        kind: "invalid",
+                        message: "Preview entry redirected outside its managed instance",
+                    };
+                }
+                current = redirected;
+                continue;
+            }
+            if (response.status < 200 || response.status >= 300) {
+                return {
+                    kind: "invalid",
+                    message: `Preview entry returned HTTP ${response.status}`,
+                };
+            }
+            try {
+                const content = await readBoundedResponseBody(response, this.responseBodyLimitBytes);
+                const mediaType = response.headers.get("content-type")?.toLowerCase() ?? "";
+                if (!mediaType.includes("text/html") && !responseLooksLikeHtml(content)) {
+                    return {
+                        kind: "invalid",
+                        message: "Preview entry did not return renderable HTML",
+                    };
+                }
+            }
+            catch (error) {
+                return {
+                    kind: "invalid",
+                    message: error instanceof Error ? error.message : "Preview entry response is invalid",
+                };
+            }
+            return { kind: "ready" };
+        }
+        return { kind: "invalid", message: "Preview entry redirected too many times" };
+    }
     recordHeartbeat(state) {
         state.lastHeartbeatAtMs = this.clockMs();
         this.scheduleIdleSweep(state);
@@ -529,6 +754,7 @@ export class ArtifactPreviewManager {
             this.clearTimeoutFn(state.idleTimer);
         }
         state.idleTimer = this.setTimeoutFn(() => this.sweepIdle(), this.idleStopTtlMs);
+        unrefTimer(state.idleTimer);
     }
     stopStaleRuntime(declaration) {
         if (this.state === undefined) {
@@ -548,12 +774,7 @@ export class ArtifactPreviewManager {
             this.clearTimeoutFn(state.idleTimer);
             state.idleTimer = undefined;
         }
-        if (state.child !== undefined &&
-            state.child.exitCode === null &&
-            state.child.signalCode === null) {
-            state.child.kill("SIGTERM");
-        }
-        state.child = undefined;
+        this.disposeStateProcess(state);
         state.status = "stopped";
         state.errorMessage = undefined;
         this.onStatusChange();
@@ -563,19 +784,43 @@ export class ArtifactPreviewManager {
             return;
         }
         state.status = "failed";
-        state.errorMessage = message;
-        if (state.child !== undefined &&
-            state.child.exitCode === null &&
-            state.child.signalCode === null) {
-            state.child.kill("SIGTERM");
-        }
-        state.child = undefined;
+        state.errorMessage = redactAndTruncateText(message, 220);
         if (state.idleTimer !== undefined) {
             this.clearTimeoutFn(state.idleTimer);
             state.idleTimer = undefined;
         }
+        this.disposeStateProcess(state);
         this.onStatusChange();
     }
+    disposeStateProcess(state) {
+        const child = state.child;
+        const runtime = state.processRuntime;
+        state.child = undefined;
+        state.processRuntime = undefined;
+        state.port = undefined;
+        if (child === undefined) {
+            if (runtime !== undefined) {
+                this.cleanupProcessRuntime(runtime);
+            }
+            return;
+        }
+        this.trackTask(this.terminateProcess(child).finally(() => {
+            if (runtime !== undefined) {
+                this.cleanupProcessRuntime(runtime);
+            }
+        }));
+    }
+    cleanupStateRuntime(state, runtime) {
+        if (state.processRuntime !== runtime) {
+            return;
+        }
+        state.processRuntime = undefined;
+        this.cleanupProcessRuntime(runtime);
+    }
+    trackTask(task) {
+        this.pendingTasks.add(task);
+        void task.finally(() => this.pendingTasks.delete(task));
+    }
     nextInstanceId() {
         this.nextInstanceSequence += 1;
         return `artifact_preview_${this.nextInstanceSequence}`;