@saptools/cf-debugger 0.1.16 → 0.2.1

package/dist/cli.js

@@ -1,2412 +1,105 @@
 #!/usr/bin/env node
+import {
+  CLEANUP_FAILURE_EXIT_CODE,
+  CfDebuggerError,
+  DEFAULT_NODE_INSPECTOR_PORT,
+  cliErrorExitCode,
+  createStartupDeadline,
+  getDebuggerHandleTunnelError,
+  getSession,
+  hasTunnelTerminationFailure,
+  listSessions,
+  readCurrentCfTarget,
+  remainingStartupMs,
+  requireCurrentCfRegion,
+  resolveNodeTarget,
+  resolveStartupTimeoutMs,
+  runDoctor,
+  startDebuggerWithinDeadline,
+  startupTimeoutError,
+  stopAllDebuggers,
+  stopDebugger
+} from "./chunk-AKQR4Y74.js";
 
 // src/cli.ts
-import process7 from "process";
+import nodeProcess from "process";
 import { Command } from "commander";
 
-// src/cloud-foundry/commands.ts
-import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
-
-// src/regions.ts
-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",
-  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",
-  eu11: "https://api.cf.eu11.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",
-  eu22: "https://api.cf.eu22.hana.ondemand.com",
-  eu30: "https://api.cf.eu30.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",
-  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",
-  us11: "https://api.cf.us11.hana.ondemand.com",
-  us20: "https://api.cf.us20.hana.ondemand.com",
-  us21: "https://api.cf.us21.hana.ondemand.com",
-  us30: "https://api.cf.us30.hana.ondemand.com"
-};
-function resolveApiEndpoint(regionKey, override) {
-  if (override !== void 0 && override !== "") {
-    return override;
-  }
-  const endpoint = REGION_API_ENDPOINTS[regionKey];
-  if (endpoint === void 0) {
-    throw new Error(
-      `Unknown region key: ${regionKey}. Pass \`apiEndpoint\` explicitly to override.`
-    );
-  }
-  return endpoint;
-}
-function listKnownRegionKeys() {
-  return Object.keys(REGION_API_ENDPOINTS);
-}
-
-// 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/cloud-foundry/execute.ts
-import { execFile } from "child_process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile);
-var MAX_BUFFER = 16 * 1024 * 1024;
-var DEFAULT_CF_COMMAND_TIMEOUT_MS = 3e5;
-var REDACTED_ARG = "<redacted>";
-var MAX_RETRIES = 3;
-function buildEnv(cfHome) {
-  return { ...process.env, CF_HOME: cfHome };
-}
-function resolveBin(context) {
-  return context.command ?? process.env["CF_DEBUGGER_CF_BIN"] ?? "cf";
-}
-function sensitiveArgs(args) {
-  if (args[0] !== "auth") {
-    return [];
-  }
-  return args.slice(1).filter((arg) => arg.length > 0);
-}
-function redactText(text, values) {
-  return 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 waitForRetry(delayMs, signal) {
-  if (signal?.aborted) {
-    return Promise.reject(new CfDebuggerError("ABORTED", "Operation aborted by caller"));
-  }
-  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 });
-  });
-}
-function formatArgsForError(args) {
-  if (args[0] !== "auth") {
-    return args.join(" ");
-  }
-  return args.map((arg, index) => index === 0 ? arg : REDACTED_ARG).join(" ");
-}
-function optionalString(value) {
-  return typeof value === "string" ? value : void 0;
-}
-function readFailureDetails(error) {
-  const errorObject = typeof error === "object" && error !== null ? error : void 0;
-  const field3 = (key) => errorObject === void 0 ? void 0 : Reflect.get(errorObject, key);
-  return {
-    code: optionalString(field3("code")),
-    killed: field3("killed") === true,
-    message: error instanceof Error ? error.message : String(error),
-    stderr: optionalString(field3("stderr")),
-    stdout: optionalString(field3("stdout"))
-  };
-}
-function isTransientNetworkError(error) {
-  if (error.killed && error.code === void 0) {
-    return true;
-  }
-  const code = error.code ?? "";
-  const networkCodes = ["ETIMEDOUT", "ECONNRESET", "ENOTFOUND", "ECONNREFUSED", "EHOSTUNREACH", "ENETUNREACH"];
-  if (networkCodes.includes(code)) {
-    return true;
-  }
-  const output = `${error.message} ${error.stderr ?? ""} ${error.stdout ?? ""}`.toLowerCase();
-  const transientPhrases = [
-    "error performing request",
-    "timeout exceeded",
-    "connection reset by peer",
-    "service unavailable",
-    "bad gateway",
-    "gateway timeout",
-    "dial tcp",
-    "i/o timeout"
-  ];
-  if (transientPhrases.some((phrase) => output.includes(phrase))) {
-    return true;
-  }
-  const transientRegexes = [/\b502\b/, /\b503\b/, /\b504\b/, /\btimeout\b/];
-  return transientRegexes.some((regex) => regex.test(output));
-}
-function resolveRunOptions(args, input) {
-  const options = typeof input === "number" ? { timeoutMs: input } : input;
-  return {
-    env: options.env,
-    redactionValues: normalizeSensitiveValues([
-      ...sensitiveArgs(args),
-      ...options.sensitiveValues ?? []
-    ]),
-    timeoutMs: options.timeoutMs ?? DEFAULT_CF_COMMAND_TIMEOUT_MS
-  };
-}
-async function executeCfAttempt(args, context, options) {
-  const { stdout } = await execFileAsync(resolveBin(context), [...args], {
-    env: { ...buildEnv(context.cfHome), ...options.env },
-    maxBuffer: MAX_BUFFER,
-    ...context.signal === void 0 ? {} : { signal: context.signal },
-    timeout: options.timeoutMs
-  });
-  return stdout;
-}
-function retryDelayMs(failure, attempt) {
-  if (!isTransientNetworkError(failure) || attempt > MAX_RETRIES) {
-    return void 0;
-  }
-  return Math.min(1e3 * 2 ** (attempt - 1), 1e4);
-}
-function createCfCliError(args, failure, redactionValues) {
-  const stderr = redactText(failure.stderr?.trim() ?? "", redactionValues);
-  const fallbackMessage = redactText(failure.message, redactionValues);
-  const detail = stderr.length > 0 ? stderr : fallbackMessage;
-  return new CfDebuggerError(
-    "CF_CLI_FAILED",
-    `cf ${formatArgsForError(args)} failed: ${detail}`,
-    stderr
-  );
-}
-async function runCf(args, context, input = {}) {
-  if (context.signal?.aborted) {
-    throw new CfDebuggerError("ABORTED", "Operation aborted by caller");
-  }
-  const options = resolveRunOptions(args, input);
-  let attempt = 0;
-  for (; ; ) {
-    try {
-      return await executeCfAttempt(args, context, options);
-    } catch (err) {
-      attempt += 1;
-      const failure = readFailureDetails(err);
-      if (context.signal?.aborted || failure.code === "ABORT_ERR") {
-        throw new CfDebuggerError("ABORTED", "Operation aborted by caller");
-      }
-      const delayMs = retryDelayMs(failure, attempt);
-      if (delayMs !== void 0) {
-        await waitForRetry(delayMs, context.signal);
-        continue;
-      }
-      throw createCfCliError(args, failure, options.redactionValues);
-    }
-  }
-}
-
-// src/cloud-foundry/commands.ts
-var execFileAsync2 = promisify2(execFile2);
-var CF_AUTH_MAX_ATTEMPTS = 3;
-var CURRENT_TARGET_TIMEOUT_MS = 3e4;
-function rethrowCallerAbort(error) {
-  if (error instanceof CfDebuggerError && error.code === "ABORTED") {
-    throw error;
-  }
-}
-function waitForAuthRetry(delayMs, signal) {
-  if (signal?.aborted) {
-    return Promise.reject(new CfDebuggerError("ABORTED", "Operation aborted by caller"));
-  }
-  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 });
-  });
-}
-async function cfApi(apiEndpoint, context) {
-  await runCf(["api", apiEndpoint], context);
-}
-async function cfAuth(email, password, context) {
-  let lastError;
-  for (let attempt = 0; attempt < CF_AUTH_MAX_ATTEMPTS; attempt++) {
-    try {
-      await runCf(["auth"], context, {
-        env: { CF_PASSWORD: password, CF_USERNAME: email },
-        sensitiveValues: [email, password]
-      });
-      return;
-    } catch (err) {
-      lastError = err;
-      if (err instanceof CfDebuggerError && err.code === "ABORTED") {
-        throw err;
-      }
-      if (attempt < CF_AUTH_MAX_ATTEMPTS - 1) {
-        await waitForAuthRetry(1e3 * (attempt + 1), context.signal);
-      }
-    }
-  }
-  if (lastError instanceof Error) {
-    throw lastError;
-  }
-  throw new CfDebuggerError("CF_AUTH_FAILED", `cf auth failed: ${String(lastError)}`);
-}
-async function cfLogin(apiEndpoint, email, password, context) {
-  try {
-    await cfApi(apiEndpoint, context);
-    await cfAuth(email, password, context);
-  } catch (err) {
-    rethrowCallerAbort(err);
-    if (err instanceof CfDebuggerError) {
-      throw new CfDebuggerError("CF_LOGIN_FAILED", err.message, err.stderr);
-    }
-    throw err;
-  }
-}
-async function cfTarget(org, space, context) {
-  try {
-    await runCf(["target", "-o", org, "-s", space], context);
-  } catch (err) {
-    rethrowCallerAbort(err);
-    if (err instanceof CfDebuggerError) {
-      throw new CfDebuggerError("CF_TARGET_FAILED", err.message, err.stderr);
-    }
-    throw err;
-  }
-}
-async function cfSshEnabled(appName, context) {
-  try {
-    const stdout = await runCf(["ssh-enabled", appName], context);
-    return stdout.toLowerCase().includes("ssh support is enabled");
-  } catch (err) {
-    rethrowCallerAbort(err);
-    return false;
-  }
-}
-async function cfEnableSsh(appName, context) {
-  try {
-    await runCf(["enable-ssh", appName], context);
-  } catch (err) {
-    rethrowCallerAbort(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 execFileAsync2(options.command ?? process.env["CF_DEBUGGER_CF_BIN"] ?? "cf", ["target"], {
-      env: options.env ?? process.env,
-      maxBuffer: 16 * 1024 * 1024,
-      timeout: options.timeoutMs ?? CURRENT_TARGET_TIMEOUT_MS
-    });
-    return parseCurrentCfTarget(stdout);
-  } catch (error) {
-    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);
-  return match?.[1];
-}
-function isPresent(value) {
-  return value !== void 0 && value.length > 0;
-}
-
-// src/cloud-foundry/ssh.ts
-import { spawn } from "child_process";
-
-// src/cloud-foundry/node-process.ts
-var DEFAULT_CF_PROCESS = "web";
-var DEFAULT_CF_INSTANCE = 0;
-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 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) {
-  if (nodePid !== void 0 && (!Number.isSafeInteger(nodePid) || nodePid <= 0)) {
-    throw new CfDebuggerError("UNSAFE_INPUT", "nodePid must be a positive safe integer.");
-  }
-  return NODE_INSPECTOR_SCRIPT.replace("__REQUESTED_NODE_PID__", nodePid?.toString() ?? "");
-}
-function parseNodeInspectorMarkers(stdout) {
-  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);
-  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) {
-  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);
-}
-function throwForRuntimeFailure(markers) {
-  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 9229 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 9229.");
-  }
-}
-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__",
-  "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_pid() {",
-  '  listener_hex="$1"',
-  '  [ -n "$listener_hex" ] || return 0',
-  `  socket_inode="$(awk -v ph=":$listener_hex" '$4 == "0A" && $2 ~ (ph "$") { print $10; exit }' /proc/net/tcp /proc/net/tcp6 2>/dev/null)"`,
-  '  [ -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_inspector_owner() {",
-  "  find_listener_pid 240D",
-  "}",
-  "find_app_port_listener() {",
-  '  [ -n "${PORT:-}" ] || return 0',
-  `  app_port_hex="$(printf '%04X' "$PORT" 2>/dev/null || true)"`,
-  '  find_listener_pid "$app_port_hex"',
-  "}",
-  '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_inspector_owner)"',
-  '  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))",
-  "  sleep 0.25",
-  "done",
-  'echo "saptools-inspector-not-ready=$selected_pid"'
-].join("\n");
-
-// src/cloud-foundry/ssh.ts
-var DEFAULT_MAX_OUTPUT_BYTES = 65536;
-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) {
-  const options = resolveSshOptions(rawOptions);
-  const args = buildCfSshArgs(appName, options.target, [
-    "--disable-pseudo-tty",
-    "-c",
-    command
-  ]);
-  return await runSshOneShot(args, context, options);
-}
-function resolveSshOptions(raw) {
-  const input = typeof raw === "number" ? { timeoutMs: raw } : raw;
-  const timeoutMs = input.timeoutMs ?? DEFAULT_CF_COMMAND_TIMEOUT_MS;
-  const maxOutputBytes = input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
-  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
-    throw new RangeError("timeoutMs must be a positive safe integer");
-  }
-  if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes <= 0) {
-    throw new RangeError("maxOutputBytes must be a positive safe integer");
-  }
-  return { target: input, timeoutMs, maxOutputBytes };
-}
-function createBoundedOutput() {
-  return { chunks: [], bytes: 0, truncated: false };
-}
-function appendBounded(output, data, limit) {
-  const incoming = Buffer.isBuffer(data) ? data : Buffer.from(data);
-  const remaining = Math.max(0, limit - output.bytes);
-  if (incoming.byteLength > remaining) {
-    output.truncated = true;
-  }
-  if (remaining === 0) {
-    return;
-  }
-  const next = incoming.subarray(0, remaining);
-  output.chunks.push(next);
-  output.bytes += next.byteLength;
-}
-function outputText(output) {
-  return Buffer.concat(output.chunks, output.bytes).toString("utf8");
-}
-function createResult(exitCode, stdout, stderr) {
-  return {
-    exitCode,
-    stdout: outputText(stdout),
-    stderr: outputText(stderr),
-    outputTruncated: stdout.truncated || stderr.truncated
-  };
-}
-function createSshExecutionState() {
-  return {
-    stdout: createBoundedOutput(),
-    stderr: createBoundedOutput(),
-    settled: false,
-    aborted: false,
-    timedOut: false
-  };
-}
-function terminateSshExecution(child, state) {
-  signalChild(child, "SIGTERM");
-  state.forceKillTimer ??= setTimeout(() => {
-    signalChild(child, "SIGKILL");
-  }, 1e3);
-}
-function createSshSettler(state, options, signal, onAbort, resolve, reject) {
-  return (result) => {
-    if (state.settled) {
-      return;
-    }
-    state.settled = true;
-    if (state.timeoutTimer !== void 0) {
-      clearTimeout(state.timeoutTimer);
-    }
-    if (state.forceKillTimer !== void 0) {
-      clearTimeout(state.forceKillTimer);
-    }
-    signal?.removeEventListener("abort", onAbort);
-    if (state.aborted) {
-      reject(new CfDebuggerError("ABORTED", "Operation aborted by caller"));
-      return;
-    }
-    resolve(state.timedOut ? { ...result, timedOutAfterMs: options.timeoutMs } : result);
-  };
-}
-function attachSshExecution(child, context, options, resolve, reject) {
-  const state = createSshExecutionState();
-  const onAbort = () => {
-    state.aborted = true;
-    terminateSshExecution(child, state);
-  };
-  const settle = createSshSettler(state, options, context.signal, 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) => {
-    appendBounded(state.stdout, data, options.maxOutputBytes);
-  });
-  child.stderr.on("data", (data) => {
-    appendBounded(state.stderr, data, options.maxOutputBytes);
-  });
-  child.on("close", (code, signal) => {
-    const base = createResult(code, state.stdout, state.stderr);
-    settle(state.timedOut || signal === null ? base : { ...base, signal });
-  });
-  child.on("error", (error) => {
-    appendBounded(state.stderr, error.message, options.maxOutputBytes);
-    settle(createResult(null, state.stdout, state.stderr));
-  });
-}
-function runSshOneShot(args, context, options) {
-  if (context.signal?.aborted) {
-    return Promise.reject(new CfDebuggerError("ABORTED", "Operation aborted by caller"));
-  }
-  return new Promise((resolve, reject) => {
-    const child = spawn(resolveBin(context), [...args], {
-      env: buildEnv(context.cfHome),
-      detached: process.platform !== "win32",
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-    attachSshExecution(child, context, options, resolve, reject);
-  });
-}
-function signalChild(child, signal) {
-  if (process.platform !== "win32" && child.pid !== void 0) {
-    try {
-      process.kill(-child.pid, signal);
-      return;
-    } catch {
-    }
-  }
-  try {
-    child.kill(signal);
-  } catch {
-  }
-}
-function isSshDisabledError(stderr) {
-  const lower = stderr.toLowerCase();
-  return lower.includes("not authorized") || lower.includes("ssh support is disabled");
-}
-function spawnSshTunnel(appName, localPort, remotePort, context, target = {}) {
-  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: process.platform !== "win32",
-    stdio: ["ignore", "pipe", "pipe"]
-  });
-  child.stdout.resume();
-  child.stderr.resume();
-  return child;
-}
-
-// src/debug-session/start.ts
-import { chmod as chmod3, mkdir as mkdir3, rm as rm2 } from "fs/promises";
-import process5 from "process";
-
-// 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 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 isSafeSessionId(sessionId) {
-  return SESSION_ID_PATTERN.test(sessionId);
-}
-function sessionCfHomeDir(sessionId) {
-  if (!isSafeSessionId(sessionId)) {
-    throw new Error("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/network/ports.ts
-import { execFile as execFile3 } from "child_process";
-import { readdir, readFile, readlink } from "fs/promises";
-import { createConnection, createServer } from "net";
-import { promisify as promisify3 } from "util";
-var execFileAsync3 = promisify3(execFile3);
-async function findListeningPidsWithNetstat(port) {
-  try {
-    const { stdout } = await execFileAsync3("netstat", ["-ano"]);
-    const pids = /* @__PURE__ */ new Set();
-    for (const line of stdout.split("\n")) {
-      if (!line.includes(`:${port.toString()}`) || !line.includes("LISTENING")) {
-        continue;
-      }
-      const parts = line.trim().split(/\s+/);
-      const last = parts[parts.length - 1];
-      if (last === void 0) {
-        continue;
-      }
-      const pid = Number.parseInt(last, 10);
-      if (!Number.isNaN(pid)) {
-        pids.add(pid);
-      }
-    }
-    return [...pids];
-  } catch {
-    return [];
-  }
-}
-async function findListeningPidsWithLsof(port) {
-  try {
-    const { stdout } = await execFileAsync3("lsof", ["-nP", "-t", "-i", `tcp:${port.toString()}`, "-sTCP:LISTEN"]);
-    return stdout.trim().split("\n").filter((line) => line.length > 0).map((line) => Number.parseInt(line, 10)).filter((pid) => !Number.isNaN(pid));
-  } catch {
-    return [];
-  }
-}
-async function findListeningPidsWithProc(port) {
-  const inodes = await findListeningSocketInodesWithProc(port);
-  if (inodes.size === 0) {
-    return [];
-  }
-  try {
-    const entries = await readdir("/proc", { withFileTypes: true });
-    const pids = /* @__PURE__ */ new Set();
-    for (const entry of entries) {
-      if (!entry.isDirectory() || !/^\d+$/.test(entry.name)) {
-        continue;
-      }
-      if (await processHasSocketInode(entry.name, inodes)) {
-        pids.add(Number.parseInt(entry.name, 10));
-      }
-    }
-    return [...pids];
-  } catch {
-    return [];
-  }
-}
-async function findListeningSocketInodesWithProc(port) {
-  const inodes = /* @__PURE__ */ new Set();
-  await collectListeningSocketInodes("/proc/net/tcp", port, inodes);
-  await collectListeningSocketInodes("/proc/net/tcp6", port, inodes);
-  return inodes;
-}
-async function collectListeningSocketInodes(path, port, inodes) {
-  try {
-    const content = await readFile(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);
-      }
-    }
-  } catch {
-  }
-}
-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 findListeningPids(port) {
-  if (process.platform === "win32") {
-    return await findListeningPidsWithNetstat(port);
-  }
-  const lsofPids = await findListeningPidsWithLsof(port);
-  return lsofPids.length > 0 ? lsofPids : await findListeningPidsWithProc(port);
-}
-async function isPortFree(port) {
-  return await new Promise((resolve) => {
-    const server = createServer();
-    server.once("error", () => {
-      resolve(false);
-    });
-    server.once("listening", () => {
-      server.close(() => {
-        resolve(true);
-      });
-    });
-    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 throwIfAborted(signal) {
-  if (signal?.aborted) {
-    throw new CfDebuggerError("ABORTED", "Operation aborted by caller");
-  }
-}
-function waitForNextProbe(delayMs, signal) {
-  throwIfAborted(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 });
-  });
-}
-async function probeTunnelReady(port, timeoutMs, signal) {
-  const pollIntervalMs = 250;
-  const started = Date.now();
-  throwIfAborted(signal);
-  while (Date.now() - started < timeoutMs) {
-    const connected = await isPortListening(port);
-    if (connected) {
-      return true;
-    }
-    const remainingMs = timeoutMs - (Date.now() - started);
-    await waitForNextProbe(Math.min(pollIntervalMs, Math.max(0, remainingMs)), signal);
-  }
-  throwIfAborted(signal);
-  return false;
-}
-async function findListeningProcessId(port) {
-  const pids = await findListeningPids(port);
-  return pids[0];
-}
-
-// src/session-state/store.ts
-import { randomUUID as randomUUID2 } from "crypto";
-import { chmod as chmod2, mkdir as mkdir2, readFile as readFile3, rename, unlink as unlink2, writeFile } from "fs/promises";
-import { hostname as getHostname } from "os";
-import { dirname as dirname2, isAbsolute as isAbsolute3 } from "path";
-import process3 from "process";
-
-// 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;
-function sleep(ms) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-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 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");
-  if (typeof lockHostname !== "string" || typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) {
-    return void 0;
-  }
-  if (typeof token !== "string" || version !== "1") {
-    return void 0;
-  }
-  return { hostname: lockHostname, pid, token, version };
-}
-function isProcessAlive(pid) {
-  try {
-    process2.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return errorCode(error) !== "ESRCH";
-  }
-}
-async function readLockOwner(lockPath) {
-  try {
-    await chmod(lockPath, 384);
-    return parseLockOwner(await readFile2(lockPath, "utf8"));
-  } catch (error) {
-    if (errorCode(error) === "ENOENT") {
-      return void 0;
-    }
-    throw error;
-  }
-}
-async function isStaleLock(lockPath, staleMs) {
-  let modifiedAt;
-  try {
-    modifiedAt = (await stat(lockPath)).mtimeMs;
-  } catch (error) {
-    if (errorCode(error) === "ENOENT") {
-      return true;
-    }
-    throw error;
-  }
-  const owner = await readLockOwner(lockPath);
-  if (owner?.hostname === hostname()) {
-    return !isProcessAlive(owner.pid);
-  }
-  return owner === void 0 && Date.now() - modifiedAt > staleMs;
-}
-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 (errorCode(error) !== "ENOENT") {
-      throw error;
-    }
-  });
-}
-async function reclaimStaleLock(lockPath, staleMs) {
-  const recoveryPath = `${lockPath}.recovery`;
-  let recoveryLock;
-  try {
-    recoveryLock = await createFileLock(recoveryPath);
-  } catch (error) {
-    if (errorCode(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 (errorCode(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 (errorCode(error) !== "ENOENT") {
-      throw error;
-    }
-  });
-}
-async function createFileLock(lockPath) {
-  const handle = await open(lockPath, "wx", 384);
-  const token = randomUUID();
-  try {
-    await handle.writeFile(`${JSON.stringify({ hostname: hostname(), pid: process2.pid, 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) {
-  const deadline = Date.now() + timeoutMs;
-  const parentDir = dirname(lockPath);
-  await mkdir(parentDir, { recursive: true, mode: 448 });
-  await chmod(parentDir, 448);
-  for (; ; ) {
-    try {
-      return await createFileLock(lockPath);
-    } catch (error) {
-      if (errorCode(error) !== "EEXIST") {
-        throw error;
-      }
-    }
-    if (await reclaimStaleLock(lockPath, staleMs)) {
-      continue;
-    }
-    if (Date.now() > deadline) {
-      throw new Error(`Timed out acquiring file lock at ${lockPath}`);
-    }
-    await sleep(pollMs);
-  }
-}
-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);
-  try {
-    return await work();
-  } finally {
-    await releaseFileLock(lockPath, lock);
-  }
-}
-
-// 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 requireInteger(value, key, minimum, maximum) {
-  const candidate = field2(value, key);
-  if (!Number.isSafeInteger(candidate) || typeof candidate !== "number") {
-    throw INVALID_SESSION;
-  }
-  if (candidate < minimum || candidate > maximum) {
-    throw INVALID_SESSION;
-  }
-  return candidate;
-}
-function optionalInteger(value, key, minimum) {
-  const candidate = field2(value, key);
-  if (candidate === void 0) {
-    return void 0;
-  }
-  if (!Number.isSafeInteger(candidate) || typeof candidate !== "number" || candidate < minimum) {
-    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 decodeSession(value) {
-  if (typeof value !== "object" || value === null) {
-    return void 0;
-  }
-  try {
-    const processName = requireString(value, "process");
-    const instance = requireInteger(value, "instance", 0, Number.MAX_SAFE_INTEGER);
-    const nodePid = optionalInteger(value, "nodePid", 1);
-    const target = resolveNodeTarget({
-      process: processName,
-      instance,
-      ...nodePid === void 0 ? {} : { nodePid }
-    });
-    const pid = requireInteger(value, "pid", 1, Number.MAX_SAFE_INTEGER);
-    const controllerPid = requireInteger(value, "controllerPid", 1, Number.MAX_SAFE_INTEGER);
-    const tunnelPid = optionalInteger(value, "tunnelPid", 1);
-    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,
-      ...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,
-      ...nodePid === void 0 ? {} : { 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 decodeStateFile(value) {
-  if (typeof value !== "object" || value === null || field2(value, "version") !== "2") {
-    return void 0;
-  }
-  const rawSessions = field2(value, "sessions");
-  if (!Array.isArray(rawSessions)) {
-    return void 0;
-  }
-  const sessionIds = /* @__PURE__ */ new Set();
-  const sessions = [];
-  for (const rawSession of rawSessions) {
-    const session = decodeSession(rawSession);
-    if (session === void 0 || sessionIds.has(session.sessionId)) {
-      return void 0;
-    }
-    sessionIds.add(session.sessionId);
-    sessions.push(session);
-  }
-  return { version: "2", sessions };
-}
-
-// src/session-state/store.ts
-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;
-}
-async function readJsonFile(path) {
-  let raw;
-  try {
-    await chmod2(path, 384);
-    raw = await readFile3(path, "utf8");
-  } catch (err) {
-    if (errorCode2(err) === "ENOENT") {
-      return void 0;
-    }
-    throw err;
-  }
-  try {
-    return JSON.parse(raw);
-  } catch {
-    process3.stderr.write(
-      `[cf-debugger] warning: state file at ${path} is not valid JSON; resetting to empty.
-`
-    );
-    return void 0;
-  }
-}
-async function writeJsonFileAtomic(path, value) {
-  const tempPath = `${path}.${randomUUID2()}.tmp`;
-  const parentDir = dirname2(path);
-  await mkdir2(parentDir, { recursive: true, mode: 448 });
-  await chmod2(parentDir, 448);
-  let renamed = false;
-  try {
-    await writeFile(tempPath, `${JSON.stringify(value, null, 2)}
-`, {
-      encoding: "utf8",
-      flag: "wx",
-      mode: 384
-    });
-    await rename(tempPath, path);
-    renamed = true;
-    await chmod2(path, 384);
-  } finally {
-    if (!renamed) {
-      await unlink2(tempPath).catch(() => false);
-    }
-  }
-}
-function emptyState() {
-  return { version: "2", sessions: [] };
-}
-function isPidAlive(pid) {
-  try {
-    process3.kill(pid, 0);
-    return true;
-  } catch (err) {
-    if (errorCode2(err) === "ESRCH") {
-      return false;
-    }
-    return true;
-  }
-}
-function isPidOrGroupAlive(pid) {
-  if (isPidAlive(pid)) {
-    return true;
-  }
-  return isProcessGroupAlive(pid);
-}
-function isProcessGroupAlive(pid) {
-  return process3.platform !== "win32" && isPidAlive(-pid);
-}
-async function isSessionHealthy(session, host) {
-  if (session.hostname !== host) {
-    return false;
-  }
-  if (session.status !== "ready" && isPidAlive(session.controllerPid ?? session.pid)) {
-    return true;
-  }
-  if (session.tunnelPid !== void 0 && isPidOrGroupAlive(session.tunnelPid)) {
-    return true;
-  }
-  return await isPortListening(session.localPort);
-}
-async function filterStaleSessions(sessions) {
-  const host = getHostname();
-  const checks = await Promise.all(
-    sessions.map(async (session) => [
-      session,
-      await isSessionHealthy(session, host)
-    ])
-  );
-  return checks.filter(([, healthy]) => healthy).map(([session]) => session);
-}
-async function readStateRaw() {
-  const path = stateFilePath();
-  const parsed = await readJsonFile(path);
-  if (parsed === void 0) {
-    return emptyState();
-  }
-  const decoded = decodeStateFile(parsed);
-  if (decoded !== void 0) {
-    return decoded;
-  }
-  process3.stderr.write(
-    `[cf-debugger] warning: state file at ${path} has an invalid structure; resetting to empty.
-`
-  );
-  return emptyState();
-}
-async function writeState(state) {
-  await writeJsonFileAtomic(stateFilePath(), state);
-}
-async function readAndPruneLocked() {
-  const raw = await readStateRaw();
-  const host = getHostname();
-  const remote = raw.sessions.filter((session) => session.hostname !== host);
-  const local = raw.sessions.filter((session) => session.hostname === host);
-  const pruned = await filterStaleSessions(local);
-  const removed = local.filter(
-    (session) => !pruned.some((active) => active.sessionId === session.sessionId)
-  );
-  if (removed.length > 0) {
-    await writeState({ version: "2", sessions: [...remote, ...pruned] });
-  }
-  return { sessions: pruned, removed };
-}
-async function readActiveSessions() {
-  const result = await withFileLock(stateLockPath(), readAndPruneLocked);
-  return result.sessions;
-}
-async function readSessionSnapshot() {
-  return await withFileLock(stateLockPath(), async () => {
-    const raw = await readStateRaw();
-    return raw.sessions;
-  });
-}
-async function readAndPruneActiveSessions() {
-  return await withFileLock(stateLockPath(), readAndPruneLocked);
-}
-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 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) && (key.nodePid === void 0 || sessionTarget.nodePid === 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
-  });
-}
-var DEFAULT_BASE_PORT = 2e4;
-var DEFAULT_MAX_PORT = 20999;
-async function pickPort(preferred, reserved, probe, basePort, maxPort) {
-  const tryOrder = [];
-  if (preferred !== void 0) {
-    tryOrder.push(preferred);
-  }
-  for (let port = basePort; port <= maxPort; port++) {
-    if (port !== preferred) {
-      tryOrder.push(port);
-    }
-  }
-  for (const port of tryOrder) {
-    if (reserved.has(port)) {
-      continue;
-    }
-    const free = await probe(port);
-    if (free) {
-      return port;
-    }
-  }
-  throw new CfDebuggerError(
-    "PORT_UNAVAILABLE",
-    `No free local port available in range ${basePort.toString()}\u2013${maxPort.toString()}`
-  );
-}
-async function registerNewSession(input) {
-  const target = resolveNodeTarget(input);
-  return await withFileLock(stateLockPath(), async () => {
-    const pruneResult = await readAndPruneLocked();
-    const persisted = await readStateRaw();
-    const host = getHostname();
-    const remoteSessions = persisted.sessions.filter((session2) => session2.hostname !== host);
-    const existing = pruneResult.sessions.find((session2) => matchesRegistrationTarget(session2, input, target));
-    if (existing) {
-      return { session: existing, existing };
-    }
-    const reservedPorts = new Set(pruneResult.sessions.map((session2) => session2.localPort));
-    const localPort = await pickPort(
-      input.preferredPort,
-      reservedPorts,
-      input.portProbe,
-      input.basePort ?? DEFAULT_BASE_PORT,
-      input.maxPort ?? DEFAULT_MAX_PORT
-    );
-    const session = createRegisteredSession(input, target, localPort);
-    const nextSessions = [...remoteSessions, ...pruneResult.sessions, session];
-    await writeState({ version: "2", sessions: nextSessions });
-    return { session };
-  });
-}
-function createRegisteredSession(input, target, localPort) {
-  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: process3.pid,
-    controllerPid: process3.pid,
-    hostname: getHostname(),
-    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: 9229,
-    cfHomeDir,
-    startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    status: "starting"
-  };
-}
-async function updateSessionStatus(sessionId, status, message) {
-  return await withFileLock(stateLockPath(), async () => {
-    const raw = await readStateRaw();
-    let updated;
-    const nextSessions = raw.sessions.map((session) => {
-      if (session.sessionId !== sessionId) {
-        return session;
-      }
-      if (status !== "stopping" && startupMutationBlocked(session)) {
-        updated = session;
-        return session;
-      }
-      if (status === "ready" && session.tunnelPid === void 0) {
-        throw new CfDebuggerError(
-          "SESSION_STATE_CONFLICT",
-          "A debugger session cannot become ready before its tunnel PID is recorded."
-        );
-      }
-      const base = withoutMessage(session);
-      const next = message === void 0 ? { ...base, status } : { ...base, status, message };
-      updated = next;
-      return next;
-    });
-    if (updated) {
-      await writeState({ version: "2", sessions: nextSessions });
-    }
-    return updated;
-  });
-}
-async function updateSessionPid(sessionId, pid) {
-  if (!Number.isSafeInteger(pid) || pid <= 0) {
-    throw new CfDebuggerError("UNSAFE_INPUT", "Tunnel PID must be a positive safe integer.");
-  }
-  return await withFileLock(stateLockPath(), async () => {
-    const raw = await readStateRaw();
-    let updated;
-    const nextSessions = raw.sessions.map((session) => {
-      if (session.sessionId !== sessionId) {
-        return session;
-      }
-      if (startupMutationBlocked(session)) {
-        updated = session;
-        return session;
-      }
-      const next = { ...session, pid, tunnelPid: pid };
-      updated = next;
-      return next;
-    });
-    if (updated !== void 0) {
-      await writeState({ version: "2", sessions: nextSessions });
-    }
-    return updated;
-  });
-}
-function withoutMessage(session) {
-  const { message, ...clone } = session;
-  void message;
-  return clone;
-}
-function startupMutationBlocked(session) {
-  return session.status === "stopping" || session.stopRequestedAt !== void 0;
-}
-async function updateSessionRemoteNodePid(sessionId, remoteNodePid) {
-  resolveNodeTarget({ nodePid: remoteNodePid });
-  return await withFileLock(stateLockPath(), async () => {
-    const raw = await readStateRaw();
-    let updated;
-    const nextSessions = raw.sessions.map((session) => {
-      if (session.sessionId !== sessionId) {
-        return session;
-      }
-      if (startupMutationBlocked(session)) {
-        updated = session;
-        return session;
-      }
-      const next = { ...session, remoteNodePid };
-      updated = next;
-      return next;
-    });
-    if (updated !== void 0) {
-      await writeState({ version: "2", sessions: nextSessions });
-    }
-    return updated;
-  });
-}
-async function removeSession(sessionId) {
-  return await withFileLock(stateLockPath(), async () => {
-    const raw = await readStateRaw();
-    const target = raw.sessions.find((session) => session.sessionId === sessionId);
-    if (!target) {
-      return void 0;
-    }
-    const remaining = raw.sessions.filter((session) => session.sessionId !== sessionId);
-    await writeState({ version: "2", sessions: remaining });
-    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" || target.stopRequestedAt !== void 0) {
-      return { session: target, previousStatus: target.status };
-    }
-    const requested = { ...target, stopRequestedAt: (/* @__PURE__ */ new Date()).toISOString() };
-    const sessions = raw.sessions.map(
-      (session) => session.sessionId === sessionId ? requested : session
-    );
-    await writeState({ version: "2", sessions });
-    return { session: requested, previousStatus: target.status };
-  });
-}
-
-// src/debug-session/constants.ts
-var DEFAULT_TUNNEL_READY_TIMEOUT_MS = 18e4;
-var POST_USR1_DELAY_MS = 300;
-var CHILD_SIGTERM_GRACE_MS = 2e3;
-var CHILD_SIGKILL_GRACE_MS = 1e3;
-var PID_TERMINATION_POLL_MS = 100;
-
-// src/debug-session/orphans.ts
-import { rm } from "fs/promises";
-import { hostname as getHostname2 } from "os";
-async function pruneAndCleanupOrphans() {
-  const result = await readAndPruneActiveSessions();
-  const host = getHostname2();
-  for (const removed of result.removed) {
-    if (removed.hostname === host && isOwnedSessionCfHomeDir(removed.sessionId, removed.cfHomeDir)) {
-      try {
-        await rm(removed.cfHomeDir, { recursive: true, force: true });
-      } catch {
-      }
-    }
-  }
-  return result;
-}
-
-// src/debug-session/processes.ts
-import process4 from "process";
-async function terminatePidOrGroup(pid, timeoutMs = CHILD_SIGTERM_GRACE_MS, pinnedTarget) {
-  const targetKind = pinnedTarget ?? (isProcessGroupAlive(pid) ? "group" : "pid");
-  const targetAlive = () => targetKind === "group" ? isProcessGroupAlive(pid) : isPidAlive(pid);
-  if (!targetAlive()) {
-    return "terminated";
-  }
-  try {
-    process4.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);
-    });
-  }
-  try {
-    process4.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, timeoutMs = CHILD_SIGTERM_GRACE_MS) {
-  if (child.pid === void 0) {
-    return "terminated";
-  }
-  const childClosed = child.exitCode !== null || child.signalCode !== null;
-  if (childClosed && process4.platform === "win32") {
-    return "terminated";
-  }
-  return await terminatePidOrGroup(child.pid, timeoutMs, childClosed ? "group" : void 0);
-}
-
-// src/debug-session/startup-cancellation.ts
-var STOP_REQUEST_POLL_MS = 50;
-function cancellationRequested(sessions, sessionId) {
-  const session = sessions.find((candidate) => candidate.sessionId === sessionId);
-  return session === void 0 || session.stopRequestedAt !== void 0;
-}
-function createStartupCancellation(sessionId, callerSignal) {
-  const controller = new AbortController();
-  let active = true;
-  let timer;
-  const onCallerAbort = () => {
-    controller.abort();
-  };
-  const schedule = () => {
-    timer = setTimeout(() => {
-      void poll();
-    }, STOP_REQUEST_POLL_MS);
-    timer.unref();
-  };
-  const poll = async () => {
-    try {
-      const sessions = await readSessionSnapshot();
-      if (active && cancellationRequested(sessions, sessionId)) {
-        controller.abort();
-      }
-    } catch {
-    }
-    if (active && !controller.signal.aborted) {
-      schedule();
-    }
-  };
-  callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
-  if (callerSignal?.aborted === true) {
-    controller.abort();
-  } else {
-    void poll();
-  }
-  return {
-    signal: controller.signal,
-    dispose: () => {
-      active = false;
-      clearTimeout(timer);
-      callerSignal?.removeEventListener("abort", onCallerAbort);
-    }
-  };
-}
-
-// src/debug-session/start.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 checkAbort(signal) {
-  if (signal?.aborted) {
-    throw new CfDebuggerError("ABORTED", "Operation aborted by caller");
-  }
-}
-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.");
+// package.json
+var package_default = {
+  name: "@saptools/cf-debugger",
+  version: "0.2.1",
+  description: "Open an SSH debug tunnel to a SAP BTP Cloud Foundry app's Node.js inspector \u2014 from any terminal, no IDE required.",
+  type: "module",
+  publishConfig: {
+    access: "public",
+    registry: "https://registry.npmjs.org/"
+  },
+  bin: {
+    "cf-debugger": "dist/cli.js"
+  },
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js"
+    }
+  },
+  files: [
+    "dist"
+  ],
+  engines: {
+    node: ">=20.0.0"
+  },
+  scripts: {
+    build: "tsup",
+    typecheck: "tsc --noEmit",
+    lint: "eslint src tests",
+    "test:unit": "vitest run --coverage",
+    "test:e2e": "playwright test"
+  },
+  keywords: [
+    "sap",
+    "cloud-foundry",
+    "btp",
+    "debug",
+    "debugger",
+    "ssh-tunnel",
+    "node-inspector",
+    "cli",
+    "saptools"
+  ],
+  author: "Dong Tran",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/dongitran/saptools.git",
+    directory: "packages/cf-debugger"
+  },
+  homepage: "https://github.com/dongitran/saptools/tree/main/packages/cf-debugger#readme",
+  bugs: {
+    url: "https://github.com/dongitran/saptools/issues"
+  },
+  dependencies: {
+    commander: "^13.0.0"
+  },
+  devDependencies: {
+    "@playwright/test": "^1.50.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    tsup: "^8.3.0",
+    vitest: "^3.0.0"
   }
-  if (expectedStatus !== void 0 && state.status !== expectedStatus) {
-    throw new CfDebuggerError(
-      "SESSION_STATE_CONFLICT",
-      `Debugger session state did not transition to ${expectedStatus}.`
-    );
-  }
-  return state;
-}
-async function transitionStartupStatus(sessionId, status, message) {
-  return requireStartupState(await updateSessionStatus(sessionId, status, message), status);
-}
-function requireCredentials(options) {
-  const email = options.email ?? process5.env["SAP_EMAIL"];
-  const password = options.password ?? process5.env["SAP_PASSWORD"];
-  if (email === void 0 || email === "") {
-    throw new CfDebuggerError(
-      "MISSING_CREDENTIALS",
-      "SAP email is required. Pass `email` or set SAP_EMAIL env var."
-    );
-  }
-  if (password === void 0 || password === "") {
-    throw new CfDebuggerError(
-      "MISSING_CREDENTIALS",
-      "SAP password is required. Pass `password` or set SAP_PASSWORD env var."
-    );
-  }
-  return { email, password };
-}
-async function registerSession(options, target, apiEndpoint) {
-  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,
-    ...options.preferredPort === void 0 ? {} : { preferredPort: options.preferredPort },
-    portProbe: isPortFree,
-    cfHomeForSession: sessionCfHomeDir
-  });
-  if (registration.existing) {
-    throw new CfDebuggerError(
-      "SESSION_ALREADY_RUNNING",
-      `A debugger session is already running for ${sessionKeyString(options)} on port ${registration.existing.localPort.toString()} (pid ${registration.existing.pid.toString()}, sessionId ${registration.existing.sessionId}). Stop it first with \`cf-debugger stop\`.`
-    );
-  }
-  return registration.session;
-}
-async function loginAndTarget(options, apiEndpoint, email, password, context, sessionId, emit) {
-  emit("logging-in");
-  await transitionStartupStatus(sessionId, "logging-in");
-  await cfLogin(apiEndpoint, email, password, context);
-  checkAbort(context.signal);
-  emit("targeting");
-  await transitionStartupStatus(sessionId, "targeting");
-  await cfTarget(options.org, options.space, context);
-  checkAbort(context.signal);
-}
-async function signalRemoteNode(options, target, context, sessionId, emit) {
-  emit("signaling");
-  await transitionStartupStatus(sessionId, "signaling");
-  const signalResult = await executeRemoteSignal(options.app, target, context);
-  if (!isSshDisabledError(signalResult.stderr)) {
-    return parseSignalResult(options.app, signalResult);
-  }
-  if (options.allowSshEnableRestart === false) {
-    throw new CfDebuggerError(
-      "SSH_NOT_ENABLED",
-      `SSH is disabled for ${options.app}; automatic SSH enable and app restart are not allowed.`,
-      signalResult.stderr
-    );
-  }
-  await enableSshAndRestart(options, target, context, sessionId, emit);
-  return await retryRemoteSignal(options, target, context, sessionId, emit);
-}
-async function enableSshAndRestart(options, target, context, sessionId, emit) {
-  if (target.nodePid !== void 0) {
-    throw new CfDebuggerError(
-      "NODE_PID_RESTART_UNSAFE",
-      `Cannot automatically restart ${options.app} while targeting remote Node PID ${target.nodePid.toString()}. Enable SSH and restart the app first, then retry with its new PID.`
-    );
-  }
-  const alreadyEnabled = await cfSshEnabled(options.app, context);
-  if (!alreadyEnabled) {
-    emit("ssh-enabling", "Enabling SSH on the app");
-    await transitionStartupStatus(sessionId, "ssh-enabling");
-    await cfEnableSsh(options.app, context);
-  }
-  emit("ssh-restarting", "Restarting app so SSH becomes active");
-  await transitionStartupStatus(sessionId, "ssh-restarting");
-  await cfRestartApp(options.app, context);
-  checkAbort(context.signal);
-}
-async function retryRemoteSignal(options, target, context, sessionId, emit) {
-  emit("signaling");
-  await transitionStartupStatus(sessionId, "signaling");
-  const retrySignalResult = await executeRemoteSignal(options.app, target, context);
-  if (retrySignalResult.exitCode === 0) {
-    return parseSignalResult(options.app, retrySignalResult);
-  }
-  throw new CfDebuggerError(
-    "USR1_SIGNAL_FAILED",
-    `Failed to send SIGUSR1 to the Node.js process on ${options.app} after enabling SSH: ${signalFailureDetail(retrySignalResult)}`,
-    retrySignalResult.stderr
-  );
-}
-async function executeRemoteSignal(appName, target, context) {
-  return await cfSshOneShot(appName, buildNodeInspectorCommand(target.nodePid), context, {
-    process: target.process,
-    instance: target.instance
-  });
-}
-function parseSignalResult(appName, 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.outputTruncated) {
-    throw new CfDebuggerError(
-      "INSPECTOR_OUTPUT_TOO_LARGE",
-      "Inspector startup output exceeded the configured capture limit."
-    );
-  }
-  return parseNodeInspectorMarkers(result.stdout).remoteNodePid;
-}
-async function waitAfterSignal(signal) {
-  if (signal?.aborted) {
-    throw new CfDebuggerError("ABORTED", "Operation aborted by caller");
-  }
-  await new Promise((resolve, reject) => {
-    const onAbort = () => {
-      clearTimeout(timer);
-      reject(new CfDebuggerError("ABORTED", "Operation aborted by caller"));
-    };
-    const timer = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, POST_USR1_DELAY_MS);
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-async function ensurePortAvailable(localPort) {
-  if (!await isPortFree(localPort)) {
-    throw new CfDebuggerError(
-      "PORT_UNAVAILABLE",
-      `Local port ${localPort.toString()} was taken before the tunnel could start.`
-    );
-  }
-}
-async function openReadyTunnel(options, target, session, context, tunnelReadyTimeoutMs, onChild) {
-  await ensurePortAvailable(session.localPort);
-  checkAbort(context.signal);
-  const child = spawnSshTunnel(options.app, session.localPort, session.remotePort, context, {
-    process: target.process,
-    instance: target.instance
-  });
-  onChild(child);
-  const childPid = child.pid;
-  if (childPid === void 0) {
-    throw new CfDebuggerError("TUNNEL_PROCESS_MISSING", "The CF SSH tunnel process did not expose a PID.");
-  }
-  const pidState = requireStartupState(await updateSessionPid(session.sessionId, childPid));
-  if (pidState.tunnelPid !== childPid || pidState.pid !== childPid) {
-    throw new CfDebuggerError(
-      "SESSION_STATE_CONFLICT",
-      "Debugger session did not retain ownership of the spawned tunnel process."
-    );
-  }
-  const ready = await probeTunnelReady(
-    session.localPort,
-    tunnelReadyTimeoutMs,
-    context.signal
-  );
-  checkAbort(context.signal);
-  if (!ready) {
-    throw new CfDebuggerError(
-      "TUNNEL_NOT_READY",
-      `SSH tunnel on port ${session.localPort.toString()} did not become ready within ${Math.round(tunnelReadyTimeoutMs / 1e3).toString()}s.`
-    );
-  }
-  const listeningPid = await findListeningProcessId(session.localPort);
-  if (listeningPid === void 0) {
-    throw new CfDebuggerError(
-      "TUNNEL_OWNER_UNVERIFIED",
-      `Could not verify the owner of local tunnel port ${session.localPort.toString()}.`
-    );
-  }
-  if (listeningPid !== childPid) {
-    throw new CfDebuggerError(
-      "TUNNEL_OWNER_MISMATCH",
-      `Local tunnel port ${session.localPort.toString()} is owned by an unexpected process.`
-    );
-  }
-}
-function attachTunnelEvents(child, resolveExit, emit) {
-  child.on("close", (code) => {
-    resolveExit(code);
-  });
-  child.on("error", (err) => {
-    emit("error", err.message);
-  });
-}
-function createHandle(session, emit, finalize, exitPromise) {
-  let disposePromise;
-  return {
-    session,
-    dispose: async () => {
-      const attempt = disposePromise ?? (async () => {
-        await runCleanupActions([
-          () => {
-            emit("stopping");
-          },
-          async () => {
-            await updateSessionStatus(session.sessionId, "stopping");
-          },
-          finalize
-        ], "Debugger disposal failed");
-      })();
-      disposePromise = attempt;
-      try {
-        await attempt;
-      } catch (error) {
-        if (disposePromise === attempt) {
-          disposePromise = void 0;
-        }
-        throw error;
-      }
-    },
-    waitForExit: async () => {
-      return await exitPromise;
-    }
-  };
-}
-async function runCleanupActions(actions, aggregateMessage) {
-  let errors = [];
-  for (const action of actions) {
-    try {
-      await action();
-    } catch (error) {
-      errors = [...errors, error];
-    }
-  }
-  if (errors.length === 1) {
-    throw errors[0];
-  }
-  if (errors.length > 1) {
-    throw new AggregateError(errors, aggregateMessage);
-  }
-}
-async function prepareCfHome(cfHomeDir) {
-  await mkdir3(cfHomeDir, { recursive: true, mode: 448 });
-  await chmod3(cfHomeDir, 448);
-}
-function createTunnelLifecycle(session, emit) {
-  let child;
-  let exitResolve = (_code) => {
-    throw new Error("Exit resolver was used before initialization");
-  };
-  const exitPromise = new Promise((resolve) => {
-    exitResolve = resolve;
-  });
-  const observeChild = (tunnelChild) => {
-    child = tunnelChild;
-    attachTunnelEvents(tunnelChild, exitResolve, emit);
-  };
-  const finalize = async () => {
-    const termination = child === void 0 ? "terminated" : await killProcessGroupOrProc(child);
-    const portListening = child !== void 0 && await isPortListening(session.localPort);
-    if (termination === "still-alive" || portListening) {
-      throw new CfDebuggerError(
-        "TUNNEL_TERMINATION_FAILED",
-        `Tunnel for session ${session.sessionId} did not terminate; state and CF home were retained.`
-      );
-    }
-    await runCleanupActions([
-      async () => {
-        await removeSession(session.sessionId);
-      },
-      async () => {
-        await cleanupFilesystem(session.cfHomeDir);
-      }
-    ], "Debugger resource cleanup failed");
-    emit("stopped");
-  };
-  return { exitPromise, finalize, observeChild };
-}
-async function establishDebuggerSession(inputs) {
-  const { options, target, session, context, credentials, timeoutMs, lifecycle, emit } = inputs;
-  await prepareCfHome(session.cfHomeDir);
-  await loginAndTarget(
-    options,
-    session.apiEndpoint,
-    credentials.email,
-    credentials.password,
-    context,
-    session.sessionId,
-    emit
-  );
-  await ensurePortAvailable(session.localPort);
-  const remoteNodePid = await signalRemoteNode(options, target, context, session.sessionId, emit);
-  const remoteState = requireStartupState(
-    await updateSessionRemoteNodePid(session.sessionId, remoteNodePid)
-  );
-  if (remoteState.remoteNodePid !== remoteNodePid) {
-    throw new CfDebuggerError(
-      "SESSION_STATE_CONFLICT",
-      "Debugger session did not retain the selected remote Node PID."
-    );
-  }
-  await waitAfterSignal(context.signal);
-  emit("tunneling");
-  await transitionStartupStatus(session.sessionId, "tunneling");
-  await openReadyTunnel(
-    options,
-    target,
-    session,
-    context,
-    timeoutMs,
-    lifecycle.observeChild
-  );
-  emit("ready");
-  return await transitionStartupStatus(session.sessionId, "ready");
-}
-async function failAfterStartupCleanup(error, finalize, emit) {
-  try {
-    await runCleanupActions([
-      () => {
-        emit("error", error instanceof Error ? error.message : String(error));
-      },
-      finalize
-    ], "Debugger startup failure reporting and cleanup failed");
-  } catch (cleanupError) {
-    throw new AggregateError(
-      [error, cleanupError],
-      "Debugger startup failed and resource cleanup was incomplete",
-      { cause: cleanupError }
-    );
-  }
-  throw error;
-}
-async function startDebugger(options) {
-  const target = resolveNodeTarget(options);
-  const credentials = requireCredentials(options);
-  const apiEndpoint = resolveApiEndpoint(options.region, options.apiEndpoint);
-  const tunnelReadyTimeoutMs = options.tunnelReadyTimeoutMs ?? DEFAULT_TUNNEL_READY_TIMEOUT_MS;
-  const emit = (status, message) => {
-    options.onStatus?.(status, message);
-  };
-  checkAbort(options.signal);
-  await pruneAndCleanupOrphans();
-  const session = await registerSession(options, target, apiEndpoint);
-  const cancellation = createStartupCancellation(session.sessionId, options.signal);
-  const context = {
-    cfHome: session.cfHomeDir,
-    signal: cancellation.signal
-  };
-  const lifecycle = createTunnelLifecycle(session, emit);
-  try {
-    const activeSession = await establishDebuggerSession({
-      options,
-      target,
-      session,
-      context,
-      credentials,
-      timeoutMs: tunnelReadyTimeoutMs,
-      lifecycle,
-      emit
-    });
-    cancellation.dispose();
-    return createHandle(activeSession, emit, lifecycle.finalize, lifecycle.exitPromise);
-  } catch (err) {
-    cancellation.dispose();
-    return await failAfterStartupCleanup(err, lifecycle.finalize, emit);
-  }
-}
-async function cleanupFilesystem(cfHomeDir) {
-  await rm2(cfHomeDir, { recursive: true, force: true });
-}
-
-// src/debug-session/sessions.ts
-import { rm as rm3 } from "fs/promises";
-import { hostname as getHostname3 } from "os";
-import process6 from "process";
-function findMatchingSession(sessions, options) {
-  if (options.sessionId !== void 0) {
-    return sessions.find((s) => s.sessionId === options.sessionId);
-  }
-  if (options.key !== 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 an exact session ID, API endpoint, or Node PID."
-      );
-    }
-    return matches[0];
-  }
-  return void 0;
-}
-async function ownsRecordedTunnel(target) {
-  if (target.tunnelPid === void 0 || !await isPortListening(target.localPort)) {
-    return false;
-  }
-  return await findListeningProcessId(target.localPort) === target.tunnelPid;
-}
-async function terminateVerifiedTunnel(target) {
-  if (target.tunnelPid !== void 0 && target.tunnelPid !== process6.pid) {
-    try {
-      return await terminatePidOrGroup(target.tunnelPid);
-    } catch {
-      return "still-alive";
-    }
-  }
-  return target.tunnelPid === process6.pid ? "still-alive" : "terminated";
-}
-async function terminateVerifiedTunnelAndConfirm(target) {
-  const termination = await terminateVerifiedTunnel(target);
-  if (termination === "still-alive" || await ownsRecordedTunnel(target)) {
-    throw new CfDebuggerError(
-      "TUNNEL_TERMINATION_FAILED",
-      `Tunnel process for session ${target.sessionId} did not terminate; state was retained.`
-    );
-  }
-}
-async function cleanupOwnedCfHome(target, locallyOwned) {
-  if (locallyOwned && isOwnedSessionCfHomeDir(target.sessionId, target.cfHomeDir)) {
-    try {
-      await rm3(target.cfHomeDir, { recursive: true, force: true });
-    } catch {
-    }
-  }
-}
-async function removeOwnedSession(target, stale) {
-  const removed = await removeSession(target.sessionId);
-  await cleanupOwnedCfHome(target, true);
-  return { ...removed ?? target, stale, pending: false };
-}
-function ownershipError(target) {
-  return new CfDebuggerError(
-    "TUNNEL_OWNERSHIP_UNVERIFIED",
-    `Cannot safely stop session ${target.sessionId}: local tunnel ownership could not be verified.`
-  );
-}
-async function stopReadySession(target) {
-  if (await ownsRecordedTunnel(target)) {
-    await terminateVerifiedTunnelAndConfirm(target);
-    return await removeOwnedSession(target, false);
-  }
-  const tunnelDead = target.tunnelPid !== void 0 && !isPidOrGroupAlive(target.tunnelPid);
-  if (tunnelDead && !await isPortListening(target.localPort)) {
-    return await removeOwnedSession(target, true);
-  }
-  throw ownershipError(target);
-}
-async function stopStartingSession(target) {
-  if (target.status === "stopping" && target.tunnelPid !== void 0 && !isPidOrGroupAlive(target.tunnelPid) && !await isPortListening(target.localPort)) {
-    return await removeOwnedSession(target, true);
-  }
-  if (isPidAlive(target.controllerPid ?? target.pid)) {
-    return { ...target, stale: false, pending: true };
-  }
-  if (await ownsRecordedTunnel(target)) {
-    await terminateVerifiedTunnelAndConfirm(target);
-    return await removeOwnedSession(target, false);
-  }
-  const tunnelAlive = target.tunnelPid !== void 0 && isPidOrGroupAlive(target.tunnelPid);
-  if (!tunnelAlive && !await isPortListening(target.localPort)) {
-    return await removeOwnedSession(target, true);
-  }
-  throw ownershipError(target);
-}
-async function stopDebugger(options) {
-  const localSessions = (await readSessionSnapshot()).filter(
-    (session) => session.hostname === getHostname3()
-  );
-  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) : await stopStartingSession(claim.session);
-}
-async function stopAllDebuggers() {
-  const sessions = (await readSessionSnapshot()).filter(
-    (session) => session.hostname === getHostname3()
-  );
-  let stopped = 0;
-  for (const session of sessions) {
-    const result = await stopDebugger({ sessionId: session.sessionId });
-    if (result) {
-      stopped += 1;
-    }
-  }
-  return stopped;
-}
-async function listSessions() {
-  return await readActiveSessions();
-}
-async function getSession(key) {
-  const sessions = await readActiveSessions();
-  return findMatchingSession(sessions, { key });
-}
+};
 
 // src/cli.ts
 function readRequiredOption(value, flag) {
-  if (value === void 0 || value === "") {
-    process7.stderr.write(`Missing required option ${flag}
-`);
-    process7.exit(1);
+  if (value === void 0 || value.trim().length === 0) {
+    throw new CfDebuggerError("UNSAFE_INPUT", `Missing required option ${flag}.`);
   }
   return value;
 }
-function parseOptionalPort(raw) {
-  if (raw === void 0) {
-    return void 0;
-  }
-  const port = Number.parseInt(raw, 10);
-  if (Number.isNaN(port) || port <= 0 || port > 65535) {
-    process7.stderr.write(`Invalid port: ${raw}
-`);
-    process7.exit(1);
-  }
-  return port;
-}
-function parseOptionalTimeout(raw) {
-  if (raw === void 0) {
-    return void 0;
-  }
-  const seconds = Number.parseInt(raw, 10);
-  if (Number.isNaN(seconds) || seconds <= 0) {
-    process7.stderr.write(`Invalid timeout: ${raw}
-`);
-    process7.exit(1);
-  }
-  return seconds * 1e3;
-}
-function parseOptionalInteger(raw, label, minimum) {
+function parseOptionalInteger(raw, label, minimum, maximum = Number.MAX_SAFE_INTEGER) {
   if (raw === void 0) {
     return void 0;
   }
@@ -2414,59 +107,84 @@ function parseOptionalInteger(raw, label, minimum) {
     throw new CfDebuggerError("UNSAFE_INPUT", `${label} must be an integer.`);
   }
   const value = Number(raw);
-  if (!Number.isSafeInteger(value) || value < minimum) {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
     throw new CfDebuggerError(
       "UNSAFE_INPUT",
-      `${label} must be at least ${minimum.toString()} and within the safe integer range.`
+      `${label} must be from ${minimum.toString()} to ${maximum.toString()}.`
     );
   }
   return value;
 }
+function parseSeconds(raw, label) {
+  const seconds = parseOptionalInteger(raw, label, 1);
+  return seconds === void 0 ? void 0 : seconds * 1e3;
+}
+var STOP_SCOPE_OPTION_NAMES = [
+  "apiEndpoint",
+  "app",
+  "instance",
+  "nodePid",
+  "org",
+  "process",
+  "region",
+  "sessionId",
+  "space"
+];
 function logStatus(verbose, status, message) {
-  if (verbose) {
-    const suffix = message === void 0 ? "" : `: ${message}`;
-    process7.stdout.write(`[cf-debugger] ${status}${suffix}
-`);
+  if (!verbose) {
+    return;
   }
+  const suffix = message === void 0 ? "" : `: ${message}`;
+  nodeProcess.stdout.write(`[cf-debugger] ${status}${suffix}
+`);
 }
-function mergeSelector(selector, opts) {
+function mergeSelector(selector, options) {
   if (selector === void 0) {
-    return opts;
+    return options;
   }
   const parts = selector.split("/");
-  if (parts.length === 4) {
-    return { ...opts, region: opts.region ?? parts[0], org: opts.org ?? parts[1], space: opts.space ?? parts[2], app: opts.app ?? parts[3] };
+  if (parts.length === 1 && parts[0]?.length !== 0) {
+    return { ...options, app: options.app ?? parts[0] };
   }
-  if (parts.length === 1) {
-    return { ...opts, app: opts.app ?? parts[0] };
+  if (parts.length === 4 && parts.every((part) => part.length > 0)) {
+    return {
+      ...options,
+      region: options.region ?? parts[0],
+      org: options.org ?? parts[1],
+      space: options.space ?? parts[2],
+      app: options.app ?? parts[3]
+    };
   }
-  throw new CfDebuggerError("UNSAFE_INPUT", "Invalid app selector format. Expected <app> or <region>/<org>/<space>/<app>.");
+  throw new CfDebuggerError(
+    "UNSAFE_INPUT",
+    "Invalid app selector. Expected <app> or non-empty <region>/<org>/<space>/<app> segments."
+  );
 }
 function startupAbort(app) {
   const controller = new AbortController();
+  let requestedExitCode;
   const handler = (exitCode) => () => {
+    requestedExitCode ??= exitCode;
     controller.abort();
-    process7.stderr.write(`
+    nodeProcess.stderr.write(`
 Aborting startup for ${app}...
 `);
-    setTimeout(() => {
-      process7.exit(exitCode);
-    }, 5e3).unref();
   };
   const onSigint = handler(130);
   const onSigterm = handler(143);
-  process7.on("SIGINT", onSigint);
-  process7.on("SIGTERM", onSigterm);
+  nodeProcess.on("SIGINT", onSigint);
+  nodeProcess.on("SIGTERM", onSigterm);
   return {
     signal: controller.signal,
+    requestedExitCode: () => requestedExitCode,
     dispose: () => {
-      process7.off("SIGINT", onSigint);
-      process7.off("SIGTERM", onSigterm);
+      nodeProcess.off("SIGINT", onSigint);
+      nodeProcess.off("SIGTERM", onSigterm);
     }
   };
 }
 function writeReady(app, key, handle) {
-  process7.stdout.write(
+  nodeProcess.stdout.write(
     `Debugger ready for ${app} (${key.region}/${key.org}/${key.space}).
   Process:     ${key.process}
   Instance:    ${key.instance.toString()}
@@ -2479,91 +197,160 @@ Press Ctrl+C to stop.
 `
   );
 }
-function handleDisposer(app, handle) {
-  let pending;
-  return async () => {
-    pending ??= (async () => {
-      process7.stdout.write(`
-Stopping debugger for ${app}...
+function writeCleanupError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  nodeProcess.stderr.write(`Error during stop: ${message}
 `);
-      try {
-        await handle.dispose();
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        process7.stderr.write(`Error during stop: ${message}
+}
+async function waitForHandle(app, handle) {
+  let pendingDispose;
+  let requestedExitCode;
+  const dispose = () => {
+    pendingDispose ??= (async () => {
+      nodeProcess.stdout.write(`
+Stopping debugger for ${app}...
 `);
-      }
+      await handle.dispose();
     })();
-    await pending;
+    return pendingDispose;
   };
-}
-async function waitForHandle(app, handle) {
-  const dispose = handleDisposer(app, handle);
   const stop = (exitCode) => () => {
-    void dispose().then(() => {
-      process7.exit(exitCode);
+    requestedExitCode = exitCode;
+    void dispose().catch((error) => {
+      writeCleanupError(error);
+      nodeProcess.exit(CLEANUP_FAILURE_EXIT_CODE);
     });
   };
-  process7.on("SIGINT", stop(130));
-  process7.on("SIGTERM", stop(143));
+  nodeProcess.on("SIGINT", stop(130));
+  nodeProcess.on("SIGTERM", stop(143));
   const code = await handle.waitForExit();
-  await dispose();
-  process7.exit(code ?? 0);
+  const tunnelError = getDebuggerHandleTunnelError(handle);
+  if (tunnelError !== void 0) {
+    nodeProcess.stderr.write(
+      `Error [${tunnelError.code}]: ${tunnelError.message}
+`
+    );
+    if (tunnelError.stderr !== void 0 && tunnelError.stderr.trim().length > 0) {
+      nodeProcess.stderr.write(`[cf-debugger transport]
+${tunnelError.stderr.trim()}
+`);
+    }
+  }
+  try {
+    await dispose();
+  } catch (error) {
+    writeCleanupError(error);
+    nodeProcess.exit(CLEANUP_FAILURE_EXIT_CODE);
+  }
+  nodeProcess.exit(requestedExitCode ?? code ?? 0);
+}
+function parseRestartEnvironment() {
+  const value = nodeProcess.env["CF_DEBUGGER_ALLOW_RESTART"];
+  if (value === void 0) {
+    return "unset";
+  }
+  if (value === "0") {
+    return "forbid";
+  }
+  if (value === "1") {
+    return "allow";
+  }
+  throw new CfDebuggerError(
+    "UNSAFE_INPUT",
+    "CF_DEBUGGER_ALLOW_RESTART must be 0 or 1."
+  );
+}
+function buildStartOptions(options, key, app, signal, startupTimeoutMs) {
+  const preferredPort = parseOptionalInteger(options.port, "port", 1, 65535);
+  const remotePort = parseOptionalInteger(options.remotePort, "remotePort", 1, 65535);
+  const nodePid = parseOptionalInteger(options.nodePid, "nodePid", 1);
+  const tunnelReadyTimeoutMs = parseSeconds(options.timeout, "timeout");
+  const restartEnvironment = parseRestartEnvironment();
+  const allowSshEnableRestart = options.sshEnableRestart !== false && restartEnvironment !== "forbid" && (options.allowSshEnableRestart === true || restartEnvironment === "allow");
+  return {
+    region: key.region,
+    org: key.org,
+    space: key.space,
+    app,
+    process: key.process,
+    instance: key.instance,
+    signal,
+    allowSshEnableRestart,
+    ...options.apiEndpoint === void 0 ? {} : { apiEndpoint: options.apiEndpoint },
+    ...preferredPort === void 0 ? {} : { preferredPort },
+    ...remotePort === void 0 ? {} : { remotePort },
+    ...nodePid === void 0 ? {} : { nodePid },
+    ...tunnelReadyTimeoutMs === void 0 ? {} : { tunnelReadyTimeoutMs },
+    startupTimeoutMs
+  };
 }
-async function handleStart(selector, rawOpts) {
-  const opts = mergeSelector(selector, rawOpts);
-  const app = readRequiredOption(opts.app, "--app or selector");
-  const key = await resolveSessionKey({ ...opts, app });
-  const verbose = opts.verbose ?? false;
-  const preferredPort = parseOptionalPort(opts.port);
-  const tunnelReadyTimeoutMs = parseOptionalTimeout(opts.timeout);
-  const nodePid = parseOptionalInteger(opts.nodePid, "nodePid", 1);
+function deadlineTimedOut(deadline) {
+  return remainingStartupMs(deadline.expiresAt) === 0 || deadline.signal.reason instanceof CfDebuggerError && deadline.signal.reason.code === "STARTUP_TIMEOUT";
+}
+async function handleStart(selector, rawOptions) {
+  const options = mergeSelector(selector, rawOptions);
+  const app = readRequiredOption(options.app, "--app or selector");
+  const verbose = options.verbose ?? false;
+  const startupTimeoutMs = resolveStartupTimeoutMs(
+    parseSeconds(options.startupTimeout, "startupTimeout")
+  );
   const abort = startupAbort(app);
+  const deadline = createStartupDeadline(startupTimeoutMs, abort.signal);
   let handle;
+  let phase = "current CF target discovery";
+  let key;
   try {
-    handle = await startDebugger({
-      region: key.region,
-      org: key.org,
-      space: key.space,
-      app,
-      process: key.process,
-      instance: key.instance,
+    key = await resolveSessionKey({ ...options, app }, deadline.signal);
+    if (deadlineTimedOut(deadline)) {
+      throw startupTimeoutError(startupTimeoutMs, phase);
+    }
+    phase = "startup";
+    handle = await startDebuggerWithinDeadline({
+      ...buildStartOptions(options, key, app, deadline.signal, startupTimeoutMs),
       verbose,
-      signal: abort.signal,
-      ...preferredPort === void 0 ? {} : { preferredPort },
-      ...tunnelReadyTimeoutMs === void 0 ? {} : { tunnelReadyTimeoutMs },
-      ...nodePid === void 0 ? {} : { nodePid },
       onStatus: (status, message) => {
         logStatus(verbose, status, message);
       }
-    });
+    }, deadline);
+  } catch (error) {
+    const normalized = deadlineTimedOut(deadline) && !(error instanceof CfDebuggerError && error.code === "STARTUP_TIMEOUT") ? startupTimeoutError(startupTimeoutMs, phase) : error;
+    const exitCode = abort.requestedExitCode();
+    if (exitCode !== void 0 && typeof normalized === "object" && normalized !== null) {
+      Reflect.set(normalized, "cliExitCode", exitCode);
+    }
+    throw normalized;
   } finally {
+    deadline.dispose();
     abort.dispose();
   }
   writeReady(app, key, handle);
   await waitForHandle(app, handle);
 }
-function hasText(value) {
-  return optionalText(value) !== void 0;
-}
 function optionalText(value) {
   const trimmed = value?.trim();
   return trimmed === void 0 || trimmed.length === 0 ? void 0 : trimmed;
 }
-function currentCfOptions() {
-  const command = process7.env["CF_DEBUGGER_CF_BIN"];
-  return command === void 0 ? void 0 : { command };
+function currentCfOptions(signal) {
+  const command = nodeProcess.env["CF_DEBUGGER_CF_BIN"];
+  if (command === void 0 && signal === void 0) {
+    return void 0;
+  }
+  return {
+    ...command === void 0 ? {} : { command },
+    ...signal === void 0 ? {} : { signal }
+  };
 }
-async function resolveSessionKey(opts) {
-  const app = readRequiredOption(opts.app, "--app or selector");
-  const region = optionalText(opts.region);
-  const org = optionalText(opts.org);
-  const space = optionalText(opts.space);
-  const processName = opts.process;
-  const instance = parseOptionalInteger(opts.instance, "instance", 0);
+async function resolveSessionKey(options, signal) {
+  const app = readRequiredOption(options.app, "--app or selector");
+  const region = optionalText(options.region);
+  const org = optionalText(options.org);
+  const space = optionalText(options.space);
+  const nodePid = parseOptionalInteger(options.nodePid, "nodePid", 1);
+  const instance = parseOptionalInteger(options.instance, "instance", 0);
   const target = resolveNodeTarget({
-    ...processName === void 0 ? {} : { process: processName },
-    ...instance === void 0 ? {} : { instance }
+    ...options.process === void 0 ? {} : { process: options.process },
+    ...instance === void 0 ? {} : { instance },
+    ...nodePid === void 0 ? {} : { nodePid }
   });
   if (region !== void 0 && org !== void 0 && space !== void 0) {
     return {
@@ -2572,20 +359,25 @@ async function resolveSessionKey(opts) {
       space,
       app,
       process: target.process,
-      instance: target.instance
+      instance: target.instance,
+      ...options.apiEndpoint === void 0 ? {} : { apiEndpoint: options.apiEndpoint },
+      ...target.nodePid === void 0 ? {} : { nodePid: target.nodePid }
     };
   }
-  const current = await readCurrentCfTarget(currentCfOptions()).catch((error) => {
+  const current = await readCurrentCfTarget(currentCfOptions(signal)).catch((error) => {
+    if (error instanceof CfDebuggerError && (error.code === "ABORTED" || error.code === "STARTUP_TIMEOUT")) {
+      throw error;
+    }
     throw new CfDebuggerError(
       "CF_TARGET_FAILED",
-      "No current CF target found. Run `cf target -o <org> -s <space>` or pass --region/--org/--space.",
+      "No current CF target. Run `cf target -o <org> -s <space>` or pass --region/--org/--space.",
       error instanceof Error ? error.message : String(error)
     );
   });
   if (current === void 0) {
     throw new CfDebuggerError(
       "CF_TARGET_FAILED",
-      "No current CF target found. Run `cf target -o <org> -s <space>` or pass --region/--org/--space."
+      "No current CF target. Run `cf target -o <org> -s <space>` or pass --region/--org/--space."
     );
   }
   return {
@@ -2594,109 +386,189 @@ async function resolveSessionKey(opts) {
     space: space ?? current.space,
     app,
     process: target.process,
-    instance: target.instance
+    instance: target.instance,
+    ...options.apiEndpoint === void 0 ? {} : { apiEndpoint: options.apiEndpoint },
+    ...target.nodePid === void 0 ? {} : { nodePid: target.nodePid }
   };
 }
-async function resolveOptionalSessionKey(opts) {
-  if (!hasText(opts.app)) {
-    if (hasText(opts.region) || hasText(opts.org) || hasText(opts.space)) {
-      readRequiredOption(opts.app, "--app");
+async function resolveOptionalSessionKey(options) {
+  if (optionalText(options.app) === void 0) {
+    if (optionalText(options.region) !== void 0 || optionalText(options.org) !== void 0 || optionalText(options.space) !== void 0) {
+      readRequiredOption(options.app, "--app");
     }
     return void 0;
   }
-  return await resolveSessionKey(opts);
+  return await resolveSessionKey(options);
 }
-async function handleStop(selector, rawOpts) {
-  const opts = mergeSelector(selector, rawOpts);
-  if (opts.all === true) {
-    const count = await stopAllDebuggers();
-    process7.stdout.write(`Stop requested for ${count.toString()} session(s).
-`);
+function writeStopResult(result) {
+  if (result === void 0) {
     return;
   }
-  const key = await resolveOptionalSessionKey(opts);
-  const result = await stopDebugger({
-    ...opts.sessionId === void 0 ? {} : { sessionId: opts.sessionId },
-    ...key === void 0 ? {} : { key }
-  });
-  if (result === void 0) {
-    process7.stderr.write(
-      "No matching session found. Use `cf-debugger list` and pass --session-id or region/org/space/app if the current CF target differs.\n"
-    );
-    process7.exit(1);
+  if (result.warning !== void 0) {
+    nodeProcess.stderr.write(`[cf-debugger] warning: ${result.warning}
+`);
   }
   if (result.pending) {
-    process7.stdout.write(
-      `Stop requested for session ${result.sessionId} (${result.app}, startup phase ${result.status}).
+    nodeProcess.stdout.write(
+      `Stop requested for session ${result.sessionId} (${result.app}, phase ${result.status}).
 `
     );
-    return;
+  } else if (result.stale) {
+    nodeProcess.stdout.write(
+      `Removed ${result.forced ? "forced " : ""}stale session ${result.sessionId} (${result.app}, port ${result.localPort.toString()}).
+`
+    );
+  } else {
+    nodeProcess.stdout.write(
+      `Stopped session ${result.sessionId} (${result.app}, port ${result.localPort.toString()}).
+`
+    );
+  }
+}
+async function handleStop(selector, rawOptions, command) {
+  if (rawOptions.all === true && (selector !== void 0 || STOP_SCOPE_OPTION_NAMES.some((name) => command.getOptionValueSource(name) === "cli"))) {
+    throw new CfDebuggerError(
+      "UNSAFE_INPUT",
+      "--all cannot be combined with a selector, --session-id, or target selector options."
+    );
   }
-  if (result.stale) {
-    process7.stdout.write(
-      `Removed stale session ${result.sessionId} (${result.app}, port ${result.localPort.toString()}).
+  const options = mergeSelector(selector, rawOptions);
+  if (options.all === true) {
+    const summary = await stopAllDebuggers(options.force === true);
+    for (const outcome of summary.outcomes) {
+      if (outcome.error === void 0) {
+        writeStopResult(outcome.result);
+      } else {
+        nodeProcess.stderr.write(
+          `Failed ${outcome.sessionId} (${outcome.app}): ${outcome.error.message}
+`
+        );
+      }
+    }
+    nodeProcess.stdout.write(
+      `Stop summary: ${summary.stopped.toString()} stopped, ${summary.stale.toString()} stale, ${summary.pending.toString()} pending, ${summary.failed.toString()} failed.
 `
     );
+    if (summary.failed > 0) {
+      nodeProcess.exitCode = 1;
+    }
     return;
   }
-  process7.stdout.write(
-    `Stopped session ${result.sessionId} (${result.app}, port ${result.localPort.toString()}).
-`
-  );
+  const key = await resolveOptionalSessionKey(options);
+  const result = await stopDebugger({
+    ...options.sessionId === void 0 ? {} : { sessionId: options.sessionId },
+    ...key === void 0 ? {} : { key },
+    force: options.force === true
+  });
+  if (result === void 0) {
+    throw new CfDebuggerError(
+      "SESSION_NOT_FOUND",
+      "No matching session. Use `cf-debugger list` and pass --session-id or an exact key."
+    );
+  }
+  writeStopResult(result);
 }
 async function handleList() {
-  const sessions = await listSessions();
-  process7.stdout.write(`${JSON.stringify(sessions, null, 2)}
+  nodeProcess.stdout.write(`${JSON.stringify(await listSessions(), null, 2)}
+`);
+}
+async function handleStatus(selector, rawOptions) {
+  const options = mergeSelector(selector, rawOptions);
+  const session = options.sessionId === void 0 ? await getSession(await resolveSessionKey(options)) : (await listSessions()).find((candidate) => candidate.sessionId === options.sessionId);
+  nodeProcess.stdout.write(`${JSON.stringify(session ?? null, null, 2)}
 `);
 }
-async function handleStatus(selector, rawOpts) {
-  const opts = mergeSelector(selector, rawOpts);
-  const session = await getSession(await resolveSessionKey(opts));
-  process7.stdout.write(`${JSON.stringify(session ?? null, null, 2)}
+async function handleDoctor(cleanup) {
+  const report = await runDoctor({ cleanup });
+  nodeProcess.stdout.write(`${JSON.stringify(report, null, 2)}
 `);
 }
 function registerStartCommand(program) {
-  program.command("start").description("Open a debug tunnel for one app").argument("[selector]", "Optional app selector: `<app>` or `region/org/space/app`").option("--region <key>", "CF region key (default: current cf target)").option("--org <name>", "CF org name (default: current cf target)").option("--space <name>", "CF space name (default: current cf target)").option("--app <name>", "CF app name").option("--process <name>", "CF process name", "web").option("-i, --instance <index>", "CF process instance index", "0").option("--node-pid <pid>", "Explicit remote Node.js PID").option("--port <number>", "Preferred local port (auto-assigned if omitted)").option("--timeout <seconds>", "Tunnel-ready timeout in seconds (default: 180)").option("--verbose", "Print status transitions", false).action(async (selector, opts) => {
-    await handleStart(selector, opts);
-  });
+  program.command("start").description("Open a debug tunnel for one app").argument("[selector]", "Optional <app> or <region>/<org>/<space>/<app>").option("--region <key>", "CF region key (default: current cf target)").option("--api-endpoint <url>", "Explicit CF API endpoint override").option("--org <name>", "CF org (default: current cf target)").option("--space <name>", "CF space (default: current cf target)").option("--app <name>", "CF app name").option("--process <name>", "CF process name", "web").option("-i, --instance <index>", "CF process instance", "0").option("--node-pid <pid>", "Explicit remote Node.js PID").option("--port <number>", "Preferred local port").option(
+    "--remote-port <number>",
+    "Remote inspector port",
+    DEFAULT_NODE_INSPECTOR_PORT.toString()
+  ).option("--timeout <seconds>", "Tunnel/inspector readiness timeout", "180").option("--startup-timeout <seconds>", "Overall startup deadline", "300").option(
+    "--allow-ssh-enable-restart",
+    "Allow app-level SSH enablement and an app restart (opt-in)"
+  ).option(
+    "--no-ssh-enable-restart",
+    "Forbid app-level SSH enablement and restart, overriding flag/environment"
+  ).option("--verbose", "Print status transitions and tunnel diagnostics", false).action(async (selector, options) => {
+    await handleStart(selector, options);
+  });
+}
+function addKeyOptions(command) {
+  return command.option("--region <key>").option("--api-endpoint <url>", "Exact API endpoint selector").option("--org <name>").option("--space <name>").option("--app <name>").option("--process <name>", "CF process name", "web").option("-i, --instance <index>", "CF process instance", "0").option("--node-pid <pid>", "Exact remote Node PID selector");
 }
 function registerStopCommand(program) {
-  program.command("stop").description("Stop one session (by key or id) or all sessions with --all").argument("[selector]", "Optional app selector: `<app>` or `region/org/space/app`").option("--region <key>").option("--org <name>").option("--space <name>").option("--app <name>").option("--process <name>", "CF process name", "web").option("-i, --instance <index>", "CF process instance index", "0").option("--session-id <id>").option("--all", "Stop every active session", false).action(async (selector, opts) => {
-    await handleStop(selector, opts);
-  });
+  addKeyOptions(
+    program.command("stop").description("Stop one session by exact key/id, or every session with --all").argument("[selector]", "Optional <app> or <region>/<org>/<space>/<app>")
+  ).option("--session-id <id>").option(
+    "--all",
+    "Attempt every active session; cannot be combined with session selectors",
+    false
+  ).option(
+    "--force",
+    "Forget unverifiable state and its owned CF home; never signal an unverified process",
+    false
+  ).action(
+    async (selector, options, command) => {
+      await handleStop(selector, options, command);
+    }
+  );
 }
 function registerReadCommands(program) {
   program.command("list").description("Print every active debugger session as JSON").action(async () => {
     await handleList();
   });
-  program.command("status").description("Print one session by key as JSON (null if not active)").argument("[selector]", "Optional app selector: `<app>` or `region/org/space/app`").option("--region <key>").option("--org <name>").option("--space <name>").option("--app <name>").option("--process <name>", "CF process name", "web").option("-i, --instance <index>", "CF process instance index", "0").action(async (selector, opts) => {
-    await handleStatus(selector, opts);
+  addKeyOptions(
+    program.command("status").description("Print one exact session as JSON; null only when no session matches").argument("[selector]", "Optional <app> or <region>/<org>/<space>/<app>")
+  ).option("--session-id <id>", "Exact session ID selector").action(async (selector, options) => {
+    await handleStatus(selector, options);
+  });
+  program.command("doctor").description("Report session health, orphan homes/ports, temp files, and legacy credentials").option("--cleanup", "Remove only safe orphan v2 homes and stale v2 temp/lock files", false).action(async (options) => {
+    await handleDoctor(options.cleanup === true);
   });
 }
 async function main(argv) {
-  const program = new Command().name("cf-debugger").description("Open an SSH debug tunnel to a SAP BTP Cloud Foundry app's Node.js inspector");
+  const program = new Command().name("cf-debugger").description("Open an SSH debug tunnel to a SAP BTP Cloud Foundry Node.js inspector").version(package_default.version);
   registerStartCommand(program);
   registerStopCommand(program);
   registerReadCommands(program);
   await program.parseAsync([...argv]);
 }
-try {
-  await main(process7.argv);
-} catch (err) {
-  if (err instanceof CfDebuggerError) {
-    if (err.code === "ABORTED") {
-      process7.stderr.write(`Aborted: ${err.message}
+function writeTopLevelError(error) {
+  if (error instanceof CfDebuggerError) {
+    if (error.code === "ABORTED") {
+      nodeProcess.stderr.write(`Aborted: ${error.message}
 `);
-      process7.exit(130);
+      nodeProcess.exit(cliErrorExitCode(error));
     }
-    process7.stderr.write(`Error [${err.code}]: ${err.message}
+    nodeProcess.stderr.write(`Error [${error.code}]: ${error.message}
 `);
-  } else {
-    const msg = err instanceof Error ? err.message : String(err);
-    process7.stderr.write(`Error: ${msg}
+    if (error.stderr !== void 0 && error.stderr.trim().length > 0) {
+      nodeProcess.stderr.write(`[cf-debugger transport]
+${error.stderr.trim()}
+`);
+    }
+    nodeProcess.exit(cliErrorExitCode(error));
+  }
+  if (hasTunnelTerminationFailure(error)) {
+    const message2 = error instanceof Error ? error.message : String(error);
+    nodeProcess.stderr.write(`Error during cleanup: ${message2}
 `);
+    nodeProcess.exit(CLEANUP_FAILURE_EXIT_CODE);
   }
-  process7.exit(1);
+  const message = error instanceof Error ? error.message : String(error);
+  nodeProcess.stderr.write(`Error: ${message}
+`);
+  nodeProcess.exit(cliErrorExitCode(error));
+}
+try {
+  await main(nodeProcess.argv);
+} catch (error) {
+  writeTopLevelError(error);
 }
 export {
   main