Track terminal listening ports in activity events and thread state#43

@@ -129,11 +139,62 @@ function isRetryableShellSpawnError(error: unknown): boolean {
   );
 }
 
-async function checkWindowsSubprocessActivity(terminalPid: number): Promise<boolean> {
+function normalizeRunningPorts(ports: number[]): number[] {
+  if (ports.length === 0) return [];
+  return [...new Set(ports)]
+    .filter((port) => Number.isInteger(port) && port > 0 && port <= MAX_PORT_NUMBER)
+    .toSorted((left, right) => left - right);
+}
+
+function parsePidList(stdout: string): number[] {
+  const pids: number[] = [];
+  for (const line of stdout.split(/\r?\n/g)) {
+    const pid = Number(line.trim());
+    if (!Number.isInteger(pid) || pid <= 0) {
+      continue;
+    }
+    pids.push(pid);
+  }
+  return [...new Set(pids)];
+}
+
+function parsePortList(stdout: string): number[] {
+  const ports: number[] = [];
+  for (const line of stdout.split(/\r?\n/g)) {
+    const port = Number(line.trim());
+    if (!Number.isInteger(port)) {
+      continue;
+    }
+    ports.push(port);
+  }
+  return normalizeRunningPorts(ports);
+}
+
+function portFromAddress(address: string): number | null {
+  const match = address.match(/:(\d+)$/);
+  if (!match?.[1]) return null;
+  const port = Number(match[1]);
+  if (!Number.isInteger(port) || port <= 0 || port > MAX_PORT_NUMBER) {
+    return null;
+  }
+  return port;
+}
+
+function arePortListsEqual(left: number[], right: number[]): boolean {
+  if (left.length !== right.length) return false;
+  for (let index = 0; index < left.length; index += 1) {
+    if (left[index] !== right[index]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+async function collectWindowsChildPids(terminalPid: number): Promise<number[]> {
   const command = [
     `$children = Get-CimInstance Win32_Process -Filter "ParentProcessId = ${terminalPid}" -ErrorAction SilentlyContinue`,
-    "if ($children) { exit 0 }",
-    "exit 1",
+    "if (-not $children) { exit 0 }",
+    "$children | Select-Object -ExpandProperty ProcessId",

@@ -178,32 +256,134 @@ async function checkPosixSubprocessActivity(terminalPid: number): Promise<boolea
       outputMode: "truncate",
     });
     if (psResult.code !== 0) {
-      return false;
+      return [];
     }
 
+    const childrenByParentPid = new Map<number, number[]>();
     for (const line of psResult.stdout.split(/\r?\n/g)) {
       const [pidRaw, ppidRaw] = line.trim().split(/\s+/g);
       const pid = Number(pidRaw);
       const ppid = Number(ppidRaw);
       if (!Number.isInteger(pid) || !Number.isInteger(ppid)) continue;
-      if (ppid === terminalPid) {
-        return true;
+      const children = childrenByParentPid.get(ppid);
+      if (children) {
+        children.push(pid);
+      } else {
+        childrenByParentPid.set(ppid, [pid]);
       }
     }
-    return false;
+
+    const processFamily = new Set<number>([terminalPid]);
+    const pendingParents = [terminalPid];
+    while (pendingParents.length > 0) {
+      const parentPid = pendingParents.shift();
+      if (!parentPid) continue;
+      const childPids = childrenByParentPid.get(parentPid);
+      if (!childPids || childPids.length === 0) continue;
+      for (const childPid of childPids) {
+        if (processFamily.has(childPid)) continue;
+        processFamily.add(childPid);
+        pendingParents.push(childPid);
+      }
+    }
+
+    return [...processFamily];
+  } catch {
+    return [];
+  }
+}
+
+async function checkPosixListeningPorts(processIds: number[]): Promise<number[]> {
+  if (processIds.length === 0) return [];
+
+  const ports = new Set<number>();
+  const pidFilter = new Set(processIds);
+
+  try {
+    const result = await runProcess(
+      "lsof",
+      ["-nP", "-iTCP", "-sTCP:LISTEN", "-p", processIds.join(",")],
+      {
+        timeoutMs: 1_500,
+        allowNonZeroExit: true,
+        maxBufferBytes: 262_144,
+        outputMode: "truncate",
+      },
+    );
+    if (result.code === 0) {
+      for (const line of result.stdout.split(/\r?\n/g)) {
+        const match = line.match(/:(\d+)\s+\(LISTEN\)$/);
+        if (!match?.[1]) continue;
+        const port = Number(match[1]);
+        if (Number.isInteger(port) && port > 0 && port <= MAX_PORT_NUMBER) {
+          ports.add(port);
+        }
+      }
+      return [...ports].toSorted((left, right) => left - right);
+    }

@@ -695,6 +599,50 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
         }
       });
 
+    const inspectWebPortCached = (port: number) =>
+      Effect.gen(function* () {
+        const now = Date.now();
+        for (const [cachedPort, entry] of webPortProbeCache) {
+          if (now - entry.checkedAt > webPortProbeCacheTtlMs) {
+            webPortProbeCache.delete(cachedPort);
+          }
+        }
+
+        const cached = webPortProbeCache.get(port);
+        if (cached) {
+          return cached.isWeb;
+        }
+
+        const isWeb = yield* webPortInspector(port).pipe(Effect.catch(() => Effect.succeed(false)));
+        webPortProbeCache.set(port, {
+          isWeb,
+          checkedAt: Date.now(),
+        });
+        return isWeb;
+      });

@@ -89,6 +89,7 @@ export const terminalRestartedEventSchema = terminalEventBaseSchema.extend({
 export const terminalActivityEventSchema = terminalEventBaseSchema.extend({
   type: z.literal("activity"),
   hasRunningSubprocess: z.boolean(),
+  runningPorts: z.array(z.number().int().min(1).max(65_535)).default([]),

@@ -834,18 +836,29 @@ export class TerminalManager extends EventEmitter<TerminalManagerEvents> {
           if (!liveSession || liveSession.status !== "running" || liveSession.pid !== terminalPid) {
             return;
           }
-          if (liveSession.hasRunningSubprocess === hasRunningSubprocess) {
+          const hasRunningSubprocess = activity.hasRunningSubprocess === true;

@@ -0,0 +1,78 @@
+import { Effect } from "effect";
+
+import type { TerminalProcessInspectionError } from "./Services/TerminalProcessInspector";
+import { parsePidList, parsePortList } from "./utils";
+
+interface InspectorCommandResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+}
+
+interface WindowsRunCommand {
+  (
+    input: Readonly<{
+      operation: string;
+      terminalPid: number;
+      command: string;
+      args: ReadonlyArray<string>;
+      timeoutMs: number;
+      maxOutputBytes: number;
+    }>,
+  ): Effect.Effect<InspectorCommandResult, TerminalProcessInspectionError>;
+}
+
+export const collectWindowsChildPids = Effect.fn("process.collectWindowsChildPids")(function* (
+  terminalPid: number,
+  runCommand: WindowsRunCommand,
+): Effect.fn.Return<number[], TerminalProcessInspectionError> {
+  const command = [
+    `$children = Get-CimInstance Win32_Process -Filter "ParentProcessId = ${terminalPid}" -ErrorAction SilentlyContinue`,
+    "if (-not $children) { exit 0 }",
+    "$children | Select-Object -ExpandProperty ProcessId",
+  ].join("; ");
+  const result = yield* runCommand({
+    operation: "TerminalProcessInspector.collectWindowsChildPids",
+    terminalPid,
+    command: "powershell.exe",
+    args: ["-NoProfile", "-NonInteractive", "-Command", command],
+    timeoutMs: 1_500,
+    maxOutputBytes: 32_768,
+  });
+  if (result.exitCode !== 0) {
+    return [];
+  }
+  return parsePidList(result.stdout);
+});

@@ -800,6 +757,48 @@ export class TerminalManager extends EventEmitter<TerminalManagerEvents> {
     this.subprocessPollTimer = null;
   }
 
+  private async inspectWebPortCached(port: number): Promise<boolean> {
+    const now = Date.now();
+    const cached = this.webPortProbeCache.get(port);
+    if (cached && now - cached.checkedAt <= this.webPortProbeCacheTtlMs) {
+      return cached.isWeb;
+    }
+
+    const inFlight = this.webPortProbeInFlight.get(port);
+    if (inFlight) {
+      return inFlight;
+    }
+
+    const probe = this.webPortInspector(port)
+      .then((isWeb) => {
+        this.webPortProbeCache.set(port, {
+          isWeb,
+          checkedAt: Date.now(),
+        });
+        return isWeb;
+      })
+      .catch(() => false)
+      .finally(() => {
+        this.webPortProbeInFlight.delete(port);
+      });
+    this.webPortProbeInFlight.set(port, probe);
+    return probe;
+  }
+
+  private async detectWebPorts(runningPorts: number[]): Promise<number[]> {
+    if (runningPorts.length === 0) return [];
+    const checks = await Promise.all(
+      runningPorts.map(async (port) => ({
+        port,
+        isWeb: await this.inspectWebPortCached(port),
+      })),
+    );
+    return checks
+      .filter((entry) => entry.isWeb)
+      .map((entry) => entry.port)
+      .toSorted((left, right) => left - right);
+  }

@@ -61,6 +62,30 @@ function normalizeRunningTerminalIds(
     .filter((id) => id.length > 0 && validTerminalIdSet.has(id));
 }
 
+export function normalizeRunningPorts(ports: readonly number[] | undefined): number[] {
+  if (!ports || ports.length === 0) return [];
+  return [...new Set(ports)]
+    .filter((port) => Number.isInteger(port) && port > 0 && port <= 65_535)
+    .toSorted((left, right) => left - right);
+}

@@ -74,6 +79,35 @@ export function selectPendingTerminalEventEntries(
   return entries.filter((entry) => entry.id > lastAppliedTerminalEventId);
 }
 
+interface TerminalRuntimeStatus {
+  label: string;
+  primaryWebPort: number | null;
+}
+
+function terminalRuntimeStatus(
+  terminalId: string,
+  runningTerminalIds: Set<string>,
+  runningTerminalPorts: Record<string, number[]>,
+): TerminalRuntimeStatus | null {
+  if (!runningTerminalIds.has(terminalId)) {
+    return null;
+  }
+
+  const runningPorts = normalizeRunningPorts(runningTerminalPorts[terminalId]);
+  const primaryWebPort = runningPorts[0] ?? null;
+  const label =
+    runningPorts.length === 0
+      ? "Terminal process running"
+      : runningPorts.length === 1
+        ? `Open web server: http://localhost:${primaryWebPort}`
+        : `Open web server: http://localhost:${primaryWebPort} (detected web ports: ${runningPorts.join(", ")})`;
+
+  return {
+    label,
+    primaryWebPort,
+  };
+}

@@ -807,9 +1000,12 @@ export class TerminalManager extends EventEmitter<TerminalManagerEvents> {
       await Promise.all(

@@ -0,0 +1,52 @@
+export const MAX_PORT_NUMBER = 65_535;
+
+export function normalizeRunningPorts(ports: number[]): number[] {
+  if (ports.length === 0) return [];
+  return [...new Set(ports)]
+    .filter((port) => Number.isInteger(port) && port > 0 && port <= MAX_PORT_NUMBER)
+    .toSorted((left, right) => left - right);
+}

@@ -178,32 +256,134 @@ async function checkPosixSubprocessActivity(terminalPid: number): Promise<boolea
       outputMode: "truncate",
     });
     if (psResult.code !== 0) {
-      return false;
+      return [];
     }
 
+    const childrenByParentPid = new Map<number, number[]>();
     for (const line of psResult.stdout.split(/\r?\n/g)) {
       const [pidRaw, ppidRaw] = line.trim().split(/\s+/g);
       const pid = Number(pidRaw);
       const ppid = Number(ppidRaw);
       if (!Number.isInteger(pid) || !Number.isInteger(ppid)) continue;
-      if (ppid === terminalPid) {
-        return true;
+      const children = childrenByParentPid.get(ppid);
+      if (children) {
+        children.push(pid);
+      } else {
+        childrenByParentPid.set(ppid, [pid]);
       }
     }
-    return false;
+
+    const processFamily = new Set<number>([terminalPid]);
+    const pendingParents = [terminalPid];
+    while (pendingParents.length > 0) {
+      const parentPid = pendingParents.shift();
+      if (!parentPid) continue;
+      const childPids = childrenByParentPid.get(parentPid);
+      if (!childPids || childPids.length === 0) continue;
+      for (const childPid of childPids) {
+        if (processFamily.has(childPid)) continue;
+        processFamily.add(childPid);
+        pendingParents.push(childPid);
+      }
+    }
+
+    return [...processFamily];
+  } catch {
+    return [];
+  }
+}
+
+async function checkPosixListeningPorts(processIds: number[]): Promise<number[]> {
+  if (processIds.length === 0) return [];
+
+  const ports = new Set<number>();
+  const pidFilter = new Set(processIds);
+
+  try {
+    const result = await runProcess(
+      "lsof",
+      ["-nP", "-iTCP", "-sTCP:LISTEN", "-p", processIds.join(",")],
+      {
+        timeoutMs: 1_500,
+        allowNonZeroExit: true,
+        maxBufferBytes: 262_144,
+        outputMode: "truncate",
+      },
+    );
+    if (result.code === 0) {
+      for (const line of result.stdout.split(/\r?\n/g)) {
+        const match = line.match(/:(\d+)\s+\(LISTEN\)$/);
+        if (!match?.[1]) continue;
+        const port = Number(match[1]);
+        if (Number.isInteger(port) && port > 0 && port <= MAX_PORT_NUMBER) {
+          ports.add(port);
+        }
+      }
+      return [...ports].toSorted((left, right) => left - right);
+    }
+  } catch {
+    // Fall back to ss if lsof is unavailable.
+  }
+
+  try {
+    const result = await runProcess("ss", ["-ltnp"], {
+      timeoutMs: 1_500,
+      allowNonZeroExit: true,
+      maxBufferBytes: 524_288,
+      outputMode: "truncate",
+    });
+    if (result.code !== 0) {
+      return [];
+    }
+
+    for (const line of result.stdout.split(/\r?\n/g)) {
+      if (!line.includes("pid=")) continue;
+      const localAddress = line.trim().split(/\s+/g)[3];
+      if (!localAddress) continue;
+      const port = portFromAddress(localAddress);
+      if (port === null) continue;
+
+      const pidMatches = [...line.matchAll(/pid=(\d+)/g)];
+      if (pidMatches.length === 0) continue;
+      if (
+        pidMatches.some((match) => {
+          const pid = Number(match[1]);
+          return Number.isInteger(pid) && pidFilter.has(pid);
+        })
+      ) {
+        ports.add(port);
+      }
+    }
+    return [...ports].toSorted((left, right) => left - right);
   } catch {
-    return false;
+    return [];
   }
 }
 
-async function defaultSubprocessChecker(terminalPid: number): Promise<boolean> {
+async function defaultSubprocessInspector(
+  terminalPid: number,
+): Promise<TerminalSubprocessActivity> {
   if (!Number.isInteger(terminalPid) || terminalPid <= 0) {
-    return false;
+    return { hasRunningSubprocess: false, runningPorts: [] };
   }
+
   if (process.platform === "win32") {
-    return checkWindowsSubprocessActivity(terminalPid);
+    const childPids = await collectWindowsChildPids(terminalPid);

@@ -0,0 +1,119 @@
+import { runProcess } from "../processRunner";
+import { MAX_PORT_NUMBER, portFromAddress } from "./utils";
+
+export async function collectPosixProcessFamilyPids(terminalPid: number): Promise<number[]> {
+  try {
+    const psResult = await runProcess("ps", ["-eo", "pid=,ppid="], {
+      timeoutMs: 1_000,
+      allowNonZeroExit: true,
+      maxBufferBytes: 262_144,
+      outputMode: "truncate",
+    });
+    if (psResult.code !== 0) {
+      return [];
+    }
+
+    const childrenByParentPid = new Map<number, number[]>();
+    for (const line of psResult.stdout.split(/\r?\n/g)) {
+      const [pidRaw, ppidRaw] = line.trim().split(/\s+/g);
+      const pid = Number(pidRaw);
+      const ppid = Number(ppidRaw);
+      if (!Number.isInteger(pid) || !Number.isInteger(ppid)) continue;
+      const children = childrenByParentPid.get(ppid);
+      if (children) {
+        children.push(pid);
+      } else {
+        childrenByParentPid.set(ppid, [pid]);
+      }
+    }
+
+    const processFamily = new Set<number>([terminalPid]);
+    const pendingParents = [terminalPid];
+    while (pendingParents.length > 0) {
+      const parentPid = pendingParents.shift();
+      if (!parentPid) continue;
+      const childPids = childrenByParentPid.get(parentPid);
+      if (!childPids || childPids.length === 0) continue;
+      for (const childPid of childPids) {
+        if (processFamily.has(childPid)) continue;
+        processFamily.add(childPid);
+        pendingParents.push(childPid);
+      }
+    }
+
+    return [...processFamily];
+  } catch {
+    return [];
+  }
+}
+
+export async function checkPosixListeningPorts(processIds: number[]): Promise<number[]> {
+  if (processIds.length === 0) return [];
+
+  const ports = new Set<number>();
+  const pidFilter = new Set(processIds);
+
+  try {
+    const result = await runProcess(
+      "lsof",
+      ["-nP", "-a", "-iTCP", "-sTCP:LISTEN", "-p", processIds.join(",")],
+      {
+        timeoutMs: 1_500,
+        allowNonZeroExit: true,
+        maxBufferBytes: 262_144,
+        outputMode: "truncate",
+      },
+    );
+    if (result.code !== 0) {
+      // `lsof` returns 1 when there are no matching files/sockets.
+      // This is a valid "no results" outcome; avoid falling back to `ss`.
+      return [];
+    }

@@ -695,6 +605,44 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
         }
       });
 
+    const inspectWebPortCached = (port: number) =>
+      Effect.gen(function* () {
+        const now = Date.now();
+        const cached = webPortProbeCache.get(port);
+        if (cached && now - cached.checkedAt <= webPortProbeCacheTtlMs) {
+          return cached.isWeb;
+        }
+
+        const isWeb = yield* webPortInspector(port).pipe(Effect.catch(() => Effect.succeed(false)));
+        webPortProbeCache.set(port, {
+          isWeb,
+          checkedAt: Date.now(),
+        });
+        return isWeb;
+      });

@@ -0,0 +1,114 @@
+import { request as httpRequest } from "node:http";
+
+export const DEFAULT_WEB_PORT_PROBE_TTL_MS = 10_000;
+const DEFAULT_WEB_PORT_PROBE_TIMEOUT_MS = 500;
+const WEB_PORT_PROBE_MAX_BODY_BYTES = 8_192;
+
+interface WebProbeResult {
+  status: number;
+  contentType: string;
+  body: string;
+  location: string;
+}
+
+function normalizeHeaderValue(value: string | string[] | undefined): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value[0] ?? "";
+  return "";
+}
+
+function isLikelyWebProbe(result: WebProbeResult | null): boolean {
+  if (!result) return false;
+  if (result.status === 404) return false;
+  if (result.status >= 300 && result.status < 400 && result.location.length > 0) {
+    return true;
+  }
+  const contentType = result.contentType.toLowerCase();
+  if (contentType.includes("text/html") || contentType.includes("application/xhtml+xml")) {
+    return true;
+  }
+  const body = result.body.toLowerCase();
+  return (
+    body.includes("<!doctype") ||
+    body.includes("<html") ||
+    body.includes("<head")
+  );
+}
+
+async function probeWebPortOnHost(
+  port: number,
+  host: string,
+): Promise<WebProbeResult | null> {
+  return new Promise((resolve) => {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let settled = false;
+    const settle = (result: WebProbeResult | null) => {
+      if (settled) return;
+      settled = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      resolve(result);
+    };
+
+    const req = httpRequest(
+      {
+        host,
+        port,
+        method: "GET",
+        path: "/",
+        timeout: DEFAULT_WEB_PORT_PROBE_TIMEOUT_MS,
+      },
+      (res) => {
+        const chunks: string[] = [];
+        let received = 0;
+        res.setEncoding("utf8");
+        res.on("data", (chunk: string) => {
+          if (received >= WEB_PORT_PROBE_MAX_BODY_BYTES) return;
+          const remaining = WEB_PORT_PROBE_MAX_BODY_BYTES - received;
+          const fragment = chunk.slice(0, remaining);
+          received += fragment.length;
+          chunks.push(fragment);
+          if (received >= WEB_PORT_PROBE_MAX_BODY_BYTES) {
+            res.destroy();
+          }
+        });

@@ -0,0 +1,60 @@
+import { runProcess } from "../processRunner";
+import { parsePidList, parsePortList } from "./utils";
+
+export async function collectWindowsChildPids(terminalPid: number): Promise<number[]> {
+  const command = [
+    `$children = Get-CimInstance Win32_Process -Filter "ParentProcessId = ${terminalPid}" -ErrorAction SilentlyContinue`,
+    "if (-not $children) { exit 0 }",
+    "$children | Select-Object -ExpandProperty ProcessId",
+  ].join("; ");
+  try {
+    const result = await runProcess(
+      "powershell.exe",
+      ["-NoProfile", "-NonInteractive", "-Command", command],
+      {
+        timeoutMs: 1_500,
+        allowNonZeroExit: true,
+        maxBufferBytes: 32_768,
+        outputMode: "truncate",
+      },
+    );
+    if (result.code !== 0) {
+      return [];

@@ -0,0 +1,162 @@
+import { spawn, type ChildProcess, type ChildProcessByStdio } from "node:child_process";
+import type { Readable } from "node:stream";
+
+import * as NodeChildProcessSpawner from "@effect/platform-node/NodeChildProcessSpawner";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+
+import { TerminalProcessInspectorLive } from "./Layers/TerminalProcessInspector";
+import { TerminalProcessInspector } from "./Services/TerminalProcessInspector";
+
+type ListenerProcess = ChildProcessByStdio<null, Readable, Readable>;
+
+interface StartedProcess {
+  readonly process: ListenerProcess;
+  readonly port: number;
+}
+
+const stopProcess = (child: ChildProcess) =>
+  Effect.callback<void>((resume) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resume(Effect.void);
+      return;
+    }
+
+    child.kill("SIGTERM");
+
+    const timeout = setTimeout(() => {
+      if (child.exitCode === null && child.signalCode === null) {
+        child.kill("SIGKILL");
+      }
+    }, 1_000);
+
+    child.once("exit", () => {
+      clearTimeout(timeout);
+      resume(Effect.void);
+    });
+  });

@@ -0,0 +1,109 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+
+import { assert, it } from "@effect/vitest";
+import { Effect } from "effect";
+
+import { WebPortInspectorLive } from "./webPortInspector";
+import { WebPortInspector } from "./terminalProcessInspector/Services/WebPortInspector";
+
+const closeServer = (server: Server) =>
+  Effect.callback<void>((resume) => {
+    server.close(() => {
+      resume(Effect.void);
+    });
+
+    return Effect.sync(() => {
+      try {
+        server.close();
+      } catch {
+        // Ignore cleanup failures in tests.
+      }
+    });
+  });
+
+const listenServer = (server: Server) =>
+  Effect.callback<number, Error>((resume) => {
+    server.listen(0, "127.0.0.1", (error?: Error) => {
+      if (error) {
+        resume(Effect.fail(error));
+        return;
+      }
+

@@ -296,27 +307,106 @@ describe("TerminalManager", () => {
     await waitFor(() => events.some((event) => event.type === "started"));
     expect(events.some((event) => event.type === "activity")).toBe(false);
 
-    hasRunningSubprocess = true;
+    activity = { hasRunningSubprocess: true, runningPorts: [3000] };
     await waitFor(
       () =>
         events.some(
-          (event) => event.type === "activity" && event.hasRunningSubprocess === true,
+          (event) =>
+            event.type === "activity" &&
+            event.hasRunningSubprocess === true &&
+            event.runningPorts.join(",") === "3000",
         ),
       1_200,
     );
 
-    hasRunningSubprocess = false;
+    activity = { hasRunningSubprocess: true, runningPorts: [5173] };
     await waitFor(
       () =>
         events.some(
-          (event) => event.type === "activity" && event.hasRunningSubprocess === false,
+          (event) =>
+            event.type === "activity" &&
+            event.hasRunningSubprocess === true &&
+            event.runningPorts.length === 0,
+        ),
+      1_200,
+    );
+
+    activity = { hasRunningSubprocess: false, runningPorts: [5173] };
+    await waitFor(
+      () =>
+        events.some(
+          (event) =>
+            event.type === "activity" &&
+            event.hasRunningSubprocess === false &&
+            event.runningPorts.length === 0,
         ),
       1_200,
     );
 
     manager.dispose();
   });
 
+  it("ignores ports that return HTTP 404 at root during web-port detection", async () => {
+    const notFoundServer = createServer((_req, res) => {
+      res.statusCode = 404;
+      res.end();
+    });
+    await new Promise<void>((resolve, reject) => {
+      notFoundServer.listen(0, "127.0.0.1", (error?: Error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });

@@ -202,16 +204,39 @@ function ThreadStatusLabel({
   );
 }
 
-function terminalStatusFromRunningIds(
+function normalizeRunningPorts(rawPorts: number[] | undefined): number[] {
+  if (!rawPorts) return [];
+  return [...new Set(rawPorts)]
+    .filter((port) => Number.isInteger(port) && port > 0 && port <= 65_535)
+    .toSorted((left, right) => left - right);
+}

@@ -178,32 +263,243 @@ async function checkPosixSubprocessActivity(terminalPid: number): Promise<boolea
       outputMode: "truncate",
     });
     if (psResult.code !== 0) {
-      return false;
+      return [];
     }
 
+    const childrenByParentPid = new Map<number, number[]>();
     for (const line of psResult.stdout.split(/\r?\n/g)) {
       const [pidRaw, ppidRaw] = line.trim().split(/\s+/g);
       const pid = Number(pidRaw);
       const ppid = Number(ppidRaw);
       if (!Number.isInteger(pid) || !Number.isInteger(ppid)) continue;
-      if (ppid === terminalPid) {
-        return true;
+      const children = childrenByParentPid.get(ppid);
+      if (children) {
+        children.push(pid);
+      } else {
+        childrenByParentPid.set(ppid, [pid]);
+      }
+    }
+
+    const processFamily = new Set<number>([terminalPid]);
+    const pendingParents = [terminalPid];
+    while (pendingParents.length > 0) {
+      const parentPid = pendingParents.shift();
+      if (!parentPid) continue;
+      const childPids = childrenByParentPid.get(parentPid);
+      if (!childPids || childPids.length === 0) continue;
+      for (const childPid of childPids) {
+        if (processFamily.has(childPid)) continue;
+        processFamily.add(childPid);
+        pendingParents.push(childPid);
+      }
+    }
+
+    return [...processFamily];
+  } catch {
+    return [];
+  }
+}
+
+async function checkPosixListeningPorts(processIds: number[]): Promise<number[]> {
+  if (processIds.length === 0) return [];
+
+  const ports = new Set<number>();
+  const pidFilter = new Set(processIds);
+
+  try {
+    const result = await runProcess(
+      "lsof",
+      ["-nP", "-a", "-iTCP", "-sTCP:LISTEN", "-p", processIds.join(",")],
+      {
+        timeoutMs: 1_500,
+        allowNonZeroExit: true,
+        maxBufferBytes: 262_144,
+        outputMode: "truncate",
+      },
+    );
+    if (result.code === 0) {
+      for (const line of result.stdout.split(/\r?\n/g)) {
+        const match = line.match(/:(\d+)\s+\(LISTEN\)$/);
+        if (!match?.[1]) continue;
+        const port = Number(match[1]);
+        if (Number.isInteger(port) && port > 0 && port <= MAX_PORT_NUMBER) {
+          ports.add(port);
+        }
       }
+      return [...ports].toSorted((left, right) => left - right);
     }
-    return false;
   } catch {
-    return false;
+    // Fall back to ss if lsof is unavailable.
+  }
+
+  try {
+    const result = await runProcess("ss", ["-ltnp"], {
+      timeoutMs: 1_500,
+      allowNonZeroExit: true,
+      maxBufferBytes: 524_288,
+      outputMode: "truncate",
+    });
+    if (result.code !== 0) {
+      return [];
+    }
+
+    for (const line of result.stdout.split(/\r?\n/g)) {
+      if (!line.includes("pid=")) continue;
+      const localAddress = line.trim().split(/\s+/g)[3];
+      if (!localAddress) continue;
+      const port = portFromAddress(localAddress);
+      if (port === null) continue;
+
+      const pidMatches = [...line.matchAll(/pid=(\d+)/g)];
+      if (pidMatches.length === 0) continue;
+      if (
+        pidMatches.some((match) => {
+          const pid = Number(match[1]);
+          return Number.isInteger(pid) && pidFilter.has(pid);
+        })
+      ) {
+        ports.add(port);
+      }
+    }
+    return [...ports].toSorted((left, right) => left - right);
+  } catch {
+    return [];
   }
 }
 
-async function defaultSubprocessChecker(terminalPid: number): Promise<boolean> {
+async function defaultSubprocessInspector(
+  terminalPid: number,
+): Promise<TerminalSubprocessActivity> {
   if (!Number.isInteger(terminalPid) || terminalPid <= 0) {
-    return false;
+    return { hasRunningSubprocess: false, runningPorts: [] };
   }
+
   if (process.platform === "win32") {
-    return checkWindowsSubprocessActivity(terminalPid);
+    const childPids = await collectWindowsChildPids(terminalPid);
+    if (childPids.length === 0) {
+      return { hasRunningSubprocess: false, runningPorts: [] };
+    }
+    const runningPorts = await checkWindowsListeningPorts(childPids);
+    return { hasRunningSubprocess: true, runningPorts };
+  }
+
+  const processFamilyPids = await collectPosixProcessFamilyPids(terminalPid);
+  const subprocessPids = processFamilyPids.filter((pid) => pid !== terminalPid);
+  if (subprocessPids.length === 0) {
+    return { hasRunningSubprocess: false, runningPorts: [] };
+  }
+
+  const runningPorts = await checkPosixListeningPorts(subprocessPids);
+  return { hasRunningSubprocess: true, runningPorts };
+}
+
+interface WebProbeResult {
+  status: number;
+  contentType: string;
+  body: string;
+  location: string;
+}
+
+function normalizeHeaderValue(value: string | string[] | undefined): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value[0] ?? "";
+  return "";
+}
+
+function isLikelyWebProbe(result: WebProbeResult | null): boolean {
+  if (!result) return false;
+  if (result.status === 404) return false;
+  if (result.status >= 300 && result.status < 400 && result.location.length > 0) {
+    return true;
+  }
+  const contentType = result.contentType.toLowerCase();
+  if (contentType.includes("text/html") || contentType.includes("application/xhtml+xml")) {
+    return true;
+  }
+  const body = result.body.toLowerCase();
+  return (
+    body.includes("<!doctype") ||
+    body.includes("<html") ||
+    body.includes("<head")
+  );
+}
+
+async function probeWebPortOnHost(
+  port: number,
+  host: string,
+): Promise<WebProbeResult | null> {
+  return new Promise((resolve) => {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let settled = false;
+    const settle = (result: WebProbeResult | null) => {
+      if (settled) return;
+      settled = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      resolve(result);
+    };
+
+    const req = httpRequest(
+      {
+        host,
+        port,
+        method: "GET",
+        path: "/",
+        timeout: DEFAULT_WEB_PORT_PROBE_TIMEOUT_MS,
+      },
+      (res) => {
+        const chunks: string[] = [];
+        let received = 0;
+        res.setEncoding("utf8");
+        res.on("data", (chunk: string) => {
+          if (received >= WEB_PORT_PROBE_MAX_BODY_BYTES) return;
+          const remaining = WEB_PORT_PROBE_MAX_BODY_BYTES - received;
+          const fragment = chunk.slice(0, remaining);
+          received += fragment.length;
+          chunks.push(fragment);
+          if (received >= WEB_PORT_PROBE_MAX_BODY_BYTES) {
+            res.destroy();
+          }

@@ -74,6 +75,45 @@ export function selectPendingTerminalEventEntries(
   return entries.filter((entry) => entry.id > lastAppliedTerminalEventId);
 }
 
+interface TerminalRuntimeStatus {
+  label: string;
+  primaryWebPort: number | null;
+  extraWebPortCount: number;
+}
+
+function normalizeRunningPorts(rawPorts: number[] | undefined): number[] {
+  if (!rawPorts) return [];
+  return [...new Set(rawPorts)]
+    .filter((port) => Number.isInteger(port) && port > 0 && port <= 65_535)
+    .toSorted((left, right) => left - right);
+}
+
+function terminalRuntimeStatus(
+  terminalId: string,
+  runningTerminalIds: Set<string>,
+  runningTerminalPorts: Record<string, number[]>,
+): TerminalRuntimeStatus | null {
+  if (!runningTerminalIds.has(terminalId)) {
+    return null;
+  }
+
+  const runningPorts = normalizeRunningPorts(runningTerminalPorts[terminalId]);
+  const primaryWebPort = runningPorts[0] ?? null;
+  const extraWebPortCount = runningPorts.length > 1 ? runningPorts.length - 1 : 0;
+  const label =
+    runningPorts.length === 0
+      ? "Terminal process running"
+      : runningPorts.length === 1
+        ? `Open web server: http://localhost:${primaryWebPort}`
+        : `Open web server: http://localhost:${primaryWebPort} (detected web ports: ${runningPorts.join(", ")})`;
+
+  return {
+    label,
+    primaryWebPort,
+    extraWebPortCount,
+  };

@@ -0,0 +1,56 @@
+import { collectPosixProcessFamilyPids, checkPosixListeningPorts } from "./posix";
+import {
+  type TerminalSubprocessActivity,
+  type TerminalSubprocessChecker,
+  type TerminalSubprocessInspector,
+  type TerminalWebPortInspector,
+} from "./types";
+import { checkWindowsListeningPorts, collectWindowsChildPids } from "./win32";
+
+export { arePortListsEqual, normalizeRunningPorts } from "./utils";
+
+export type {
+  TerminalSubprocessActivity,
+  TerminalSubprocessChecker,
+  TerminalSubprocessInspector,
+  TerminalWebPortInspector,
+} from "./types";
+
+export async function defaultSubprocessInspector(
+  terminalPid: number,
+): Promise<TerminalSubprocessActivity> {
+  if (!Number.isInteger(terminalPid) || terminalPid <= 0) {
+    return { hasRunningSubprocess: false, runningPorts: [] };
+  }
+
+  if (process.platform === "win32") {
+    const childPids = await collectWindowsChildPids(terminalPid);
+    const processPidsForPortScan = [terminalPid, ...childPids];
+    const runningPorts = await checkWindowsListeningPorts(processPidsForPortScan);
+    return {
+      hasRunningSubprocess: childPids.length > 0 || runningPorts.length > 0,
+      runningPorts,
+    };
+  }
+
+  const processFamilyPids = await collectPosixProcessFamilyPids(terminalPid);
+  if (processFamilyPids.length === 0) {
+    return { hasRunningSubprocess: false, runningPorts: [] };
+  }
+
+  const subprocessPids = processFamilyPids.filter((pid) => pid !== terminalPid);
+  const runningPorts = await checkPosixListeningPorts(processFamilyPids);
+  return {
+    hasRunningSubprocess: subprocessPids.length > 0 || runningPorts.length > 0,
+    runningPorts,
+  };
+}
+
+export function subprocessCheckerToInspector(
+  subprocessChecker: TerminalSubprocessChecker,
+): TerminalSubprocessInspector {
+  return async (terminalPid: number) => ({
+    hasRunningSubprocess: await subprocessChecker(terminalPid),
+    runningPorts: [],
+  });
+}

@@ -0,0 +1,179 @@
+import { Buffer } from "node:buffer";
+
+import { Effect, Layer, Option, Stream } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+
+import { WebPortInspectionError } from "../Errors";
+import type { WebPortInspectorShape } from "../Services/WebPortInspector";
+import { WebPortInspector } from "../Services/WebPortInspector";
+
+const DEFAULT_WEB_PORT_PROBE_TIMEOUT_MS = 2_000;
+const WEB_PORT_PROBE_MAX_BODY_BYTES = 8_192;
+
+interface WebProbeResult {
+  readonly status: number;
+  readonly contentType: string;
+  readonly body: string;
+  readonly location: string;
+}
+
+function normalizeHeaderValue(value: string | string[] | undefined): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value[0] ?? "";
+  return "";
+}
+
+function isLikelyWebProbe(result: WebProbeResult | null): boolean {
+  if (!result) return false;
+  if (result.status === 404) return false;
+  if (result.status >= 300 && result.status < 400 && result.location.length > 0) {
+    return true;
+  }
+  const contentType = result.contentType.toLowerCase();
+  if (contentType.includes("text/html") || contentType.includes("application/xhtml+xml")) {
+    return true;
+  }
+  const body = result.body.toLowerCase();
+  return body.includes("<!doctype") || body.includes("<html") || body.includes("<head");
+}
+
+const collectBodyPreview = <E>(
+  stream: Stream.Stream<Uint8Array, E>,
+): Effect.Effect<string, never> =>
+  stream.pipe(
+    Stream.decodeText(),
+    Stream.runFold(
+      () => ({
+        text: "",
+        bytes: 0,
+      }),
+      (state, chunk) => {
+        if (state.bytes >= WEB_PORT_PROBE_MAX_BODY_BYTES) {
+          return state;
+        }
+
+        const chunkBytes = Buffer.byteLength(chunk);
+        const remainingBytes = WEB_PORT_PROBE_MAX_BODY_BYTES - state.bytes;
+        if (chunkBytes <= remainingBytes) {
+          return {
+            text: `${state.text}${chunk}`,
+            bytes: state.bytes + chunkBytes,
+          };
+        }
+
+        return {
+          text: `${state.text}${Buffer.from(chunk).subarray(0, remainingBytes).toString("utf8")}`,
+          bytes: state.bytes + remainingBytes,
+        };
+      },
+    ),
+    Effect.map((preview) => preview.text),
+    Effect.orElseSucceed(() => ""),
+  );
+
+const makeWebPortInspector = Effect.gen(function* () {
+  const httpClient = yield* HttpClient.HttpClient;
+
+  const probeWebPortOnHost = Effect.fn("process.probeWebPortOnHost")(function* (
+    port: number,
+    host: string,
+  ): Effect.fn.Return<WebProbeResult | null, WebPortInspectionError> {
+    const request = HttpClientRequest.get(`http://${host}:${port}/`).pipe(
+      HttpClientRequest.setHeaders({
+        accept: "text/html,application/xhtml+xml;q=1,*/*;q=0.1",
+      }),
+    );
+
+    return yield* httpClient.execute(request).pipe(
+      Effect.flatMap((response) =>
+        Effect.gen(function* () {
+          const status = response.status;
+          const contentType = normalizeHeaderValue(response.headers["content-type"]);
+          const location = normalizeHeaderValue(response.headers.location);
+
+          if (
+            (status >= 300 && status < 400 && location.length > 0) ||
+            contentType.toLowerCase().includes("text/html") ||
+            contentType.toLowerCase().includes("application/xhtml+xml")
+          ) {
+            return {
+              status,
+              contentType,
+              location,
+              body: "",
+            } satisfies WebProbeResult;
+          }
+
+          const body = yield* collectBodyPreview(response.stream);
+          return {
+            status,
+            contentType,
+            location,
+            body,
+          } satisfies WebProbeResult;
+        }),
+      ),
+      Effect.timeoutOption(DEFAULT_WEB_PORT_PROBE_TIMEOUT_MS),
+      Effect.flatMap(
+        Option.match({
+          onNone: () =>
+            Effect.fail(
+              new WebPortInspectionError({
+                port,
+                host,
+                detail: "HTTP probe timed out.",
+              }),
+            ),
+          onSome: Effect.succeed,
+        }),
+      ),
+      Effect.mapError(
+        (cause) =>
+          new WebPortInspectionError({
+            port,
+            host,
+            detail: "Failed to execute HTTP probe request.",
+            cause,
+          }),
+      ),

@@ -674,24 +705,32 @@ export function reducer(state: AppState, action: Action): AppState {
         threads: updateThread(state.threads, action.event.threadId, (thread) => {
           const normalizedThread = normalizeThreadTerminals(thread);
           const runningTerminalIdSet = new Set(normalizedThread.runningTerminalIds);
+          const runningTerminalPorts = { ...normalizedThread.runningTerminalPorts };
           if (
             action.event.type === "started" ||
             action.event.type === "restarted"
           ) {
             runningTerminalIdSet.delete(action.event.terminalId);
+            delete runningTerminalPorts[action.event.terminalId];
           } else if (action.event.type === "activity") {
             if (action.event.hasRunningSubprocess) {
               runningTerminalIdSet.add(action.event.terminalId);
+              runningTerminalPorts[action.event.terminalId] = normalizeRunningPorts(
+                action.event.runningPorts,
+              );
             } else {
               runningTerminalIdSet.delete(action.event.terminalId);
+              delete runningTerminalPorts[action.event.terminalId];
             }
           } else if (action.event.type === "exited" || action.event.type === "error") {
             runningTerminalIdSet.delete(action.event.terminalId);
+            delete runningTerminalPorts[action.event.terminalId];
           }
 
           return normalizeThreadTerminals({
             ...normalizedThread,
             runningTerminalIds: [...runningTerminalIdSet],
+            runningTerminalPorts,
           });

@@ -0,0 +1,58 @@
+import { runProcess } from "../processRunner";
+import { parsePidList, parsePortList } from "./utils";
+
+export async function collectWindowsChildPids(terminalPid: number): Promise<number[]> {
+  const command = [
+    `$children = Get-CimInstance Win32_Process -Filter "ParentProcessId = ${terminalPid}" -ErrorAction SilentlyContinue`,
+    "if (-not $children) { exit 0 }",
+    "$children | Select-Object -ExpandProperty ProcessId",
+  ].join("; ");
+  try {
+    const result = await runProcess(
+      "powershell.exe",
+      ["-NoProfile", "-NonInteractive", "-Command", command],
+      {
+        timeoutMs: 1_500,
+        allowNonZeroExit: true,
+        maxBufferBytes: 32_768,
+        outputMode: "truncate",
+      },
+    );
+    if (result.code !== 0) {
+      return [];
+    }
+    return parsePidList(result.stdout);
+  } catch {
+    return [];
+  }
+}

@@ -834,18 +836,29 @@ export class TerminalManager extends EventEmitter<TerminalManagerEvents> {
           if (!liveSession || liveSession.status !== "running" || liveSession.pid !== terminalPid) {
             return;
           }
-          if (liveSession.hasRunningSubprocess === hasRunningSubprocess) {
+          const hasRunningSubprocess = activity.hasRunningSubprocess === true;
+          const runningPorts = hasRunningSubprocess
+            ? normalizeRunningPorts(
+                await this.detectWebPorts(normalizeRunningPorts(activity.runningPorts)),
+              )
+            : [];