issue-flow 0.13.0 → 0.15.0

package/dist/chunk-BMHGRYL6.js

@@ -0,0 +1,890 @@
+#!/usr/bin/env node
+import {
+  writeAgentPreference
+} from "./chunk-6FXOU2KR.js";
+import {
+  resolvePackageDir
+} from "./chunk-A35HE4V7.js";
+import {
+  printInfo,
+  printWarning
+} from "./chunk-NVZMBXTE.js";
+import {
+  NullPublisher
+} from "./chunk-6QYMSNVA.js";
+import {
+  readDiagnostics
+} from "./chunk-AYYMW33T.js";
+import {
+  getGlobalRoot
+} from "./chunk-HAKDLR6N.js";
+import {
+  isoNow
+} from "./chunk-XQHFC62U.js";
+import {
+  isAgentPhase,
+  isAgentProviderId,
+  isProcessAlive,
+  webLockSchema
+} from "./chunk-XDKGA6UX.js";
+
+// src/web/lock.ts
+import { spawn as nodeSpawn } from "child_process";
+import { randomUUID as randomUUID2 } from "crypto";
+import { mkdir, readFile as readFile2, rm, writeFile } from "fs/promises";
+import { join as join2 } from "path";
+import chalk2 from "chalk";
+import { execa } from "execa";
+
+// src/web/server.ts
+import { createHash, randomUUID } from "crypto";
+import { readFile } from "fs/promises";
+import { createServer } from "http";
+import { createRequire } from "module";
+import { join } from "path";
+import chalk from "chalk";
+var require2 = createRequire(import.meta.url);
+var SESSION_LIST_DESCRIPTION_MAX = 280;
+function readPackageVersion() {
+  for (const candidate of ["../package.json", "../../package.json"]) {
+    try {
+      return require2(candidate).version;
+    } catch {
+    }
+  }
+  return "0.0.0";
+}
+function truncateSessionDescription(text, max = SESSION_LIST_DESCRIPTION_MAX) {
+  if (text === null || text === void 0) return null;
+  const normalized = text.replace(/\s+/g, " ").trim();
+  if (normalized.length === 0) return normalized;
+  if (normalized.length <= max) return normalized;
+  return `${normalized.slice(0, max - 1).trimEnd()}\u2026`;
+}
+var JSON_TYPE = "application/json; charset=utf-8";
+function publisherSessionSource(publisher) {
+  return {
+    list: () => {
+      const snapshot = publisher.snapshot();
+      return snapshot.sessionId === null ? [] : [snapshot];
+    },
+    get: (sessionId) => {
+      const snapshot = publisher.snapshot();
+      return snapshot.sessionId === sessionId ? snapshot : void 0;
+    },
+    events: async (sessionId) => publisher.snapshot().sessionId === sessionId ? [] : void 0
+  };
+}
+function directorySessionSource(handle) {
+  return {
+    list: () => handle.sessions().map((entry) => entry.snapshot),
+    get: (sessionId) => handle.getSession(sessionId)?.snapshot,
+    events: (sessionId) => handle.events(sessionId)
+  };
+}
+function resolveSessionSource(options) {
+  if (options.sessions) return directorySessionSource(options.sessions);
+  return publisherSessionSource(options.publisher ?? new NullPublisher());
+}
+var STATIC_ROUTES = {
+  "/": { file: "index.html", contentType: "text/html; charset=utf-8" },
+  "/app.css": { file: "app.css", contentType: "text/css; charset=utf-8" },
+  "/app.js": { file: "app.js", contentType: "text/javascript; charset=utf-8" }
+};
+async function loadStaticAssets(publicDir) {
+  const assets = /* @__PURE__ */ new Map();
+  if (publicDir === null) return assets;
+  for (const [route, { file, contentType }] of Object.entries(STATIC_ROUTES)) {
+    try {
+      const body = await readFile(join(publicDir, file), "utf-8");
+      assets.set(route, { body, contentType });
+    } catch {
+    }
+  }
+  return assets;
+}
+function baseHeaders(res, instanceId) {
+  res.setHeader("Cache-Control", "no-store");
+  res.setHeader("X-Issue-Flow-Instance", instanceId);
+  res.setHeader("X-Content-Type-Options", "nosniff");
+  res.setHeader("Referrer-Policy", "no-referrer");
+  res.setHeader("X-Robots-Tag", "noindex, nofollow");
+}
+function respond(res, status, contentType, body) {
+  res.statusCode = status;
+  res.setHeader("Content-Type", contentType);
+  res.end(body);
+}
+function respondJson(res, status, payload) {
+  respond(res, status, JSON_TYPE, JSON.stringify(payload));
+}
+function isLoopbackHost(host) {
+  return host === "127.0.0.1" || host === "::1" || host === "localhost";
+}
+async function readJsonBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > 64 * 1024) throw new Error("Request body too large.");
+    chunks.push(buffer);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString("utf-8") || "{}");
+}
+async function startWebServer(options) {
+  const info = options.info ?? printInfo;
+  const warn = options.warn ?? printWarning;
+  const version = options.version ?? readPackageVersion();
+  const instanceId = options.instanceId ?? randomUUID();
+  const startedAtMs = Date.now();
+  const assets = await loadStaticAssets(
+    options.publicDir ?? resolvePackageDir(join("web", "public"))
+  );
+  const source = resolveSessionSource(options);
+  const statusCache = /* @__PURE__ */ new Map();
+  const statusPayload = (snapshot) => {
+    const key = snapshot.sessionId ?? "";
+    const body = JSON.stringify(snapshot);
+    const cached = statusCache.get(key);
+    if (cached !== void 0 && cached.body === body) return cached;
+    const etag = `"${createHash("sha1").update(body).digest("hex")}"`;
+    const entry = { body, etag };
+    statusCache.set(key, entry);
+    return entry;
+  };
+  const handleRequest = async (req, res) => {
+    baseHeaders(res, instanceId);
+    const requestUrl = new URL(req.url ?? "/", "http://localhost");
+    const path = requestUrl.pathname;
+    if (req.method === "POST" && path === "/api/config/agent") {
+      if (!isLoopbackHost(options.host)) {
+        respondJson(res, 403, {
+          error: "Configuration writes are disabled when the monitor is not bound to loopback."
+        });
+        return;
+      }
+      const body = await readJsonBody(req);
+      if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        respondJson(res, 400, { error: "Expected a JSON object." });
+        return;
+      }
+      const input = body;
+      if (typeof input.provider !== "string" || !isAgentProviderId(input.provider)) {
+        respondJson(res, 400, { error: "Invalid provider." });
+        return;
+      }
+      if (input.phase !== void 0 && (typeof input.phase !== "string" || !isAgentPhase(input.phase))) {
+        respondJson(res, 400, { error: "Invalid phase." });
+        return;
+      }
+      if (input.model !== void 0 && typeof input.model !== "string") {
+        respondJson(res, 400, { error: "Invalid model." });
+        return;
+      }
+      const file = await writeAgentPreference({
+        target: "global",
+        provider: input.provider,
+        ...input.model ? { model: input.model } : {},
+        ...input.phase ? { phase: input.phase } : {}
+      });
+      respondJson(res, 200, { ok: true, file, appliesTo: "future executions" });
+      return;
+    }
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      respondJson(res, 404, { error: "Not found" });
+      return;
+    }
+    if (path === "/api/status" || path === "/status.json") {
+      const sessionId = requestUrl.searchParams.get("session");
+      let snapshot;
+      if (sessionId !== null) {
+        snapshot = source.get(sessionId);
+        if (snapshot === void 0) {
+          respondJson(res, 404, { error: `No active session with id '${sessionId}'.` });
+          return;
+        }
+      } else {
+        const active = source.list();
+        if (active.length === 0) {
+          respondJson(res, 404, {
+            error: "No active session. Pass ?session=<id> \u2014 see GET /api/sessions."
+          });
+          return;
+        }
+        if (active.length > 1) {
+          respondJson(res, 409, {
+            error: "Multiple active sessions; specify ?session=<id>.",
+            sessions: active.map((entry) => entry.sessionId)
+          });
+          return;
+        }
+        snapshot = active[0];
+      }
+      const { body, etag } = statusPayload(snapshot);
+      res.setHeader("ETag", etag);
+      if (req.headers["if-none-match"] === etag) {
+        res.statusCode = 304;
+        res.end();
+        return;
+      }
+      respond(res, 200, JSON_TYPE, body);
+      return;
+    }
+    if (path === "/api/sessions") {
+      respondJson(
+        res,
+        200,
+        source.list().map((snapshot) => ({
+          sessionId: snapshot.sessionId,
+          issueNumber: snapshot.issue.number,
+          issueTitle: snapshot.issue.title,
+          issueDescription: truncateSessionDescription(snapshot.issue.description),
+          repositoryName: snapshot.repository.name,
+          currentPhase: snapshot.currentPhase,
+          progressPercent: snapshot.progress.percent,
+          elapsedSeconds: snapshot.elapsedSeconds,
+          status: snapshot.status,
+          startedAt: snapshot.startedAt,
+          updatedAt: snapshot.updatedAt,
+          // Resilience fields, for a card that has to answer "is this still
+          // moving" during a six-hour run. `updatedAt` is already the last
+          // activity; these two say how hard the run has had to work for it.
+          retries: snapshot.execution.retries,
+          correctionCycle: snapshot.execution.correctionCycle,
+          attempt: snapshot.resilience.attempt,
+          provider: snapshot.resilience.provider,
+          lastFailureKind: snapshot.resilience.lastFailureKind,
+          cooldownUntil: snapshot.resilience.cooldownUntil,
+          lastActivityAt: snapshot.resilience.lastActivityAt,
+          statusUrl: `/api/status?session=${encodeURIComponent(snapshot.sessionId ?? "")}`,
+          eventsUrl: `/api/events?session=${encodeURIComponent(snapshot.sessionId ?? "")}`
+        }))
+      );
+      return;
+    }
+    if (path === "/api/events") {
+      const sessionId = requestUrl.searchParams.get("session");
+      if (sessionId === null) {
+        respondJson(res, 400, { error: "Pass ?session=<id>." });
+        return;
+      }
+      const entries = await source.events(sessionId);
+      if (entries === void 0) {
+        respondJson(res, 404, { error: `No active session with id '${sessionId}'.` });
+        return;
+      }
+      respondJson(res, 200, entries);
+      return;
+    }
+    if (path === "/api/diagnostics") {
+      const sessionId = requestUrl.searchParams.get("session") ?? void 0;
+      respondJson(res, 200, await readDiagnostics({ sessionId, limit: 500 }));
+      return;
+    }
+    if (path === "/api/config") {
+      const sessionId = requestUrl.searchParams.get("session");
+      const snapshot = sessionId === null ? void 0 : source.get(sessionId);
+      respondJson(res, 200, {
+        effective: snapshot?.configuration ?? null,
+        capturedForSession: snapshot?.sessionId ?? null,
+        writable: isLoopbackHost(options.host),
+        writeScope: "global preferences for future executions"
+      });
+      return;
+    }
+    if (path === "/api/health") {
+      respondJson(res, 200, {
+        ok: true,
+        pid: process.pid,
+        instanceId,
+        startedAt: new Date(startedAtMs).toISOString(),
+        uptime: Math.round((Date.now() - startedAtMs) / 1e3),
+        version,
+        refreshSeconds: options.refreshSeconds ?? 5,
+        capabilities: isLoopbackHost(options.host) ? ["config:agent:write"] : []
+      });
+      return;
+    }
+    const asset = assets.get(path);
+    if (asset) {
+      respond(res, 200, asset.contentType, asset.body);
+      return;
+    }
+    respondJson(res, 404, { error: "Not found" });
+  };
+  const server = createServer((req, res) => {
+    void handleRequest(req, res).catch((err) => {
+      try {
+        respondJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+      } catch {
+      }
+    });
+  });
+  const listening = await new Promise((resolve) => {
+    const onError = (err) => {
+      if (err.code === "EADDRINUSE") {
+        warn(
+          `Web monitor port ${options.port} is already in use. Continuing without the web server.`
+        );
+      } else {
+        warn(`Web monitor failed to start (${err.message}). Continuing without the web server.`);
+      }
+      resolve(false);
+    };
+    server.once("error", onError);
+    server.listen(options.port, options.host, () => {
+      server.removeListener("error", onError);
+      resolve(true);
+    });
+  });
+  if (!listening) return null;
+  if (options.unref !== false) {
+    server.unref();
+  }
+  server.on("error", (err) => {
+    warn(`Web monitor server error: ${err.message}`);
+  });
+  const address = server.address();
+  const port = address.port;
+  const displayHost = options.host === "0.0.0.0" ? "localhost" : options.host;
+  const url = `http://${displayHost}:${port}`;
+  if (options.host === "0.0.0.0") {
+    warn("Web monitor bound to 0.0.0.0: anyone on your local network can view the session state.");
+  }
+  info(`Web monitor running at ${chalk.bold.cyan(url)}`);
+  let closed = false;
+  let closePromise = null;
+  const doClose = () => new Promise((resolve) => {
+    process.removeListener("SIGINT", onSignal);
+    process.removeListener("SIGTERM", onSignal);
+    server.close(() => resolve());
+    server.closeAllConnections();
+  });
+  const close = () => {
+    if (closed) return closePromise ?? Promise.resolve();
+    closed = true;
+    closePromise = doClose();
+    return closePromise;
+  };
+  const handle = { server, host: options.host, port, url, instanceId, close };
+  const onSignal = (signal) => {
+    void handle.close().finally(() => {
+      process.kill(process.pid, signal);
+    });
+  };
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+  return handle;
+}
+
+// src/web/lock.ts
+var WEB_LOCK_FILENAME = "web.lock";
+var WEB_RESTART_LOCK_FILENAME = "web.restart.lock";
+var HEALTH_PROBE_TIMEOUT_MS = 1e3;
+var LOCK_CLAIM_RETRIES = 5;
+var LOCK_CLAIM_RETRY_DELAY_MS = 100;
+function getWebLockFile(options = {}) {
+  return join2(getGlobalRoot(options), WEB_LOCK_FILENAME);
+}
+function getWebRestartLockFile(options = {}) {
+  return join2(getGlobalRoot(options), WEB_RESTART_LOCK_FILENAME);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function probeUrl(host, port) {
+  const probeHost = host === "0.0.0.0" ? "127.0.0.1" : host;
+  return `http://${probeHost}:${port}/api/health`;
+}
+async function probeHealth(host, port) {
+  try {
+    const res = await fetch(probeUrl(host, port), {
+      signal: AbortSignal.timeout(HEALTH_PROBE_TIMEOUT_MS)
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    if (body.ok !== true) return null;
+    return {
+      ok: true,
+      ...typeof body.pid === "number" && Number.isInteger(body.pid) && body.pid > 0 ? { pid: body.pid } : {},
+      ...typeof body.instanceId === "string" && body.instanceId !== "" ? { instanceId: body.instanceId } : {},
+      ...typeof body.startedAt === "string" && body.startedAt !== "" ? { startedAt: body.startedAt } : {},
+      ...typeof body.uptime === "number" && Number.isFinite(body.uptime) ? { uptime: body.uptime } : {},
+      ...typeof body.version === "string" && body.version !== "" ? { version: body.version } : {}
+    };
+  } catch {
+    return null;
+  }
+}
+function sameLock(a, b) {
+  return a !== null && a.pid === b.pid && a.port === b.port && a.host === b.host && a.startedAt === b.startedAt && a.instanceId === b.instanceId;
+}
+async function removeWebLockIfOwned(lockFile, expected) {
+  if (sameLock(await readWebLock(lockFile), expected)) {
+    await removeWebLock(lockFile);
+  }
+}
+async function inspectProcessCommand(pid) {
+  const invocation = process.platform === "win32" ? {
+    command: "powershell.exe",
+    args: [
+      "-NoProfile",
+      "-NonInteractive",
+      "-Command",
+      `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}").CommandLine`
+    ]
+  } : { command: "ps", args: ["-p", String(pid), "-o", "command="] };
+  try {
+    const result = await execa(invocation.command, invocation.args, { reject: false });
+    const command = result.stdout.trim();
+    return result.exitCode === 0 && command !== "" ? command : null;
+  } catch {
+    return null;
+  }
+}
+async function findListeningProcess(port) {
+  try {
+    let pids;
+    if (process.platform === "win32") {
+      const result = await execa(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          `(Get-NetTCPConnection -State Listen -LocalPort ${port} -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess -Unique) -join [Environment]::NewLine`
+        ],
+        { reject: false }
+      );
+      pids = result.stdout.split(/\s+/).map(Number).filter((pid2) => Number.isInteger(pid2) && pid2 > 0);
+    } else {
+      const result = await execa("lsof", ["-nP", "-t", `-iTCP:${port}`, "-sTCP:LISTEN"], {
+        reject: false
+      });
+      pids = result.stdout.split(/\s+/).map(Number).filter((pid2) => Number.isInteger(pid2) && pid2 > 0);
+    }
+    const unique = [...new Set(pids)];
+    if (unique.length !== 1) return null;
+    const pid = unique[0];
+    const command = await inspectProcessCommand(pid);
+    return command === null ? null : { pid, command };
+  } catch {
+    return null;
+  }
+}
+function isIssueFlowWebServe(owner, port) {
+  const escapedPort = String(port).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return /(?:^|\s)web\s+serve(?:\s|$)/.test(owner.command) && new RegExp(`(?:^|\\s)--port(?:=|\\s+)${escapedPort}(?:\\s|$)`).test(owner.command) && /issue-flow|(?:^|[/\\])dist[/\\]cli\.js/.test(owner.command);
+}
+async function readWebLock(lockFile) {
+  let raw;
+  try {
+    raw = await readFile2(lockFile, "utf-8");
+  } catch {
+    return null;
+  }
+  try {
+    const result = webLockSchema.safeParse(JSON.parse(raw));
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
+async function removeWebLock(lockFile) {
+  try {
+    await rm(lockFile, { force: true });
+  } catch {
+  }
+}
+async function detectActiveInstance(lockFile) {
+  const lock = await readWebLock(lockFile);
+  if (lock === null) return null;
+  const health = isProcessAlive(lock.pid) ? await probeHealth(lock.host, lock.port) : null;
+  if (health !== null && (lock.instanceId === void 0 || health.instanceId === lock.instanceId)) {
+    return lock;
+  }
+  await removeWebLockIfOwned(lockFile, lock);
+  return null;
+}
+async function claimWebLock(lockFile, lock) {
+  try {
+    await writeFile(lockFile, JSON.stringify(lock, null, 2), { encoding: "utf-8", flag: "wx" });
+    return true;
+  } catch (err) {
+    if (err.code === "EEXIST") return false;
+    throw err;
+  }
+}
+async function readRestartLock(file) {
+  try {
+    const value = JSON.parse(await readFile2(file, "utf-8"));
+    return typeof value.pid === "number" && Number.isInteger(value.pid) && value.pid > 0 && typeof value.operationId === "string" && value.operationId !== "" && typeof value.startedAt === "string" && value.startedAt !== "" ? { pid: value.pid, operationId: value.operationId, startedAt: value.startedAt } : null;
+  } catch {
+    return null;
+  }
+}
+async function removeRestartLockIfOwned(file, expected) {
+  const current = await readRestartLock(file);
+  if (current?.operationId === expected.operationId) {
+    await rm(file, { force: true }).catch(() => {
+    });
+  }
+}
+async function waitForRestart(file, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const lock = await readRestartLock(file);
+    if (lock === null) {
+      return true;
+    }
+    if (!isProcessAlive(lock.pid)) {
+      await removeRestartLockIfOwned(file, lock);
+      return true;
+    }
+    await sleep(LOCK_CLAIM_RETRY_DELAY_MS);
+  }
+  return false;
+}
+async function acquireRestartLock(file, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let waited = false;
+  while (Date.now() < deadline) {
+    const lock = {
+      pid: process.pid,
+      operationId: randomUUID2(),
+      startedAt: isoNow()
+    };
+    try {
+      await writeFile(file, JSON.stringify(lock, null, 2), { encoding: "utf-8", flag: "wx" });
+      return {
+        lock,
+        waited,
+        release: () => removeRestartLockIfOwned(file, lock)
+      };
+    } catch (err) {
+      if (err.code !== "EEXIST") return null;
+    }
+    waited = true;
+    const existing = await readRestartLock(file);
+    if (existing === null || !isProcessAlive(existing.pid)) {
+      if (existing === null) await rm(file, { force: true }).catch(() => {
+      });
+      else await removeRestartLockIfOwned(file, existing);
+      continue;
+    }
+    await sleep(LOCK_CLAIM_RETRY_DELAY_MS);
+  }
+  return null;
+}
+function reusedHandle(lock) {
+  const displayHost = lock.host === "0.0.0.0" ? "localhost" : lock.host;
+  return {
+    host: lock.host,
+    port: lock.port,
+    url: `http://${displayHost}:${lock.port}`,
+    instanceId: lock.instanceId ?? `legacy-${lock.pid}-${lock.startedAt}`,
+    close: async () => {
+    }
+  };
+}
+async function ensureSingleWebServer(options, lockOptions = {}) {
+  const warn = options.warn ?? printWarning;
+  const info = options.info ?? printInfo;
+  const lockFile = getWebLockFile(lockOptions);
+  for (let attempt = 0; attempt <= LOCK_CLAIM_RETRIES; attempt++) {
+    const active = await detectActiveInstance(lockFile);
+    if (active !== null) {
+      info(`Reusing existing web monitor at ${reusedHandle(active).url}`);
+      return reusedHandle(active);
+    }
+    const handle = await startWebServer(options);
+    if (handle === null) {
+      await sleep(LOCK_CLAIM_RETRY_DELAY_MS);
+      continue;
+    }
+    let claimed;
+    try {
+      claimed = await claimWebLock(lockFile, {
+        pid: process.pid,
+        port: handle.port,
+        host: handle.host,
+        startedAt: isoNow(),
+        instanceId: handle.instanceId
+      });
+    } catch (err) {
+      await handle.close();
+      throw err;
+    }
+    if (!claimed) {
+      await handle.close();
+      await sleep(LOCK_CLAIM_RETRY_DELAY_MS);
+      continue;
+    }
+    const originalClose = handle.close;
+    handle.close = async () => {
+      await originalClose();
+      await removeWebLock(lockFile);
+    };
+    return handle;
+  }
+  warn("Could not determine the web monitor lock ownership. Continuing without the web server.");
+  return null;
+}
+var DETACHED_CLAIM_TIMEOUT_MS = 5e3;
+var DETACHED_CLAIM_POLL_MS = 150;
+function inferredStartedAt(health) {
+  if (health.startedAt !== void 0) return health.startedAt;
+  if (health.uptime !== void 0) {
+    return new Date(Date.now() - Math.max(0, health.uptime) * 1e3).toISOString();
+  }
+  return isoNow();
+}
+async function discoverManagedInstance(lockFile, options, monitorOptions) {
+  const existingLock = await readWebLock(lockFile);
+  if (existingLock !== null) {
+    const health2 = isProcessAlive(existingLock.pid) ? await probeHealth(existingLock.host, existingLock.port) : null;
+    if (health2 !== null && (existingLock.instanceId === void 0 || health2.instanceId === existingLock.instanceId)) {
+      return { instance: { lock: existingLock, health: health2, source: "lock" }, unownedMonitor: false };
+    }
+    await removeWebLockIfOwned(lockFile, existingLock);
+  }
+  const health = await probeHealth(options.host, options.port);
+  if (health === null) return { instance: null, unownedMonitor: false };
+  const inspect = monitorOptions.inspectProcess ?? inspectProcessCommand;
+  let owner = null;
+  if (health.pid !== void 0) {
+    const command = await inspect(health.pid);
+    if (command !== null) owner = { pid: health.pid, command };
+  }
+  owner ??= await (monitorOptions.findPortOwner ?? findListeningProcess)(options.port);
+  if (owner === null || !isIssueFlowWebServe(owner, options.port)) {
+    return { instance: null, unownedMonitor: true };
+  }
+  const recovered = {
+    pid: owner.pid,
+    port: options.port,
+    host: options.host,
+    startedAt: inferredStartedAt(health),
+    ...health.instanceId === void 0 ? {} : { instanceId: health.instanceId }
+  };
+  const claimed = await claimWebLock(lockFile, recovered).catch(() => false);
+  if (!claimed) {
+    const winner = await readWebLock(lockFile);
+    if (winner !== null) {
+      const winnerHealth = await probeHealth(winner.host, winner.port);
+      if (winnerHealth !== null) {
+        return {
+          instance: { lock: winner, health: winnerHealth, source: "lock" },
+          unownedMonitor: false
+        };
+      }
+    }
+  }
+  return { instance: { lock: recovered, health, source: "port" }, unownedMonitor: false };
+}
+async function stopManagedInstance(instance, lockFile, options, monitorOptions) {
+  const info = options.info ?? printInfo;
+  const warn = options.warn ?? printWarning;
+  const version = instance.health.version === void 0 ? "" : `, version ${instance.health.version}`;
+  info(`Web monitor: stopping previous instance (pid ${instance.lock.pid}${version}).`);
+  try {
+    (monitorOptions.kill ?? process.kill)(instance.lock.pid, "SIGTERM");
+  } catch (err) {
+    if (err.code === "ESRCH") {
+      await removeWebLockIfOwned(lockFile, instance.lock);
+      info(`Web monitor: previous pid ${instance.lock.pid} was already gone; stale lock removed.`);
+      return true;
+    }
+    warn(
+      `Web monitor: failed to stop pid ${instance.lock.pid} (${err instanceof Error ? err.message : String(err)}). Continuing the pipeline without restarting it.`
+    );
+    return false;
+  }
+  const isAlive = monitorOptions.isAlive ?? isProcessAlive;
+  const deadline = Date.now() + (monitorOptions.shutdownTimeoutMs ?? 5e3);
+  const pollMs = monitorOptions.claimPollIntervalMs ?? DETACHED_CLAIM_POLL_MS;
+  while (Date.now() < deadline) {
+    const alive = isAlive(instance.lock.pid);
+    const health = alive ? await probeHealth(instance.lock.host, instance.lock.port) : null;
+    if (!alive || health === null) {
+      await removeWebLockIfOwned(lockFile, instance.lock);
+      info(`Web monitor: previous instance stopped (pid ${instance.lock.pid}).`);
+      info(
+        "Web monitor: process-local static asset and ETag caches invalidated; no on-disk web build cache exists."
+      );
+      return true;
+    }
+    await sleep(pollMs);
+  }
+  warn(
+    `Web monitor: pid ${instance.lock.pid} did not confirm shutdown in time. Continuing the pipeline without starting a competing instance.`
+  );
+  return false;
+}
+async function stopWebMonitor(options, monitorOptions = {}) {
+  const info = options.info ?? printInfo;
+  const warn = options.warn ?? printWarning;
+  let lockFile;
+  let restartLockFile;
+  try {
+    await mkdir(getGlobalRoot(monitorOptions), { recursive: true });
+    lockFile = getWebLockFile(monitorOptions);
+    restartLockFile = getWebRestartLockFile(monitorOptions);
+  } catch (err) {
+    warn(
+      `Web monitor: global storage unavailable (${err instanceof Error ? err.message : String(err)}).`
+    );
+    return "failed";
+  }
+  const lease = await acquireRestartLock(
+    restartLockFile,
+    monitorOptions.restartLockTimeoutMs ?? 5e3
+  );
+  if (lease === null) {
+    warn("Web monitor: could not acquire the maintenance lock; no process was stopped.");
+    return "failed";
+  }
+  try {
+    const stale = await readWebLock(lockFile);
+    const discovered = await discoverManagedInstance(lockFile, options, monitorOptions);
+    if (discovered.instance === null) {
+      if (stale !== null && !isProcessAlive(stale.pid)) {
+        info(`Web monitor: stale lock for dead pid ${stale.pid} removed.`);
+      }
+      if (discovered.unownedMonitor) {
+        warn(
+          `Web monitor: port ${options.port} looks like an Issue Flow monitor, but its process ownership could not be verified; it was left untouched.`
+        );
+        return "unowned";
+      }
+      info("No web monitor is currently running.");
+      return "not-running";
+    }
+    return await stopManagedInstance(discovered.instance, lockFile, options, monitorOptions) ? "stopped" : "failed";
+  } finally {
+    await lease.release();
+  }
+}
+async function ensureWebMonitor(options, monitorOptions = {}) {
+  const warn = options.warn ?? printWarning;
+  const info = options.info ?? printInfo;
+  let lockFile;
+  let restartLockFile;
+  try {
+    await mkdir(getGlobalRoot(monitorOptions), { recursive: true });
+    lockFile = getWebLockFile(monitorOptions);
+    restartLockFile = getWebRestartLockFile(monitorOptions);
+  } catch (err) {
+    warn(
+      `Web monitor: global storage unavailable (${err instanceof Error ? err.message : String(err)}). Falling back to legacy in-process mode.`
+    );
+    return startWebServer(options);
+  }
+  const coordinationTimeout = monitorOptions.restartLockTimeoutMs ?? 5e3;
+  const restartRequestedAt = Date.now();
+  const restartLease = monitorOptions.restart ? await acquireRestartLock(restartLockFile, coordinationTimeout) : null;
+  if (monitorOptions.restart && restartLease === null) {
+    warn(
+      "Web monitor: could not acquire the restart lock. Continuing the pipeline without changing the server."
+    );
+    return null;
+  }
+  if (!monitorOptions.restart && !await waitForRestart(restartLockFile, coordinationTimeout)) {
+    warn(
+      "Web monitor: another restart is still in progress. Continuing the pipeline without starting a competing instance."
+    );
+    return null;
+  }
+  try {
+    const discovered = await discoverManagedInstance(lockFile, options, monitorOptions);
+    const active = discovered.instance;
+    if (monitorOptions.restart && restartLease?.waited === true && active !== null && Date.parse(active.lock.startedAt) >= restartRequestedAt) {
+      info(
+        `Web monitor: a concurrent restart already started pid ${active.lock.pid}; reusing ${reusedHandle(active.lock).url}`
+      );
+      return reusedHandle(active.lock);
+    }
+    if (active !== null && !monitorOptions.restart) {
+      if (active.source === "port") {
+        info(
+          `Recovered orphaned web monitor pid ${active.lock.pid} on port ${active.lock.port} and restored web.lock.`
+        );
+      }
+      info(`Reusing existing web monitor at ${reusedHandle(active.lock).url}`);
+      return reusedHandle(active.lock);
+    }
+    if (active !== null && monitorOptions.restart) {
+      if (!await stopManagedInstance(active, lockFile, options, monitorOptions)) return null;
+    } else if (discovered.unownedMonitor) {
+      warn(
+        `Web monitor: port ${options.port} answers an Issue Flow health check, but its owning process could not be verified. It was left untouched and no competing server was started.`
+      );
+      return null;
+    } else if (monitorOptions.restart) {
+      info("Web monitor: no previous managed instance was found; starting a fresh one.");
+      info("Web monitor: no on-disk web build cache exists; no files were removed.");
+    }
+    const execPath = monitorOptions.execPath ?? process.execPath;
+    const entryScript = monitorOptions.entryScript ?? process.argv[1];
+    if (entryScript === void 0) {
+      warn("Web monitor: could not determine the CLI entry point to spawn a detached server.");
+      return null;
+    }
+    const args = [
+      entryScript,
+      "web",
+      "serve",
+      "--port",
+      String(options.port),
+      "--host",
+      options.host
+    ];
+    if (options.refreshSeconds !== void 0) {
+      args.push("--refresh", String(options.refreshSeconds));
+    }
+    const spawnFn = monitorOptions.spawn ?? nodeSpawn;
+    try {
+      const child = spawnFn(execPath, args, { detached: true, stdio: "ignore" });
+      child.unref();
+    } catch (err) {
+      warn(
+        `Web monitor: failed to start the detached server (${err instanceof Error ? err.message : String(err)}). Continuing without the web server.`
+      );
+      return null;
+    }
+    const timeoutMs = monitorOptions.claimTimeoutMs ?? DETACHED_CLAIM_TIMEOUT_MS;
+    const pollMs = monitorOptions.claimPollIntervalMs ?? DETACHED_CLAIM_POLL_MS;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const claimed = await detectActiveInstance(lockFile);
+      if (claimed !== null) {
+        const handle = reusedHandle(claimed);
+        const health = await probeHealth(claimed.host, claimed.port);
+        if (monitorOptions.restart) {
+          const version = health?.version === void 0 ? "" : `, version ${health.version}`;
+          info(
+            `Web monitor: new instance started (pid ${claimed.pid}${version}) at ${chalk2.bold.cyan(handle.url)}`
+          );
+        } else {
+          info(`Web monitor running at ${chalk2.bold.cyan(handle.url)}`);
+        }
+        return handle;
+      }
+      await sleep(pollMs);
+    }
+    warn(
+      "Web monitor: the detached server did not start in time. Continuing without the web server."
+    );
+    return null;
+  } finally {
+    await restartLease?.release();
+  }
+}
+
+export {
+  ensureSingleWebServer,
+  stopWebMonitor,
+  ensureWebMonitor
+};
+//# sourceMappingURL=chunk-BMHGRYL6.js.map