@saptools/cf-debugger 0.1.14 → 0.1.15

package/dist/index.js

@@ -15,8 +15,8 @@ var CfDebuggerError = class extends Error {
 };
 
 // src/debug-session/start.ts
-import { mkdir as mkdir3, rm } from "fs/promises";
-import process4 from "process";
+import { chmod as chmod3, mkdir as mkdir3, rm as rm2 } from "fs/promises";
+import process5 from "process";
 
 // src/cloud-foundry/commands.ts
 import { execFile as execFile2 } from "child_process";
@@ -95,8 +95,9 @@ 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 = 18e4;
+var DEFAULT_CF_COMMAND_TIMEOUT_MS = 3e5;
 var REDACTED_ARG = "<redacted>";
+var MAX_RETRIES = 3;
 function buildEnv(cfHome) {
   return { ...process.env, CF_HOME: cfHome };
 }
@@ -112,30 +113,129 @@ function sensitiveArgs(args) {
 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(" ");
 }
-async function runCf(args, context, timeoutMs = DEFAULT_CF_COMMAND_TIMEOUT_MS) {
-  try {
-    const { stdout } = await execFileAsync(resolveBin(context), [...args], {
-      env: buildEnv(context.cfHome),
-      maxBuffer: MAX_BUFFER,
-      timeout: timeoutMs
-    });
-    return stdout;
-  } catch (err) {
-    const e = err;
-    const redactionValues = sensitiveArgs(args);
-    const stderr = redactText(e.stderr?.trim() ?? "", redactionValues);
-    const fallbackMessage = redactText(e.message, redactionValues);
-    throw new CfDebuggerError(
-      "CF_CLI_FAILED",
-      `cf ${formatArgsForError(args)} failed: ${stderr.length > 0 ? stderr : fallbackMessage}`,
-      stderr
-    );
+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);
+    }
   }
 }
 
@@ -143,6 +243,27 @@ async function runCf(args, context, timeoutMs = DEFAULT_CF_COMMAND_TIMEOUT_MS) {
 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);
 }
@@ -150,14 +271,18 @@ async function cfAuth(email, password, context) {
   let lastError;
   for (let attempt = 0; attempt < CF_AUTH_MAX_ATTEMPTS; attempt++) {
     try {
-      await runCf(["auth", email, password], context);
+      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 new Promise((resolve) => {
-          setTimeout(resolve, 1e3 * (attempt + 1));
-        });
+        await waitForAuthRetry(1e3 * (attempt + 1), context.signal);
       }
     }
   }
@@ -171,6 +296,7 @@ async function cfLogin(apiEndpoint, email, password, context) {
     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);
     }
@@ -181,6 +307,7 @@ 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);
     }
@@ -191,7 +318,8 @@ async function cfSshEnabled(appName, context) {
   try {
     const stdout = await runCf(["ssh-enabled", appName], context);
     return stdout.toLowerCase().includes("ssh support is enabled");
-  } catch {
+  } catch (err) {
+    rethrowCallerAbort(err);
     return false;
   }
 }
@@ -199,6 +327,7 @@ 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);
     }
@@ -257,7 +386,7 @@ function parseTargetFields(stdout) {
         line.slice(0, separator).trim().toLowerCase(),
         line.slice(separator + 1).trim()
       ];
-    }).filter((field) => field !== void 0)
+    }).filter((field3) => field3 !== void 0)
   );
 }
 function regionKeyForApiEndpoint(apiEndpoint) {
@@ -281,69 +410,366 @@ function isPresent(value) {
 
 // src/cloud-foundry/ssh.ts
 import { spawn } from "child_process";
-async function cfSshOneShot(appName, command, context, timeoutMs = DEFAULT_CF_COMMAND_TIMEOUT_MS) {
-  return await new Promise((resolve) => {
-    const child = spawn(resolveBin(context), ["ssh", appName, "-c", command], {
+
+// 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_inspector_owner() {",
+  `  socket_inode="$(awk '$2 ~ /:240D$/ && $4 == "0A" { 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",
+  "}",
+  '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 echo "saptools-inspector-node-ambiguous=$candidate_pids"; exit 0; 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"]
     });
-    let stderrBuf = "";
-    let settled = false;
-    const timeout = setTimeout(() => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      try {
-        child.kill();
-      } catch {
-      }
-      resolve({ exitCode: null, stderr: stderrBuf, timedOutAfterMs: timeoutMs });
-    }, timeoutMs);
-    child.stderr.on("data", (data) => {
-      stderrBuf += data.toString();
-    });
-    child.on("close", (code, signal) => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      clearTimeout(timeout);
-      resolve(
-        signal === null ? { exitCode: code, stderr: stderrBuf } : { exitCode: code, stderr: stderrBuf, signal }
-      );
-    });
-    child.on("error", (err) => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      clearTimeout(timeout);
-      resolve({ exitCode: null, stderr: err.message });
-    });
+    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) {
+function spawnSshTunnel(appName, localPort, remotePort, context, target = {}) {
   const tunnelArg = `${localPort.toString()}:localhost:${remotePort.toString()}`;
-  const isWindows = process.platform === "win32";
-  return spawn(resolveBin(context), ["ssh", appName, "-N", "-L", tunnelArg], {
+  const args = buildCfSshArgs(appName, target, ["-N", "-L", tunnelArg]);
+  const child = spawn(resolveBin(context), [...args], {
     env: buildEnv(context.cfHome),
-    shell: isWindows,
-    detached: !isWindows
+    detached: process.platform !== "win32",
+    stdio: ["ignore", "pipe", "pipe"]
   });
+  child.stdout.resume();
+  child.stderr.resume();
+  return child;
 }
 
 // src/paths.ts
 import { homedir } from "os";
-import { join } from "path";
+import { isAbsolute, join } from "path";
 var SAPTOOLS_DIR_NAME = ".saptools";
-var CF_DEBUGGER_STATE_FILENAME = "cf-debugger-state.json";
-var CF_DEBUGGER_LOCK_FILENAME = "cf-debugger-state.lock";
-var CF_DEBUGGER_HOMES_DIRNAME = "cf-debugger-homes";
+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);
 }
@@ -353,9 +779,21 @@ function stateFilePath() {
 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";
@@ -496,177 +934,488 @@ async function isPortListening(port, timeoutMs = 200) {
     });
   });
 }
-async function probeTunnelReady(port, timeoutMs) {
+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;
     }
-    await new Promise((resolve) => {
-      setTimeout(resolve, pollIntervalMs);
-    });
+    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];
 }
-async function killProcessOnPort(port) {
-  const portStr = port.toString();
-  if (process.platform === "win32") {
-    try {
-      const pids = await findListeningPidsWithNetstat(port);
-      for (const pid of pids) {
-        try {
-          await execFileAsync3("taskkill", ["/F", "/PID", pid.toString()]);
-        } catch {
-        }
-      }
-    } catch {
-    }
-    return;
-  }
-  try {
-    const { stdout } = await execFileAsync3("lsof", ["-t", "-i", `tcp:${portStr}`]);
-    const lines = stdout.trim().split("\n").filter((line) => line.length > 0);
-    for (const line of lines) {
-      const pid = Number.parseInt(line, 10);
-      if (Number.isNaN(pid)) {
-        continue;
-      }
-      try {
-        process.kill(pid, "SIGKILL");
-      } catch {
-      }
-    }
-  } catch {
-  }
-}
 
 // src/session-state/store.ts
-import { randomUUID } from "crypto";
-import { mkdir as mkdir2, readFile as readFile2, rename, writeFile } from "fs/promises";
+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 } from "path";
-import process2 from "process";
+import { dirname as dirname2, isAbsolute as isAbsolute3 } from "path";
+import process3 from "process";
 
 // src/lock.ts
-import { mkdir, open, unlink } from "fs/promises";
+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);
   });
 }
-async function acquireFileLock(lockPath, timeoutMs, pollMs) {
-  const deadline = Date.now() + timeoutMs;
-  await mkdir(dirname(lockPath), { recursive: true });
-  for (; ; ) {
-    try {
-      return await open(lockPath, "wx");
-    } catch (err) {
-      const code = err.code;
-      if (code !== "EEXIST") {
-        throw err;
-      }
-    }
-    if (Date.now() > deadline) {
-      throw new Error(`Timed out acquiring file lock at ${lockPath}`);
-    }
-    await sleep(pollMs);
+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;
 }
-async function releaseFileLock(lockPath, handle) {
-  await handle.close();
-  await unlink(lockPath).catch((err) => {
-    const code = err.code;
-    if (code !== "ENOENT") {
-      throw err;
-    }
-  });
+function field(value, key) {
+  return Reflect.get(value, key);
 }
-async function withFileLock(lockPath, work, options) {
-  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const pollMs = options?.pollMs ?? DEFAULT_POLL_MS;
-  const handle = await acquireFileLock(lockPath, timeoutMs, pollMs);
+function parseLockOwner(raw) {
+  let value;
   try {
-    return await work();
-  } finally {
-    await releaseFileLock(lockPath, handle);
+    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 };
 }
-
-// src/session-state/store.ts
-async function readJsonFile(path) {
-  let raw;
+function isProcessAlive(pid) {
   try {
-    raw = await readFile2(path, "utf8");
-  } catch (err) {
-    const code = err.code;
-    if (code === "ENOENT") {
+    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 err;
+    throw error;
   }
+}
+async function isStaleLock(lockPath, staleMs) {
+  let modifiedAt;
   try {
-    return JSON.parse(raw);
-  } catch {
-    process2.stderr.write(
-      `[cf-debugger] warning: state file at ${path} is not valid JSON; resetting to empty.
-`
-    );
-    return void 0;
+    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 writeJsonFileAtomic(path, value) {
-  const tempPath = `${path}.${randomUUID()}.tmp`;
-  await mkdir2(dirname2(path), { recursive: true });
-  await writeFile(tempPath, `${JSON.stringify(value, null, 2)}
-`, "utf8");
-  await rename(tempPath, path);
-}
-function emptyState() {
-  return { version: "1", sessions: [] };
-}
-function isValidState(value) {
-  if (typeof value !== "object" || value === null) {
-    return false;
+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;
   }
-  const candidate = value;
-  return candidate.version === "1" && Array.isArray(candidate.sessions);
+  await unlink(recoveryPath).catch((error) => {
+    if (errorCode(error) !== "ENOENT") {
+      throw error;
+    }
+  });
 }
-function isPidAlive(pid) {
+async function reclaimStaleLock(lockPath, staleMs) {
+  const recoveryPath = `${lockPath}.recovery`;
+  let recoveryLock;
   try {
-    process2.kill(pid, 0);
-    return true;
-  } catch (err) {
-    const code = err.code;
-    if (code === "ESRCH") {
+    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 isSessionHealthy(session, host) {
-  if (session.hostname !== host) {
-    return true;
+async function removeOwnedLock(lockPath, token) {
+  const owner = await readLockOwner(lockPath);
+  if (owner?.token !== token) {
+    return;
   }
-  if (!isPidAlive(session.pid)) {
-    return false;
+  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);
+    }
   }
-  if (session.status !== "ready") {
+}
+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;
   }
-  if (!await isPortListening(session.localPort)) {
+  return isProcessGroupAlive(pid);
+}
+function isProcessGroupAlive(pid) {
+  return process3.platform !== "win32" && isPidAlive(-pid);
+}
+async function isSessionHealthy(session, host) {
+  if (session.hostname !== host) {
     return false;
   }
-  const listeningPid = await findListeningProcessId(session.localPort);
-  return listeningPid === void 0 || listeningPid === session.pid;
+  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();
@@ -679,23 +1428,35 @@ async function filterStaleSessions(sessions) {
   return checks.filter(([, healthy]) => healthy).map(([session]) => session);
 }
 async function readStateRaw() {
-  const parsed = await readJsonFile(stateFilePath());
-  if (!isValidState(parsed)) {
+  const path = stateFilePath();
+  const parsed = await readJsonFile(path);
+  if (parsed === void 0) {
     return emptyState();
   }
-  return parsed;
+  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 pruned = await filterStaleSessions(raw.sessions);
-  const removed = raw.sessions.filter(
+  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: "1", sessions: pruned });
+    await writeState({ version: "2", sessions: [...remote, ...pruned] });
   }
   return { sessions: pruned, removed };
 }
@@ -703,14 +1464,38 @@ 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) {
-  return `${key.region}:${key.org}:${key.space}:${key.app}`;
+  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) {
-  return session.region === key.region && session.org === key.org && session.space === key.space && session.app === key.app;
+  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;
@@ -739,9 +1524,13 @@ async function pickPort(preferred, reserved, probe, basePort, maxPort) {
   );
 }
 async function registerNewSession(input) {
+  const target = resolveNodeTarget(input);
   return await withFileLock(stateLockPath(), async () => {
     const pruneResult = await readAndPruneLocked();
-    const existing = pruneResult.sessions.find((session2) => matchesKey(session2, input));
+    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 };
     }
@@ -753,28 +1542,41 @@ async function registerNewSession(input) {
       input.basePort ?? DEFAULT_BASE_PORT,
       input.maxPort ?? DEFAULT_MAX_PORT
     );
-    const sessionId = (input.sessionIdFactory ?? randomUUID)();
-    const cfHomeDir = input.cfHomeForSession(sessionId);
-    const session = {
-      sessionId,
-      pid: process2.pid,
-      hostname: getHostname(),
-      region: input.region,
-      org: input.org,
-      space: input.space,
-      app: input.app,
-      apiEndpoint: input.apiEndpoint,
-      localPort,
-      remotePort: 9229,
-      cfHomeDir,
-      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      status: "starting"
-    };
-    const nextSessions = [...pruneResult.sessions, session];
-    await writeState({ version: "1", sessions: nextSessions });
+    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();
@@ -783,32 +1585,31 @@ async function updateSessionStatus(sessionId, status, message) {
       if (session.sessionId !== sessionId) {
         return session;
       }
-      const base = {
-        sessionId: session.sessionId,
-        pid: session.pid,
-        hostname: session.hostname,
-        region: session.region,
-        org: session.org,
-        space: session.space,
-        app: session.app,
-        apiEndpoint: session.apiEndpoint,
-        localPort: session.localPort,
-        remotePort: session.remotePort,
-        cfHomeDir: session.cfHomeDir,
-        startedAt: session.startedAt,
-        status
-      };
-      const next = message === void 0 ? base : { ...base, message };
+      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: "1", sessions: nextSessions });
+      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;
@@ -816,27 +1617,47 @@ async function updateSessionPid(sessionId, pid) {
       if (session.sessionId !== sessionId) {
         return session;
       }
-      const next = {
-        sessionId: session.sessionId,
-        pid,
-        hostname: session.hostname,
-        region: session.region,
-        org: session.org,
-        space: session.space,
-        app: session.app,
-        apiEndpoint: session.apiEndpoint,
-        localPort: session.localPort,
-        remotePort: session.remotePort,
-        cfHomeDir: session.cfHomeDir,
-        startedAt: session.startedAt,
-        status: session.status,
-        ...session.message === void 0 ? {} : { message: session.message }
-      };
+      if (startupMutationBlocked(session)) {
+        updated = session;
+        return session;
+      }
+      const next = { ...session, pid, tunnelPid: pid };
       updated = next;
       return next;
     });
     if (updated !== void 0) {
-      await writeState({ version: "1", sessions: nextSessions });
+      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;
   });
@@ -849,72 +1670,145 @@ async function removeSession(sessionId) {
       return void 0;
     }
     const remaining = raw.sessions.filter((session) => session.sessionId !== sessionId);
-    await writeState({ version: "1", sessions: remaining });
+    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 PORT_CLEANUP_DELAY_MS = 600;
 var CHILD_SIGTERM_GRACE_MS = 2e3;
-var PORT_RECLAIM_DELAY_MS = 250;
+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) {
-      void killProcessOnPort(removed.localPort);
+    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 process3 from "process";
-function signalPidOrGroup(pid, signal) {
-  const isWindows = process3.platform === "win32";
-  if (!isWindows) {
-    try {
-      process3.kill(-pid, signal);
-      return;
-    } catch {
-    }
+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 {
-    process3.kill(pid, signal);
+    process4.kill(targetKind === "group" ? -pid : pid, "SIGTERM");
   } catch {
   }
-}
-async function terminatePidOrGroup(pid, timeoutMs = CHILD_SIGTERM_GRACE_MS) {
-  if (!isPidAlive(pid)) {
-    return;
-  }
-  signalPidOrGroup(pid, "SIGTERM");
   const startedAt = Date.now();
   while (Date.now() - startedAt < timeoutMs) {
-    if (!isPidAlive(pid)) {
-      return;
+    if (!targetAlive()) {
+      return "terminated";
     }
     await new Promise((resolve) => {
       setTimeout(resolve, PID_TERMINATION_POLL_MS);
     });
   }
-  signalPidOrGroup(pid, "SIGKILL");
+  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;
+    return "terminated";
   }
-  if (child.exitCode !== null || child.signalCode !== null) {
-    return;
+  const childClosed = child.exitCode !== null || child.signalCode !== null;
+  if (childClosed && process4.platform === "win32") {
+    return "terminated";
   }
-  await terminatePidOrGroup(child.pid, timeoutMs);
+  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
@@ -936,9 +1830,30 @@ function checkAbort(signal) {
     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.");
+  }
+  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 ?? process4.env["SAP_EMAIL"];
-  const password = options.password ?? process4.env["SAP_PASSWORD"];
+  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",
@@ -953,12 +1868,15 @@ function requireCredentials(options) {
   }
   return { email, password };
 }
-async function registerSession(options, apiEndpoint) {
+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,
@@ -974,50 +1892,55 @@ async function registerSession(options, apiEndpoint) {
 }
 async function loginAndTarget(options, apiEndpoint, email, password, context, sessionId, emit) {
   emit("logging-in");
-  await updateSessionStatus(sessionId, "logging-in");
+  await transitionStartupStatus(sessionId, "logging-in");
   await cfLogin(apiEndpoint, email, password, context);
-  checkAbort(options.signal);
+  checkAbort(context.signal);
   emit("targeting");
-  await updateSessionStatus(sessionId, "targeting");
+  await transitionStartupStatus(sessionId, "targeting");
   await cfTarget(options.org, options.space, context);
-  checkAbort(options.signal);
+  checkAbort(context.signal);
 }
-async function signalRemoteNode(options, context, sessionId, emit) {
+async function signalRemoteNode(options, target, context, sessionId, emit) {
   emit("signaling");
-  await updateSessionStatus(sessionId, "signaling");
-  const signalResult = await cfSshOneShot(options.app, `kill -s USR1 $(pidof node)`, context);
+  await transitionStartupStatus(sessionId, "signaling");
+  const signalResult = await executeRemoteSignal(options.app, target, context);
   if (!isSshDisabledError(signalResult.stderr)) {
-    if (signalResult.exitCode === 0) {
-      return;
-    }
+    return parseSignalResult(options.app, signalResult);
+  }
+  if (options.allowSshEnableRestart === false) {
     throw new CfDebuggerError(
-      "USR1_SIGNAL_FAILED",
-      `Failed to send SIGUSR1 to the Node.js process on ${options.app}: ${signalFailureDetail(signalResult)}`,
+      "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 updateSessionStatus(sessionId, "ssh-enabling");
+    await transitionStartupStatus(sessionId, "ssh-enabling");
     await cfEnableSsh(options.app, context);
   }
   emit("ssh-restarting", "Restarting app so SSH becomes active");
-  await updateSessionStatus(sessionId, "ssh-restarting");
+  await transitionStartupStatus(sessionId, "ssh-restarting");
   await cfRestartApp(options.app, context);
-  checkAbort(options.signal);
-  await retryRemoteSignal(options, context, sessionId, emit);
+  checkAbort(context.signal);
 }
-async function retryRemoteSignal(options, context, sessionId, emit) {
+async function retryRemoteSignal(options, target, context, sessionId, emit) {
   emit("signaling");
-  await updateSessionStatus(sessionId, "signaling");
-  const retrySignalResult = await cfSshOneShot(
-    options.app,
-    `kill -s USR1 $(pidof node)`,
-    context
-  );
+  await transitionStartupStatus(sessionId, "signaling");
+  const retrySignalResult = await executeRemoteSignal(options.app, target, context);
   if (retrySignalResult.exitCode === 0) {
-    return;
+    return parseSignalResult(options.app, retrySignalResult);
   }
   throw new CfDebuggerError(
     "USR1_SIGNAL_FAILED",
@@ -1025,36 +1948,77 @@ async function retryRemoteSignal(options, context, sessionId, emit) {
     retrySignalResult.stderr
   );
 }
-async function waitAfterSignal(signal) {
-  await new Promise((resolve) => {
-    setTimeout(resolve, POST_USR1_DELAY_MS);
+async function executeRemoteSignal(appName, target, context) {
+  return await cfSshOneShot(appName, buildNodeInspectorCommand(target.nodePid), context, {
+    process: target.process,
+    instance: target.instance
   });
-  checkAbort(signal);
 }
-async function ensurePortAvailable(localPort) {
-  if (await isPortFree(localPort)) {
-    return;
+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
+    );
   }
-  await killProcessOnPort(localPort);
-  await new Promise((resolve) => {
-    setTimeout(resolve, PORT_RECLAIM_DELAY_MS);
+  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()} is in use and could not be reclaimed for the tunnel.`
+      `Local port ${localPort.toString()} was taken before the tunnel could start.`
     );
   }
 }
-async function openReadyTunnel(options, session, context, tunnelReadyTimeoutMs, onChild) {
+async function openReadyTunnel(options, target, session, context, tunnelReadyTimeoutMs, onChild) {
   await ensurePortAvailable(session.localPort);
-  const child = spawnSshTunnel(options.app, session.localPort, session.remotePort, context);
+  checkAbort(context.signal);
+  const child = spawnSshTunnel(options.app, session.localPort, session.remotePort, context, {
+    process: target.process,
+    instance: target.instance
+  });
   onChild(child);
-  if (child.pid !== void 0) {
-    await updateSessionPid(session.sessionId, child.pid);
+  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 ready = await probeTunnelReady(session.localPort, tunnelReadyTimeoutMs);
-  checkAbort(options.signal);
+  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",
@@ -1062,15 +2026,21 @@ async function openReadyTunnel(options, session, context, tunnelReadyTimeoutMs,
     );
   }
   const listeningPid = await findListeningProcessId(session.localPort);
-  const activePid = listeningPid ?? child.pid ?? session.pid;
-  if (activePid !== session.pid) {
-    await updateSessionPid(session.sessionId, activePid);
+  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.`
+    );
   }
-  return { child, activePid };
 }
-function attachTunnelEvents(child, markClosed, resolveExit, emit) {
+function attachTunnelEvents(child, resolveExit, emit) {
   child.on("close", (code) => {
-    markClosed();
     resolveExit(code);
   });
   child.on("error", (err) => {
@@ -1082,139 +2052,291 @@ function createHandle(session, emit, finalize, exitPromise) {
   return {
     session,
     dispose: async () => {
-      disposePromise ??= (async () => {
-        emit("stopping");
-        await updateSessionStatus(session.sessionId, "stopping");
-        await finalize();
+      const attempt = disposePromise ?? (async () => {
+        await runCleanupActions([
+          () => {
+            emit("stopping");
+          },
+          async () => {
+            await updateSessionStatus(session.sessionId, "stopping");
+          },
+          finalize
+        ], "Debugger disposal failed");
       })();
-      await disposePromise;
+      disposePromise = attempt;
+      try {
+        await attempt;
+      } catch (error) {
+        if (disposePromise === attempt) {
+          disposePromise = void 0;
+        }
+        throw error;
+      }
     },
     waitForExit: async () => {
       return await exitPromise;
     }
   };
 }
-async function startDebugger(options) {
-  const { email, password } = 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, apiEndpoint);
-  const context = { cfHome: session.cfHomeDir };
+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 tunnelClosed = false;
   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 () => {
-    if (!tunnelClosed) {
-      tunnelClosed = true;
-      if (child) {
-        await killProcessGroupOrProc(child);
-      }
-      setTimeout(() => {
-        void killProcessOnPort(session.localPort);
-      }, PORT_CLEANUP_DELAY_MS);
+    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 removeSession(session.sessionId);
-    await cleanupFilesystem(session.cfHomeDir);
+    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 mkdir3(session.cfHomeDir, { recursive: true });
-    await loginAndTarget(options, apiEndpoint, email, password, context, session.sessionId, emit);
-    await killProcessOnPort(session.localPort);
-    await new Promise((resolve) => {
-      setTimeout(resolve, 200);
-    });
-    await signalRemoteNode(options, context, session.sessionId, emit);
-    await waitAfterSignal(options.signal);
-    emit("tunneling");
-    await updateSessionStatus(session.sessionId, "tunneling");
-    const tunnel = await openReadyTunnel(
+    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,
-      tunnelReadyTimeoutMs,
-      (tunnelChild) => {
-        child = tunnelChild;
-        attachTunnelEvents(tunnelChild, () => {
-          tunnelClosed = true;
-        }, exitResolve, emit);
-      }
-    );
-    child = tunnel.child;
-    emit("ready");
-    const readySession = await updateSessionStatus(session.sessionId, "ready");
-    const activeSession = readySession ?? { ...session, pid: tunnel.activePid, status: "ready" };
-    return createHandle(activeSession, emit, finalize, exitPromise);
+      credentials,
+      timeoutMs: tunnelReadyTimeoutMs,
+      lifecycle,
+      emit
+    });
+    cancellation.dispose();
+    return createHandle(activeSession, emit, lifecycle.finalize, lifecycle.exitPromise);
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    emit("error", message);
-    await finalize();
-    throw err;
+    cancellation.dispose();
+    return await failAfterStartupCleanup(err, lifecycle.finalize, emit);
   }
 }
 async function cleanupFilesystem(cfHomeDir) {
-  try {
-    await rm(cfHomeDir, { recursive: true, force: true });
-  } catch {
-  }
+  await rm2(cfHomeDir, { recursive: true, force: true });
 }
 
 // src/debug-session/sessions.ts
-import { rm as rm2 } from "fs/promises";
-import process5 from "process";
+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;
-    return sessions.find((s) => matchesKey(s, 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 cleanupSession(target, stale) {
-  if (!stale && target.pid !== process5.pid) {
+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 {
-      await terminatePidOrGroup(target.pid);
+      return await terminatePidOrGroup(target.tunnelPid);
     } catch {
+      return "still-alive";
     }
   }
-  setTimeout(() => {
-    void killProcessOnPort(target.localPort);
-  }, PORT_CLEANUP_DELAY_MS);
-  const removed = stale ? void 0 : await removeSession(target.sessionId);
-  try {
-    await rm2(target.cfHomeDir, { recursive: true, force: true });
-  } catch {
+  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.`
+    );
   }
-  return { ...removed ?? target, stale };
+}
+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 pruneResult = await pruneAndCleanupOrphans();
-  const activeTarget = findMatchingSession(pruneResult.sessions, options);
-  if (activeTarget !== void 0) {
-    return await cleanupSession(activeTarget, false);
+  const localSessions = (await readSessionSnapshot()).filter(
+    (session) => session.hostname === getHostname3()
+  );
+  const target = findMatchingSession(localSessions, options);
+  if (target === void 0) {
+    return void 0;
   }
-  const staleTarget = findMatchingSession(pruneResult.removed, options);
-  if (staleTarget !== void 0) {
-    return await cleanupSession(staleTarget, true);
+  const claim = await requestSessionStop(target.sessionId);
+  if (claim === void 0) {
+    return void 0;
   }
-  return void 0;
+  return claim.previousStatus === "ready" ? await stopReadySession(claim.session) : await stopStartingSession(claim.session);
 }
 async function stopAllDebuggers() {
-  const pruneResult = await pruneAndCleanupOrphans();
-  let stopped = pruneResult.removed.length;
-  for (const session of pruneResult.sessions) {
+  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;
@@ -1227,17 +2349,20 @@ async function listSessions() {
 }
 async function getSession(key) {
   const sessions = await readActiveSessions();
-  return sessions.find((s) => matchesKey(s, key));
+  return findMatchingSession(sessions, { key });
 }
 export {
   CfDebuggerError,
+  buildNodeInspectorCommand,
   getSession,
   listKnownRegionKeys,
   listSessions,
   parseCurrentCfTarget,
+  parseNodeInspectorMarkers,
   readCurrentCfTarget,
   requireCurrentCfRegion,
   resolveApiEndpoint,
+  resolveNodeTarget,
   sessionKeyString,
   startDebugger,
   stopAllDebuggers,