@saptools/cf-debugger 0.1.15 → 0.2.0

package/dist/chunk-ZWAQD7KL.js

@@ -0,0 +1,4734 @@
+// src/types.ts
+var CfDebuggerError = class extends Error {
+  code;
+  stderr;
+  constructor(code, message, stderr) {
+    super(message);
+    this.name = "CfDebuggerError";
+    this.code = code;
+    if (stderr !== void 0) {
+      this.stderr = stderr;
+    }
+  }
+};
+
+// src/regions.ts
+var REGION_KEY_PATTERN = /^[a-z]{2}\d{2}(?:-\d{3})?$/;
+var REGION_API_ENDPOINTS = {
+  ae01: "https://api.cf.ae01.hana.ondemand.com",
+  ap01: "https://api.cf.ap01.hana.ondemand.com",
+  ap10: "https://api.cf.ap10.hana.ondemand.com",
+  ap11: "https://api.cf.ap11.hana.ondemand.com",
+  ap12: "https://api.cf.ap12.hana.ondemand.com",
+  ap20: "https://api.cf.ap20.hana.ondemand.com",
+  ap21: "https://api.cf.ap21.hana.ondemand.com",
+  ap30: "https://api.cf.ap30.hana.ondemand.com",
+  ap31: "https://api.cf.ap31.hana.ondemand.com",
+  br10: "https://api.cf.br10.hana.ondemand.com",
+  br20: "https://api.cf.br20.hana.ondemand.com",
+  br30: "https://api.cf.br30.hana.ondemand.com",
+  ca10: "https://api.cf.ca10.hana.ondemand.com",
+  ca20: "https://api.cf.ca20.hana.ondemand.com",
+  ch20: "https://api.cf.ch20.hana.ondemand.com",
+  cn20: "https://api.cf.cn20.platform.sapcloud.cn",
+  cn40: "https://api.cf.cn40.platform.sapcloud.cn",
+  eu01: "https://api.cf.eu01.hana.ondemand.com",
+  eu02: "https://api.cf.eu02.hana.ondemand.com",
+  eu10: "https://api.cf.eu10.hana.ondemand.com",
+  "eu10-002": "https://api.cf.eu10-002.hana.ondemand.com",
+  "eu10-003": "https://api.cf.eu10-003.hana.ondemand.com",
+  "eu10-004": "https://api.cf.eu10-004.hana.ondemand.com",
+  "eu10-005": "https://api.cf.eu10-005.hana.ondemand.com",
+  "eu10-006": "https://api.cf.eu10-006.hana.ondemand.com",
+  eu11: "https://api.cf.eu11.hana.ondemand.com",
+  eu12: "https://api.cf.eu12.hana.ondemand.com",
+  eu13: "https://api.cf.eu13.hana.ondemand.com",
+  eu20: "https://api.cf.eu20.hana.ondemand.com",
+  "eu20-001": "https://api.cf.eu20-001.hana.ondemand.com",
+  "eu20-002": "https://api.cf.eu20-002.hana.ondemand.com",
+  eu21: "https://api.cf.eu21.hana.ondemand.com",
+  eu22: "https://api.cf.eu22.hana.ondemand.com",
+  eu30: "https://api.cf.eu30.hana.ondemand.com",
+  eu31: "https://api.cf.eu31.hana.ondemand.com",
+  il30: "https://api.cf.il30.hana.ondemand.com",
+  in30: "https://api.cf.in30.hana.ondemand.com",
+  jp01: "https://api.cf.jp01.hana.ondemand.com",
+  jp10: "https://api.cf.jp10.hana.ondemand.com",
+  jp20: "https://api.cf.jp20.hana.ondemand.com",
+  jp30: "https://api.cf.jp30.hana.ondemand.com",
+  jp31: "https://api.cf.jp31.hana.ondemand.com",
+  kr30: "https://api.cf.kr30.hana.ondemand.com",
+  sa30: "https://api.cf.sa30.hana.ondemand.com",
+  sa31: "https://api.cf.sa31.hana.ondemand.com",
+  uk20: "https://api.cf.uk20.hana.ondemand.com",
+  us01: "https://api.cf.us01.hana.ondemand.com",
+  us02: "https://api.cf.us02.hana.ondemand.com",
+  us10: "https://api.cf.us10.hana.ondemand.com",
+  "us10-001": "https://api.cf.us10-001.hana.ondemand.com",
+  "us10-002": "https://api.cf.us10-002.hana.ondemand.com",
+  "us10-003": "https://api.cf.us10-003.hana.ondemand.com",
+  us11: "https://api.cf.us11.hana.ondemand.com",
+  us20: "https://api.cf.us20.hana.ondemand.com",
+  us21: "https://api.cf.us21.hana.ondemand.com",
+  "us21-001": "https://api.cf.us21-001.hana.ondemand.com",
+  us22: "https://api.cf.us22.hana.ondemand.com",
+  us30: "https://api.cf.us30.hana.ondemand.com",
+  us31: "https://api.cf.us31.hana.ondemand.com",
+  us32: "https://api.cf.us32.hana.ondemand.com"
+};
+function synthesizeApiEndpoint(regionKey) {
+  const domain = regionKey.startsWith("cn") ? "platform.sapcloud.cn" : "hana.ondemand.com";
+  return `https://api.cf.${regionKey}.${domain}`;
+}
+function resolveApiEndpoint(regionKey, override, onWarning) {
+  if (override !== void 0 && override !== "") {
+    return override;
+  }
+  if (!REGION_KEY_PATTERN.test(regionKey)) {
+    throw new CfDebuggerError(
+      "UNKNOWN_REGION",
+      `Unknown region key: ${JSON.stringify(regionKey)}. Expected a key matching aa00 or aa00-000, or pass --api-endpoint <url>.`
+    );
+  }
+  const endpoint = Object.hasOwn(REGION_API_ENDPOINTS, regionKey) ? REGION_API_ENDPOINTS[regionKey] : void 0;
+  if (endpoint !== void 0) {
+    return endpoint;
+  }
+  const synthesized = synthesizeApiEndpoint(regionKey);
+  onWarning?.(
+    `Region key ${regionKey} is not in the curated region list; using synthesized API endpoint ${synthesized}. Verify it or pass --api-endpoint <url>.`
+  );
+  return synthesized;
+}
+function listKnownRegionKeys() {
+  return Object.keys(REGION_API_ENDPOINTS);
+}
+
+// src/cloud-foundry/execute.ts
+import { execFile } from "child_process";
+import nodeProcess from "process";
+var MAX_BUFFER = 16 * 1024 * 1024;
+var DEFAULT_CF_COMMAND_TIMEOUT_MS = 6e4;
+var DEFAULT_CF_OPERATION_TIMEOUT_MS = 3e5;
+var REDACTED_ARG = "<redacted>";
+var MAX_RETRY_DELAY_MS = 1e4;
+function buildEnv(cfHome) {
+  return { ...nodeProcess.env, CF_COLOR: "false", CF_HOME: cfHome };
+}
+function resolveBin(context) {
+  return context.command ?? nodeProcess.env["CF_DEBUGGER_CF_BIN"] ?? "cf";
+}
+function redactSensitiveText(text, values) {
+  return normalizeSensitiveValues(values).reduce((current, value) => current.split(value).join(REDACTED_ARG), text);
+}
+function normalizeSensitiveValues(values) {
+  return [...new Set(values.filter((value) => value.length > 0))].sort((left, right) => right.length - left.length);
+}
+function abortError(context) {
+  if (context.deadlineAt !== void 0 && Date.now() >= context.deadlineAt) {
+    const timeoutMs = context.startupTimeoutMs;
+    const duration = timeoutMs === void 0 ? "configured" : `${(timeoutMs / 1e3).toString()}s`;
+    return new CfDebuggerError(
+      "STARTUP_TIMEOUT",
+      `Debugger startup exceeded its ${duration} deadline during ${context.phase ?? "a CF command"}.`
+    );
+  }
+  return new CfDebuggerError("ABORTED", "Operation aborted by caller");
+}
+function waitForRetry(delayMs, context) {
+  if (context.signal?.aborted) {
+    return Promise.reject(abortError(context));
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError(context));
+    };
+    const timer = setTimeout(() => {
+      context.signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, delayMs);
+    context.signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function formatArgsForError(args, sensitiveValues) {
+  return redactSensitiveText(args.join(" "), sensitiveValues);
+}
+function optionalString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function readFailureDetails(error) {
+  const object = typeof error === "object" && error !== null ? error : void 0;
+  const field3 = (key) => object === void 0 ? void 0 : Reflect.get(object, key);
+  return {
+    code: optionalString(field3("code")),
+    killed: field3("killed") === true,
+    message: error instanceof Error ? error.message : String(error),
+    stderr: optionalString(field3("stderr"))
+  };
+}
+function hasTransientDiagnostic(error) {
+  const diagnostic = error.stderr?.toLowerCase() ?? "";
+  const phrases = [
+    "error performing request",
+    "connection reset by peer",
+    "service unavailable",
+    "bad gateway",
+    "gateway timeout",
+    "dial tcp",
+    "i/o timeout"
+  ];
+  return phrases.some((phrase) => diagnostic.includes(phrase));
+}
+function isCredentialRejection(args, error) {
+  if (args[0] !== "auth") {
+    return false;
+  }
+  const diagnostic = `${error.stderr ?? ""} ${error.message}`.toLowerCase();
+  const phrases = [
+    "authentication failed",
+    "credentials were rejected",
+    "invalid credentials",
+    "invalid email",
+    "invalid password",
+    "invalid username",
+    "incorrect password",
+    "not authorized",
+    "unauthorized"
+  ];
+  return phrases.some((phrase) => diagnostic.includes(phrase)) || /\b(?:401|403)\b/.test(diagnostic);
+}
+function isTransientNetworkError(error, attemptTimedOut) {
+  if (attemptTimedOut) {
+    return true;
+  }
+  const networkCodes = [
+    "ETIMEDOUT",
+    "ECONNRESET",
+    "ENOTFOUND",
+    "ECONNREFUSED",
+    "EHOSTUNREACH",
+    "ENETUNREACH"
+  ];
+  return error.code !== void 0 && networkCodes.includes(error.code) || hasTransientDiagnostic(error);
+}
+function requirePositiveMilliseconds(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new CfDebuggerError(
+      "UNSAFE_INPUT",
+      `${name} must be a positive safe integer.`
+    );
+  }
+  return value;
+}
+function resolveRunOptions(context, input) {
+  const options = typeof input === "number" ? { timeoutMs: input } : input;
+  const retryBudgetMs = requirePositiveMilliseconds(
+    options.retryBudgetMs ?? DEFAULT_CF_OPERATION_TIMEOUT_MS,
+    "retryBudgetMs"
+  );
+  const attemptTimeoutMs = requirePositiveMilliseconds(
+    options.timeoutMs ?? DEFAULT_CF_COMMAND_TIMEOUT_MS,
+    "timeoutMs"
+  );
+  const deadlineAt = context.deadlineAt ?? Date.now() + retryBudgetMs;
+  if (!Number.isSafeInteger(deadlineAt) || deadlineAt <= 0) {
+    throw new CfDebuggerError(
+      "UNSAFE_INPUT",
+      "deadlineAt must be a positive safe integer timestamp."
+    );
+  }
+  return {
+    env: options.env,
+    redactionValues: normalizeSensitiveValues([
+      ...context.sensitiveValues ?? [],
+      ...options.sensitiveValues ?? []
+    ]),
+    attemptTimeoutMs,
+    deadlineAt
+  };
+}
+async function executeCfAttempt(args, context, options, timeoutMs) {
+  const result = await executeFileBounded(resolveBin(context), args, {
+    env: {
+      ...buildEnv(context.cfHome),
+      ...options.env,
+      CF_COLOR: "false",
+      CF_HOME: context.cfHome
+    },
+    maxBuffer: MAX_BUFFER,
+    timeoutMs,
+    ...context.signal === void 0 ? {} : { signal: context.signal }
+  });
+  return result.stdout;
+}
+function signalCfChild(child, signal) {
+  try {
+    child.kill(signal);
+  } catch {
+  }
+}
+async function executeFileBounded(command, args, options) {
+  return await new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+    };
+    const rejectOnce = (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+    const child = execFile(command, [...args], {
+      env: options.env,
+      maxBuffer: options.maxBuffer ?? MAX_BUFFER,
+      encoding: "utf8"
+    }, (error, stdout, stderr) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      if (error === null && options.signal?.aborted !== true) {
+        resolve({ stderr, stdout });
+        return;
+      }
+      const failure = error ?? new Error("Command was aborted.");
+      Reflect.set(failure, "stderr", stderr);
+      reject(failure);
+    });
+    const terminateAndReject = (code, message) => {
+      if (settled) {
+        return;
+      }
+      signalCfChild(child, "SIGKILL");
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      const failure = new Error(message);
+      Reflect.set(failure, "code", code);
+      Reflect.set(failure, "killed", true);
+      Reflect.set(failure, "stderr", "");
+      rejectOnce(failure);
+    };
+    const onAbort = () => {
+      terminateAndReject("ABORT_ERR", "Command was aborted.");
+    };
+    const timer = setTimeout(() => {
+      terminateAndReject("ETIMEDOUT", "Command exceeded its execution deadline.");
+    }, options.timeoutMs);
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    if (options.signal?.aborted) {
+      onAbort();
+    }
+  });
+}
+function retryDelayMs(attempt) {
+  return Math.min(1e3 * 2 ** Math.min(attempt - 1, 10), MAX_RETRY_DELAY_MS);
+}
+function createCfCliError(args, failure, redactionValues) {
+  const stderr = redactSensitiveText(failure.stderr?.trim() ?? "", redactionValues);
+  const fallback = redactSensitiveText(failure.message, redactionValues);
+  const detail = stderr.length > 0 ? stderr : fallback;
+  return new CfDebuggerError(
+    "CF_CLI_FAILED",
+    `cf ${formatArgsForError(args, redactionValues)} failed: ${detail}`,
+    stderr
+  );
+}
+function timeoutError(context, args, redactionValues) {
+  if (context.deadlineAt !== void 0) {
+    const timeoutMs = context.startupTimeoutMs;
+    const duration = timeoutMs === void 0 ? "configured" : `${(timeoutMs / 1e3).toString()}s`;
+    return new CfDebuggerError(
+      "STARTUP_TIMEOUT",
+      `Debugger startup could not complete within its ${duration} deadline during ${context.phase ?? "a CF command"}.`
+    );
+  }
+  return new CfDebuggerError(
+    "CF_CLI_TIMEOUT",
+    `cf ${formatArgsForError(args, redactionValues)} exceeded its overall retry budget.`
+  );
+}
+function reportRetry(context, args, attempt, delayMs, remainingMs, redactionValues) {
+  context.onRetry?.({
+    attempt,
+    command: `cf ${formatArgsForError(args, redactionValues)}`,
+    delayMs,
+    remainingMs
+  });
+}
+async function runCf(args, context, input = {}) {
+  if (context.signal?.aborted) {
+    throw abortError(context);
+  }
+  const options = resolveRunOptions(context, input);
+  let attempt = 0;
+  for (; ; ) {
+    const remainingMs = options.deadlineAt - Date.now();
+    if (remainingMs <= 0) {
+      throw timeoutError(context, args, options.redactionValues);
+    }
+    attempt += 1;
+    const attemptTimeoutMs = Math.max(1, Math.min(options.attemptTimeoutMs, remainingMs));
+    const startedAt = Date.now();
+    try {
+      return await executeCfAttempt(args, context, options, attemptTimeoutMs);
+    } catch (error) {
+      const failure = readFailureDetails(error);
+      if (context.signal?.aborted || failure.code === "ABORT_ERR") {
+        throw abortError(context);
+      }
+      const elapsedMs = Date.now() - startedAt;
+      const attemptTimedOut = failure.killed && elapsedMs + 100 >= attemptTimeoutMs;
+      if (isCredentialRejection(args, failure) || !isTransientNetworkError(failure, attemptTimedOut)) {
+        throw createCfCliError(args, failure, options.redactionValues);
+      }
+      const delayMs = retryDelayMs(attempt);
+      const afterFailureMs = options.deadlineAt - Date.now();
+      if (afterFailureMs <= delayMs) {
+        throw timeoutError(context, args, options.redactionValues);
+      }
+      reportRetry(
+        context,
+        args,
+        attempt,
+        delayMs,
+        afterFailureMs,
+        options.redactionValues
+      );
+      await waitForRetry(delayMs, context);
+    }
+  }
+}
+
+// src/cloud-foundry/commands.ts
+var CURRENT_TARGET_TIMEOUT_MS = 3e4;
+function rethrowControlFlowError(error) {
+  if (error instanceof CfDebuggerError && (error.code === "ABORTED" || error.code === "STARTUP_TIMEOUT")) {
+    throw error;
+  }
+}
+async function cfApi(apiEndpoint, context) {
+  await runCf(["api", apiEndpoint], context);
+}
+async function cfAuth(email, password, context) {
+  try {
+    await runCf(["auth"], context, {
+      env: { CF_PASSWORD: password, CF_USERNAME: email },
+      sensitiveValues: [email, password]
+    });
+  } catch (error) {
+    rethrowControlFlowError(error);
+    if (error instanceof CfDebuggerError) {
+      throw new CfDebuggerError(
+        "CF_AUTH_FAILED",
+        `${error.message}. Check SAP_EMAIL and SAP_PASSWORD before retrying.`,
+        error.stderr
+      );
+    }
+    throw error;
+  }
+}
+async function cfLogin(apiEndpoint, email, password, context) {
+  try {
+    await cfApi(apiEndpoint, context);
+  } catch (error) {
+    rethrowControlFlowError(error);
+    if (error instanceof CfDebuggerError) {
+      throw new CfDebuggerError("CF_LOGIN_FAILED", error.message, error.stderr);
+    }
+    throw error;
+  }
+  await cfAuth(email, password, context);
+}
+async function cfTarget(org, space, context) {
+  try {
+    await runCf(["target", "-o", org, "-s", space], context);
+  } catch (err) {
+    rethrowControlFlowError(err);
+    if (err instanceof CfDebuggerError) {
+      throw new CfDebuggerError("CF_TARGET_FAILED", err.message, err.stderr);
+    }
+    throw err;
+  }
+}
+async function cfAppExists(appName, context) {
+  try {
+    await runCf(["app", appName], context);
+    return true;
+  } catch (err) {
+    rethrowControlFlowError(err);
+    const stderr = err instanceof CfDebuggerError ? err.stderr ?? "" : "";
+    if (stderr.toLowerCase().includes("not found")) {
+      return false;
+    }
+    throw err;
+  }
+}
+async function cfSshEnabled(appName, context) {
+  try {
+    const stdout = await runCf(["ssh-enabled", appName], context);
+    const normalized = stdout.toLowerCase();
+    if (normalized.includes("ssh support is enabled")) {
+      return "enabled";
+    }
+    if (normalized.includes("ssh support is disabled")) {
+      return "disabled";
+    }
+    return "unknown";
+  } catch (err) {
+    rethrowControlFlowError(err);
+    return "unknown";
+  }
+}
+async function cfEnableSsh(appName, context) {
+  try {
+    await runCf(["enable-ssh", appName], context);
+  } catch (err) {
+    rethrowControlFlowError(err);
+    if (err instanceof CfDebuggerError) {
+      throw new CfDebuggerError("SSH_NOT_ENABLED", err.message, err.stderr);
+    }
+    throw err;
+  }
+}
+async function cfRestartApp(appName, context) {
+  await runCf(["restart", appName], context);
+}
+async function readCurrentCfTarget(options = {}) {
+  try {
+    const { stdout } = await executeFileBounded(
+      options.command ?? process.env["CF_DEBUGGER_CF_BIN"] ?? "cf",
+      ["target"],
+      {
+        env: { ...process.env, ...options.env, CF_COLOR: "false" },
+        maxBuffer: 16 * 1024 * 1024,
+        timeoutMs: options.timeoutMs ?? CURRENT_TARGET_TIMEOUT_MS,
+        ...options.signal === void 0 ? {} : { signal: options.signal }
+      }
+    );
+    return parseCurrentCfTarget(stdout);
+  } catch (error) {
+    if (options.signal?.aborted === true || typeof error === "object" && error !== null && Reflect.get(error, "code") === "ABORT_ERR") {
+      throw new CfDebuggerError("ABORTED", "Current CF target discovery was aborted.");
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CfDebuggerError("CF_TARGET_FAILED", `cf target failed: ${message}`);
+  }
+}
+function parseCurrentCfTarget(stdout) {
+  const fields = parseTargetFields(stdout);
+  const apiEndpoint = fields.get("api endpoint");
+  const org = fields.get("org");
+  const space = fields.get("space");
+  if (!isPresent(apiEndpoint) || !isPresent(org) || !isPresent(space)) {
+    return void 0;
+  }
+  const region = regionKeyForApiEndpoint(apiEndpoint);
+  return {
+    apiEndpoint,
+    ...region === void 0 ? {} : { region },
+    org,
+    space
+  };
+}
+function requireCurrentCfRegion(target, instruction = "Pass --region explicitly.") {
+  if (target.region !== void 0) {
+    return target.region;
+  }
+  throw new CfDebuggerError(
+    "CF_TARGET_FAILED",
+    `Current CF API endpoint "${target.apiEndpoint}" does not match a known SAP region. ${instruction}`
+  );
+}
+function parseTargetFields(stdout) {
+  return new Map(
+    stdout.split("\n").map((line) => {
+      const separator = line.indexOf(":");
+      if (separator < 0) {
+        return void 0;
+      }
+      return [
+        line.slice(0, separator).trim().toLowerCase(),
+        line.slice(separator + 1).trim()
+      ];
+    }).filter((field3) => field3 !== void 0)
+  );
+}
+function regionKeyForApiEndpoint(apiEndpoint) {
+  const normalized = normalizeApiEndpoint(apiEndpoint);
+  const known = listKnownRegionKeys().find((key) => normalizeApiEndpoint(resolveApiEndpoint(key)) === normalized);
+  if (known !== void 0) {
+    return known;
+  }
+  return regionKeyFromSapApiEndpoint(normalized);
+}
+function normalizeApiEndpoint(apiEndpoint) {
+  return apiEndpoint.trim().replace(/\/+$/, "").toLowerCase();
+}
+function regionKeyFromSapApiEndpoint(apiEndpoint) {
+  const match = /^https:\/\/api\.cf\.([a-z]{2}\d{2}(?:-\d{3})?)\.(hana\.ondemand\.com|platform\.sapcloud\.cn)$/.exec(apiEndpoint);
+  const regionKey = match?.[1];
+  const domain = match?.[2];
+  if (regionKey === void 0 || domain === void 0) {
+    return void 0;
+  }
+  const expectedDomain = regionKey.startsWith("cn") ? "platform.sapcloud.cn" : "hana.ondemand.com";
+  return domain === expectedDomain ? regionKey : void 0;
+}
+function isPresent(value) {
+  return value !== void 0 && value.length > 0;
+}
+
+// src/cloud-foundry/node-process.ts
+var DEFAULT_CF_PROCESS = "web";
+var DEFAULT_CF_INSTANCE = 0;
+var DEFAULT_NODE_INSPECTOR_PORT = 9229;
+var MAX_MARKER_BYTES = 65536;
+var PID_LIST_PATTERN = /^\d+(?:,\d+)*$/;
+var PID_PATTERN = /^\d+$/;
+function validateProcessName(processName) {
+  if (processName.length === 0 || processName.startsWith("-") || hasControlCharacter(processName)) {
+    throw new CfDebuggerError(
+      "UNSAFE_INPUT",
+      "process must be non-empty, must not start with a hyphen, and must contain no control characters."
+    );
+  }
+}
+function validateInstance(instance) {
+  if (!Number.isSafeInteger(instance) || instance < 0) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "instance must be a non-negative safe integer.");
+  }
+}
+function validateNodePid(nodePid) {
+  if (nodePid !== void 0 && (!Number.isSafeInteger(nodePid) || nodePid <= 0)) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "nodePid must be a positive safe integer.");
+  }
+}
+function validateRemotePort(remotePort) {
+  if (!Number.isSafeInteger(remotePort) || remotePort < 1 || remotePort > 65535) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "remotePort must be an integer between 1 and 65535.");
+  }
+}
+function resolveNodeTarget(input) {
+  const processName = (input.process ?? DEFAULT_CF_PROCESS).trim();
+  const instance = input.instance ?? DEFAULT_CF_INSTANCE;
+  validateProcessName(processName);
+  validateInstance(instance);
+  validateNodePid(input.nodePid);
+  return input.nodePid === void 0 ? { process: processName, instance } : { process: processName, instance, nodePid: input.nodePid };
+}
+function hasControlCharacter(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code < 32 || code === 127) {
+      return true;
+    }
+  }
+  return false;
+}
+function buildNodeInspectorCommand(nodePid, remotePort = DEFAULT_NODE_INSPECTOR_PORT) {
+  validateNodePid(nodePid);
+  validateRemotePort(remotePort);
+  const remotePortHex = remotePort.toString(16).toUpperCase().padStart(4, "0");
+  return NODE_INSPECTOR_SCRIPT.replace("__REQUESTED_NODE_PID__", nodePid?.toString() ?? "").replaceAll("__INSPECTOR_PORT_HEX__", remotePortHex);
+}
+function parseNodeInspectorMarkers(stdout, remotePort = DEFAULT_NODE_INSPECTOR_PORT) {
+  validateRemotePort(remotePort);
+  if (Buffer.byteLength(stdout, "utf8") > MAX_MARKER_BYTES) {
+    throw new CfDebuggerError("INSPECTOR_OUTPUT_TOO_LARGE", "Inspector startup output exceeded 65536 bytes.");
+  }
+  const markers = parseMarkers(stdout);
+  throwForFailureMarker(markers, remotePort);
+  const remoteNodePid = readMarkerPid(markers, "saptools-inspector-node-pid");
+  const ownerPid = readMarkerPid(markers, "saptools-inspector-owner-pid");
+  if (!markers.has("saptools-inspector-ready") || remoteNodePid === void 0 || ownerPid !== remoteNodePid) {
+    throw new CfDebuggerError("INSPECTOR_NOT_READY", "Remote Node inspector did not report a verified owner.");
+  }
+  return { remoteNodePid };
+}
+function parseMarkers(stdout) {
+  const markers = /* @__PURE__ */ new Map();
+  for (const rawLine of stdout.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line.startsWith("saptools-inspector-")) {
+      continue;
+    }
+    const separator = line.indexOf("=");
+    markers.set(separator < 0 ? line : line.slice(0, separator), separator < 0 ? "" : line.slice(separator + 1));
+  }
+  return markers;
+}
+function throwForFailureMarker(markers, remotePort) {
+  if (markers.has("saptools-inspector-node-not-found")) {
+    throw new CfDebuggerError("NODE_PROCESS_NOT_FOUND", "No Node.js process was found in the selected CF instance.");
+  }
+  const ambiguous = markers.get("saptools-inspector-node-ambiguous");
+  if (ambiguous !== void 0) {
+    const candidates = PID_LIST_PATTERN.test(ambiguous) ? ambiguous.split(",").join(", ") : "unknown";
+    throw new CfDebuggerError("NODE_PROCESS_AMBIGUOUS", `Multiple Node.js processes were found: ${candidates}. Pass nodePid explicitly.`);
+  }
+  const invalid = markers.get("saptools-inspector-node-invalid");
+  if (invalid !== void 0) {
+    throw new CfDebuggerError("NODE_PID_INVALID", `Remote PID ${safePidText(invalid)} is not a Node.js process.`);
+  }
+  throwForRuntimeFailure(markers, remotePort);
+}
+function throwForRuntimeFailure(markers, remotePort) {
+  const mismatch = markers.get("saptools-inspector-owner-mismatch");
+  if (mismatch !== void 0) {
+    const [selected = "unknown", owner = "unknown"] = mismatch.split(":", 2).map(safePidText);
+    throw new CfDebuggerError(
+      "INSPECTOR_OWNER_MISMATCH",
+      `Selected Node PID ${selected}, but inspector port ${remotePort.toString()} is owned by PID ${owner}.`
+    );
+  }
+  const signalFailed = markers.get("saptools-inspector-signal-failed");
+  if (signalFailed !== void 0) {
+    throw new CfDebuggerError("USR1_SIGNAL_FAILED", `Failed to signal remote Node PID ${safePidText(signalFailed)}.`);
+  }
+  if (markers.has("saptools-inspector-not-ready")) {
+    throw new CfDebuggerError(
+      "INSPECTOR_NOT_READY",
+      `Remote Node inspector did not become ready on port ${remotePort.toString()}.`
+    );
+  }
+}
+function readMarkerPid(markers, name) {
+  const raw = markers.get(name);
+  if (raw === void 0 || !PID_PATTERN.test(raw)) {
+    return void 0;
+  }
+  const value = Number.parseInt(raw, 10);
+  return Number.isSafeInteger(value) && value > 0 ? value : void 0;
+}
+function safePidText(raw) {
+  return PID_PATTERN.test(raw) ? raw : "unknown";
+}
+var NODE_INSPECTOR_SCRIPT = [
+  "requested_node_pid=__REQUESTED_NODE_PID__",
+  "inspector_port_hex=__INSPECTOR_PORT_HEX__",
+  "is_node_pid() {",
+  '  candidate_pid="$1"',
+  '  candidate_exe="$(readlink "/proc/$candidate_pid/exe" 2>/dev/null || true)"',
+  '  [ "${candidate_exe##*/}" = node ] || [ "${candidate_exe##*/}" = nodejs ]',
+  "}",
+  "find_listener_inode() {",
+  '  listener_hex="$1"',
+  '  [ -n "$listener_hex" ] || return 0',
+  `  awk -v ph=":$listener_hex" '$4 == "0A" && $2 ~ (ph "$") { print $10; exit }' /proc/net/tcp /proc/net/tcp6 2>/dev/null`,
+  "}",
+  "find_inode_owner_fallback() {",
+  '  socket_inode="$1"',
+  '  [ -n "$socket_inode" ] || return 0',
+  "  for pid_dir in /proc/[0-9]*; do",
+  '    [ -d "$pid_dir/fd" ] || continue',
+  '    for fd_path in "$pid_dir"/fd/*; do',
+  '      fd_target="$(readlink "$fd_path" 2>/dev/null || true)"',
+  '      if [ "$fd_target" = "socket:[$socket_inode]" ]; then',
+  `        printf '%s' "\${pid_dir##*/}"`,
+  "        return 0",
+  "      fi",
+  "    done",
+  "  done",
+  "}",
+  "find_inode_owner() {",
+  '  socket_inode="$1"',
+  '  [ -n "$socket_inode" ] || return 0',
+  '  if [ "$find_supports_lname" = true ]; then',
+  '    fd_path="$(find /proc/[0-9]*/fd -lname "socket:\\[$socket_inode\\]" -print -quit 2>/dev/null || true)"',
+  '    [ -n "$fd_path" ] || return 0',
+  '    pid_path="${fd_path#/proc/}"',
+  `    printf '%s' "\${pid_path%%/*}"`,
+  "    return 0",
+  "  fi",
+  '  find_inode_owner_fallback "$socket_inode"',
+  "}",
+  "pid_owns_inode() {",
+  '  candidate_pid="$1"',
+  '  socket_inode="$2"',
+  '  [ -d "/proc/$candidate_pid/fd" ] || return 1',
+  '  if [ "$find_supports_lname" = true ]; then',
+  '    fd_path="$(find "/proc/$candidate_pid/fd" -lname "socket:\\[$socket_inode\\]" -print -quit 2>/dev/null || true)"',
+  '    [ -n "$fd_path" ]',
+  "    return",
+  "  fi",
+  '  for fd_path in "/proc/$candidate_pid/fd"/*; do',
+  '    fd_target="$(readlink "$fd_path" 2>/dev/null || true)"',
+  '    [ "$fd_target" = "socket:[$socket_inode]" ] && return 0',
+  "  done",
+  "  return 1",
+  "}",
+  "find_listener_pid() {",
+  '  socket_inode="$(find_listener_inode "$1")"',
+  '  find_inode_owner "$socket_inode"',
+  "}",
+  "find_inspector_owner() {",
+  '  find_listener_pid "$inspector_port_hex"',
+  "}",
+  "find_selected_inspector_owner() {",
+  '  candidate_pid="$1"',
+  '  socket_inode="$(find_listener_inode "$inspector_port_hex")"',
+  '  [ -n "$socket_inode" ] || return 0',
+  '  if pid_owns_inode "$candidate_pid" "$socket_inode"; then',
+  `    printf '%s' "$candidate_pid"`,
+  "    return 0",
+  "  fi",
+  '  find_inode_owner "$socket_inode"',
+  "}",
+  "find_app_port_listener() {",
+  '  [ -n "${PORT:-}" ] || return 0',
+  `  app_port_hex="$(printf '%04X' "$PORT" 2>/dev/null || true)"`,
+  '  find_listener_pid "$app_port_hex"',
+  "}",
+  "find_supports_lname=false",
+  "if find /proc/self/fd -lname __saptools_no_match__ -print -quit >/dev/null 2>&1; then",
+  "  find_supports_lname=true",
+  "fi",
+  'owner_pid="$(find_inspector_owner)"',
+  'selected_pid=""',
+  'if [ -n "$requested_node_pid" ]; then',
+  '  if ! is_node_pid "$requested_node_pid"; then',
+  '    echo "saptools-inspector-node-invalid=$requested_node_pid"',
+  "    exit 0",
+  "  fi",
+  '  selected_pid="$requested_node_pid"',
+  'elif [ -n "$owner_pid" ] && is_node_pid "$owner_pid"; then',
+  '  selected_pid="$owner_pid"',
+  "else",
+  '  candidate_pids=""',
+  "  candidate_count=0",
+  "  for pid_dir in /proc/[0-9]*; do",
+  '    candidate_pid="${pid_dir##*/}"',
+  '    is_node_pid "$candidate_pid" || continue',
+  "    candidate_count=$((candidate_count + 1))",
+  '    candidate_pids="${candidate_pids}${candidate_pids:+,}$candidate_pid"',
+  '    selected_pid="$candidate_pid"',
+  "  done",
+  '  if [ "$candidate_count" -eq 0 ]; then echo saptools-inspector-node-not-found; exit 0; fi',
+  '  if [ "$candidate_count" -ne 1 ]; then',
+  '    app_port_pid="$(find_app_port_listener)"',
+  '    if [ -n "$app_port_pid" ] && is_node_pid "$app_port_pid"; then',
+  '      selected_pid="$app_port_pid"',
+  "    else",
+  '      echo "saptools-inspector-node-ambiguous=$candidate_pids"; exit 0',
+  "    fi",
+  "  fi",
+  "fi",
+  'if [ -n "$owner_pid" ]; then',
+  '  if [ "$owner_pid" != "$selected_pid" ]; then echo "saptools-inspector-owner-mismatch=$selected_pid:$owner_pid"; exit 0; fi',
+  '  echo "saptools-inspector-node-pid=$selected_pid"',
+  '  echo "saptools-inspector-owner-pid=$owner_pid"',
+  "  echo saptools-inspector-ready",
+  "  exit 0",
+  "fi",
+  'if ! kill -USR1 "$selected_pid" 2>/dev/null; then echo "saptools-inspector-signal-failed=$selected_pid"; exit 0; fi',
+  "attempt=0",
+  'while [ "$attempt" -lt 20 ]; do',
+  '  owner_pid="$(find_selected_inspector_owner "$selected_pid")"',
+  '  if [ -n "$owner_pid" ]; then',
+  '    if [ "$owner_pid" != "$selected_pid" ]; then echo "saptools-inspector-owner-mismatch=$selected_pid:$owner_pid"; exit 0; fi',
+  '    echo "saptools-inspector-node-pid=$selected_pid"',
+  '    echo "saptools-inspector-owner-pid=$owner_pid"',
+  "    echo saptools-inspector-ready",
+  "    exit 0",
+  "  fi",
+  "  attempt=$((attempt + 1))",
+  // CF Linux stacks accept fractional sleep; retain a one-second POSIX fallback.
+  "  sleep 0.25 2>/dev/null || sleep 1",
+  "done",
+  'echo "saptools-inspector-not-ready=$selected_pid"'
+].join("\n");
+
+// src/cloud-foundry/ssh.ts
+import { spawn } from "child_process";
+import nodeProcess2 from "process";
+import { StringDecoder } from "string_decoder";
+var DEFAULT_MAX_OUTPUT_BYTES = 65536;
+var LIVE_LINE_LIMIT_BYTES = 65536;
+var MAX_REDACTION_OVERLAP_BYTES = 4096;
+var SENSITIVE_OUTPUT_OMITTED = "[diagnostic output omitted to protect a sensitive value]";
+var tunnelCaptures = /* @__PURE__ */ new WeakMap();
+function buildCfSshArgs(appName, target, tail) {
+  const resolved = resolveNodeTarget(target);
+  const processArgs = resolved.process === DEFAULT_CF_PROCESS ? [] : ["--process", resolved.process];
+  return [
+    "ssh",
+    appName,
+    ...processArgs,
+    "-i",
+    resolved.instance.toString(),
+    ...tail
+  ];
+}
+async function cfSshOneShot(appName, command, context, rawOptions = DEFAULT_CF_COMMAND_TIMEOUT_MS) {
+  if (context.signal?.aborted || isDeadlineExpired(context)) {
+    throw sshAbortError(context);
+  }
+  const options = resolveSshOptions(rawOptions, context);
+  const args = buildCfSshArgs(appName, options.target, [
+    "--disable-pseudo-tty",
+    "-c",
+    command
+  ]);
+  return await runSshOneShot(args, context, options);
+}
+function resolveSshOptions(raw, context) {
+  const input = typeof raw === "number" ? { timeoutMs: raw } : raw;
+  const requestedTimeoutMs = input.timeoutMs ?? DEFAULT_CF_COMMAND_TIMEOUT_MS;
+  const maxOutputBytes = input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  if (!Number.isSafeInteger(requestedTimeoutMs) || requestedTimeoutMs <= 0) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "timeoutMs must be a positive safe integer.");
+  }
+  if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes <= 0) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "maxOutputBytes must be a positive safe integer.");
+  }
+  const remainingMs = context.deadlineAt === void 0 ? requestedTimeoutMs : Math.max(1, context.deadlineAt - Date.now());
+  return {
+    target: input,
+    timeoutMs: Math.min(requestedTimeoutMs, remainingMs),
+    maxOutputBytes
+  };
+}
+function createBoundedOutput() {
+  return { chunks: [], bytes: 0, truncated: false };
+}
+function appendHead(output, data, outputLimit, retainedLimit) {
+  const incoming = Buffer.isBuffer(data) ? data : Buffer.from(data);
+  if (incoming.byteLength === 0) {
+    return;
+  }
+  output.truncated ||= output.bytes + incoming.byteLength > outputLimit;
+  const remaining = Math.max(0, retainedLimit - output.bytes);
+  if (remaining === 0) {
+    return;
+  }
+  const next = incoming.byteLength <= remaining ? incoming : Buffer.from(incoming.subarray(0, remaining));
+  output.chunks.push(next);
+  output.bytes += next.byteLength;
+}
+function appendTail(output, data, outputLimit, retainedLimit) {
+  const incoming = Buffer.isBuffer(data) ? data : Buffer.from(data);
+  if (incoming.byteLength === 0) {
+    return;
+  }
+  output.chunks.push(incoming);
+  output.bytes += incoming.byteLength;
+  output.truncated ||= output.bytes > outputLimit;
+  while (output.bytes > retainedLimit && output.chunks.length > 0) {
+    const first = output.chunks[0];
+    if (first === void 0) {
+      break;
+    }
+    const excess = output.bytes - retainedLimit;
+    if (first.byteLength <= excess) {
+      output.chunks.shift();
+      output.bytes -= first.byteLength;
+    } else {
+      output.chunks[0] = Buffer.from(first.subarray(excess));
+      output.bytes -= excess;
+    }
+  }
+}
+function outputText(output) {
+  return Buffer.concat(output.chunks, output.bytes).toString("utf8");
+}
+function createRedactionPolicy(values) {
+  const sensitiveValues = normalizeSensitiveValues(values);
+  const overlapBytes = sensitiveValues.reduce(
+    (largest, value) => Math.max(largest, Buffer.byteLength(value)),
+    0
+  );
+  return {
+    safeToSurface: overlapBytes <= MAX_REDACTION_OVERLAP_BYTES && !sensitiveValues.some((value) => /[\r\n]/.test(value)),
+    sensitiveValues,
+    overlapBytes: Math.min(overlapBytes, MAX_REDACTION_OVERLAP_BYTES)
+  };
+}
+function limitText(text, limit, keep) {
+  const buffer = Buffer.from(text);
+  if (buffer.byteLength <= limit) {
+    return text;
+  }
+  const limited = keep === "head" ? buffer.subarray(0, limit) : buffer.subarray(buffer.byteLength - limit);
+  return limited.toString("utf8");
+}
+function safeOutputText(output, policy, limit, keep) {
+  if (!policy.safeToSurface && output.bytes > 0) {
+    return SENSITIVE_OUTPUT_OMITTED;
+  }
+  const redacted = redactSensitiveText(outputText(output), policy.sensitiveValues);
+  return limitText(redacted, limit, keep);
+}
+function createResult(exitCode, state) {
+  const stdout = safeOutputText(state.stdout, state.redaction, state.outputLimit, "head");
+  const stderr = safeOutputText(state.stderr, state.redaction, state.outputLimit, "head");
+  return {
+    exitCode,
+    stdout,
+    stderr,
+    outputTruncated: state.stdout.truncated || state.stderr.truncated,
+    stdoutTruncated: state.stdout.truncated,
+    stderrTruncated: state.stderr.truncated
+  };
+}
+function createSshExecutionState(context, outputLimit) {
+  const redaction = createRedactionPolicy(context.sensitiveValues ?? []);
+  return {
+    stdout: createBoundedOutput(),
+    stderr: createBoundedOutput(),
+    outputLimit,
+    retainedLimit: outputLimit + redaction.overlapBytes,
+    redaction,
+    settled: false,
+    aborted: false,
+    timedOut: false
+  };
+}
+function terminateSshExecution(child, state) {
+  signalChild(child, "SIGTERM");
+  state.forceKillTimer ??= setTimeout(() => {
+    signalChild(child, "SIGKILL");
+  }, 1e3);
+}
+function sshAbortError(context) {
+  if (context.deadlineAt !== void 0 && Date.now() >= context.deadlineAt) {
+    return new CfDebuggerError(
+      "STARTUP_TIMEOUT",
+      `Debugger startup exceeded its configured deadline during ${context.phase ?? "remote signalling"}.`
+    );
+  }
+  return new CfDebuggerError("ABORTED", "Operation aborted by caller");
+}
+function isDeadlineExpired(context) {
+  return context.deadlineAt !== void 0 && Date.now() >= context.deadlineAt;
+}
+function createSshSettler(state, options, context, onAbort, resolve, reject) {
+  return (result) => {
+    if (state.settled) {
+      return;
+    }
+    state.settled = true;
+    clearTimeout(state.timeoutTimer);
+    clearTimeout(state.forceKillTimer);
+    context.signal?.removeEventListener("abort", onAbort);
+    if (state.aborted) {
+      reject(sshAbortError(context));
+      return;
+    }
+    resolve(state.timedOut ? { ...result, timedOutAfterMs: options.timeoutMs } : result);
+  };
+}
+function attachSshExecution(child, context, options, resolve, reject) {
+  const state = createSshExecutionState(context, options.maxOutputBytes);
+  const onAbort = () => {
+    state.aborted = true;
+    terminateSshExecution(child, state);
+  };
+  const settle = createSshSettler(state, options, context, onAbort, resolve, reject);
+  state.timeoutTimer = setTimeout(() => {
+    state.timedOut = true;
+    terminateSshExecution(child, state);
+  }, options.timeoutMs);
+  if (context.signal?.aborted) {
+    onAbort();
+  } else {
+    context.signal?.addEventListener("abort", onAbort, { once: true });
+  }
+  child.stdout.on("data", (data) => {
+    appendHead(state.stdout, data, state.outputLimit, state.retainedLimit);
+  });
+  child.stderr.on("data", (data) => {
+    appendHead(state.stderr, data, state.outputLimit, state.retainedLimit);
+  });
+  child.on("close", (code, signal) => {
+    const base = createResult(code, state);
+    settle(state.timedOut || signal === null ? base : { ...base, signal });
+  });
+  child.on("error", (error) => {
+    appendHead(state.stderr, error.message, state.outputLimit, state.retainedLimit);
+    settle(createResult(null, state));
+  });
+}
+function runSshOneShot(args, context, options) {
+  if (context.signal?.aborted || isDeadlineExpired(context)) {
+    return Promise.reject(sshAbortError(context));
+  }
+  return new Promise((resolve, reject) => {
+    const child = spawn(resolveBin(context), [...args], {
+      env: buildEnv(context.cfHome),
+      detached: nodeProcess2.platform !== "win32",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    attachSshExecution(child, context, options, resolve, reject);
+  });
+}
+function signalChild(child, signal) {
+  if (nodeProcess2.platform !== "win32" && child.pid !== void 0) {
+    try {
+      nodeProcess2.kill(-child.pid, signal);
+      return;
+    } catch {
+    }
+  }
+  try {
+    child.kill(signal);
+  } catch {
+  }
+}
+function isSshDisabledError(stderr) {
+  return stderr.toLowerCase().includes("ssh support is disabled");
+}
+function isSshPermissionError(stderr) {
+  return stderr.toLowerCase().includes("not authorized");
+}
+function liveOutputText(capture, line) {
+  if (!capture.redaction.safeToSurface && line.length > 0) {
+    return SENSITIVE_OUTPUT_OMITTED;
+  }
+  if (Buffer.byteLength(line) > LIVE_LINE_LIMIT_BYTES) {
+    return "[output line omitted: exceeded live diagnostic limit]";
+  }
+  return redactSensitiveText(line, capture.redaction.sensitiveValues);
+}
+function skipSuppressedLine(capture, stream, text) {
+  const suppressedKey = stream === "stdout" ? "stdoutSuppressed" : "stderrSuppressed";
+  if (!capture[suppressedKey]) {
+    return text;
+  }
+  const newline = text.indexOf("\n");
+  if (newline < 0) {
+    return "";
+  }
+  capture[suppressedKey] = false;
+  return text.slice(newline + 1);
+}
+function emitCompleteLines(capture, stream, data, emit) {
+  if (emit === void 0) {
+    return;
+  }
+  const key = stream === "stdout" ? "stdoutCarry" : "stderrCarry";
+  const suppressedKey = stream === "stdout" ? "stdoutSuppressed" : "stderrSuppressed";
+  const decoder = stream === "stdout" ? capture.stdoutDecoder : capture.stderrDecoder;
+  const incoming = decoder.write(Buffer.isBuffer(data) ? data : Buffer.from(data));
+  const combined = `${capture[key]}${skipSuppressedLine(capture, stream, incoming)}`;
+  const lines = combined.split("\n");
+  capture[key] = lines.pop() ?? "";
+  for (const line of lines) {
+    emit(stream, liveOutputText(capture, line.endsWith("\r") ? line.slice(0, -1) : line));
+  }
+  if (Buffer.byteLength(capture[key]) > LIVE_LINE_LIMIT_BYTES) {
+    capture[key] = "";
+    capture[suppressedKey] = true;
+    emit(stream, "[output line omitted: exceeded live diagnostic limit]");
+  }
+}
+function flushLiveCarry(capture, stream, emit) {
+  if (emit === void 0) {
+    return;
+  }
+  const key = stream === "stdout" ? "stdoutCarry" : "stderrCarry";
+  const suppressedKey = stream === "stdout" ? "stdoutSuppressed" : "stderrSuppressed";
+  if (capture[suppressedKey]) {
+    capture[suppressedKey] = false;
+    capture[key] = "";
+    return;
+  }
+  if (capture[key].length === 0) {
+    return;
+  }
+  emit(stream, liveOutputText(capture, capture[key]));
+  capture[key] = "";
+}
+function attachTunnelCapture(child, context) {
+  const redaction = createRedactionPolicy(context.sensitiveValues ?? []);
+  const capture = {
+    stdout: createBoundedOutput(),
+    stderr: createBoundedOutput(),
+    outputLimit: DEFAULT_MAX_OUTPUT_BYTES,
+    retainedLimit: DEFAULT_MAX_OUTPUT_BYTES + redaction.overlapBytes,
+    redaction,
+    stderrDecoder: new StringDecoder("utf8"),
+    stdoutDecoder: new StringDecoder("utf8"),
+    stdoutCarry: "",
+    stdoutSuppressed: false,
+    stderrCarry: "",
+    stderrSuppressed: false
+  };
+  tunnelCaptures.set(child, capture);
+  child.stdout.on("data", (data) => {
+    appendTail(capture.stdout, data, capture.outputLimit, capture.retainedLimit);
+    emitCompleteLines(capture, "stdout", data, context.onTunnelOutput);
+  });
+  child.stderr.on("data", (data) => {
+    appendTail(capture.stderr, data, capture.outputLimit, capture.retainedLimit);
+    emitCompleteLines(capture, "stderr", data, context.onTunnelOutput);
+  });
+  child.on("error", (error) => {
+    const diagnostic = `${error.message}
+`;
+    appendTail(capture.stderr, diagnostic, capture.outputLimit, capture.retainedLimit);
+    emitCompleteLines(capture, "stderr", diagnostic, context.onTunnelOutput);
+  });
+  child.once("close", () => {
+    emitCompleteLines(
+      capture,
+      "stdout",
+      capture.stdoutDecoder.end(),
+      context.onTunnelOutput
+    );
+    emitCompleteLines(
+      capture,
+      "stderr",
+      capture.stderrDecoder.end(),
+      context.onTunnelOutput
+    );
+    flushLiveCarry(capture, "stdout", context.onTunnelOutput);
+    flushLiveCarry(capture, "stderr", context.onTunnelOutput);
+  });
+}
+function getTunnelDiagnostics(child) {
+  const capture = tunnelCaptures.get(child);
+  if (capture === void 0) {
+    return {
+      stdout: "",
+      stderr: "",
+      stdoutTruncated: false,
+      stderrTruncated: false
+    };
+  }
+  return {
+    stdout: safeOutputText(
+      capture.stdout,
+      capture.redaction,
+      capture.outputLimit,
+      "tail"
+    ),
+    stderr: safeOutputText(
+      capture.stderr,
+      capture.redaction,
+      capture.outputLimit,
+      "tail"
+    ),
+    stdoutTruncated: capture.stdout.truncated,
+    stderrTruncated: capture.stderr.truncated
+  };
+}
+function formatTunnelDiagnostics(diagnostics) {
+  const sections = [];
+  const stdout = diagnostics.stdout.trim();
+  const stderr = diagnostics.stderr.trim();
+  if (stdout.length > 0) {
+    sections.push(`[tunnel stdout]
+${stdout}`);
+  }
+  if (diagnostics.stdoutTruncated) {
+    sections.push("[tunnel stdout tail was truncated]");
+  }
+  if (stderr.length > 0) {
+    sections.push(`[tunnel stderr]
+${stderr}`);
+  }
+  if (diagnostics.stderrTruncated) {
+    sections.push("[tunnel stderr tail was truncated]");
+  }
+  return sections.length === 0 ? void 0 : sections.join("\n");
+}
+function spawnSshTunnel(appName, localPort, remotePort, context, target = {}) {
+  if (context.signal?.aborted || isDeadlineExpired(context)) {
+    throw sshAbortError(context);
+  }
+  const tunnelArg = `${localPort.toString()}:localhost:${remotePort.toString()}`;
+  const args = buildCfSshArgs(appName, target, ["-N", "-L", tunnelArg]);
+  const child = spawn(resolveBin(context), [...args], {
+    env: buildEnv(context.cfHome),
+    detached: nodeProcess2.platform !== "win32",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  attachTunnelCapture(child, context);
+  return child;
+}
+
+// src/session-state/store.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { chmod as chmod3, mkdir as mkdir3, readFile as readFile4, rename, unlink as unlink3, writeFile as writeFile2 } from "fs/promises";
+import { hostname as getHostname2 } from "os";
+import { dirname as dirname2, isAbsolute as isAbsolute3 } from "path";
+import nodeProcess5 from "process";
+
+// src/debug-session/constants.ts
+var DEFAULT_TUNNEL_READY_TIMEOUT_MS = 18e4;
+var DEFAULT_STARTUP_TIMEOUT_MS = 3e5;
+var MAX_STARTUP_TIMEOUT_MS = 18e5;
+var STARTUP_STALE_SLACK_MS = 6e4;
+var CHILD_SIGTERM_GRACE_MS = 2e3;
+var CHILD_SIGKILL_GRACE_MS = 1e3;
+var PID_TERMINATION_POLL_MS = 100;
+
+// src/debug-session/process-identity.ts
+import { execFile as execFile2 } from "child_process";
+import { readFile } from "fs/promises";
+import nodeProcess3 from "process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile2);
+function errorCode(error) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
+  }
+  const code = Reflect.get(error, "code");
+  return typeof code === "string" ? code : void 0;
+}
+function parseLinuxProcessStartTime(statLine) {
+  const commandEnd = statLine.lastIndexOf(")");
+  if (commandEnd < 0) {
+    return void 0;
+  }
+  const fieldsAfterCommand = statLine.slice(commandEnd + 1).trim().split(/\s+/);
+  const startTime = fieldsAfterCommand[19];
+  return startTime !== void 0 && /^\d+$/.test(startTime) ? startTime : void 0;
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw new CfDebuggerError("ABORTED", "Process identity inspection was aborted.");
+  }
+}
+async function linuxProcessIdentity(pid, signal) {
+  try {
+    const statLine = await readFile(`/proc/${pid.toString()}/stat`, {
+      encoding: "utf8",
+      ...signal === void 0 ? {} : { signal }
+    });
+    const startTime = parseLinuxProcessStartTime(statLine);
+    return startTime === void 0 ? void 0 : `linux:${startTime}`;
+  } catch (error) {
+    throwIfAborted(signal);
+    if (errorCode(error) === "ENOENT") {
+      return void 0;
+    }
+    return void 0;
+  }
+}
+async function darwinProcessIdentity(pid, signal) {
+  try {
+    const { stdout } = await execFileAsync("ps", ["-p", pid.toString(), "-o", "lstart="], {
+      ...signal === void 0 ? {} : { signal },
+      timeout: 2e3
+    });
+    const startedAt = stdout.trim();
+    return startedAt.length === 0 ? void 0 : `darwin:${startedAt}`;
+  } catch {
+    throwIfAborted(signal);
+    return void 0;
+  }
+}
+async function readProcessIdentity(pid, signal) {
+  throwIfAborted(signal);
+  if (!Number.isSafeInteger(pid) || pid <= 0) {
+    return void 0;
+  }
+  if (nodeProcess3.platform === "linux") {
+    return await linuxProcessIdentity(pid, signal);
+  }
+  if (nodeProcess3.platform === "darwin") {
+    return await darwinProcessIdentity(pid, signal);
+  }
+  return void 0;
+}
+async function inspectProcessIdentity(pid, expected, signal) {
+  throwIfAborted(signal);
+  if (expected === void 0) {
+    return "match";
+  }
+  const current = await readProcessIdentity(pid, signal);
+  if (current === void 0) {
+    return "unavailable";
+  }
+  return current === expected ? "match" : "mismatch";
+}
+
+// src/lock.ts
+import { randomUUID } from "crypto";
+import { chmod, mkdir, open, readFile as readFile2, stat, unlink } from "fs/promises";
+import { hostname } from "os";
+import { dirname } from "path";
+import process2 from "process";
+var DEFAULT_POLL_MS = 50;
+var DEFAULT_STALE_MS = 6e4;
+var DEFAULT_TIMEOUT_MS = 1e4;
+var FOREIGN_HOST_STALE_MULTIPLIER = 10;
+var LEGACY_SAME_HOST_STALE_MULTIPLIER = 24 * 60;
+function sleep(ms, signal) {
+  if (signal?.aborted) {
+    return Promise.reject(new CfDebuggerError("ABORTED", "State lock acquisition was aborted."));
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new CfDebuggerError("ABORTED", "State lock acquisition was aborted."));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function errorCode2(error) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
+  }
+  const code = Reflect.get(error, "code");
+  return typeof code === "string" ? code : void 0;
+}
+function field(value, key) {
+  return Reflect.get(value, key);
+}
+function parseLockOwner(raw) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  if (typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  const lockHostname = field(value, "hostname");
+  const pid = field(value, "pid");
+  const token = field(value, "token");
+  const version = field(value, "version");
+  const processIdentity = field(value, "processIdentity");
+  if (typeof lockHostname !== "string" || typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) {
+    return void 0;
+  }
+  if (typeof token !== "string" || version !== "1") {
+    return void 0;
+  }
+  if (processIdentity !== void 0 && (typeof processIdentity !== "string" || processIdentity.length === 0)) {
+    return void 0;
+  }
+  return {
+    hostname: lockHostname,
+    pid,
+    ...processIdentity === void 0 ? {} : { processIdentity },
+    token,
+    version
+  };
+}
+function isProcessAlive(pid) {
+  try {
+    process2.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return errorCode2(error) !== "ESRCH";
+  }
+}
+async function readLockOwner(lockPath) {
+  try {
+    await chmod(lockPath, 384);
+    return parseLockOwner(await readFile2(lockPath, "utf8"));
+  } catch (error) {
+    if (errorCode2(error) === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+}
+async function isStaleLock(lockPath, staleMs) {
+  let modifiedAt2;
+  try {
+    modifiedAt2 = (await stat(lockPath)).mtimeMs;
+  } catch (error) {
+    if (errorCode2(error) === "ENOENT") {
+      return true;
+    }
+    throw error;
+  }
+  const owner = await readLockOwner(lockPath);
+  const ageMs = Date.now() - modifiedAt2;
+  if (owner?.hostname === hostname()) {
+    if (!isProcessAlive(owner.pid)) {
+      return true;
+    }
+    if (owner.processIdentity !== void 0) {
+      const identity = await inspectProcessIdentity(owner.pid, owner.processIdentity);
+      if (identity === "mismatch") {
+        return true;
+      }
+      if (identity === "match") {
+        return false;
+      }
+    }
+    return ageMs > staleMs * LEGACY_SAME_HOST_STALE_MULTIPLIER;
+  }
+  if (owner === void 0) {
+    return ageMs > staleMs;
+  }
+  return ageMs > staleMs * FOREIGN_HOST_STALE_MULTIPLIER;
+}
+async function reclaimAbandonedRecoveryLock(recoveryPath, staleMs) {
+  if (!await isStaleLock(recoveryPath, staleMs)) {
+    return;
+  }
+  const owner = await readLockOwner(recoveryPath);
+  if (owner !== void 0) {
+    await removeOwnedLock(recoveryPath, owner.token);
+    return;
+  }
+  await unlink(recoveryPath).catch((error) => {
+    if (errorCode2(error) !== "ENOENT") {
+      throw error;
+    }
+  });
+}
+async function reclaimStaleLock(lockPath, staleMs) {
+  const recoveryPath = `${lockPath}.recovery`;
+  let recoveryLock;
+  try {
+    recoveryLock = await createFileLock(recoveryPath);
+  } catch (error) {
+    if (errorCode2(error) === "EEXIST") {
+      await reclaimAbandonedRecoveryLock(recoveryPath, staleMs);
+      return false;
+    }
+    throw error;
+  }
+  try {
+    if (!await isStaleLock(lockPath, staleMs)) {
+      return false;
+    }
+    try {
+      await unlink(lockPath);
+    } catch (error) {
+      if (errorCode2(error) !== "ENOENT") {
+        throw error;
+      }
+    }
+    return true;
+  } finally {
+    await releaseFileLock(recoveryPath, recoveryLock);
+  }
+}
+async function removeOwnedLock(lockPath, token) {
+  const owner = await readLockOwner(lockPath);
+  if (owner?.token !== token) {
+    return;
+  }
+  await unlink(lockPath).catch((error) => {
+    if (errorCode2(error) !== "ENOENT") {
+      throw error;
+    }
+  });
+}
+async function createFileLock(lockPath) {
+  const processIdentity = await readProcessIdentity(process2.pid);
+  const handle = await open(lockPath, "wx", 384);
+  const token = randomUUID();
+  try {
+    await handle.writeFile(`${JSON.stringify({
+      hostname: hostname(),
+      pid: process2.pid,
+      ...processIdentity === void 0 ? {} : { processIdentity },
+      token,
+      version: "1"
+    })}
+`, "utf8");
+    return { handle, token };
+  } catch (error) {
+    await handle.close();
+    await unlink(lockPath).catch(() => false);
+    throw error;
+  }
+}
+async function acquireFileLock(lockPath, timeoutMs, pollMs, staleMs, signal) {
+  const deadline = Date.now() + timeoutMs;
+  const parentDir = dirname(lockPath);
+  await mkdir(parentDir, { recursive: true, mode: 448 });
+  await chmod(parentDir, 448);
+  for (; ; ) {
+    if (signal?.aborted) {
+      throw new CfDebuggerError("ABORTED", "State lock acquisition was aborted.");
+    }
+    try {
+      return await createFileLock(lockPath);
+    } catch (error) {
+      if (errorCode2(error) !== "EEXIST") {
+        throw error;
+      }
+    }
+    if (await reclaimStaleLock(lockPath, staleMs)) {
+      continue;
+    }
+    if (Date.now() > deadline) {
+      throw new CfDebuggerError(
+        "STATE_LOCK_TIMEOUT",
+        `Timed out acquiring debugger state lock at ${lockPath}. Keep ~/.saptools on a local filesystem and retry.`
+      );
+    }
+    await sleep(pollMs, signal);
+  }
+}
+async function releaseFileLock(lockPath, lock) {
+  await lock.handle.close();
+  await removeOwnedLock(lockPath, lock.token);
+}
+async function withFileLock(lockPath, work, options) {
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const pollMs = options?.pollMs ?? DEFAULT_POLL_MS;
+  const staleMs = options?.staleMs ?? DEFAULT_STALE_MS;
+  const lock = await acquireFileLock(
+    lockPath,
+    timeoutMs,
+    pollMs,
+    staleMs,
+    options?.signal
+  );
+  try {
+    return await work();
+  } finally {
+    await releaseFileLock(lockPath, lock);
+  }
+}
+
+// src/paths.ts
+import { homedir } from "os";
+import { isAbsolute, join } from "path";
+var SAPTOOLS_DIR_NAME = ".saptools";
+var CF_DEBUGGER_STATE_FILENAME = "cf-debugger-state-v2.json";
+var CF_DEBUGGER_LOCK_FILENAME = "cf-debugger-state-v2.lock";
+var CF_DEBUGGER_HOMES_DIRNAME = "cf-debugger-homes-v2";
+var CF_DEBUGGER_STOP_INTENT_PREFIX = "cf-debugger-stop-v2-";
+var SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function saptoolsDir() {
+  return join(homedir(), SAPTOOLS_DIR_NAME);
+}
+function stateFilePath() {
+  return join(saptoolsDir(), CF_DEBUGGER_STATE_FILENAME);
+}
+function stateLockPath() {
+  return join(saptoolsDir(), CF_DEBUGGER_LOCK_FILENAME);
+}
+function sessionStopIntentPath(sessionId) {
+  if (!isSafeSessionId(sessionId)) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "Invalid debugger session ID.");
+  }
+  return join(saptoolsDir(), `${CF_DEBUGGER_STOP_INTENT_PREFIX}${sessionId}.stop`);
+}
+function isSafeSessionId(sessionId) {
+  return SESSION_ID_PATTERN.test(sessionId);
+}
+function sessionCfHomeDir(sessionId) {
+  if (!isSafeSessionId(sessionId)) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "Invalid debugger session ID.");
+  }
+  return join(saptoolsDir(), CF_DEBUGGER_HOMES_DIRNAME, sessionId);
+}
+function isOwnedSessionCfHomeDir(sessionId, candidate) {
+  if (!isSafeSessionId(sessionId) || !isAbsolute(candidate)) {
+    return false;
+  }
+  return candidate === sessionCfHomeDir(sessionId);
+}
+
+// src/session-state/decoder.ts
+import { isAbsolute as isAbsolute2 } from "path";
+var INVALID_SESSION = new Error("Invalid persisted debugger session");
+var VALID_STATUSES = /* @__PURE__ */ new Set([
+  "starting",
+  "logging-in",
+  "targeting",
+  "ssh-enabling",
+  "ssh-restarting",
+  "signaling",
+  "tunneling",
+  "ready",
+  "stopping",
+  "stopped",
+  "error"
+]);
+function field2(value, key) {
+  return Reflect.get(value, key);
+}
+function requireString(value, key) {
+  const candidate = field2(value, key);
+  if (typeof candidate !== "string" || candidate.length === 0) {
+    throw INVALID_SESSION;
+  }
+  return candidate;
+}
+function optionalString2(value, key) {
+  const candidate = field2(value, key);
+  if (candidate === void 0) {
+    return void 0;
+  }
+  if (typeof candidate !== "string") {
+    throw INVALID_SESSION;
+  }
+  return candidate;
+}
+function optionalNonEmptyString(value, key) {
+  const candidate = optionalString2(value, key);
+  if (candidate?.length === 0) {
+    throw INVALID_SESSION;
+  }
+  return candidate;
+}
+function requireInteger(value, key, minimum, maximum) {
+  const candidate = field2(value, key);
+  if (typeof candidate !== "number" || !Number.isSafeInteger(candidate) || candidate < minimum || candidate > maximum) {
+    throw INVALID_SESSION;
+  }
+  return candidate;
+}
+function optionalInteger(value, key, minimum, maximum = Number.MAX_SAFE_INTEGER) {
+  const candidate = field2(value, key);
+  if (candidate === void 0) {
+    return void 0;
+  }
+  if (typeof candidate !== "number" || !Number.isSafeInteger(candidate) || candidate < minimum || candidate > maximum) {
+    throw INVALID_SESSION;
+  }
+  return candidate;
+}
+function requireSessionId(value) {
+  const sessionId = requireString(value, "sessionId");
+  if (!isSafeSessionId(sessionId)) {
+    throw INVALID_SESSION;
+  }
+  return sessionId;
+}
+function requireAbsolutePath(value, key) {
+  const path = requireString(value, key);
+  if (!isAbsolute2(path)) {
+    throw INVALID_SESSION;
+  }
+  return path;
+}
+function requireTimestamp(value) {
+  const timestamp = requireString(value, "startedAt");
+  if (Number.isNaN(Date.parse(timestamp))) {
+    throw INVALID_SESSION;
+  }
+  return timestamp;
+}
+function optionalTimestamp(value, key) {
+  const timestamp = optionalString2(value, key);
+  if (timestamp !== void 0 && Number.isNaN(Date.parse(timestamp))) {
+    throw INVALID_SESSION;
+  }
+  return timestamp;
+}
+function isSessionStatus(value) {
+  return VALID_STATUSES.has(value);
+}
+function requireStatus(value) {
+  const status = requireString(value, "status");
+  if (!isSessionStatus(status)) {
+    throw INVALID_SESSION;
+  }
+  return status;
+}
+function optionalFields(value) {
+  const controllerProcessIdentity = optionalNonEmptyString(value, "controllerProcessIdentity");
+  const tunnelProcessIdentity = optionalNonEmptyString(value, "tunnelProcessIdentity");
+  const startupTimeoutMs = optionalInteger(value, "startupTimeoutMs", 1, MAX_STARTUP_TIMEOUT_MS);
+  return {
+    ...controllerProcessIdentity === void 0 ? {} : { controllerProcessIdentity },
+    ...tunnelProcessIdentity === void 0 ? {} : { tunnelProcessIdentity },
+    ...startupTimeoutMs === void 0 ? {} : { startupTimeoutMs }
+  };
+}
+function decodeTarget(value) {
+  const nodePid = optionalInteger(value, "nodePid", 1);
+  return resolveNodeTarget({
+    process: requireString(value, "process"),
+    instance: requireInteger(value, "instance", 0, Number.MAX_SAFE_INTEGER),
+    ...nodePid === void 0 ? {} : { nodePid }
+  });
+}
+function decodeSession(value) {
+  if (typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  try {
+    const target = decodeTarget(value);
+    const pid = requireInteger(value, "pid", 1, Number.MAX_SAFE_INTEGER);
+    const tunnelPid = optionalInteger(value, "tunnelPid", 1);
+    const controllerPid = optionalInteger(value, "controllerPid", 1) ?? pid;
+    const remoteNodePid = optionalInteger(value, "remoteNodePid", 1);
+    const stopRequestedAt = optionalTimestamp(value, "stopRequestedAt");
+    const message = optionalString2(value, "message");
+    const status = requireStatus(value);
+    if (pid !== (tunnelPid ?? controllerPid) || status === "ready" && tunnelPid === void 0) {
+      throw INVALID_SESSION;
+    }
+    return {
+      sessionId: requireSessionId(value),
+      pid,
+      controllerPid,
+      ...optionalFields(value),
+      ...tunnelPid === void 0 ? {} : { tunnelPid },
+      hostname: requireString(value, "hostname"),
+      region: requireString(value, "region"),
+      org: requireString(value, "org"),
+      space: requireString(value, "space"),
+      app: requireString(value, "app"),
+      process: target.process,
+      instance: target.instance,
+      ...target.nodePid === void 0 ? {} : { nodePid: target.nodePid },
+      apiEndpoint: requireString(value, "apiEndpoint"),
+      localPort: requireInteger(value, "localPort", 1, 65535),
+      remotePort: requireInteger(value, "remotePort", 1, 65535),
+      cfHomeDir: requireAbsolutePath(value, "cfHomeDir"),
+      startedAt: requireTimestamp(value),
+      status,
+      ...remoteNodePid === void 0 ? {} : { remoteNodePid },
+      ...stopRequestedAt === void 0 ? {} : { stopRequestedAt },
+      ...message === void 0 ? {} : { message }
+    };
+  } catch {
+    return void 0;
+  }
+}
+function duplicateSessionIds(sessions) {
+  const seen = /* @__PURE__ */ new Set();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const session of sessions) {
+    if (seen.has(session.sessionId)) {
+      duplicates.add(session.sessionId);
+    }
+    seen.add(session.sessionId);
+  }
+  return duplicates;
+}
+function decodeStateFileDetailed(value) {
+  if (typeof value !== "object" || value === null) {
+    return { kind: "invalid-file", reason: "root is not an object" };
+  }
+  if (field2(value, "version") !== "2") {
+    return { kind: "invalid-file", reason: "unsupported or missing version" };
+  }
+  const rawSessions = field2(value, "sessions");
+  if (!Array.isArray(rawSessions)) {
+    return { kind: "invalid-file", reason: "sessions is not an array" };
+  }
+  const decoded = rawSessions.map((raw) => decodeSession(raw));
+  const valid = decoded.filter((session) => session !== void 0);
+  const duplicates = duplicateSessionIds(valid);
+  const sessions = valid.filter((session) => !duplicates.has(session.sessionId));
+  const dropped = decoded.flatMap((session, index) => {
+    if (session === void 0) {
+      return [`session[${index.toString()}]: invalid entry`];
+    }
+    return duplicates.has(session.sessionId) ? [`session[${index.toString()}]: duplicate sessionId ${session.sessionId}`] : [];
+  });
+  return {
+    kind: "decoded",
+    state: { version: "2", sessions },
+    dropped
+  };
+}
+
+// src/session-state/health.ts
+import { hostname as getHostname } from "os";
+import nodeProcess4 from "process";
+
+// src/network/ports.ts
+import { execFile as execFile3 } from "child_process";
+import { readdir, readFile as readFile3, readlink } from "fs/promises";
+import { get as httpGet } from "http";
+import { createConnection, createServer } from "net";
+import { promisify as promisify2 } from "util";
+var execFileAsync2 = promisify2(execFile3);
+var PROBE_INTERVAL_MS = 250;
+var INSPECTOR_ATTEMPT_TIMEOUT_MS = 2500;
+var MAX_INSPECTOR_RESPONSE_BYTES = 64 * 1024;
+var OWNER_COMMAND_TIMEOUT_MS = 5e3;
+function sortedUniquePids(pids) {
+  return [...new Set(pids)].sort((left, right) => left - right);
+}
+function parseAddressPort(address) {
+  const separator = address.lastIndexOf(":");
+  const portText = separator >= 0 ? address.slice(separator + 1) : "";
+  if (!/^\d+$/.test(portText)) {
+    return void 0;
+  }
+  return Number.parseInt(portText, 10);
+}
+function parseWindowsNetstatListeningPids(output, port) {
+  const pids = /* @__PURE__ */ new Set();
+  for (const line of output.split(/\r?\n/)) {
+    const fields = line.trim().split(/\s+/);
+    const protocol = fields[0]?.toUpperCase();
+    const localAddress = fields[1];
+    const state = fields[3]?.toUpperCase();
+    const pidText = fields[4];
+    if (protocol !== "TCP" || localAddress === void 0 || state !== "LISTENING" || pidText === void 0 || parseAddressPort(localAddress) !== port) {
+      continue;
+    }
+    const pid = Number.parseInt(pidText, 10);
+    if (Number.isSafeInteger(pid) && pid > 0) {
+      pids.add(pid);
+    }
+  }
+  return sortedUniquePids(pids);
+}
+function errorCode3(error) {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return void 0;
+  }
+  const code = error.code;
+  return typeof code === "string" || typeof code === "number" ? code : void 0;
+}
+function errorStderr(error) {
+  if (typeof error !== "object" || error === null || !("stderr" in error)) {
+    return "";
+  }
+  return typeof error.stderr === "string" ? error.stderr.trim() : "";
+}
+async function findListeningPidsWithNetstat(port, signal) {
+  try {
+    const { stdout } = await execFileAsync2("netstat", ["-ano"], {
+      ...signal === void 0 ? {} : { signal },
+      timeout: OWNER_COMMAND_TIMEOUT_MS
+    });
+    return {
+      available: true,
+      pids: parseWindowsNetstatListeningPids(stdout, port)
+    };
+  } catch (error) {
+    throwIfAborted2(signal);
+    return {
+      available: false,
+      pids: [],
+      reason: `Unable to inspect listening ports with netstat (${String(errorCode3(error) ?? "unknown error")}).`
+    };
+  }
+}
+async function findListeningPidsWithLsof(port, signal) {
+  try {
+    const { stdout } = await execFileAsync2("lsof", [
+      "-nP",
+      "-t",
+      "-i",
+      `tcp:${port.toString()}`,
+      "-sTCP:LISTEN"
+    ], {
+      ...signal === void 0 ? {} : { signal },
+      timeout: OWNER_COMMAND_TIMEOUT_MS
+    });
+    const pids = stdout.trim().split("\n").filter((line) => line.length > 0).map((line) => Number.parseInt(line, 10)).filter((pid) => Number.isSafeInteger(pid) && pid > 0);
+    return { available: true, pids: sortedUniquePids(pids) };
+  } catch (error) {
+    throwIfAborted2(signal);
+    if (errorCode3(error) === 1 && errorStderr(error).length === 0) {
+      return { available: true, pids: [] };
+    }
+    const missing = errorCode3(error) === "ENOENT";
+    return {
+      available: false,
+      pids: [],
+      reason: missing ? "The lsof command is required to verify tunnel ownership on this platform." : `lsof could not inspect the listening port (${String(errorCode3(error) ?? "unknown error")}).`
+    };
+  }
+}
+async function collectListeningSocketInodes(path, port, inodes) {
+  try {
+    const content = await readFile3(path, "utf8");
+    for (const line of content.split("\n").slice(1)) {
+      const fields = line.trim().split(/\s+/);
+      const localAddress = fields[1];
+      const state = fields[3];
+      const inode = fields[9];
+      if (localAddress === void 0 || state === void 0 || inode === void 0) {
+        continue;
+      }
+      const localPort = Number.parseInt(localAddress.split(":")[1] ?? "", 16);
+      if (localPort === port && state === "0A") {
+        inodes.add(inode);
+      }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function findListeningSocketInodesWithProc(port) {
+  const inodes = /* @__PURE__ */ new Set();
+  const tcpAvailable = await collectListeningSocketInodes("/proc/net/tcp", port, inodes);
+  const tcp6Available = await collectListeningSocketInodes("/proc/net/tcp6", port, inodes);
+  return { available: tcpAvailable || tcp6Available, inodes };
+}
+async function processHasSocketInode(pid, inodes) {
+  try {
+    const descriptors = await readdir(`/proc/${pid}/fd`);
+    for (const descriptor of descriptors) {
+      try {
+        const link = await readlink(`/proc/${pid}/fd/${descriptor}`);
+        const match = /^socket:\[(\d+)\]$/.exec(link);
+        if (match?.[1] !== void 0 && inodes.has(match[1])) {
+          return true;
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return false;
+}
+async function findListeningPidsWithProc(port, signal) {
+  throwIfAborted2(signal);
+  const socketResult = await findListeningSocketInodesWithProc(port);
+  if (!socketResult.available) {
+    return {
+      available: false,
+      listenerFound: false,
+      pids: [],
+      reason: "The /proc socket tables are unavailable."
+    };
+  }
+  if (socketResult.inodes.size === 0) {
+    return { available: true, listenerFound: false, pids: [] };
+  }
+  try {
+    const entries = await readdir("/proc", { withFileTypes: true });
+    const pids = /* @__PURE__ */ new Set();
+    for (const entry of entries) {
+      throwIfAborted2(signal);
+      if (entry.isDirectory() && /^\d+$/.test(entry.name) && await processHasSocketInode(entry.name, socketResult.inodes)) {
+        pids.add(Number.parseInt(entry.name, 10));
+      }
+    }
+    return {
+      available: true,
+      listenerFound: true,
+      pids: sortedUniquePids(pids)
+    };
+  } catch {
+    throwIfAborted2(signal);
+    return {
+      available: false,
+      listenerFound: true,
+      pids: [],
+      reason: "A listener exists, but its owner could not be inspected through /proc."
+    };
+  }
+}
+function inspectionFromPids(pids) {
+  return pids.length > 0 ? { status: "found", pids } : { status: "not-listening", pids };
+}
+async function inspectListeningProcesses(port, signal) {
+  throwIfAborted2(signal);
+  if (process.platform === "win32") {
+    const netstat = await findListeningPidsWithNetstat(port, signal);
+    return netstat.available ? inspectionFromPids(netstat.pids) : { status: "unverified", reason: netstat.reason ?? "netstat is unavailable." };
+  }
+  const lsof = await findListeningPidsWithLsof(port, signal);
+  if (lsof.pids.length > 0) {
+    return { status: "found", pids: lsof.pids };
+  }
+  if (process.platform === "darwin") {
+    return lsof.available ? { status: "not-listening", pids: [] } : { status: "unverified", reason: lsof.reason ?? "lsof is unavailable." };
+  }
+  const proc = await findListeningPidsWithProc(port, signal);
+  if (proc.pids.length > 0) {
+    return { status: "found", pids: proc.pids };
+  }
+  if (proc.listenerFound || !proc.available && !lsof.available) {
+    return {
+      status: "unverified",
+      reason: proc.reason ?? lsof.reason ?? "The listener owner could not be verified."
+    };
+  }
+  return { status: "not-listening", pids: [] };
+}
+function classifyPortOwnership(pids, expectedPid) {
+  return pids.includes(expectedPid) ? { status: "owned", pids } : { status: "not-owned", pids };
+}
+async function inspectPortOwnership(port, expectedPid, signal) {
+  const inspection = await inspectListeningProcesses(port, signal);
+  if (inspection.status === "unverified") {
+    return inspection;
+  }
+  if (inspection.status === "not-listening") {
+    return inspection;
+  }
+  return classifyPortOwnership(inspection.pids, expectedPid);
+}
+async function isPortFree(port, signal) {
+  throwIfAborted2(signal);
+  return await new Promise((resolve, reject) => {
+    const server = createServer();
+    let settled = false;
+    const finish = (available) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      signal?.removeEventListener("abort", onAbort);
+      resolve(available);
+    };
+    const onAbort = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (server.listening) {
+        server.close();
+      }
+      signal?.removeEventListener("abort", onAbort);
+      reject(new CfDebuggerError("ABORTED", "Operation aborted by caller"));
+    };
+    server.once("error", () => {
+      finish(false);
+    });
+    server.once("listening", () => {
+      server.close(() => {
+        finish(true);
+      });
+    });
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    server.listen(port, "127.0.0.1");
+  });
+}
+async function isPortListening(port, timeoutMs = 200) {
+  return await new Promise((resolve) => {
+    const socket = createConnection({ port, host: "127.0.0.1" });
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", () => {
+      socket.destroy();
+      resolve(false);
+    });
+    socket.once("timeout", () => {
+      socket.destroy();
+      resolve(false);
+    });
+  });
+}
+function throwIfAborted2(signal) {
+  if (signal?.aborted) {
+    throw new CfDebuggerError("ABORTED", "Operation aborted by caller");
+  }
+}
+function waitForNextProbe(delayMs, signal) {
+  throwIfAborted2(signal);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new CfDebuggerError("ABORTED", "Operation aborted by caller"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, delayMs);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) {
+      onAbort();
+    }
+  });
+}
+async function probeTunnelReady(port, timeoutMs, signal) {
+  const deadline = Date.now() + timeoutMs;
+  throwIfAborted2(signal);
+  while (Date.now() < deadline) {
+    const remainingMs = deadline - Date.now();
+    if (await isPortListening(port, Math.min(200, remainingMs))) {
+      return true;
+    }
+    const waitMs = Math.min(PROBE_INTERVAL_MS, Math.max(0, deadline - Date.now()));
+    if (waitMs > 0) {
+      await waitForNextProbe(waitMs, signal);
+    }
+  }
+  throwIfAborted2(signal);
+  return false;
+}
+function parseJson(body) {
+  return JSON.parse(body);
+}
+function isUnknownRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isUnknownArray(value) {
+  return Array.isArray(value);
+}
+function hasAttachableInspectorTarget(body) {
+  let parsed;
+  try {
+    parsed = parseJson(body);
+  } catch {
+    return false;
+  }
+  if (!isUnknownArray(parsed) || parsed.length === 0) {
+    return false;
+  }
+  const first = parsed[0];
+  if (!isUnknownRecord(first)) {
+    return false;
+  }
+  const candidate = first["webSocketDebuggerUrl"];
+  if (typeof candidate !== "string") {
+    return false;
+  }
+  try {
+    const url = new URL(candidate);
+    return (url.protocol === "ws:" || url.protocol === "wss:") && url.hostname.length > 0;
+  } catch {
+    return false;
+  }
+}
+function readInspectorResponse(response, finish) {
+  if (response.statusCode !== 200) {
+    response.destroy();
+    finish(false);
+    return;
+  }
+  const chunks = [];
+  let totalBytes = 0;
+  response.on("data", (chunk) => {
+    totalBytes += chunk.length;
+    if (totalBytes > MAX_INSPECTOR_RESPONSE_BYTES) {
+      response.destroy();
+      finish(false);
+      return;
+    }
+    chunks.push(chunk);
+  });
+  response.once("end", () => {
+    finish(hasAttachableInspectorTarget(Buffer.concat(chunks).toString("utf8")));
+  });
+  response.once("error", () => {
+    finish(false);
+  });
+}
+function probeInspectorAttempt(port, timeoutMs, signal) {
+  throwIfAborted2(signal);
+  return new Promise((resolve, reject) => {
+    const state = { settled: false };
+    const finish = (ready) => {
+      if (!state.settled) {
+        state.settled = true;
+        clearTimeout(state.timer);
+        state.removeAbortListener?.();
+        resolve(ready);
+      }
+    };
+    const request = httpGet({ host: "127.0.0.1", port, path: "/json/list" }, (response) => {
+      readInspectorResponse(response, finish);
+    });
+    const onAbort = () => {
+      request.destroy();
+      if (!state.settled) {
+        state.settled = true;
+        clearTimeout(state.timer);
+        state.removeAbortListener?.();
+        reject(new CfDebuggerError("ABORTED", "Operation aborted by caller"));
+      }
+    };
+    state.removeAbortListener = () => {
+      signal?.removeEventListener("abort", onAbort);
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    state.timer = setTimeout(() => {
+      request.destroy();
+      finish(false);
+    }, timeoutMs);
+    request.once("error", () => {
+      if (signal?.aborted) {
+        onAbort();
+        return;
+      }
+      finish(false);
+    });
+  });
+}
+async function probeInspectorReady(port, timeoutMs, signal) {
+  const deadline = Date.now() + timeoutMs;
+  throwIfAborted2(signal);
+  while (Date.now() < deadline) {
+    const remainingMs = deadline - Date.now();
+    const attemptTimeoutMs = Math.max(
+      1,
+      Math.min(INSPECTOR_ATTEMPT_TIMEOUT_MS, remainingMs)
+    );
+    if (await probeInspectorAttempt(port, attemptTimeoutMs, signal)) {
+      return { status: "ready" };
+    }
+    const waitMs = Math.min(PROBE_INTERVAL_MS, Math.max(0, deadline - Date.now()));
+    if (waitMs > 0) {
+      await waitForNextProbe(waitMs, signal);
+    }
+  }
+  throwIfAborted2(signal);
+  return { status: "unreachable" };
+}
+
+// src/session-state/health.ts
+function errorCode4(error) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
+  }
+  const code = Reflect.get(error, "code");
+  return typeof code === "string" ? code : void 0;
+}
+function isPidAlive(pid) {
+  try {
+    nodeProcess4.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return errorCode4(error) !== "ESRCH";
+  }
+}
+function isProcessGroupAlive(pid) {
+  return nodeProcess4.platform !== "win32" && isPidAlive(-pid);
+}
+function isPidOrGroupAlive(pid) {
+  return isPidAlive(pid) || isProcessGroupAlive(pid);
+}
+function startupAgeLimit(session) {
+  return (session.startupTimeoutMs ?? MAX_STARTUP_TIMEOUT_MS) + STARTUP_STALE_SLACK_MS;
+}
+function startupExpired(session) {
+  const startedAt = Date.parse(session.startedAt);
+  return Number.isNaN(startedAt) || Date.now() - startedAt > startupAgeLimit(session);
+}
+async function inspectRecordedProcess(pid, identity, signal) {
+  if (signal?.aborted) {
+    throw new CfDebuggerError("ABORTED", "Session health inspection was aborted.");
+  }
+  if (!isPidAlive(pid)) {
+    return "dead";
+  }
+  return await inspectProcessIdentity(pid, identity, signal);
+}
+async function readySessionHealth(session, signal) {
+  const tunnelPid = session.tunnelPid;
+  if (tunnelPid === void 0) {
+    return { status: "stale", reason: "recorded tunnel PID is missing" };
+  }
+  const processVerdict = await inspectRecordedProcess(
+    tunnelPid,
+    session.tunnelProcessIdentity,
+    signal
+  );
+  if (processVerdict === "dead" && isProcessGroupAlive(tunnelPid)) {
+    return {
+      status: "unverified",
+      reason: "tunnel leader exited while its process group is still alive"
+    };
+  }
+  if (processVerdict === "dead" || processVerdict === "mismatch") {
+    return { status: "stale", reason: "recorded tunnel process is gone or was reused" };
+  }
+  if (processVerdict === "unavailable") {
+    return { status: "unverified", reason: "recorded tunnel identity could not be inspected" };
+  }
+  const ownership = await inspectPortOwnership(session.localPort, tunnelPid, signal);
+  if (ownership.status === "owned") {
+    return { status: "healthy", reason: "recorded tunnel owns the local port" };
+  }
+  if (ownership.status === "unverified") {
+    return { status: "unverified", reason: ownership.reason };
+  }
+  return {
+    status: "unverified",
+    reason: ownership.status === "not-owned" ? `recorded live tunnel no longer owns the local port; observed PID(s) ${ownership.pids.join(", ")}` : "recorded live tunnel no longer has a listening local port"
+  };
+}
+async function startingSessionHealth(session, signal) {
+  if (startupExpired(session)) {
+    if (session.tunnelPid !== void 0) {
+      return await readySessionHealth(session, signal);
+    }
+    return { status: "stale", reason: "startup exceeded its maximum supported age" };
+  }
+  const controllerPid = session.controllerPid ?? session.pid;
+  const processVerdict = await inspectRecordedProcess(
+    controllerPid,
+    session.controllerProcessIdentity,
+    signal
+  );
+  if (processVerdict === "match") {
+    return { status: "healthy", reason: "startup controller identity matches" };
+  }
+  if (processVerdict === "unavailable") {
+    return { status: "unverified", reason: "startup controller identity could not be inspected" };
+  }
+  if (session.tunnelPid === void 0) {
+    return { status: "stale", reason: "startup controller is gone or was reused" };
+  }
+  return await readySessionHealth(session, signal);
+}
+async function inspectSessionHealth(session, host = getHostname(), signal) {
+  if (session.hostname !== host) {
+    return { status: "stale", reason: "session belongs to another host" };
+  }
+  return session.status === "ready" ? await readySessionHealth(session, signal) : await startingSessionHealth(session, signal);
+}
+async function filterStaleSessions(sessions, signal) {
+  const host = getHostname();
+  const verdicts = await Promise.all(
+    sessions.map(async (session) => [
+      session,
+      await inspectSessionHealth(session, host, signal)
+    ])
+  );
+  return verdicts.filter(([, verdict]) => verdict.status !== "stale").map(([session]) => session);
+}
+
+// src/session-state/stop-intent.ts
+import { access, chmod as chmod2, mkdir as mkdir2, unlink as unlink2, writeFile } from "fs/promises";
+function errorCode5(error) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
+  }
+  const code = Reflect.get(error, "code");
+  return typeof code === "string" ? code : void 0;
+}
+async function writeSessionStopIntent(sessionId) {
+  const directory = saptoolsDir();
+  await mkdir2(directory, { recursive: true, mode: 448 });
+  await chmod2(directory, 448);
+  try {
+    await writeFile(sessionStopIntentPath(sessionId), "", {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 384
+    });
+  } catch (error) {
+    if (errorCode5(error) !== "EEXIST") {
+      throw error;
+    }
+  }
+}
+async function hasSessionStopIntent(sessionId) {
+  try {
+    await access(sessionStopIntentPath(sessionId));
+    return true;
+  } catch (error) {
+    if (errorCode5(error) === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+async function clearSessionStopIntent(sessionId) {
+  await unlink2(sessionStopIntentPath(sessionId)).catch((error) => {
+    if (errorCode5(error) !== "ENOENT") {
+      throw error;
+    }
+  });
+}
+
+// src/session-state/store.ts
+var DEFAULT_BASE_PORT = 2e4;
+var DEFAULT_MAX_PORT = 20999;
+function errorCode6(error) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
+  }
+  const code = Reflect.get(error, "code");
+  return typeof code === "string" ? code : void 0;
+}
+async function readFileIfPresent(path) {
+  try {
+    await chmod3(path, 384);
+    return await readFile4(path, "utf8");
+  } catch (error) {
+    if (errorCode6(error) === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+}
+async function writeJsonFileAtomic(path, value) {
+  const tempPath = `${path}.${randomUUID2()}.tmp`;
+  const parentDir = dirname2(path);
+  await mkdir3(parentDir, { recursive: true, mode: 448 });
+  await chmod3(parentDir, 448);
+  let renamed = false;
+  try {
+    await writeFile2(tempPath, `${JSON.stringify(value, null, 2)}
+`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 384
+    });
+    await rename(tempPath, path);
+    renamed = true;
+    await chmod3(path, 384);
+  } finally {
+    if (!renamed) {
+      await unlink3(tempPath).catch(() => false);
+    }
+  }
+}
+function emptyState() {
+  return { version: "2", sessions: [] };
+}
+function corruptBackupPath(path) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(":", "-");
+  return `${path}.corrupt-${timestamp}-${randomUUID2()}`;
+}
+async function preserveCorruptState(path, reason) {
+  const backup = corruptBackupPath(path);
+  await rename(path, backup);
+  await chmod3(backup, 384);
+  nodeProcess5.stderr.write(
+    `[cf-debugger] warning: preserved invalid state at ${backup} (${reason}).
+`
+  );
+  return backup;
+}
+async function resetInvalidState(path, reason) {
+  await preserveCorruptState(path, reason);
+  const state = emptyState();
+  await writeJsonFileAtomic(path, state);
+  return state;
+}
+async function readStateRaw() {
+  const path = stateFilePath();
+  const raw = await readFileIfPresent(path);
+  if (raw === void 0) {
+    return emptyState();
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return await resetInvalidState(path, "invalid JSON");
+  }
+  const decoded = decodeStateFileDetailed(parsed);
+  if (decoded.kind === "invalid-file") {
+    return await resetInvalidState(path, decoded.reason);
+  }
+  if (decoded.dropped.length > 0) {
+    await preserveCorruptState(path, decoded.dropped.join("; "));
+    await writeJsonFileAtomic(path, decoded.state);
+    nodeProcess5.stderr.write(
+      `[cf-debugger] warning: dropped ${decoded.dropped.length.toString()} invalid state entr${decoded.dropped.length === 1 ? "y" : "ies"}; valid sessions were retained.
+`
+    );
+  }
+  return decoded.state;
+}
+async function writeState(state) {
+  await writeJsonFileAtomic(stateFilePath(), state);
+}
+async function readAndPruneLocked(signal) {
+  const raw = await readStateRaw();
+  const host = getHostname2();
+  const remote = raw.sessions.filter((session) => session.hostname !== host);
+  const local = raw.sessions.filter((session) => session.hostname === host);
+  const sessions = await filterStaleSessions(local, signal);
+  const activeIds = new Set(sessions.map((session) => session.sessionId));
+  const removed = local.filter((session) => !activeIds.has(session.sessionId));
+  const persisted = { version: "2", sessions: [...remote, ...sessions] };
+  if (removed.length > 0) {
+    await writeState(persisted);
+  }
+  return { sessions, removed, persisted };
+}
+async function readActiveSessions() {
+  const result = await withFileLock(stateLockPath(), readAndPruneLocked);
+  return result.sessions;
+}
+async function readSessionSnapshot(options) {
+  return await withFileLock(stateLockPath(), async () => {
+    return (await readStateRaw()).sessions;
+  }, options);
+}
+async function readAndPruneActiveSessions(options) {
+  const result = await withFileLock(
+    stateLockPath(),
+    async () => await readAndPruneLocked(options?.signal),
+    options
+  );
+  return { sessions: result.sessions, removed: result.removed };
+}
+function sessionKeyString(key) {
+  const base = `${key.region}:${key.org}:${key.space}:${key.app}`;
+  if (key.process === void 0 && key.instance === void 0) {
+    return base;
+  }
+  const target = resolveNodeTarget(key);
+  return `${base}:${target.process}:${target.instance.toString()}`;
+}
+function matchesSelectedNodePid(session, requestedNodePid) {
+  if (requestedNodePid === void 0) {
+    return true;
+  }
+  const remoteNodePid = Reflect.get(session, "remoteNodePid");
+  return session.nodePid === requestedNodePid || remoteNodePid === requestedNodePid;
+}
+function matchesKey(session, key) {
+  const sessionTarget = resolveNodeTarget(session);
+  const keyTarget = resolveNodeTarget(key);
+  return session.region === key.region && session.org === key.org && session.space === key.space && session.app === key.app && sessionTarget.process === keyTarget.process && sessionTarget.instance === keyTarget.instance && (key.apiEndpoint === void 0 || session.apiEndpoint === key.apiEndpoint) && matchesSelectedNodePid(session, keyTarget.nodePid);
+}
+function matchesRegistrationTarget(session, input, target) {
+  return matchesKey(session, {
+    region: input.region,
+    org: input.org,
+    space: input.space,
+    app: input.app,
+    process: target.process,
+    instance: target.instance,
+    apiEndpoint: input.apiEndpoint
+  });
+}
+async function pickPort(preferred, reserved, probe, basePort, maxPort) {
+  const candidates = preferred === void 0 ? [] : [preferred];
+  for (let port = basePort; port <= maxPort; port += 1) {
+    if (port !== preferred) {
+      candidates.push(port);
+    }
+  }
+  for (const port of candidates) {
+    if (!reserved.has(port) && await probe(port)) {
+      return port;
+    }
+  }
+  throw new CfDebuggerError(
+    "PORT_UNAVAILABLE",
+    `No free local port available in range ${basePort.toString()}\u2013${maxPort.toString()}`
+  );
+}
+async function selectRegistrationCandidate(input, target, excluded) {
+  return await withFileLock(stateLockPath(), async () => {
+    const current = await readAndPruneLocked(input.stateAccess?.signal);
+    const existing = current.sessions.find(
+      (session) => matchesRegistrationTarget(session, input, target)
+    );
+    if (existing !== void 0) {
+      return { existing };
+    }
+    const reserved = /* @__PURE__ */ new Set([
+      ...current.sessions.map((session) => session.localPort),
+      ...excluded
+    ]);
+    return {
+      candidate: await pickPort(
+        input.preferredPort,
+        reserved,
+        () => Promise.resolve(true),
+        input.basePort ?? DEFAULT_BASE_PORT,
+        input.maxPort ?? DEFAULT_MAX_PORT
+      )
+    };
+  }, input.stateAccess);
+}
+function validateSessionInput(input) {
+  const remotePort = input.remotePort ?? DEFAULT_NODE_INSPECTOR_PORT;
+  if (!Number.isSafeInteger(remotePort) || remotePort <= 0 || remotePort > 65535) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "Remote inspector port must be from 1 to 65535.");
+  }
+  if (input.startupTimeoutMs !== void 0 && (!Number.isSafeInteger(input.startupTimeoutMs) || input.startupTimeoutMs <= 0 || input.startupTimeoutMs > MAX_STARTUP_TIMEOUT_MS)) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "Persisted startup timeout is outside the supported range.");
+  }
+}
+function createRegisteredSession(input, target, localPort, controllerProcessIdentity) {
+  const sessionId = (input.sessionIdFactory ?? randomUUID2)();
+  if (!isSafeSessionId(sessionId)) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "Generated debugger session ID is invalid.");
+  }
+  const cfHomeDir = input.cfHomeForSession(sessionId);
+  if (!isAbsolute3(cfHomeDir)) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "Debugger CF home must be an absolute path.");
+  }
+  return {
+    sessionId,
+    pid: nodeProcess5.pid,
+    controllerPid: nodeProcess5.pid,
+    ...controllerProcessIdentity === void 0 ? {} : { controllerProcessIdentity },
+    hostname: getHostname2(),
+    region: input.region,
+    org: input.org,
+    space: input.space,
+    app: input.app,
+    process: target.process,
+    instance: target.instance,
+    ...target.nodePid === void 0 ? {} : { nodePid: target.nodePid },
+    apiEndpoint: input.apiEndpoint,
+    localPort,
+    remotePort: input.remotePort ?? DEFAULT_NODE_INSPECTOR_PORT,
+    cfHomeDir,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    status: "starting",
+    ...input.startupTimeoutMs === void 0 ? {} : { startupTimeoutMs: input.startupTimeoutMs }
+  };
+}
+async function persistRegistration(input, target, candidate, controllerProcessIdentity) {
+  return await withFileLock(stateLockPath(), async () => {
+    const current = await readAndPruneLocked(input.stateAccess?.signal);
+    const existing = current.sessions.find(
+      (session2) => matchesRegistrationTarget(session2, input, target)
+    );
+    if (existing !== void 0) {
+      return { session: existing, existing };
+    }
+    const reserved = current.sessions.some((session2) => session2.localPort === candidate);
+    if (reserved || !await input.portProbe(candidate)) {
+      return void 0;
+    }
+    const session = createRegisteredSession(input, target, candidate, controllerProcessIdentity);
+    await writeState({
+      version: "2",
+      sessions: [...current.persisted.sessions, session]
+    });
+    return { session };
+  }, input.stateAccess);
+}
+async function registerNewSession(input) {
+  validateSessionInput(input);
+  const target = resolveNodeTarget(input);
+  const controllerIdentity = await readProcessIdentity(
+    nodeProcess5.pid,
+    input.stateAccess?.signal
+  );
+  const excluded = /* @__PURE__ */ new Set();
+  const maximumAttempts = (input.maxPort ?? DEFAULT_MAX_PORT) - (input.basePort ?? DEFAULT_BASE_PORT) + 2;
+  for (let attempt = 0; attempt < maximumAttempts; attempt += 1) {
+    const selection = await selectRegistrationCandidate(input, target, excluded);
+    if (selection.existing !== void 0) {
+      return { session: selection.existing, existing: selection.existing };
+    }
+    const candidate = selection.candidate;
+    if (candidate === void 0 || !await input.portProbe(candidate)) {
+      if (candidate !== void 0) {
+        excluded.add(candidate);
+      }
+      continue;
+    }
+    const result = await persistRegistration(input, target, candidate, controllerIdentity);
+    if (result !== void 0) {
+      return result;
+    }
+    excluded.add(candidate);
+  }
+  throw new CfDebuggerError("PORT_UNAVAILABLE", "No free local debugger port remained available.");
+}
+function withoutMessage(session) {
+  const { message, ...clone } = session;
+  void message;
+  return clone;
+}
+function startupMutationBlocked(session) {
+  return session.status === "stopping" || session.stopRequestedAt !== void 0;
+}
+function replaceSession(sessions, replacement) {
+  return sessions.map(
+    (session) => session.sessionId === replacement.sessionId ? replacement : session
+  );
+}
+async function updateSessionStatus(sessionId, status, message, access2) {
+  return await withFileLock(stateLockPath(), async () => {
+    const raw = await readStateRaw();
+    const target = raw.sessions.find((session) => session.sessionId === sessionId);
+    if (target === void 0 || status !== "stopping" && startupMutationBlocked(target)) {
+      return target;
+    }
+    if (status === "ready" && target.tunnelPid === void 0) {
+      throw new CfDebuggerError(
+        "SESSION_STATE_CONFLICT",
+        "A debugger session cannot become ready before its tunnel PID is recorded."
+      );
+    }
+    const base = withoutMessage(target);
+    const next = message === void 0 ? { ...base, status } : { ...base, status, message };
+    if (JSON.stringify(next) !== JSON.stringify(target)) {
+      await writeState({ version: "2", sessions: replaceSession(raw.sessions, next) });
+    }
+    return next;
+  }, access2);
+}
+async function updateSessionPid(sessionId, pid, access2) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "Tunnel PID must be a positive safe integer.");
+  }
+  const tunnelProcessIdentity = await readProcessIdentity(pid, access2?.signal);
+  return await withFileLock(stateLockPath(), async () => {
+    const raw = await readStateRaw();
+    const target = raw.sessions.find((session) => session.sessionId === sessionId);
+    if (target === void 0 || startupMutationBlocked(target)) {
+      return target;
+    }
+    const { tunnelProcessIdentity: previousIdentity, ...base } = target;
+    void previousIdentity;
+    const next = {
+      ...base,
+      pid,
+      tunnelPid: pid,
+      ...tunnelProcessIdentity === void 0 ? {} : { tunnelProcessIdentity }
+    };
+    if (JSON.stringify(next) !== JSON.stringify(target)) {
+      await writeState({ version: "2", sessions: replaceSession(raw.sessions, next) });
+    }
+    return next;
+  }, access2);
+}
+async function updateSessionRemoteNodePid(sessionId, remoteNodePid, access2) {
+  resolveNodeTarget({ nodePid: remoteNodePid });
+  return await withFileLock(stateLockPath(), async () => {
+    const raw = await readStateRaw();
+    const target = raw.sessions.find((session) => session.sessionId === sessionId);
+    if (target === void 0 || startupMutationBlocked(target)) {
+      return target;
+    }
+    const next = { ...target, remoteNodePid };
+    if (target.remoteNodePid !== remoteNodePid) {
+      await writeState({ version: "2", sessions: replaceSession(raw.sessions, next) });
+    }
+    return next;
+  }, access2);
+}
+async function removeSession(sessionId) {
+  return await withFileLock(stateLockPath(), async () => {
+    const raw = await readStateRaw();
+    const target = raw.sessions.find((session) => session.sessionId === sessionId);
+    if (target === void 0) {
+      return void 0;
+    }
+    await writeState({
+      version: "2",
+      sessions: raw.sessions.filter((session) => session.sessionId !== sessionId)
+    });
+    return target;
+  });
+}
+async function requestSessionStop(sessionId) {
+  return await withFileLock(stateLockPath(), async () => {
+    const raw = await readStateRaw();
+    const target = raw.sessions.find((session) => session.sessionId === sessionId);
+    if (target === void 0) {
+      return void 0;
+    }
+    if (target.status === "ready") {
+      return { session: target, previousStatus: target.status };
+    }
+    await writeSessionStopIntent(sessionId);
+    if (target.stopRequestedAt !== void 0) {
+      return { session: target, previousStatus: target.status };
+    }
+    const requested = { ...target, stopRequestedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    await writeState({
+      version: "2",
+      sessions: raw.sessions.map(
+        (session) => session.sessionId === sessionId ? requested : session
+      )
+    });
+    return { session: requested, previousStatus: target.status };
+  });
+}
+
+// src/cli-errors.ts
+var CLEANUP_FAILURE_EXIT_CODE = 70;
+var CleanupFailureError = class extends AggregateError {
+  constructor(errors, cause) {
+    super(
+      errors,
+      "Debugger startup failed and resource cleanup was incomplete",
+      { cause }
+    );
+    this.name = "CleanupFailureError";
+  }
+};
+function requestedCliExitCode(error) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
+  }
+  const value = Reflect.get(error, "cliExitCode");
+  return value === 130 || value === 143 ? value : void 0;
+}
+function hasTunnelTerminationFailure(error) {
+  if (error instanceof CfDebuggerError) {
+    return error.code === "TUNNEL_TERMINATION_FAILED";
+  }
+  return error instanceof AggregateError && error.errors.some((nested) => hasTunnelTerminationFailure(nested));
+}
+function hasCleanupFailure(error) {
+  return error instanceof CleanupFailureError || hasTunnelTerminationFailure(error);
+}
+function cliErrorExitCode(error) {
+  const requested = requestedCliExitCode(error);
+  if (requested !== void 0) {
+    return requested;
+  }
+  if (error instanceof CfDebuggerError && error.code === "ABORTED") {
+    return 130;
+  }
+  return hasCleanupFailure(error) ? CLEANUP_FAILURE_EXIT_CODE : 1;
+}
+
+// src/debug-session/lifecycle.ts
+import { constants as osConstants } from "os";
+
+// src/debug-session/processes.ts
+import process3 from "process";
+async function terminatePidOrGroup(pid, timeoutMs = CHILD_SIGTERM_GRACE_MS, pinnedTarget, verifyBeforeSignal) {
+  const targetKind = pinnedTarget ?? (isProcessGroupAlive(pid) ? "group" : "pid");
+  const targetAlive = () => targetKind === "group" ? isProcessGroupAlive(pid) : isPidAlive(pid);
+  if (!targetAlive()) {
+    return "terminated";
+  }
+  if (verifyBeforeSignal !== void 0 && !await verifyBeforeSignal("SIGTERM")) {
+    return "ownership-lost";
+  }
+  try {
+    process3.kill(targetKind === "group" ? -pid : pid, "SIGTERM");
+  } catch {
+  }
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (!targetAlive()) {
+      return "terminated";
+    }
+    await new Promise((resolve) => {
+      setTimeout(resolve, PID_TERMINATION_POLL_MS);
+    });
+  }
+  if (verifyBeforeSignal !== void 0 && !await verifyBeforeSignal("SIGKILL")) {
+    return "ownership-lost";
+  }
+  try {
+    process3.kill(targetKind === "group" ? -pid : pid, "SIGKILL");
+  } catch {
+  }
+  const forceStartedAt = Date.now();
+  while (Date.now() - forceStartedAt < CHILD_SIGKILL_GRACE_MS) {
+    if (!targetAlive()) {
+      return "terminated";
+    }
+    await new Promise((resolve) => {
+      setTimeout(resolve, PID_TERMINATION_POLL_MS);
+    });
+  }
+  return targetAlive() ? "still-alive" : "terminated";
+}
+async function killProcessGroupOrProc(child, verifyBeforeSignal, timeoutMs = CHILD_SIGTERM_GRACE_MS) {
+  if (child.pid === void 0) {
+    return "terminated";
+  }
+  const childClosed = child.exitCode !== null || child.signalCode !== null;
+  if (childClosed && process3.platform === "win32") {
+    return "terminated";
+  }
+  return await terminatePidOrGroup(
+    child.pid,
+    timeoutMs,
+    childClosed ? "group" : void 0,
+    verifyBeforeSignal
+  );
+}
+
+// src/debug-session/session-home.ts
+import { rm } from "fs/promises";
+async function removeOwnedSessionCfHome(sessionId, candidate) {
+  if (!isOwnedSessionCfHomeDir(sessionId, candidate)) {
+    throw new CfDebuggerError(
+      "UNSAFE_INPUT",
+      `Refusing to remove unowned debugger CF home for session ${sessionId}.`
+    );
+  }
+  await rm(candidate, { recursive: true, force: true });
+}
+async function tryRemoveOwnedSessionCfHome(sessionId, candidate) {
+  if (!isOwnedSessionCfHomeDir(sessionId, candidate)) {
+    return false;
+  }
+  try {
+    await removeOwnedSessionCfHome(sessionId, candidate);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/debug-session/lifecycle.ts
+var handleLifecycles = /* @__PURE__ */ new WeakMap();
+function childIsOpen(child) {
+  return child.exitCode === null && child.signalCode === null;
+}
+function signalExitCode(signal) {
+  return 128 + osConstants.signals[signal];
+}
+function unexpectedExitCode(code, signal) {
+  if (signal !== null) {
+    return signalExitCode(signal);
+  }
+  return code === null || code === 0 ? 1 : code;
+}
+function emitSafely(emit, status, message) {
+  try {
+    emit(status, message);
+  } catch {
+  }
+}
+async function runCleanupActions(actions, aggregateMessage) {
+  const errors = [];
+  for (const action of actions) {
+    try {
+      await action();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length === 1) {
+    throw errors[0];
+  }
+  if (errors.length > 1) {
+    throw new AggregateError(errors, aggregateMessage);
+  }
+}
+async function handleTunnelClose(sessionId, code, signal, child, resolveExit, isFinalizing, hasFailed, markFailed, emit) {
+  const stopRequested = await hasSessionStopIntent(sessionId);
+  const expected = isFinalizing() || stopRequested;
+  if (stopRequested) {
+    await clearSessionStopIntent(sessionId);
+  }
+  if (!expected && !hasFailed()) {
+    const detail = signal === null ? code === null ? "no exit status" : `exit code ${code.toString()}` : `signal ${signal}`;
+    const diagnostics = formatTunnelDiagnostics(getTunnelDiagnostics(child));
+    const error = new CfDebuggerError(
+      "TUNNEL_EXITED",
+      `SSH tunnel ended unexpectedly with ${detail}.`,
+      diagnostics
+    );
+    markFailed(error);
+    emitSafely(emit, "error", error.message);
+  }
+  resolveExit(expected && !hasFailed() ? 0 : unexpectedExitCode(code, signal));
+}
+function attachTunnelEvents(sessionId, child, resolveExit, isFinalizing, hasFailed, markFailed, emit) {
+  child.once("close", (code, signal) => {
+    void handleTunnelClose(
+      sessionId,
+      code,
+      signal,
+      child,
+      resolveExit,
+      isFinalizing,
+      hasFailed,
+      markFailed,
+      emit
+    ).catch((error) => {
+      const failure = new CfDebuggerError(
+        "TUNNEL_EXITED",
+        `SSH tunnel ended and its stop intent could not be verified: ${error instanceof Error ? error.message : String(error)}`,
+        formatTunnelDiagnostics(getTunnelDiagnostics(child))
+      );
+      markFailed(failure);
+      emitSafely(emit, "error", failure.message);
+      resolveExit(unexpectedExitCode(code, signal));
+    });
+  });
+  child.once("error", (error) => {
+    const failure = new CfDebuggerError(
+      "TUNNEL_EXITED",
+      error.message,
+      formatTunnelDiagnostics(getTunnelDiagnostics(child))
+    );
+    markFailed(failure);
+    emitSafely(emit, "error", failure.message);
+  });
+}
+async function expectedTunnelStillOwned(session, child) {
+  const childPid = child?.pid;
+  if (childPid === void 0) {
+    return false;
+  }
+  const ownership = await inspectPortOwnership(session.localPort, childPid);
+  return ownership.status === "unverified" ? "unverified" : ownership.status === "owned";
+}
+async function cleanupFinishedSession(session) {
+  await removeOwnedSessionCfHome(session.sessionId, session.cfHomeDir);
+  await removeSession(session.sessionId);
+  await clearSessionStopIntent(session.sessionId);
+}
+function createTunnelLifecycle(session, emit) {
+  let child;
+  let childIdentity;
+  let childFailed = false;
+  let tunnelError;
+  let finalizing = false;
+  let exitResolve = (_code) => {
+    throw new Error("Tunnel exit resolver was used before initialization.");
+  };
+  const exitPromise = new Promise((resolve) => {
+    exitResolve = resolve;
+  });
+  const observeChild = (tunnelChild) => {
+    child = tunnelChild;
+    childIdentity = tunnelChild.pid === void 0 ? void 0 : readProcessIdentity(tunnelChild.pid);
+    attachTunnelEvents(
+      session.sessionId,
+      tunnelChild,
+      exitResolve,
+      () => finalizing,
+      () => childFailed,
+      (error) => {
+        if (!childFailed) {
+          childFailed = true;
+          tunnelError = error;
+        }
+      },
+      emit
+    );
+  };
+  const verifyBeforeSignal = async (signal) => {
+    const tunnelChild = child;
+    const childPid = tunnelChild?.pid;
+    if (tunnelChild === void 0 || childPid === void 0 || !childIsOpen(tunnelChild)) {
+      return false;
+    }
+    const expectedIdentity = await childIdentity;
+    if (expectedIdentity !== void 0) {
+      return await inspectProcessIdentity(childPid, expectedIdentity) === "match" && childIsOpen(tunnelChild);
+    }
+    if (signal === "SIGKILL") {
+      return await expectedTunnelStillOwned(session, tunnelChild) === true;
+    }
+    return true;
+  };
+  const finalize = async (emitStopped) => {
+    finalizing = true;
+    const termination = child === void 0 ? "terminated" : await killProcessGroupOrProc(child, verifyBeforeSignal);
+    const stillOwned = await expectedTunnelStillOwned(session, child);
+    if (termination !== "terminated" || stillOwned === true || stillOwned === "unverified") {
+      const stderr = child === void 0 ? void 0 : formatTunnelDiagnostics(getTunnelDiagnostics(child));
+      throw new CfDebuggerError(
+        "TUNNEL_TERMINATION_FAILED",
+        `Tunnel for session ${session.sessionId} did not terminate cleanly; state and CF home were retained.`,
+        stderr
+      );
+    }
+    await cleanupFinishedSession(session);
+    if (emitStopped) {
+      emitSafely(emit, "stopped");
+    }
+  };
+  return {
+    exitPromise,
+    assertRunning: () => {
+      if (child === void 0 || !childIsOpen(child) || childFailed) {
+        throw new CfDebuggerError(
+          "TUNNEL_NOT_READY",
+          `SSH tunnel for session ${session.sessionId} exited before readiness could be committed.`,
+          child === void 0 ? void 0 : formatTunnelDiagnostics(getTunnelDiagnostics(child))
+        );
+      }
+    },
+    finalize,
+    observeChild,
+    failed: () => childFailed,
+    error: () => tunnelError
+  };
+}
+function createDebuggerHandle(session, emit, lifecycle) {
+  let disposePromise;
+  const handle = {
+    session,
+    dispose: async () => {
+      const attempt = disposePromise ?? (async () => {
+        const reportLifecycle = !lifecycle.failed();
+        await runCleanupActions([
+          async () => {
+            if (reportLifecycle) {
+              emitSafely(emit, "stopping");
+              await updateSessionStatus(session.sessionId, "stopping");
+            }
+          },
+          async () => {
+            await lifecycle.finalize(reportLifecycle);
+          }
+        ], "Debugger disposal failed");
+      })();
+      disposePromise = attempt;
+      try {
+        await attempt;
+      } catch (error) {
+        if (disposePromise === attempt) {
+          disposePromise = void 0;
+        }
+        throw error;
+      }
+    },
+    waitForExit: async () => await lifecycle.exitPromise
+  };
+  handleLifecycles.set(handle, lifecycle);
+  return handle;
+}
+function getDebuggerHandleTunnelError(handle) {
+  return handleLifecycles.get(handle)?.error();
+}
+async function cleanupFailedStartup(error, lifecycle, emit) {
+  emitSafely(emit, "error", error instanceof Error ? error.message : String(error));
+  try {
+    await lifecycle.finalize(false);
+  } catch (cleanupError) {
+    throw new CleanupFailureError(
+      [error, cleanupError],
+      cleanupError
+    );
+  }
+  throw error;
+}
+
+// src/debug-session/startup-deadline.ts
+function resolveStartupTimeoutMs(value) {
+  const timeoutMs = value ?? DEFAULT_STARTUP_TIMEOUT_MS;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_STARTUP_TIMEOUT_MS) {
+    throw new CfDebuggerError(
+      "UNSAFE_INPUT",
+      `Startup timeout must be an integer from 1 to ${MAX_STARTUP_TIMEOUT_MS.toString()} milliseconds.`
+    );
+  }
+  return timeoutMs;
+}
+function remainingStartupMs(expiresAt) {
+  return Math.max(0, expiresAt - Date.now());
+}
+function startupTimeoutError(timeoutMs, phase) {
+  return new CfDebuggerError(
+    "STARTUP_TIMEOUT",
+    `Debugger startup exceeded its ${(timeoutMs / 1e3).toString()}s deadline during ${phase}.`
+  );
+}
+function createStartupDeadline(timeoutMs, callerSignal) {
+  const controller = new AbortController();
+  const expiresAt = Date.now() + timeoutMs;
+  const onCallerAbort = () => {
+    controller.abort(callerSignal?.reason);
+  };
+  const timer = setTimeout(() => {
+    controller.abort(startupTimeoutError(timeoutMs, "startup"));
+  }, timeoutMs);
+  timer.unref();
+  callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+  if (callerSignal?.aborted === true) {
+    controller.abort(callerSignal.reason);
+  }
+  return {
+    expiresAt,
+    signal: controller.signal,
+    timeoutMs,
+    dispose: () => {
+      clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+    }
+  };
+}
+function throwIfStartupAborted(signal, expiresAt, timeoutMs, phase) {
+  if (remainingStartupMs(expiresAt) === 0) {
+    throw startupTimeoutError(timeoutMs, phase);
+  }
+  if (signal?.aborted) {
+    throw new CfDebuggerError("ABORTED", "Operation aborted by caller");
+  }
+}
+
+// src/debug-session/start.ts
+import { chmod as chmod4, mkdir as mkdir4 } from "fs/promises";
+import nodeProcess6 from "process";
+
+// src/debug-session/orphans.ts
+import { readdir as readdir2, stat as stat2, unlink as unlink4 } from "fs/promises";
+import { hostname as getHostname3 } from "os";
+import { join as join2 } from "path";
+var STALE_TEMP_AGE_MS = 24 * 60 * 60 * 1e3;
+async function modifiedAt(path) {
+  try {
+    return (await stat2(path)).mtimeMs;
+  } catch {
+    return void 0;
+  }
+}
+async function cleanupStaleStateTemps() {
+  const root = saptoolsDir();
+  const entries = await readdir2(root, { withFileTypes: true }).catch(() => []);
+  const now = Date.now();
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.startsWith(`${CF_DEBUGGER_STATE_FILENAME}.`) || !entry.name.endsWith(".tmp")) {
+      continue;
+    }
+    const path = join2(root, entry.name);
+    const mtimeMs = await modifiedAt(path);
+    if (mtimeMs !== void 0 && now - mtimeMs >= STALE_TEMP_AGE_MS) {
+      await unlink4(path).catch(() => false);
+    }
+  }
+}
+async function pruneAndCleanupOrphans(stateAccess) {
+  const result = await readAndPruneActiveSessions(stateAccess);
+  const host = getHostname3();
+  for (const removed of result.removed) {
+    if (removed.hostname === host) {
+      await tryRemoveOwnedSessionCfHome(removed.sessionId, removed.cfHomeDir);
+    }
+  }
+  await cleanupStaleStateTemps();
+  return result;
+}
+
+// src/debug-session/startup-cancellation.ts
+var STOP_REQUEST_POLL_MS = 500;
+function createStartupCancellation(sessionId, callerSignal) {
+  const controller = new AbortController();
+  let active = true;
+  let timer;
+  const onCallerAbort = () => {
+    controller.abort(callerSignal?.reason);
+  };
+  const schedule = () => {
+    timer = setTimeout(() => {
+      void poll();
+    }, STOP_REQUEST_POLL_MS);
+    timer.unref();
+  };
+  const poll = async () => {
+    try {
+      if (active && await hasSessionStopIntent(sessionId)) {
+        controller.abort();
+      }
+    } catch {
+    }
+    if (active && !controller.signal.aborted) {
+      schedule();
+    }
+  };
+  callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+  if (callerSignal?.aborted === true) {
+    controller.abort(callerSignal.reason);
+  } else {
+    void poll();
+  }
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      active = false;
+      clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+      controller.abort();
+    }
+  };
+}
+
+// src/debug-session/startup-remote.ts
+function signalFailureDetail(result) {
+  if (result.timedOutAfterMs !== void 0) {
+    return `timed out after ${(result.timedOutAfterMs / 1e3).toString()}s`;
+  }
+  const stderr = result.stderr.trim();
+  if (stderr.length > 0) {
+    return stderr;
+  }
+  if (result.signal !== void 0) {
+    return `terminated by signal ${result.signal}`;
+  }
+  return `exit code ${String(result.exitCode)}`;
+}
+function warnOnTruncatedStderr(inputs, result) {
+  if (result.stderrTruncated) {
+    inputs.warn(
+      "Remote SSH stderr diagnostics were truncated; inspector marker parsing used complete stdout."
+    );
+  }
+}
+function parseSignalResult(appName, remotePort, result) {
+  if (result.exitCode !== 0) {
+    throw new CfDebuggerError(
+      "USR1_SIGNAL_FAILED",
+      `Failed to send SIGUSR1 to the Node.js process on ${appName}: ${signalFailureDetail(result)}`,
+      result.stderr
+    );
+  }
+  if (result.stdoutTruncated) {
+    throw new CfDebuggerError(
+      "INSPECTOR_OUTPUT_TOO_LARGE",
+      "Inspector startup stdout exceeded the configured capture limit.",
+      result.stderr
+    );
+  }
+  return parseNodeInspectorMarkers(result.stdout, remotePort).remoteNodePid;
+}
+async function executeRemoteSignal(inputs) {
+  const { options, target, context } = inputs;
+  return await cfSshOneShot(
+    options.app,
+    buildNodeInspectorCommand(target.nodePid, options.remotePort),
+    { ...context, phase: "remote inspector signalling" },
+    {
+      process: target.process,
+      instance: target.instance
+    }
+  );
+}
+function restartRefusal(options, stderr) {
+  return new CfDebuggerError(
+    "SSH_NOT_ENABLED",
+    `SSH is disabled for ${options.app}. Re-run with --allow-ssh-enable-restart, or run \`cf enable-ssh ${options.app} && cf restart ${options.app}\` manually.`,
+    stderr
+  );
+}
+function ensureRestartSafe(inputs, stderr) {
+  if (inputs.options.allowSshEnableRestart !== true) {
+    throw restartRefusal(inputs.options, stderr);
+  }
+  if (inputs.target.nodePid !== void 0) {
+    throw new CfDebuggerError(
+      "NODE_PID_RESTART_UNSAFE",
+      `Cannot restart ${inputs.options.app} while targeting Node PID ${inputs.target.nodePid.toString()}; restart manually and select its new PID.`,
+      stderr
+    );
+  }
+}
+async function enableAppSsh(inputs, stderr) {
+  ensureRestartSafe(inputs, stderr);
+  const state = await cfSshEnabled(
+    inputs.options.app,
+    { ...inputs.context, phase: "checking app SSH state" }
+  );
+  if (state === "enabled") {
+    throw new CfDebuggerError(
+      "SSH_NOT_ENABLED",
+      `SSH is already enabled for ${inputs.options.app}, so restarting it is not a remedy. Check space-level SSH policy and your Developer role.`,
+      stderr
+    );
+  }
+  if (state === "unknown") {
+    throw new CfDebuggerError(
+      "SSH_STATE_UNKNOWN",
+      `Could not verify whether SSH is enabled for ${inputs.options.app}; no deployment change was made.`,
+      stderr
+    );
+  }
+  inputs.emit("ssh-enabling", "Enabling app-level SSH");
+  await inputs.transition("ssh-enabling", "Enabling app-level SSH");
+  await cfEnableSsh(
+    inputs.options.app,
+    { ...inputs.context, phase: "enabling app SSH" }
+  );
+  const confirmed = await cfSshEnabled(
+    inputs.options.app,
+    { ...inputs.context, phase: "confirming app SSH state" }
+  );
+  if (confirmed !== "enabled") {
+    throw new CfDebuggerError(
+      "SSH_STATE_UNKNOWN",
+      `App-level SSH enablement for ${inputs.options.app} could not be confirmed; no restart was attempted.`
+    );
+  }
+}
+async function enableAndRestart(inputs, stderr) {
+  await enableAppSsh(inputs, stderr);
+  const { app, org, space } = inputs.options;
+  inputs.warn(
+    `Restarting app ${app} in ${org}/${space} so newly enabled SSH becomes active.`
+  );
+  inputs.emit("ssh-restarting", "Restarting app so SSH becomes active");
+  await inputs.transition("ssh-restarting", "Restarting app so SSH becomes active");
+  await cfRestartApp(app, { ...inputs.context, phase: "restarting the app" });
+}
+async function retrySignal(inputs) {
+  inputs.emit("signaling");
+  await inputs.transition("signaling");
+  const result = await executeRemoteSignal(inputs);
+  warnOnTruncatedStderr(inputs, result);
+  if (result.exitCode !== 0) {
+    throw new CfDebuggerError(
+      "USR1_SIGNAL_FAILED",
+      `Failed to signal ${inputs.options.app} after enabling SSH: ${signalFailureDetail(result)}`,
+      result.stderr
+    );
+  }
+  return parseSignalResult(
+    inputs.options.app,
+    inputs.options.remotePort ?? DEFAULT_NODE_INSPECTOR_PORT,
+    result
+  );
+}
+async function signalRemoteNode(inputs) {
+  inputs.emit("signaling");
+  await inputs.transition("signaling");
+  const result = await executeRemoteSignal(inputs);
+  warnOnTruncatedStderr(inputs, result);
+  const remotePort = inputs.options.remotePort ?? DEFAULT_NODE_INSPECTOR_PORT;
+  if (result.exitCode === 0) {
+    return parseSignalResult(inputs.options.app, remotePort, result);
+  }
+  if (isSshPermissionError(result.stderr)) {
+    throw new CfDebuggerError(
+      "SSH_PERMISSION_DENIED",
+      `CF SSH permission was denied for ${inputs.options.app}. Check your space role and SSH policy.`,
+      result.stderr
+    );
+  }
+  if (!isSshDisabledError(result.stderr)) {
+    return parseSignalResult(inputs.options.app, remotePort, result);
+  }
+  await enableAndRestart(inputs, result.stderr);
+  return await retrySignal(inputs);
+}
+
+// src/debug-session/startup-tunnel.ts
+function linkAbortSignals(signals) {
+  const controller = new AbortController();
+  const subscriptions = [];
+  for (const signal of signals) {
+    const abort = () => {
+      controller.abort(signal.reason);
+    };
+    if (signal.aborted) {
+      abort();
+      break;
+    }
+    signal.addEventListener("abort", abort, { once: true });
+    subscriptions.push([signal, abort]);
+  }
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      for (const [signal, abort] of subscriptions) {
+        signal.removeEventListener("abort", abort);
+      }
+    }
+  };
+}
+function diagnosticsStderr(child) {
+  return formatTunnelDiagnostics(getTunnelDiagnostics(child));
+}
+async function ensurePortAvailable(localPort, signal) {
+  if (!await isPortFree(localPort, signal)) {
+    throw new CfDebuggerError(
+      "PORT_UNAVAILABLE",
+      `Local port ${localPort.toString()} was taken before the tunnel could start.`
+    );
+  }
+}
+function remainingReadyTimeout(inputs) {
+  if (inputs.context.deadlineAt === void 0) {
+    return inputs.tunnelReadyTimeoutMs;
+  }
+  return Math.max(
+    1,
+    Math.min(inputs.tunnelReadyTimeoutMs, inputs.context.deadlineAt - Date.now())
+  );
+}
+function startupStateAccess(inputs) {
+  return {
+    ...inputs.context.signal === void 0 ? {} : { signal: inputs.context.signal },
+    ...inputs.context.deadlineAt === void 0 ? {} : { timeoutMs: Math.max(1, inputs.context.deadlineAt - Date.now()) }
+  };
+}
+function ownerVerificationError(localPort, inspection, child) {
+  const stderr = diagnosticsStderr(child);
+  if (inspection.status === "unverified") {
+    return new CfDebuggerError(
+      "TUNNEL_OWNER_UNVERIFIED",
+      `Could not verify local tunnel port ${localPort.toString()}: ${inspection.reason}`,
+      stderr
+    );
+  }
+  const owners = inspection.status === "not-owned" ? inspection.pids.join(", ") : "none";
+  return new CfDebuggerError(
+    "TUNNEL_OWNER_MISMATCH",
+    `Local tunnel port ${localPort.toString()} is not owned by the spawned tunnel (observed PID(s): ${owners}).`,
+    stderr
+  );
+}
+async function waitForLocalTunnel(inputs, child, timeoutMs) {
+  const childEnded = new AbortController();
+  const linked = linkAbortSignals([
+    ...inputs.context.signal === void 0 ? [] : [inputs.context.signal],
+    childEnded.signal
+  ]);
+  try {
+    const probe = probeTunnelReady(inputs.session.localPort, timeoutMs, linked.signal);
+    const winner = await Promise.race([
+      probe.then((ready) => ({ kind: "probe", ready })),
+      childExitPromise(child).then(() => ({ kind: "child-exit" }))
+    ]);
+    if (winner.kind === "probe" && winner.ready) {
+      return;
+    }
+    if (winner.kind === "child-exit") {
+      childEnded.abort();
+      await probe.catch(() => false);
+    }
+  } finally {
+    linked.dispose();
+  }
+  throw new CfDebuggerError(
+    "TUNNEL_NOT_READY",
+    `SSH tunnel on local port ${inputs.session.localPort.toString()} did not bind within ${Math.round(timeoutMs / 1e3).toString()}s.`,
+    diagnosticsStderr(child)
+  );
+}
+async function verifyLocalOwner(inputs, child, childPid) {
+  const ownership = await inspectPortOwnership(
+    inputs.session.localPort,
+    childPid,
+    inputs.context.signal
+  );
+  if (ownership.status !== "owned") {
+    throw ownerVerificationError(inputs.session.localPort, ownership, child);
+  }
+}
+function childExitPromise(child) {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    child.once("close", () => {
+      resolve();
+    });
+  });
+}
+async function verifyInspector(inputs, child, timeoutMs) {
+  const childEnded = new AbortController();
+  const linked = linkAbortSignals([
+    ...inputs.context.signal === void 0 ? [] : [inputs.context.signal],
+    childEnded.signal
+  ]);
+  try {
+    const probe = probeInspectorReady(inputs.session.localPort, timeoutMs, linked.signal);
+    const winner = await Promise.race([
+      probe.then((result) => ({ kind: "probe", result })),
+      childExitPromise(child).then(() => ({ kind: "child-exit" }))
+    ]);
+    if (winner.kind === "probe" && winner.result.status === "ready") {
+      return;
+    }
+    if (winner.kind === "child-exit") {
+      childEnded.abort();
+      await probe.catch(() => ({ status: "unreachable" }));
+    }
+  } finally {
+    linked.dispose();
+  }
+  throw new CfDebuggerError(
+    "INSPECTOR_UNREACHABLE",
+    `The inspector did not answer through local port ${inputs.session.localPort.toString()} to remote port ${inputs.session.remotePort.toString()}. The inspector may not have opened, the app or container may have restarted, or a different Node PID may own it.`,
+    diagnosticsStderr(child)
+  );
+}
+function requireChildPid(child) {
+  if (child.pid === void 0) {
+    throw new CfDebuggerError(
+      "TUNNEL_PROCESS_MISSING",
+      "The CF SSH tunnel process did not expose a PID."
+    );
+  }
+  return child.pid;
+}
+async function recordTunnelPid(inputs, childPid) {
+  const state = await updateSessionPid(
+    inputs.session.sessionId,
+    childPid,
+    startupStateAccess(inputs)
+  );
+  if (state === void 0 || state.stopRequestedAt !== void 0 || state.status === "stopping") {
+    throw new CfDebuggerError(
+      state === void 0 ? "SESSION_STATE_LOST" : "ABORTED",
+      state === void 0 ? "Debugger session ownership state disappeared while recording the tunnel PID." : "Debugger session stop was requested while recording the tunnel PID."
+    );
+  }
+  if (state.tunnelPid !== childPid || state.pid !== childPid) {
+    throw new CfDebuggerError(
+      "SESSION_STATE_CONFLICT",
+      "Debugger session did not retain ownership of the spawned tunnel process."
+    );
+  }
+}
+function ensureStartupActive(inputs, phase) {
+  throwIfStartupAborted(
+    inputs.context.signal,
+    inputs.context.deadlineAt ?? Number.MAX_SAFE_INTEGER,
+    inputs.context.startupTimeoutMs ?? Number.MAX_SAFE_INTEGER,
+    phase
+  );
+}
+async function openReadyTunnel(inputs) {
+  await ensurePortAvailable(inputs.session.localPort, inputs.context.signal);
+  ensureStartupActive(inputs, "the final local-port check");
+  const child = spawnSshTunnel(
+    inputs.options.app,
+    inputs.session.localPort,
+    inputs.session.remotePort,
+    { ...inputs.context, phase: "opening the SSH tunnel" },
+    { process: inputs.target.process, instance: inputs.target.instance }
+  );
+  inputs.onChild(child);
+  const childPid = requireChildPid(child);
+  await recordTunnelPid(inputs, childPid);
+  const timeoutMs = remainingReadyTimeout(inputs);
+  const readyDeadline = Date.now() + timeoutMs;
+  await waitForLocalTunnel(inputs, child, timeoutMs);
+  ensureStartupActive(inputs, "local tunnel binding");
+  await verifyLocalOwner(inputs, child, childPid);
+  ensureStartupActive(inputs, "local tunnel ownership verification");
+  await verifyInspector(inputs, child, Math.max(1, readyDeadline - Date.now()));
+  ensureStartupActive(inputs, "inspector readiness verification");
+  await verifyLocalOwner(inputs, child, childPid);
+  ensureStartupActive(inputs, "final local tunnel ownership verification");
+  if (child.exitCode !== null || child.signalCode !== null) {
+    throw new CfDebuggerError(
+      "TUNNEL_NOT_READY",
+      `SSH tunnel on local port ${inputs.session.localPort.toString()} exited during readiness verification.`,
+      diagnosticsStderr(child)
+    );
+  }
+}
+
+// src/debug-session/start.ts
+function requireCredentials(options) {
+  const email = options.email ?? nodeProcess6.env["SAP_EMAIL"];
+  const password = options.password ?? nodeProcess6.env["SAP_PASSWORD"];
+  if (email === void 0 || email.length === 0) {
+    throw new CfDebuggerError(
+      "MISSING_CREDENTIALS",
+      "SAP email is required. Pass `email` or set SAP_EMAIL."
+    );
+  }
+  if (password === void 0 || password.length === 0) {
+    throw new CfDebuggerError(
+      "MISSING_CREDENTIALS",
+      "SAP password is required. Pass `password` or set SAP_PASSWORD."
+    );
+  }
+  return { email, password };
+}
+function resolveTunnelReadyTimeoutMs(value) {
+  const timeoutMs = value ?? DEFAULT_TUNNEL_READY_TIMEOUT_MS;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new CfDebuggerError(
+      "UNSAFE_INPUT",
+      "Tunnel-ready timeout must be a positive integer number of milliseconds."
+    );
+  }
+  return timeoutMs;
+}
+async function registerSession(options, target, apiEndpoint, deadline) {
+  const portProbe = async (port) => {
+    throwIfStartupAborted(
+      deadline.signal,
+      deadline.expiresAt,
+      deadline.timeoutMs,
+      "local port selection"
+    );
+    const available = await isPortFree(port, deadline.signal);
+    throwIfStartupAborted(
+      deadline.signal,
+      deadline.expiresAt,
+      deadline.timeoutMs,
+      "local port selection"
+    );
+    return available;
+  };
+  const registration = await registerNewSession({
+    region: options.region,
+    org: options.org,
+    space: options.space,
+    app: options.app,
+    process: target.process,
+    instance: target.instance,
+    ...target.nodePid === void 0 ? {} : { nodePid: target.nodePid },
+    apiEndpoint,
+    remotePort: options.remotePort ?? DEFAULT_NODE_INSPECTOR_PORT,
+    startupTimeoutMs: deadline.timeoutMs,
+    ...options.preferredPort === void 0 ? {} : { preferredPort: options.preferredPort },
+    portProbe,
+    cfHomeForSession: sessionCfHomeDir,
+    stateAccess: startupStateAccess2(deadline.signal, deadline.expiresAt)
+  });
+  if (registration.existing !== void 0) {
+    throw new CfDebuggerError(
+      "SESSION_ALREADY_RUNNING",
+      `A debugger session already exists for ${sessionKeyString(options)} on port ${registration.existing.localPort.toString()} (session ${registration.existing.sessionId}).`
+    );
+  }
+  return registration.session;
+}
+function requireStartupState(state, expectedStatus) {
+  if (state === void 0) {
+    throw new CfDebuggerError(
+      "SESSION_STATE_LOST",
+      "Debugger session ownership state disappeared during startup."
+    );
+  }
+  if (state.stopRequestedAt !== void 0 || state.status === "stopping") {
+    throw new CfDebuggerError("ABORTED", "Debugger session stop was requested during startup.");
+  }
+  if (expectedStatus !== void 0 && state.status !== expectedStatus) {
+    throw new CfDebuggerError(
+      "SESSION_STATE_CONFLICT",
+      `Debugger session state did not transition to ${expectedStatus}.`
+    );
+  }
+  return state;
+}
+function startupStateAccess2(signal, expiresAt) {
+  return {
+    ...signal === void 0 ? {} : { signal },
+    ...expiresAt === void 0 ? {} : { timeoutMs: Math.max(1, remainingStartupMs(expiresAt)) }
+  };
+}
+function createTransition(sessionId, context) {
+  return async (status, message) => {
+    return requireStartupState(
+      await updateSessionStatus(
+        sessionId,
+        status,
+        message,
+        startupStateAccess2(context.signal, context.deadlineAt)
+      ),
+      status
+    );
+  };
+}
+async function prepareCfHome(cfHomeDir) {
+  await mkdir4(cfHomeDir, { recursive: true, mode: 448 });
+  await chmod4(cfHomeDir, 448);
+}
+async function loginAndTarget(inputs) {
+  const { options, context, credentials, emit, transition } = inputs;
+  emit("logging-in");
+  await transition("logging-in");
+  await cfLogin(
+    inputs.session.apiEndpoint,
+    credentials.email,
+    credentials.password,
+    { ...context, phase: "Cloud Foundry login" }
+  );
+  emit("targeting");
+  await transition("targeting");
+  const targetingContext = { ...context, phase: "Cloud Foundry target selection" };
+  await cfTarget(options.org, options.space, targetingContext);
+  if (!await cfAppExists(options.app, targetingContext)) {
+    throw new CfDebuggerError(
+      "APP_NOT_FOUND",
+      `Cloud Foundry app ${options.app} was not found in ${options.org}/${options.space}.`
+    );
+  }
+}
+async function ensurePortAvailable2(localPort, context) {
+  if (!await isPortFree(localPort, context.signal)) {
+    throw new CfDebuggerError(
+      "PORT_UNAVAILABLE",
+      `Local port ${localPort.toString()} was taken before remote signalling began.`
+    );
+  }
+}
+async function recordRemoteNodePid(sessionId, remoteNodePid, context) {
+  const state = requireStartupState(
+    await updateSessionRemoteNodePid(
+      sessionId,
+      remoteNodePid,
+      startupStateAccess2(context.signal, context.deadlineAt)
+    )
+  );
+  if (state.remoteNodePid !== remoteNodePid) {
+    throw new CfDebuggerError(
+      "SESSION_STATE_CONFLICT",
+      "Debugger session did not retain the selected remote Node PID."
+    );
+  }
+}
+async function establishDebuggerSession(inputs) {
+  await prepareCfHome(inputs.session.cfHomeDir);
+  await loginAndTarget(inputs);
+  await ensurePortAvailable2(inputs.session.localPort, inputs.context);
+  const remoteNodePid = await signalRemoteNode({
+    options: inputs.options,
+    target: inputs.target,
+    context: inputs.context,
+    transition: inputs.transition,
+    emit: inputs.emit,
+    warn: writeWarning
+  });
+  throwIfStartupAborted(
+    inputs.context.signal,
+    inputs.context.deadlineAt ?? Number.MAX_SAFE_INTEGER,
+    inputs.context.startupTimeoutMs ?? Number.MAX_SAFE_INTEGER,
+    "remote inspector signalling"
+  );
+  await recordRemoteNodePid(inputs.session.sessionId, remoteNodePid, inputs.context);
+  inputs.emit("tunneling");
+  await inputs.transition("tunneling");
+  await openReadyTunnel({
+    options: inputs.options,
+    target: inputs.target,
+    session: inputs.session,
+    context: inputs.context,
+    tunnelReadyTimeoutMs: inputs.tunnelReadyTimeoutMs,
+    onChild: inputs.lifecycle.observeChild
+  });
+  const readySession = await inputs.transition("ready");
+  inputs.lifecycle.assertRunning();
+  inputs.emit("ready");
+  return readySession;
+}
+function writeWarning(message) {
+  nodeProcess6.stderr.write(`[cf-debugger] warning: ${message}
+`);
+}
+function writeTunnelOutput(stream, text) {
+  nodeProcess6.stderr.write(`[cf-debugger tunnel ${stream}] ${text}
+`);
+}
+function retryMessage(status) {
+  const remainingSeconds = Math.ceil(status.remainingMs / 1e3);
+  return `${status.command} attempt ${status.attempt.toString()} failed; retrying in ${status.delayMs.toString()}ms (${remainingSeconds.toString()}s startup budget left)`;
+}
+function createStatusTracker(options) {
+  let currentStatus = "starting";
+  return {
+    current: () => currentStatus,
+    emit: (status, message) => {
+      currentStatus = status;
+      try {
+        options.onStatus?.(status, message);
+      } catch {
+        writeWarning("The onStatus callback threw; lifecycle cleanup will continue.");
+      }
+    }
+  };
+}
+function createCfContext(session, credentials, cancellation, deadline, tracker, verbose) {
+  return {
+    cfHome: session.cfHomeDir,
+    signal: cancellation.signal,
+    deadlineAt: deadline.expiresAt,
+    startupTimeoutMs: deadline.timeoutMs,
+    sensitiveValues: [credentials.email, credentials.password],
+    ...verbose ? {
+      onRetry: (status) => {
+        tracker.emit(tracker.current(), retryMessage(status));
+      },
+      onTunnelOutput: writeTunnelOutput
+    } : {}
+  };
+}
+function normalizeStartupError(error, expiresAt, timeoutMs) {
+  if (error instanceof CfDebuggerError && error.code === "ABORTED" && remainingStartupMs(expiresAt) === 0) {
+    return startupTimeoutError(timeoutMs, "startup");
+  }
+  return error;
+}
+async function startDebuggerUsingDeadline(options, deadline) {
+  const target = resolveNodeTarget(options);
+  const credentials = requireCredentials(options);
+  const apiEndpoint = resolveApiEndpoint(options.region, options.apiEndpoint, writeWarning);
+  const startupTimeoutMs = deadline.timeoutMs;
+  const tunnelReadyTimeoutMs = resolveTunnelReadyTimeoutMs(options.tunnelReadyTimeoutMs);
+  const tracker = createStatusTracker(options);
+  tracker.emit("starting");
+  let cancellation;
+  let lifecycle;
+  try {
+    throwIfStartupAborted(deadline.signal, deadline.expiresAt, startupTimeoutMs, "initialization");
+    await pruneAndCleanupOrphans(
+      startupStateAccess2(deadline.signal, deadline.expiresAt)
+    );
+    throwIfStartupAborted(deadline.signal, deadline.expiresAt, startupTimeoutMs, "state cleanup");
+    const session = await registerSession(options, target, apiEndpoint, deadline);
+    cancellation = createStartupCancellation(session.sessionId, deadline.signal);
+    const context = createCfContext(
+      session,
+      credentials,
+      cancellation,
+      deadline,
+      tracker,
+      options.verbose === true
+    );
+    lifecycle = createTunnelLifecycle(session, tracker.emit);
+    const activeSession = await establishDebuggerSession({
+      options: { ...options, remotePort: session.remotePort },
+      target,
+      session,
+      context,
+      credentials,
+      tunnelReadyTimeoutMs,
+      emit: tracker.emit,
+      transition: createTransition(session.sessionId, context),
+      lifecycle
+    });
+    cancellation.dispose();
+    deadline.dispose();
+    return createDebuggerHandle(activeSession, tracker.emit, lifecycle);
+  } catch (error) {
+    cancellation?.dispose();
+    deadline.dispose();
+    const normalized = normalizeStartupError(error, deadline.expiresAt, startupTimeoutMs);
+    if (lifecycle === void 0) {
+      tracker.emit(
+        "error",
+        normalized instanceof Error ? normalized.message : String(normalized)
+      );
+      throw normalized;
+    }
+    return await cleanupFailedStartup(normalized, lifecycle, tracker.emit);
+  }
+}
+async function startDebuggerWithinDeadline(options, deadline) {
+  try {
+    return await startDebuggerUsingDeadline(options, deadline);
+  } catch (error) {
+    deadline.dispose();
+    throw error;
+  }
+}
+async function startDebugger(options) {
+  const startupTimeoutMs = resolveStartupTimeoutMs(options.startupTimeoutMs);
+  const deadline = createStartupDeadline(startupTimeoutMs, options.signal);
+  return await startDebuggerWithinDeadline(options, deadline);
+}
+
+// src/debug-session/doctor.ts
+import {
+  lstat,
+  readFile as readFile5,
+  readdir as readdir3,
+  unlink as unlink5
+} from "fs/promises";
+import { hostname as hostname2 } from "os";
+import { join as join3 } from "path";
+import nodeProcess7 from "process";
+var MANAGED_PORT_MIN = 2e4;
+var MANAGED_PORT_MAX = 20999;
+var PORT_SCAN_CONCURRENCY = 32;
+var STALE_TEMP_AGE_MS2 = 24 * 60 * 60 * 1e3;
+var STALE_LOCK_AGE_MS = 60 * 60 * 1e3;
+var FOREIGN_OR_MALFORMED_LOCK_AGE_MS = 24 * 60 * 60 * 1e3;
+var LEGACY_STATE_FILENAME = "cf-debugger-state.json";
+var LEGACY_LOCK_FILENAME = "cf-debugger-state.lock";
+var LEGACY_HOMES_DIRNAME = "cf-debugger-homes";
+function errorCode7(error) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
+  }
+  const value = Reflect.get(error, "code");
+  return typeof value === "string" ? value : void 0;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function emptyState2() {
+  return { version: "2", sessions: [] };
+}
+async function readDoctorState() {
+  let raw;
+  try {
+    raw = await readFile5(stateFilePath(), "utf8");
+  } catch (error) {
+    if (errorCode7(error) === "ENOENT") {
+      return { state: emptyState2(), warnings: [], homeCleanupSafe: true };
+    }
+    return {
+      state: emptyState2(),
+      warnings: [`Could not read debugger state: ${errorMessage(error)}`],
+      homeCleanupSafe: false
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {
+      state: emptyState2(),
+      warnings: ["Debugger state contains invalid JSON."],
+      homeCleanupSafe: false
+    };
+  }
+  const decoded = decodeStateFileDetailed(parsed);
+  if (decoded.kind === "invalid-file") {
+    return {
+      state: emptyState2(),
+      warnings: [`Debugger state is invalid: ${decoded.reason}.`],
+      homeCleanupSafe: false
+    };
+  }
+  return {
+    state: decoded.state,
+    warnings: decoded.dropped.map((reason) => `Dropped state entry: ${reason}.`),
+    homeCleanupSafe: decoded.dropped.length === 0
+  };
+}
+async function inspectSessions(sessions) {
+  const local = sessions.filter((session) => session.hostname === hostname2());
+  return await Promise.all(local.map(async (session) => {
+    try {
+      return { session, health: await inspectSessionHealth(session) };
+    } catch (error) {
+      return {
+        session,
+        health: {
+          status: "unverified",
+          reason: `health inspection failed: ${errorMessage(error)}`
+        }
+      };
+    }
+  }));
+}
+async function readDirectory(path) {
+  try {
+    return await readdir3(path, { withFileTypes: true });
+  } catch (error) {
+    if (errorCode7(error) === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+async function findOrphanHomes(sessions, cleanup) {
+  const root = join3(saptoolsDir(), CF_DEBUGGER_HOMES_DIRNAME);
+  const claimed = new Set(sessions.map((session) => session.sessionId));
+  const entries = await readDirectory(root);
+  const orphans = entries.filter((entry) => entry.isDirectory() && !claimed.has(entry.name)).sort((left, right) => left.name.localeCompare(right.name));
+  return await Promise.all(orphans.map(async (entry) => {
+    const path = join3(root, entry.name);
+    const cleanupEligible = isOwnedSessionCfHomeDir(entry.name, path);
+    if (!cleanup) {
+      return { sessionId: entry.name, path, cleanupEligible, cleanupStatus: "not-requested" };
+    }
+    if (!cleanupEligible) {
+      return { sessionId: entry.name, path, cleanupEligible, cleanupStatus: "not-eligible" };
+    }
+    const cleanupStatus = await cleanupOrphanHome(entry.name, path);
+    return {
+      sessionId: entry.name,
+      path,
+      cleanupEligible,
+      cleanupStatus
+    };
+  }));
+}
+async function cleanupOrphanHome(sessionId, path) {
+  try {
+    return await withFileLock(
+      stateLockPath(),
+      async () => {
+        const current = await readDoctorState();
+        if (!current.homeCleanupSafe || current.state.sessions.some((session) => session.sessionId === sessionId)) {
+          return "skipped";
+        }
+        return await tryRemoveOwnedSessionCfHome(sessionId, path) ? "removed" : "failed";
+      }
+    );
+  } catch {
+    return "failed";
+  }
+}
+async function mapConcurrent(values, concurrency, work) {
+  const results = [];
+  let nextIndex = 0;
+  const worker = async () => {
+    for (; ; ) {
+      const index = nextIndex;
+      nextIndex += 1;
+      const value = values[index];
+      if (value === void 0) {
+        return;
+      }
+      const result = await work(value);
+      if (result !== void 0) {
+        results.push(result);
+      }
+    }
+  };
+  const workerCount = Math.min(concurrency, values.length);
+  await Promise.all(Array.from({ length: workerCount }, worker));
+  return results;
+}
+function unclaimedManagedPorts(sessions) {
+  const localClaims = new Set(
+    sessions.filter((session) => session.hostname === hostname2()).map((session) => session.localPort)
+  );
+  const ports = [];
+  for (let port = MANAGED_PORT_MIN; port <= MANAGED_PORT_MAX; port += 1) {
+    if (!localClaims.has(port)) {
+      ports.push(port);
+    }
+  }
+  return ports;
+}
+async function inspectUnclaimedPort(port) {
+  if (!await isPortListening(port)) {
+    return void 0;
+  }
+  const inspection = await inspectListeningProcesses(port);
+  if (inspection.status === "found") {
+    return { port, pids: inspection.pids, ownerStatus: "found" };
+  }
+  if (inspection.status === "unverified") {
+    return {
+      port,
+      pids: [],
+      ownerStatus: "unverified",
+      reason: inspection.reason
+    };
+  }
+  return void 0;
+}
+async function findUnclaimedPorts(sessions) {
+  const findings = await mapConcurrent(
+    unclaimedManagedPorts(sessions),
+    PORT_SCAN_CONCURRENCY,
+    inspectUnclaimedPort
+  );
+  return [...findings].sort((left, right) => left.port - right.port);
+}
+function artifactKind(name) {
+  if (name === CF_DEBUGGER_LOCK_FILENAME) {
+    return "state-lock";
+  }
+  if (name === `${CF_DEBUGGER_LOCK_FILENAME}.recovery`) {
+    return "state-recovery";
+  }
+  if (name.startsWith(`${CF_DEBUGGER_STATE_FILENAME}.`) && name.endsWith(".tmp")) {
+    return "state-temp";
+  }
+  if (name.startsWith(CF_DEBUGGER_STOP_INTENT_PREFIX) && name.endsWith(".stop")) {
+    return "stop-intent";
+  }
+  return name.startsWith(`${CF_DEBUGGER_STATE_FILENAME}.corrupt-`) ? "corrupt-backup" : void 0;
+}
+function parseLockOwner2(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return void 0;
+  }
+  const ownerHostname = Reflect.get(parsed, "hostname");
+  const pid = Reflect.get(parsed, "pid");
+  const processIdentity = Reflect.get(parsed, "processIdentity");
+  const token = Reflect.get(parsed, "token");
+  if (typeof ownerHostname !== "string" || typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0 || processIdentity !== void 0 && (typeof processIdentity !== "string" || processIdentity.length === 0) || typeof token !== "string") {
+    return void 0;
+  }
+  return {
+    hostname: ownerHostname,
+    pid,
+    ...processIdentity === void 0 ? {} : { processIdentity },
+    token
+  };
+}
+function isPidAlive2(pid) {
+  try {
+    nodeProcess7.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return errorCode7(error) !== "ESRCH";
+  }
+}
+async function readLockOwner2(path) {
+  try {
+    return parseLockOwner2(await readFile5(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+async function lockCleanupEligible(path, ageMs) {
+  if (ageMs < STALE_LOCK_AGE_MS) {
+    return false;
+  }
+  const owner = await readLockOwner2(path);
+  if (owner?.hostname === hostname2()) {
+    if (!isPidAlive2(owner.pid)) {
+      return true;
+    }
+    if (owner.processIdentity !== void 0) {
+      const identity = await inspectProcessIdentity(owner.pid, owner.processIdentity);
+      if (identity === "mismatch") {
+        return true;
+      }
+      if (identity === "match") {
+        return false;
+      }
+    }
+    return ageMs >= FOREIGN_OR_MALFORMED_LOCK_AGE_MS;
+  }
+  return ageMs >= FOREIGN_OR_MALFORMED_LOCK_AGE_MS;
+}
+function artifactFingerprint(stats) {
+  return [
+    stats.dev.toString(),
+    stats.ino.toString(),
+    stats.size.toString(),
+    stats.mtimeMs.toString()
+  ].join(":");
+}
+async function inspectArtifact(entry, now, claimedSessionIds, stopIntentCleanupSafe) {
+  const kind = artifactKind(entry.name);
+  if (kind === void 0) {
+    return void 0;
+  }
+  const path = join3(saptoolsDir(), entry.name);
+  const stats = await lstat(path);
+  const ageMs = Math.max(0, now - stats.mtimeMs);
+  const regularFile = stats.isFile();
+  let sessionId;
+  let cleanupEligible = regularFile && kind === "state-temp" && ageMs >= STALE_TEMP_AGE_MS2;
+  if (regularFile && kind === "stop-intent") {
+    sessionId = entry.name.slice(
+      CF_DEBUGGER_STOP_INTENT_PREFIX.length,
+      -".stop".length
+    );
+    cleanupEligible = stopIntentCleanupSafe && ageMs >= STALE_TEMP_AGE_MS2 && !claimedSessionIds.has(sessionId);
+  }
+  if (regularFile && (kind === "state-lock" || kind === "state-recovery")) {
+    cleanupEligible = await lockCleanupEligible(path, ageMs);
+  }
+  return {
+    kind,
+    path,
+    ageMs,
+    cleanupEligible,
+    fingerprint: artifactFingerprint(stats),
+    ...sessionId === void 0 ? {} : { sessionId }
+  };
+}
+async function candidateStillMatches(candidate) {
+  try {
+    const stats = await lstat(candidate.path);
+    return artifactFingerprint(stats) === candidate.fingerprint;
+  } catch {
+    return false;
+  }
+}
+async function cleanupArtifact(candidate) {
+  if (!candidate.cleanupEligible) {
+    return { status: "not-eligible" };
+  }
+  try {
+    if (candidate.kind === "stop-intent" && candidate.sessionId !== void 0) {
+      return await withFileLock(
+        stateLockPath(),
+        async () => {
+          const current = await readDoctorState();
+          if (!current.homeCleanupSafe || current.state.sessions.some(
+            (session) => session.sessionId === candidate.sessionId
+          ) || !await candidateStillMatches(candidate)) {
+            return { status: "skipped" };
+          }
+          await unlink5(candidate.path);
+          return { status: "removed" };
+        }
+      );
+    }
+    if (!await candidateStillMatches(candidate)) {
+      return { status: "skipped" };
+    }
+    await unlink5(candidate.path);
+    return { status: "removed" };
+  } catch (error) {
+    if (errorCode7(error) === "ENOENT") {
+      return { status: "skipped" };
+    }
+    return { status: "failed", error: errorMessage(error) };
+  }
+}
+async function findArtifacts(cleanup, sessions, stopIntentCleanupSafe) {
+  const entries = await readDirectory(saptoolsDir());
+  const claimedSessionIds = new Set(sessions.map((session) => session.sessionId));
+  const inspected = await Promise.all(
+    entries.map(
+      async (entry) => await inspectArtifact(entry, Date.now(), claimedSessionIds, stopIntentCleanupSafe)
+    )
+  );
+  const candidates = inspected.filter(
+    (candidate) => candidate !== void 0
+  ).sort((left, right) => left.path.localeCompare(right.path));
+  const findings = [];
+  for (const candidate of candidates) {
+    const result = cleanup ? await cleanupArtifact(candidate) : {
+      status: candidate.cleanupEligible ? "not-requested" : "not-eligible"
+    };
+    findings.push({
+      kind: candidate.kind,
+      path: candidate.path,
+      ageMs: candidate.ageMs,
+      cleanupEligible: candidate.cleanupEligible,
+      cleanupStatus: result.status,
+      ...result.error === void 0 ? {} : { cleanupError: result.error }
+    });
+  }
+  return findings;
+}
+async function pathExists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (errorCode7(error) === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+function shellQuote(value) {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+async function findLegacyArtifacts() {
+  const statePath = join3(saptoolsDir(), LEGACY_STATE_FILENAME);
+  const lockPath = join3(saptoolsDir(), LEGACY_LOCK_FILENAME);
+  const homesPath = join3(saptoolsDir(), LEGACY_HOMES_DIRNAME);
+  const [statePresent, homesPresent] = await Promise.all([
+    pathExists(statePath),
+    pathExists(homesPath)
+  ]);
+  if (!statePresent && !homesPresent) {
+    return { statePath, statePresent, homesPath, homesPresent };
+  }
+  const command = `rm -rf -- ${shellQuote(homesPath)} ${shellQuote(statePath)} ${shellQuote(lockPath)}`;
+  return {
+    statePath,
+    statePresent,
+    homesPath,
+    homesPresent,
+    warning: "Legacy v1 debugger homes may contain live CF refresh and access tokens. Confirm no v1 tunnel is running before removing them.",
+    manualRemovalCommand: command
+  };
+}
+function reportWarnings(stateWarnings, orphanHomes, unclaimedPorts, legacy) {
+  const warnings = [...stateWarnings];
+  if (orphanHomes.length > 0) {
+    warnings.push(`${orphanHomes.length.toString()} orphaned v2 CF home(s) found.`);
+  }
+  if (unclaimedPorts.length > 0) {
+    warnings.push(`${unclaimedPorts.length.toString()} unclaimed managed-port listener(s) found.`);
+  }
+  if (legacy.warning !== void 0) {
+    warnings.push(legacy.warning);
+  }
+  return warnings;
+}
+async function runDoctor(options = {}) {
+  const cleanup = options.cleanup === true;
+  const stateResult = await readDoctorState();
+  const homeCleanup = cleanup && stateResult.homeCleanupSafe;
+  const [sessions, orphanHomes, unclaimedPorts, artifacts, legacy] = await Promise.all([
+    inspectSessions(stateResult.state.sessions),
+    findOrphanHomes(stateResult.state.sessions, homeCleanup),
+    findUnclaimedPorts(stateResult.state.sessions),
+    findArtifacts(cleanup, stateResult.state.sessions, stateResult.homeCleanupSafe),
+    findLegacyArtifacts()
+  ]);
+  const cleanedPaths = [
+    ...orphanHomes.filter((finding) => finding.cleanupStatus === "removed").map((finding) => finding.path),
+    ...artifacts.filter((finding) => finding.cleanupStatus === "removed").map((finding) => finding.path)
+  ];
+  return {
+    sessions,
+    orphanHomes,
+    unclaimedPorts,
+    artifacts,
+    legacy,
+    warnings: [
+      ...reportWarnings(stateResult.warnings, orphanHomes, unclaimedPorts, legacy),
+      ...cleanup && !stateResult.homeCleanupSafe ? [
+        "Skipped orphan-home and stop-intent cleanup because debugger state was incomplete or invalid."
+      ] : []
+    ],
+    cleanedPaths
+  };
+}
+
+// src/debug-session/sessions.ts
+import { hostname as getHostname4 } from "os";
+import nodeProcess8 from "process";
+function findMatchingSession(sessions, options) {
+  if (options.sessionId !== void 0) {
+    return sessions.find((session) => session.sessionId === options.sessionId);
+  }
+  if (options.key === void 0) {
+    return void 0;
+  }
+  const key = options.key;
+  const matches = sessions.filter((session) => matchesKey(session, key));
+  if (matches.length > 1) {
+    throw new CfDebuggerError(
+      "SESSION_AMBIGUOUS",
+      "Multiple debugger sessions match this target. Pass --session-id, --api-endpoint, or --node-pid."
+    );
+  }
+  return matches[0];
+}
+function startupAgeLimit2(session) {
+  return (session.startupTimeoutMs ?? MAX_STARTUP_TIMEOUT_MS) + STARTUP_STALE_SLACK_MS;
+}
+function startupExpired2(session) {
+  const startedAt = Date.parse(session.startedAt);
+  return Number.isNaN(startedAt) || Date.now() - startedAt > startupAgeLimit2(session);
+}
+async function inspectRecordedProcess2(pid, identity) {
+  if (!isPidAlive(pid)) {
+    return "dead";
+  }
+  return await inspectProcessIdentity(pid, identity);
+}
+async function inspectController(target) {
+  const controllerPid = target.controllerPid ?? target.pid;
+  return await inspectRecordedProcess2(controllerPid, target.controllerProcessIdentity);
+}
+async function ownsRecordedTunnel(target) {
+  const tunnelPid = target.tunnelPid;
+  if (tunnelPid === void 0) {
+    return false;
+  }
+  const processVerdict = await inspectRecordedProcess2(
+    tunnelPid,
+    target.tunnelProcessIdentity
+  );
+  if (processVerdict !== "match") {
+    return false;
+  }
+  return (await inspectPortOwnership(target.localPort, tunnelPid)).status === "owned";
+}
+async function terminateVerifiedTunnel(target) {
+  const tunnelPid = target.tunnelPid;
+  if (tunnelPid === void 0 || tunnelPid === nodeProcess8.pid) {
+    return tunnelPid === nodeProcess8.pid ? "still-alive" : "terminated";
+  }
+  try {
+    const verifyBeforeSignal = async (signal) => {
+      if (signal === "SIGTERM" || target.tunnelProcessIdentity === void 0) {
+        return await ownsRecordedTunnel(target);
+      }
+      return await inspectRecordedProcess2(
+        tunnelPid,
+        target.tunnelProcessIdentity
+      ) === "match";
+    };
+    return await terminatePidOrGroup(
+      tunnelPid,
+      void 0,
+      void 0,
+      verifyBeforeSignal
+    );
+  } catch {
+    return "still-alive";
+  }
+}
+async function terminateVerifiedTunnelAndConfirm(target, recordExpectedStop = false) {
+  if (recordExpectedStop) {
+    await writeSessionStopIntent(target.sessionId);
+  }
+  if (!await ownsRecordedTunnel(target)) {
+    throw ownershipError(target, "recorded tunnel no longer owns the local port");
+  }
+  const termination = await terminateVerifiedTunnel(target);
+  if (termination !== "terminated" || await ownsRecordedTunnel(target)) {
+    throw new CfDebuggerError(
+      "TUNNEL_TERMINATION_FAILED",
+      termination === "ownership-lost" ? `Tunnel ownership for session ${target.sessionId} could not be reverified during termination; no unverified process was signalled and state was retained.` : `Tunnel process for session ${target.sessionId} did not terminate; state was retained.`
+    );
+  }
+}
+async function removeOwnedSession(target, stale, forced = false, warning, preserveStopIntent = false) {
+  let resultWarning = warning;
+  if (isOwnedSessionCfHomeDir(target.sessionId, target.cfHomeDir)) {
+    await removeOwnedSessionCfHome(target.sessionId, target.cfHomeDir);
+  } else {
+    const skipped = `State referenced unowned CF home ${target.cfHomeDir}; it was not deleted.`;
+    resultWarning = resultWarning === void 0 ? skipped : `${resultWarning} ${skipped}`;
+  }
+  const removed = await removeSession(target.sessionId);
+  if (!preserveStopIntent) {
+    await clearSessionStopIntent(target.sessionId);
+  }
+  return {
+    ...removed ?? target,
+    stale,
+    pending: false,
+    forced,
+    ...resultWarning === void 0 ? {} : { warning: resultWarning }
+  };
+}
+function ownershipError(target, detail) {
+  return new CfDebuggerError(
+    "TUNNEL_OWNERSHIP_UNVERIFIED",
+    `Cannot safely stop session ${target.sessionId}: ${detail}. No process was signalled. Retry with --force to forget the record and its owned CF home.`
+  );
+}
+function forcedWarning(target, detail) {
+  return `Forced state cleanup abandoned PID ${String(target.tunnelPid ?? target.controllerPid ?? target.pid)} and local port ${target.localPort.toString()}: ${detail}. No unverified process was signalled.`;
+}
+async function forceRemoveUnverified(target, detail, preserveStopIntent = false) {
+  return await removeOwnedSession(
+    target,
+    true,
+    true,
+    forcedWarning(target, detail),
+    preserveStopIntent
+  );
+}
+async function stopReadySession(target, force) {
+  if (await ownsRecordedTunnel(target)) {
+    await terminateVerifiedTunnelAndConfirm(target, true);
+    return await removeOwnedSession(target, false, false, void 0, true);
+  }
+  const tunnelVerdict = target.tunnelPid === void 0 ? "dead" : await inspectRecordedProcess2(target.tunnelPid, target.tunnelProcessIdentity);
+  const tunnelDead = target.tunnelPid === void 0 || !isPidOrGroupAlive(target.tunnelPid) || tunnelVerdict === "mismatch";
+  const ownership = target.tunnelPid === void 0 ? await inspectListeningProcesses(target.localPort) : await inspectPortOwnership(target.localPort, target.tunnelPid);
+  if (tunnelDead && ownership.status === "not-listening") {
+    return await removeOwnedSession(target, true, false, void 0, true);
+  }
+  const detail = ownership.status === "unverified" ? ownership.reason : ownership.status === "not-owned" ? `local port ${target.localPort.toString()} belongs to PID(s) ${ownership.pids.join(", ")}` : tunnelVerdict === "unavailable" ? "the recorded tunnel identity could not be inspected" : "the recorded tunnel could not be proven dead and owned";
+  if (force) {
+    return await forceRemoveUnverified(target, detail, true);
+  }
+  throw ownershipError(target, detail);
+}
+async function stopStartingSession(target, force) {
+  const expired = startupExpired2(target);
+  const controllerVerdict = await inspectController(target);
+  if (!force && !expired && controllerVerdict === "match") {
+    return { ...target, stale: false, pending: true, forced: false };
+  }
+  if (await ownsRecordedTunnel(target)) {
+    await terminateVerifiedTunnelAndConfirm(target);
+    return await removeOwnedSession(target, false, false, void 0, true);
+  }
+  const tunnelAlive = target.tunnelPid !== void 0 && isPidOrGroupAlive(target.tunnelPid);
+  const listening = await inspectListeningProcesses(target.localPort);
+  const detail = listening.status === "unverified" ? listening.reason : listening.status === "found" ? `local port ${target.localPort.toString()} belongs to PID(s) ${listening.pids.join(", ")}` : controllerVerdict === "unavailable" ? "the startup controller identity could not be inspected" : "the recorded startup owner could not be verified as a tunnel";
+  if (force) {
+    return await forceRemoveUnverified(
+      target,
+      detail,
+      controllerVerdict === "match"
+    );
+  }
+  if (!tunnelAlive && listening.status === "not-listening" && (expired || controllerVerdict !== "unavailable")) {
+    return await removeOwnedSession(target, true);
+  }
+  throw ownershipError(target, detail);
+}
+async function stopDebugger(options) {
+  const localSessions = (await readSessionSnapshot()).filter(
+    (session) => session.hostname === getHostname4()
+  );
+  const target = findMatchingSession(localSessions, options);
+  if (target === void 0) {
+    return void 0;
+  }
+  const claim = await requestSessionStop(target.sessionId);
+  if (claim === void 0) {
+    return void 0;
+  }
+  return claim.previousStatus === "ready" ? await stopReadySession(claim.session, options.force === true) : await stopStartingSession(claim.session, options.force === true);
+}
+function outcomeForResult(result) {
+  return {
+    sessionId: result.sessionId,
+    app: result.app,
+    status: result.pending ? "pending" : result.stale ? "stale" : "stopped",
+    result
+  };
+}
+function outcomeForError(session, error) {
+  const normalized = error instanceof CfDebuggerError ? error : new CfDebuggerError(
+    "STOP_FAILED",
+    error instanceof Error ? error.message : String(error)
+  );
+  return {
+    sessionId: session.sessionId,
+    app: session.app,
+    status: "failed",
+    error: normalized
+  };
+}
+function outcomeForMissing(session) {
+  return {
+    sessionId: session.sessionId,
+    app: session.app,
+    status: "stale"
+  };
+}
+function summarizeOutcomes(outcomes) {
+  const count = (status) => outcomes.filter((outcome) => outcome.status === status).length;
+  return {
+    outcomes,
+    failed: count("failed"),
+    pending: count("pending"),
+    stale: count("stale"),
+    stopped: count("stopped")
+  };
+}
+async function stopAllDebuggers(force = false) {
+  const sessions = (await readSessionSnapshot()).filter(
+    (session) => session.hostname === getHostname4()
+  );
+  const outcomes = [];
+  for (const session of sessions) {
+    try {
+      const result = await stopDebugger({ sessionId: session.sessionId, force });
+      outcomes.push(
+        result === void 0 ? outcomeForMissing(session) : outcomeForResult(result)
+      );
+    } catch (error) {
+      outcomes.push(outcomeForError(session, error));
+    }
+  }
+  return summarizeOutcomes(outcomes);
+}
+async function listSessions() {
+  return await readActiveSessions();
+}
+async function getSession(key) {
+  const sessions = await readActiveSessions();
+  return findMatchingSession(sessions, { key });
+}
+
+export {
+  CfDebuggerError,
+  resolveApiEndpoint,
+  listKnownRegionKeys,
+  readCurrentCfTarget,
+  parseCurrentCfTarget,
+  requireCurrentCfRegion,
+  regionKeyForApiEndpoint,
+  regionKeyFromSapApiEndpoint,
+  DEFAULT_NODE_INSPECTOR_PORT,
+  resolveNodeTarget,
+  buildNodeInspectorCommand,
+  parseNodeInspectorMarkers,
+  sessionKeyString,
+  CLEANUP_FAILURE_EXIT_CODE,
+  hasTunnelTerminationFailure,
+  cliErrorExitCode,
+  getDebuggerHandleTunnelError,
+  resolveStartupTimeoutMs,
+  remainingStartupMs,
+  startupTimeoutError,
+  createStartupDeadline,
+  startDebuggerWithinDeadline,
+  startDebugger,
+  runDoctor,
+  stopDebugger,
+  stopAllDebuggers,
+  listSessions,
+  getSession
+};
+//# sourceMappingURL=chunk-ZWAQD7KL.js.map